andre@0: /* This Source Code Form is subject to the terms of the Mozilla Public andre@0: * License, v. 2.0. If a copy of the MPL was not distributed with this andre@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ andre@0: andre@0: /* andre@0: * Types for encoding/decoding of ASN.1 using BER/DER (Basic/Distinguished andre@0: * Encoding Rules). andre@0: */ andre@0: andre@0: #ifndef _SECASN1T_H_ andre@0: #define _SECASN1T_H_ andre@0: andre@0: #include "utilrename.h" andre@0: andre@0: /* andre@0: ** An array of these structures defines a BER/DER encoding for an object. andre@0: ** andre@0: ** The array usually starts with a dummy entry whose kind is SEC_ASN1_SEQUENCE; andre@0: ** such an array is terminated with an entry where kind == 0. (An array andre@0: ** which consists of a single component does not require a second dummy andre@0: ** entry -- the array is only searched as long as previous component(s) andre@0: ** instruct it.) andre@0: */ andre@0: typedef struct sec_ASN1Template_struct { andre@0: /* andre@0: ** Kind of item being decoded/encoded, including tags and modifiers. andre@0: */ andre@0: unsigned long kind; andre@0: andre@0: /* andre@0: ** The value is the offset from the base of the structure to the andre@0: ** field that holds the value being decoded/encoded. andre@0: */ andre@0: unsigned long offset; andre@0: andre@0: /* andre@0: ** When kind suggests it (SEC_ASN1_POINTER, SEC_ASN1_GROUP, SEC_ASN1_INLINE, andre@0: ** or a component that is *not* a SEC_ASN1_UNIVERSAL), this points to andre@0: ** a sub-template for nested encoding/decoding, andre@0: ** OR, iff SEC_ASN1_DYNAMIC is set, then this is a pointer to a pointer andre@0: ** to a function which will return the appropriate template when called andre@0: ** at runtime. NOTE! that explicit level of indirection, which is andre@0: ** necessary because ANSI does not allow you to store a function andre@0: ** pointer directly as a "void *" so we must store it separately and andre@0: ** dereference it to get at the function pointer itself. andre@0: */ andre@0: const void *sub; andre@0: andre@0: /* andre@0: ** In the first element of a template array, the value is the size andre@0: ** of the structure to allocate when this template is being referenced andre@0: ** by another template via SEC_ASN1_POINTER or SEC_ASN1_GROUP. andre@0: ** In all other cases, the value is ignored. andre@0: */ andre@0: unsigned int size; andre@0: } SEC_ASN1Template; andre@0: andre@0: andre@0: /* default size used for allocation of encoding/decoding stuff */ andre@0: /* XXX what is the best value here? */ andre@0: #define SEC_ASN1_DEFAULT_ARENA_SIZE (2048) andre@0: andre@0: /* andre@0: ** BER/DER values for ASN.1 identifier octets. andre@0: */ andre@0: #define SEC_ASN1_TAG_MASK 0xff andre@0: andre@0: /* andre@0: * BER/DER universal type tag numbers. andre@0: * The values are defined by the X.208 standard; do not change them! andre@0: * NOTE: if you add anything to this list, you must add code to secasn1d.c andre@0: * to accept the tag, and probably also to secasn1e.c to encode it. andre@0: * XXX It appears some have been added recently without being added to andre@0: * the code; so need to go through the list now and double-check them all. andre@0: * (Look especially at those added in revision 1.10.) andre@0: */ andre@0: #define SEC_ASN1_TAGNUM_MASK 0x1f andre@0: #define SEC_ASN1_BOOLEAN 0x01 andre@0: #define SEC_ASN1_INTEGER 0x02 andre@0: #define SEC_ASN1_BIT_STRING 0x03 andre@0: #define SEC_ASN1_OCTET_STRING 0x04 andre@0: #define SEC_ASN1_NULL 0x05 andre@0: #define SEC_ASN1_OBJECT_ID 0x06 andre@0: #define SEC_ASN1_OBJECT_DESCRIPTOR 0x07 andre@0: /* External type and instance-of type 0x08 */ andre@0: #define SEC_ASN1_REAL 0x09 andre@0: #define SEC_ASN1_ENUMERATED 0x0a andre@0: #define SEC_ASN1_EMBEDDED_PDV 0x0b andre@0: #define SEC_ASN1_UTF8_STRING 0x0c andre@0: /* 0x0d */ andre@0: /* 0x0e */ andre@0: /* 0x0f */ andre@0: #define SEC_ASN1_SEQUENCE 0x10 andre@0: #define SEC_ASN1_SET 0x11 andre@0: #define SEC_ASN1_NUMERIC_STRING 0x12 andre@0: #define SEC_ASN1_PRINTABLE_STRING 0x13 andre@0: #define SEC_ASN1_T61_STRING 0x14 andre@0: #define SEC_ASN1_VIDEOTEX_STRING 0x15 andre@0: #define SEC_ASN1_IA5_STRING 0x16 andre@0: #define SEC_ASN1_UTC_TIME 0x17 andre@0: #define SEC_ASN1_GENERALIZED_TIME 0x18 andre@0: #define SEC_ASN1_GRAPHIC_STRING 0x19 andre@0: #define SEC_ASN1_VISIBLE_STRING 0x1a andre@0: #define SEC_ASN1_GENERAL_STRING 0x1b andre@0: #define SEC_ASN1_UNIVERSAL_STRING 0x1c andre@0: /* 0x1d */ andre@0: #define SEC_ASN1_BMP_STRING 0x1e andre@0: #define SEC_ASN1_HIGH_TAG_NUMBER 0x1f andre@0: #define SEC_ASN1_TELETEX_STRING SEC_ASN1_T61_STRING andre@0: andre@0: /* andre@0: ** Modifiers to type tags. These are also specified by a/the andre@0: ** standard, and must not be changed. andre@0: */ andre@0: andre@0: #define SEC_ASN1_METHOD_MASK 0x20 andre@0: #define SEC_ASN1_PRIMITIVE 0x00 andre@0: #define SEC_ASN1_CONSTRUCTED 0x20 andre@0: andre@0: #define SEC_ASN1_CLASS_MASK 0xc0 andre@0: #define SEC_ASN1_UNIVERSAL 0x00 andre@0: #define SEC_ASN1_APPLICATION 0x40 andre@0: #define SEC_ASN1_CONTEXT_SPECIFIC 0x80 andre@0: #define SEC_ASN1_PRIVATE 0xc0 andre@0: andre@0: /* andre@0: ** Our additions, used for templates. andre@0: ** These are not defined by any standard; the values are used internally only. andre@0: ** Just be careful to keep them out of the low 8 bits. andre@0: ** XXX finish comments andre@0: */ andre@0: #define SEC_ASN1_OPTIONAL 0x00100 andre@0: #define SEC_ASN1_EXPLICIT 0x00200 andre@0: #define SEC_ASN1_ANY 0x00400 andre@0: #define SEC_ASN1_INLINE 0x00800 andre@0: #define SEC_ASN1_POINTER 0x01000 andre@0: #define SEC_ASN1_GROUP 0x02000 /* with SET or SEQUENCE means andre@0: * SET OF or SEQUENCE OF */ andre@0: #define SEC_ASN1_DYNAMIC 0x04000 /* subtemplate is found by calling andre@0: * a function at runtime */ andre@0: #define SEC_ASN1_SKIP 0x08000 /* skip a field; only for decoding */ andre@0: #define SEC_ASN1_INNER 0x10000 /* with ANY means capture the andre@0: * contents only (not the id, len, andre@0: * or eoc); only for decoding */ andre@0: #define SEC_ASN1_SAVE 0x20000 /* stash away the encoded bytes first; andre@0: * only for decoding */ andre@0: #define SEC_ASN1_MAY_STREAM 0x40000 /* field or one of its sub-fields may andre@0: * stream in and so should encode as andre@0: * indefinite-length when streaming andre@0: * has been indicated; only for andre@0: * encoding */ andre@0: #define SEC_ASN1_SKIP_REST 0x80000 /* skip all following fields; andre@0: only for decoding */ andre@0: #define SEC_ASN1_CHOICE 0x100000 /* pick one from a template */ andre@0: #define SEC_ASN1_NO_STREAM 0X200000 /* This entry will not stream andre@0: even if the sub-template says andre@0: streaming is possible. Helps andre@0: to solve ambiguities with potential andre@0: streaming entries that are andre@0: optional */ andre@0: #define SEC_ASN1_DEBUG_BREAK 0X400000 /* put this in your template and the andre@0: decoder will assert when it andre@0: processes it. Only for use with andre@0: SEC_QuickDERDecodeItem */ andre@0: andre@0: andre@0: andre@0: /* Shorthand/Aliases */ andre@0: #define SEC_ASN1_SEQUENCE_OF (SEC_ASN1_GROUP | SEC_ASN1_SEQUENCE) andre@0: #define SEC_ASN1_SET_OF (SEC_ASN1_GROUP | SEC_ASN1_SET) andre@0: #define SEC_ASN1_ANY_CONTENTS (SEC_ASN1_ANY | SEC_ASN1_INNER) andre@0: andre@0: /* Maximum depth of nested SEQUENCEs and SETs */ andre@0: #define SEC_ASN1D_MAX_DEPTH 32 andre@0: andre@0: /* andre@0: ** Function used for SEC_ASN1_DYNAMIC. andre@0: ** "arg" is a pointer to the structure being encoded/decoded andre@0: ** "enc", when true, means that we are encoding (false means decoding) andre@0: */ andre@0: typedef const SEC_ASN1Template * SEC_ASN1TemplateChooser(void *arg, PRBool enc); andre@0: typedef SEC_ASN1TemplateChooser * SEC_ASN1TemplateChooserPtr; andre@0: andre@0: #if defined(_WIN32) || defined(ANDROID) andre@0: #define SEC_ASN1_GET(x) NSS_Get_##x(NULL, PR_FALSE) andre@0: #define SEC_ASN1_SUB(x) &p_NSS_Get_##x andre@0: #define SEC_ASN1_XTRN SEC_ASN1_DYNAMIC andre@0: #define SEC_ASN1_MKSUB(x) \ andre@0: static const SEC_ASN1TemplateChooserPtr p_NSS_Get_##x = &NSS_Get_##x; andre@0: #else andre@0: #define SEC_ASN1_GET(x) x andre@0: #define SEC_ASN1_SUB(x) x andre@0: #define SEC_ASN1_XTRN 0 andre@0: #define SEC_ASN1_MKSUB(x) andre@0: #endif andre@0: andre@0: #define SEC_ASN1_CHOOSER_DECLARE(x) \ andre@0: extern const SEC_ASN1Template * NSS_Get_##x (void *arg, PRBool enc); andre@0: andre@0: #define SEC_ASN1_CHOOSER_IMPLEMENT(x) \ andre@0: const SEC_ASN1Template * NSS_Get_##x(void * arg, PRBool enc) \ andre@0: { return x; } andre@0: andre@0: /* andre@0: ** Opaque object used by the decoder to store state. andre@0: */ andre@0: typedef struct sec_DecoderContext_struct SEC_ASN1DecoderContext; andre@0: andre@0: /* andre@0: ** Opaque object used by the encoder to store state. andre@0: */ andre@0: typedef struct sec_EncoderContext_struct SEC_ASN1EncoderContext; andre@0: andre@0: /* andre@0: * This is used to describe to a filter function the bytes that are andre@0: * being passed to it. This is only useful when the filter is an "outer" andre@0: * one, meaning it expects to get *all* of the bytes not just the andre@0: * contents octets. andre@0: */ andre@0: typedef enum { andre@0: SEC_ASN1_Identifier = 0, andre@0: SEC_ASN1_Length = 1, andre@0: SEC_ASN1_Contents = 2, andre@0: SEC_ASN1_EndOfContents = 3 andre@0: } SEC_ASN1EncodingPart; andre@0: andre@0: /* andre@0: * Type of the function pointer used either for decoding or encoding, andre@0: * when doing anything "funny" (e.g. manipulating the data stream) andre@0: */ andre@0: typedef void (* SEC_ASN1NotifyProc)(void *arg, PRBool before, andre@0: void *dest, int real_depth); andre@0: andre@0: /* andre@0: * Type of the function pointer used for grabbing encoded bytes. andre@0: * This can be used during either encoding or decoding, as follows... andre@0: * andre@0: * When decoding, this can be used to filter the encoded bytes as they andre@0: * are parsed. This is what you would do if you wanted to process the data andre@0: * along the way (like to decrypt it, or to perform a hash on it in order andre@0: * to do a signature check later). See SEC_ASN1DecoderSetFilterProc(). andre@0: * When processing only part of the encoded bytes is desired, you "watch" andre@0: * for the field(s) you are interested in with a "notify proc" (see andre@0: * SEC_ASN1DecoderSetNotifyProc()) and for even finer granularity (e.g. to andre@0: * ignore all by the contents bytes) you pay attention to the "data_kind" andre@0: * parameter. andre@0: * andre@0: * When encoding, this is the specification for the output function which andre@0: * will receive the bytes as they are encoded. The output function can andre@0: * perform any postprocessing necessary (like hashing (some of) the data andre@0: * to create a digest that gets included at the end) as well as shoving andre@0: * the data off wherever it needs to go. (In order to "tune" any processing, andre@0: * you can set a "notify proc" as described above in the decoding case.) andre@0: * andre@0: * The parameters: andre@0: * - "arg" is an opaque pointer that you provided at the same time you andre@0: * specified a function of this type andre@0: * - "data" is a buffer of length "len", containing the encoded bytes andre@0: * - "depth" is how deep in a nested encoding we are (it is not usually andre@0: * valuable, but can be useful sometimes so I included it) andre@0: * - "data_kind" tells you if these bytes are part of the ASN.1 encoded andre@0: * octets for identifier, length, contents, or end-of-contents andre@0: */ andre@0: typedef void (* SEC_ASN1WriteProc)(void *arg, andre@0: const char *data, unsigned long len, andre@0: int depth, SEC_ASN1EncodingPart data_kind); andre@0: andre@0: #endif /* _SECASN1T_H_ */