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