Back to index

lightning-sunbird  0.9+nobinonly
secasn1t.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 /*
00038  * Types for encoding/decoding of ASN.1 using BER/DER (Basic/Distinguished
00039  * Encoding Rules).
00040  *
00041  * $Id: secasn1t.h,v 1.9 2004/04/25 15:03:18 gerv%gerv.net Exp $
00042  */
00043 
00044 #ifndef _SECASN1T_H_
00045 #define _SECASN1T_H_
00046 
00047 /*
00048 ** An array of these structures defines a BER/DER encoding for an object.
00049 **
00050 ** The array usually starts with a dummy entry whose kind is SEC_ASN1_SEQUENCE;
00051 ** such an array is terminated with an entry where kind == 0.  (An array
00052 ** which consists of a single component does not require a second dummy
00053 ** entry -- the array is only searched as long as previous component(s)
00054 ** instruct it.)
00055 */
00056 typedef struct sec_ASN1Template_struct {
00057     /*
00058     ** Kind of item being decoded/encoded, including tags and modifiers.
00059     */
00060     unsigned long kind;
00061 
00062     /*
00063     ** The value is the offset from the base of the structure to the
00064     ** field that holds the value being decoded/encoded.
00065     */
00066     unsigned long offset;
00067 
00068     /*
00069     ** When kind suggests it (SEC_ASN1_POINTER, SEC_ASN1_GROUP, SEC_ASN1_INLINE,
00070     ** or a component that is *not* a SEC_ASN1_UNIVERSAL), this points to
00071     ** a sub-template for nested encoding/decoding,
00072     ** OR, iff SEC_ASN1_DYNAMIC is set, then this is a pointer to a pointer
00073     ** to a function which will return the appropriate template when called
00074     ** at runtime.  NOTE! that explicit level of indirection, which is
00075     ** necessary because ANSI does not allow you to store a function
00076     ** pointer directly as a "void *" so we must store it separately and
00077     ** dereference it to get at the function pointer itself.
00078     */
00079     const void *sub;
00080 
00081     /*
00082     ** In the first element of a template array, the value is the size
00083     ** of the structure to allocate when this template is being referenced
00084     ** by another template via SEC_ASN1_POINTER or SEC_ASN1_GROUP.
00085     ** In all other cases, the value is ignored.
00086     */
00087     unsigned int size;
00088 } SEC_ASN1Template;
00089 
00090 
00091 /* default size used for allocation of encoding/decoding stuff */
00092 /* XXX what is the best value here? */
00093 #define SEC_ASN1_DEFAULT_ARENA_SIZE       (2048)
00094 
00095 /*
00096 ** BER/DER values for ASN.1 identifier octets.
00097 */
00098 #define SEC_ASN1_TAG_MASK          0xff
00099 
00100 /*
00101  * BER/DER universal type tag numbers.
00102  * The values are defined by the X.208 standard; do not change them!
00103  * NOTE: if you add anything to this list, you must add code to secasn1d.c
00104  * to accept the tag, and probably also to secasn1e.c to encode it.
00105  * XXX It appears some have been added recently without being added to
00106  * the code; so need to go through the list now and double-check them all.
00107  * (Look especially at those added in revision 1.10.)
00108  */
00109 #define SEC_ASN1_TAGNUM_MASK              0x1f
00110 #define SEC_ASN1_BOOLEAN           0x01
00111 #define SEC_ASN1_INTEGER           0x02
00112 #define SEC_ASN1_BIT_STRING        0x03
00113 #define SEC_ASN1_OCTET_STRING             0x04
00114 #define SEC_ASN1_NULL                     0x05
00115 #define SEC_ASN1_OBJECT_ID         0x06
00116 #define SEC_ASN1_OBJECT_DESCRIPTOR      0x07
00117 /* External type and instance-of type   0x08 */
00118 #define SEC_ASN1_REAL                   0x09
00119 #define SEC_ASN1_ENUMERATED        0x0a
00120 #define SEC_ASN1_EMBEDDED_PDV           0x0b
00121 #define SEC_ASN1_UTF8_STRING              0x0c
00122 /*                                      0x0d */
00123 /*                                      0x0e */
00124 /*                                      0x0f */
00125 #define SEC_ASN1_SEQUENCE          0x10
00126 #define SEC_ASN1_SET               0x11
00127 #define SEC_ASN1_NUMERIC_STRING         0x12
00128 #define SEC_ASN1_PRINTABLE_STRING  0x13
00129 #define SEC_ASN1_T61_STRING        0x14
00130 #define SEC_ASN1_VIDEOTEX_STRING        0x15
00131 #define SEC_ASN1_IA5_STRING        0x16
00132 #define SEC_ASN1_UTC_TIME          0x17
00133 #define SEC_ASN1_GENERALIZED_TIME  0x18
00134 #define SEC_ASN1_GRAPHIC_STRING         0x19
00135 #define SEC_ASN1_VISIBLE_STRING           0x1a
00136 #define SEC_ASN1_GENERAL_STRING         0x1b
00137 #define SEC_ASN1_UNIVERSAL_STRING  0x1c
00138 /*                                      0x1d */
00139 #define SEC_ASN1_BMP_STRING        0x1e
00140 #define SEC_ASN1_HIGH_TAG_NUMBER   0x1f
00141 #define SEC_ASN1_TELETEX_STRING    SEC_ASN1_T61_STRING
00142 
00143 /*
00144 ** Modifiers to type tags.  These are also specified by a/the
00145 ** standard, and must not be changed.
00146 */
00147 
00148 #define SEC_ASN1_METHOD_MASK              0x20
00149 #define SEC_ASN1_PRIMITIVE         0x00
00150 #define SEC_ASN1_CONSTRUCTED              0x20
00151 
00152 #define SEC_ASN1_CLASS_MASK        0xc0
00153 #define SEC_ASN1_UNIVERSAL         0x00
00154 #define SEC_ASN1_APPLICATION              0x40
00155 #define SEC_ASN1_CONTEXT_SPECIFIC  0x80
00156 #define SEC_ASN1_PRIVATE           0xc0
00157 
00158 /*
00159 ** Our additions, used for templates.
00160 ** These are not defined by any standard; the values are used internally only.
00161 ** Just be careful to keep them out of the low 8 bits.
00162 ** XXX finish comments
00163 */
00164 #define SEC_ASN1_OPTIONAL   0x00100
00165 #define SEC_ASN1_EXPLICIT   0x00200
00166 #define SEC_ASN1_ANY        0x00400
00167 #define SEC_ASN1_INLINE            0x00800
00168 #define SEC_ASN1_POINTER    0x01000
00169 #define SEC_ASN1_GROUP             0x02000       /* with SET or SEQUENCE means
00170                                     * SET OF or SEQUENCE OF */
00171 #define SEC_ASN1_DYNAMIC    0x04000 /* subtemplate is found by calling
00172                                     * a function at runtime */
00173 #define SEC_ASN1_SKIP              0x08000 /* skip a field; only for decoding */
00174 #define SEC_ASN1_INNER             0x10000       /* with ANY means capture the
00175                                     * contents only (not the id, len,
00176                                     * or eoc); only for decoding */
00177 #define SEC_ASN1_SAVE              0x20000 /* stash away the encoded bytes first;
00178                                     * only for decoding */
00179 #define SEC_ASN1_MAY_STREAM 0x40000       /* field or one of its sub-fields may
00180                                     * stream in and so should encode as
00181                                     * indefinite-length when streaming
00182                                     * has been indicated; only for
00183                                     * encoding */
00184 #define SEC_ASN1_SKIP_REST  0x80000       /* skip all following fields;
00185                                       only for decoding */
00186 #define SEC_ASN1_CHOICE        0x100000 /* pick one from a template */
00187 #define SEC_ASN1_NO_STREAM     0X200000 /* This entry will not stream
00188                                            even if the sub-template says
00189                                            streaming is possible.  Helps
00190                                            to solve ambiguities with potential
00191                                            streaming entries that are 
00192                                            optional */
00193 #define SEC_ASN1_DEBUG_BREAK   0X400000 /* put this in your template and the
00194                                            decoder will assert when it
00195                                            processes it. Only for use with
00196                                            SEC_QuickDERDecodeItem */
00197 
00198                                           
00199 
00200 /* Shorthand/Aliases */
00201 #define SEC_ASN1_SEQUENCE_OF       (SEC_ASN1_GROUP | SEC_ASN1_SEQUENCE)
00202 #define SEC_ASN1_SET_OF            (SEC_ASN1_GROUP | SEC_ASN1_SET)
00203 #define SEC_ASN1_ANY_CONTENTS      (SEC_ASN1_ANY | SEC_ASN1_INNER)
00204 
00205 /* Maximum depth of nested SEQUENCEs and SETs */
00206 #define SEC_ASN1D_MAX_DEPTH 32
00207 
00208 /*
00209 ** Function used for SEC_ASN1_DYNAMIC.
00210 ** "arg" is a pointer to the structure being encoded/decoded
00211 ** "enc", when true, means that we are encoding (false means decoding)
00212 */
00213 typedef const SEC_ASN1Template * SEC_ASN1TemplateChooser(void *arg, PRBool enc);
00214 typedef SEC_ASN1TemplateChooser * SEC_ASN1TemplateChooserPtr;
00215 
00216 #if defined(_WIN32)
00217 #define SEC_ASN1_GET(x)        NSS_Get_##x(NULL, PR_FALSE)
00218 #define SEC_ASN1_SUB(x)        &p_NSS_Get_##x
00219 #define SEC_ASN1_XTRN          SEC_ASN1_DYNAMIC
00220 #define SEC_ASN1_MKSUB(x) \
00221 static const SEC_ASN1TemplateChooserPtr p_NSS_Get_##x = &NSS_Get_##x;
00222 #else
00223 #define SEC_ASN1_GET(x)        x
00224 #define SEC_ASN1_SUB(x)        x
00225 #define SEC_ASN1_XTRN          0
00226 #define SEC_ASN1_MKSUB(x) 
00227 #endif
00228 
00229 #define SEC_ASN1_CHOOSER_DECLARE(x) \
00230 extern const SEC_ASN1Template * NSS_Get_##x (void *arg, PRBool enc);
00231 
00232 #define SEC_ASN1_CHOOSER_IMPLEMENT(x) \
00233 const SEC_ASN1Template * NSS_Get_##x(void * arg, PRBool enc) \
00234 { return x; }
00235 
00236 /*
00237 ** Opaque object used by the decoder to store state.
00238 */
00239 typedef struct sec_DecoderContext_struct SEC_ASN1DecoderContext;
00240 
00241 /*
00242 ** Opaque object used by the encoder to store state.
00243 */
00244 typedef struct sec_EncoderContext_struct SEC_ASN1EncoderContext;
00245 
00246 /*
00247  * This is used to describe to a filter function the bytes that are
00248  * being passed to it.  This is only useful when the filter is an "outer"
00249  * one, meaning it expects to get *all* of the bytes not just the
00250  * contents octets.
00251  */
00252 typedef enum {
00253     SEC_ASN1_Identifier = 0,
00254     SEC_ASN1_Length = 1,
00255     SEC_ASN1_Contents = 2,
00256     SEC_ASN1_EndOfContents = 3
00257 } SEC_ASN1EncodingPart;
00258 
00259 /*
00260  * Type of the function pointer used either for decoding or encoding,
00261  * when doing anything "funny" (e.g. manipulating the data stream)
00262  */ 
00263 typedef void (* SEC_ASN1NotifyProc)(void *arg, PRBool before,
00264                                 void *dest, int real_depth);
00265 
00266 /*
00267  * Type of the function pointer used for grabbing encoded bytes.
00268  * This can be used during either encoding or decoding, as follows...
00269  *
00270  * When decoding, this can be used to filter the encoded bytes as they
00271  * are parsed.  This is what you would do if you wanted to process the data
00272  * along the way (like to decrypt it, or to perform a hash on it in order
00273  * to do a signature check later).  See SEC_ASN1DecoderSetFilterProc().
00274  * When processing only part of the encoded bytes is desired, you "watch"
00275  * for the field(s) you are interested in with a "notify proc" (see
00276  * SEC_ASN1DecoderSetNotifyProc()) and for even finer granularity (e.g. to
00277  * ignore all by the contents bytes) you pay attention to the "data_kind"
00278  * parameter.
00279  *
00280  * When encoding, this is the specification for the output function which
00281  * will receive the bytes as they are encoded.  The output function can
00282  * perform any postprocessing necessary (like hashing (some of) the data
00283  * to create a digest that gets included at the end) as well as shoving
00284  * the data off wherever it needs to go.  (In order to "tune" any processing,
00285  * you can set a "notify proc" as described above in the decoding case.)
00286  *
00287  * The parameters:
00288  * - "arg" is an opaque pointer that you provided at the same time you
00289  *   specified a function of this type
00290  * - "data" is a buffer of length "len", containing the encoded bytes
00291  * - "depth" is how deep in a nested encoding we are (it is not usually
00292  *   valuable, but can be useful sometimes so I included it)
00293  * - "data_kind" tells you if these bytes are part of the ASN.1 encoded
00294  *   octets for identifier, length, contents, or end-of-contents
00295  */ 
00296 typedef void (* SEC_ASN1WriteProc)(void *arg,
00297                                const char *data, unsigned long len,
00298                                int depth, SEC_ASN1EncodingPart data_kind);
00299 
00300 #endif /* _SECASN1T_H_ */