1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/util/secasn1t.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,268 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +/*
1.9 + * Types for encoding/decoding of ASN.1 using BER/DER (Basic/Distinguished
1.10 + * Encoding Rules).
1.11 + */
1.12 +
1.13 +#ifndef _SECASN1T_H_
1.14 +#define _SECASN1T_H_
1.15 +
1.16 +#include "utilrename.h"
1.17 +
1.18 +/*
1.19 +** An array of these structures defines a BER/DER encoding for an object.
1.20 +**
1.21 +** The array usually starts with a dummy entry whose kind is SEC_ASN1_SEQUENCE;
1.22 +** such an array is terminated with an entry where kind == 0. (An array
1.23 +** which consists of a single component does not require a second dummy
1.24 +** entry -- the array is only searched as long as previous component(s)
1.25 +** instruct it.)
1.26 +*/
1.27 +typedef struct sec_ASN1Template_struct {
1.28 + /*
1.29 + ** Kind of item being decoded/encoded, including tags and modifiers.
1.30 + */
1.31 + unsigned long kind;
1.32 +
1.33 + /*
1.34 + ** The value is the offset from the base of the structure to the
1.35 + ** field that holds the value being decoded/encoded.
1.36 + */
1.37 + unsigned long offset;
1.38 +
1.39 + /*
1.40 + ** When kind suggests it (SEC_ASN1_POINTER, SEC_ASN1_GROUP, SEC_ASN1_INLINE,
1.41 + ** or a component that is *not* a SEC_ASN1_UNIVERSAL), this points to
1.42 + ** a sub-template for nested encoding/decoding,
1.43 + ** OR, iff SEC_ASN1_DYNAMIC is set, then this is a pointer to a pointer
1.44 + ** to a function which will return the appropriate template when called
1.45 + ** at runtime. NOTE! that explicit level of indirection, which is
1.46 + ** necessary because ANSI does not allow you to store a function
1.47 + ** pointer directly as a "void *" so we must store it separately and
1.48 + ** dereference it to get at the function pointer itself.
1.49 + */
1.50 + const void *sub;
1.51 +
1.52 + /*
1.53 + ** In the first element of a template array, the value is the size
1.54 + ** of the structure to allocate when this template is being referenced
1.55 + ** by another template via SEC_ASN1_POINTER or SEC_ASN1_GROUP.
1.56 + ** In all other cases, the value is ignored.
1.57 + */
1.58 + unsigned int size;
1.59 +} SEC_ASN1Template;
1.60 +
1.61 +
1.62 +/* default size used for allocation of encoding/decoding stuff */
1.63 +/* XXX what is the best value here? */
1.64 +#define SEC_ASN1_DEFAULT_ARENA_SIZE (2048)
1.65 +
1.66 +/*
1.67 +** BER/DER values for ASN.1 identifier octets.
1.68 +*/
1.69 +#define SEC_ASN1_TAG_MASK 0xff
1.70 +
1.71 +/*
1.72 + * BER/DER universal type tag numbers.
1.73 + * The values are defined by the X.208 standard; do not change them!
1.74 + * NOTE: if you add anything to this list, you must add code to secasn1d.c
1.75 + * to accept the tag, and probably also to secasn1e.c to encode it.
1.76 + * XXX It appears some have been added recently without being added to
1.77 + * the code; so need to go through the list now and double-check them all.
1.78 + * (Look especially at those added in revision 1.10.)
1.79 + */
1.80 +#define SEC_ASN1_TAGNUM_MASK 0x1f
1.81 +#define SEC_ASN1_BOOLEAN 0x01
1.82 +#define SEC_ASN1_INTEGER 0x02
1.83 +#define SEC_ASN1_BIT_STRING 0x03
1.84 +#define SEC_ASN1_OCTET_STRING 0x04
1.85 +#define SEC_ASN1_NULL 0x05
1.86 +#define SEC_ASN1_OBJECT_ID 0x06
1.87 +#define SEC_ASN1_OBJECT_DESCRIPTOR 0x07
1.88 +/* External type and instance-of type 0x08 */
1.89 +#define SEC_ASN1_REAL 0x09
1.90 +#define SEC_ASN1_ENUMERATED 0x0a
1.91 +#define SEC_ASN1_EMBEDDED_PDV 0x0b
1.92 +#define SEC_ASN1_UTF8_STRING 0x0c
1.93 +/* 0x0d */
1.94 +/* 0x0e */
1.95 +/* 0x0f */
1.96 +#define SEC_ASN1_SEQUENCE 0x10
1.97 +#define SEC_ASN1_SET 0x11
1.98 +#define SEC_ASN1_NUMERIC_STRING 0x12
1.99 +#define SEC_ASN1_PRINTABLE_STRING 0x13
1.100 +#define SEC_ASN1_T61_STRING 0x14
1.101 +#define SEC_ASN1_VIDEOTEX_STRING 0x15
1.102 +#define SEC_ASN1_IA5_STRING 0x16
1.103 +#define SEC_ASN1_UTC_TIME 0x17
1.104 +#define SEC_ASN1_GENERALIZED_TIME 0x18
1.105 +#define SEC_ASN1_GRAPHIC_STRING 0x19
1.106 +#define SEC_ASN1_VISIBLE_STRING 0x1a
1.107 +#define SEC_ASN1_GENERAL_STRING 0x1b
1.108 +#define SEC_ASN1_UNIVERSAL_STRING 0x1c
1.109 +/* 0x1d */
1.110 +#define SEC_ASN1_BMP_STRING 0x1e
1.111 +#define SEC_ASN1_HIGH_TAG_NUMBER 0x1f
1.112 +#define SEC_ASN1_TELETEX_STRING SEC_ASN1_T61_STRING
1.113 +
1.114 +/*
1.115 +** Modifiers to type tags. These are also specified by a/the
1.116 +** standard, and must not be changed.
1.117 +*/
1.118 +
1.119 +#define SEC_ASN1_METHOD_MASK 0x20
1.120 +#define SEC_ASN1_PRIMITIVE 0x00
1.121 +#define SEC_ASN1_CONSTRUCTED 0x20
1.122 +
1.123 +#define SEC_ASN1_CLASS_MASK 0xc0
1.124 +#define SEC_ASN1_UNIVERSAL 0x00
1.125 +#define SEC_ASN1_APPLICATION 0x40
1.126 +#define SEC_ASN1_CONTEXT_SPECIFIC 0x80
1.127 +#define SEC_ASN1_PRIVATE 0xc0
1.128 +
1.129 +/*
1.130 +** Our additions, used for templates.
1.131 +** These are not defined by any standard; the values are used internally only.
1.132 +** Just be careful to keep them out of the low 8 bits.
1.133 +** XXX finish comments
1.134 +*/
1.135 +#define SEC_ASN1_OPTIONAL 0x00100
1.136 +#define SEC_ASN1_EXPLICIT 0x00200
1.137 +#define SEC_ASN1_ANY 0x00400
1.138 +#define SEC_ASN1_INLINE 0x00800
1.139 +#define SEC_ASN1_POINTER 0x01000
1.140 +#define SEC_ASN1_GROUP 0x02000 /* with SET or SEQUENCE means
1.141 + * SET OF or SEQUENCE OF */
1.142 +#define SEC_ASN1_DYNAMIC 0x04000 /* subtemplate is found by calling
1.143 + * a function at runtime */
1.144 +#define SEC_ASN1_SKIP 0x08000 /* skip a field; only for decoding */
1.145 +#define SEC_ASN1_INNER 0x10000 /* with ANY means capture the
1.146 + * contents only (not the id, len,
1.147 + * or eoc); only for decoding */
1.148 +#define SEC_ASN1_SAVE 0x20000 /* stash away the encoded bytes first;
1.149 + * only for decoding */
1.150 +#define SEC_ASN1_MAY_STREAM 0x40000 /* field or one of its sub-fields may
1.151 + * stream in and so should encode as
1.152 + * indefinite-length when streaming
1.153 + * has been indicated; only for
1.154 + * encoding */
1.155 +#define SEC_ASN1_SKIP_REST 0x80000 /* skip all following fields;
1.156 + only for decoding */
1.157 +#define SEC_ASN1_CHOICE 0x100000 /* pick one from a template */
1.158 +#define SEC_ASN1_NO_STREAM 0X200000 /* This entry will not stream
1.159 + even if the sub-template says
1.160 + streaming is possible. Helps
1.161 + to solve ambiguities with potential
1.162 + streaming entries that are
1.163 + optional */
1.164 +#define SEC_ASN1_DEBUG_BREAK 0X400000 /* put this in your template and the
1.165 + decoder will assert when it
1.166 + processes it. Only for use with
1.167 + SEC_QuickDERDecodeItem */
1.168 +
1.169 +
1.170 +
1.171 +/* Shorthand/Aliases */
1.172 +#define SEC_ASN1_SEQUENCE_OF (SEC_ASN1_GROUP | SEC_ASN1_SEQUENCE)
1.173 +#define SEC_ASN1_SET_OF (SEC_ASN1_GROUP | SEC_ASN1_SET)
1.174 +#define SEC_ASN1_ANY_CONTENTS (SEC_ASN1_ANY | SEC_ASN1_INNER)
1.175 +
1.176 +/* Maximum depth of nested SEQUENCEs and SETs */
1.177 +#define SEC_ASN1D_MAX_DEPTH 32
1.178 +
1.179 +/*
1.180 +** Function used for SEC_ASN1_DYNAMIC.
1.181 +** "arg" is a pointer to the structure being encoded/decoded
1.182 +** "enc", when true, means that we are encoding (false means decoding)
1.183 +*/
1.184 +typedef const SEC_ASN1Template * SEC_ASN1TemplateChooser(void *arg, PRBool enc);
1.185 +typedef SEC_ASN1TemplateChooser * SEC_ASN1TemplateChooserPtr;
1.186 +
1.187 +#if defined(_WIN32) || defined(ANDROID)
1.188 +#define SEC_ASN1_GET(x) NSS_Get_##x(NULL, PR_FALSE)
1.189 +#define SEC_ASN1_SUB(x) &p_NSS_Get_##x
1.190 +#define SEC_ASN1_XTRN SEC_ASN1_DYNAMIC
1.191 +#define SEC_ASN1_MKSUB(x) \
1.192 +static const SEC_ASN1TemplateChooserPtr p_NSS_Get_##x = &NSS_Get_##x;
1.193 +#else
1.194 +#define SEC_ASN1_GET(x) x
1.195 +#define SEC_ASN1_SUB(x) x
1.196 +#define SEC_ASN1_XTRN 0
1.197 +#define SEC_ASN1_MKSUB(x)
1.198 +#endif
1.199 +
1.200 +#define SEC_ASN1_CHOOSER_DECLARE(x) \
1.201 +extern const SEC_ASN1Template * NSS_Get_##x (void *arg, PRBool enc);
1.202 +
1.203 +#define SEC_ASN1_CHOOSER_IMPLEMENT(x) \
1.204 +const SEC_ASN1Template * NSS_Get_##x(void * arg, PRBool enc) \
1.205 +{ return x; }
1.206 +
1.207 +/*
1.208 +** Opaque object used by the decoder to store state.
1.209 +*/
1.210 +typedef struct sec_DecoderContext_struct SEC_ASN1DecoderContext;
1.211 +
1.212 +/*
1.213 +** Opaque object used by the encoder to store state.
1.214 +*/
1.215 +typedef struct sec_EncoderContext_struct SEC_ASN1EncoderContext;
1.216 +
1.217 +/*
1.218 + * This is used to describe to a filter function the bytes that are
1.219 + * being passed to it. This is only useful when the filter is an "outer"
1.220 + * one, meaning it expects to get *all* of the bytes not just the
1.221 + * contents octets.
1.222 + */
1.223 +typedef enum {
1.224 + SEC_ASN1_Identifier = 0,
1.225 + SEC_ASN1_Length = 1,
1.226 + SEC_ASN1_Contents = 2,
1.227 + SEC_ASN1_EndOfContents = 3
1.228 +} SEC_ASN1EncodingPart;
1.229 +
1.230 +/*
1.231 + * Type of the function pointer used either for decoding or encoding,
1.232 + * when doing anything "funny" (e.g. manipulating the data stream)
1.233 + */
1.234 +typedef void (* SEC_ASN1NotifyProc)(void *arg, PRBool before,
1.235 + void *dest, int real_depth);
1.236 +
1.237 +/*
1.238 + * Type of the function pointer used for grabbing encoded bytes.
1.239 + * This can be used during either encoding or decoding, as follows...
1.240 + *
1.241 + * When decoding, this can be used to filter the encoded bytes as they
1.242 + * are parsed. This is what you would do if you wanted to process the data
1.243 + * along the way (like to decrypt it, or to perform a hash on it in order
1.244 + * to do a signature check later). See SEC_ASN1DecoderSetFilterProc().
1.245 + * When processing only part of the encoded bytes is desired, you "watch"
1.246 + * for the field(s) you are interested in with a "notify proc" (see
1.247 + * SEC_ASN1DecoderSetNotifyProc()) and for even finer granularity (e.g. to
1.248 + * ignore all by the contents bytes) you pay attention to the "data_kind"
1.249 + * parameter.
1.250 + *
1.251 + * When encoding, this is the specification for the output function which
1.252 + * will receive the bytes as they are encoded. The output function can
1.253 + * perform any postprocessing necessary (like hashing (some of) the data
1.254 + * to create a digest that gets included at the end) as well as shoving
1.255 + * the data off wherever it needs to go. (In order to "tune" any processing,
1.256 + * you can set a "notify proc" as described above in the decoding case.)
1.257 + *
1.258 + * The parameters:
1.259 + * - "arg" is an opaque pointer that you provided at the same time you
1.260 + * specified a function of this type
1.261 + * - "data" is a buffer of length "len", containing the encoded bytes
1.262 + * - "depth" is how deep in a nested encoding we are (it is not usually
1.263 + * valuable, but can be useful sometimes so I included it)
1.264 + * - "data_kind" tells you if these bytes are part of the ASN.1 encoded
1.265 + * octets for identifier, length, contents, or end-of-contents
1.266 + */
1.267 +typedef void (* SEC_ASN1WriteProc)(void *arg,
1.268 + const char *data, unsigned long len,
1.269 + int depth, SEC_ASN1EncodingPart data_kind);
1.270 +
1.271 +#endif /* _SECASN1T_H_ */
