security/nss/lib/util/secasn1t.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is the Netscape security libraries.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Netscape Communications Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *
  23  * Alternatively, the contents of this file may be used under the terms of
  24  * either the GNU General Public License Version 2 or later (the "GPL"), or
  25  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26  * in which case the provisions of the GPL or the LGPL are applicable instead
  27  * of those above. If you wish to allow use of your version of this file only
  28  * under the terms of either the GPL or the LGPL, and not to allow others to
  29  * use your version of this file under the terms of the MPL, indicate your
  30  * decision by deleting the provisions above and replace them with the notice
  31  * and other provisions required by the GPL or the LGPL. If you do not delete
  32  * the provisions above, a recipient may use your version of this file under
  33  * the terms of any one of the MPL, the GPL or the LGPL.
  34  *
  35  * ***** END LICENSE BLOCK ***** */
  36
  37 /*
  38  * Types for encoding/decoding of ASN.1 using BER/DER (Basic/Distinguished
  39  * Encoding Rules).
  40  *
  41  * $Id: secasn1t.h,v 1.10 2007/10/12 01:44:51 julien.pierre.boogz%sun.com Exp $
  42  */
  43
  44 #ifndef _SECASN1T_H_
  45 #define _SECASN1T_H_
  46
  47 #include "utilrename.h"
  48
  49 /*
  50 ** An array of these structures defines a BER/DER encoding for an object.
  51 **
  52 ** The array usually starts with a dummy entry whose kind is SEC_ASN1_SEQUENCE;
  53 ** such an array is terminated with an entry where kind == 0.  (An array
  54 ** which consists of a single component does not require a second dummy
  55 ** entry -- the array is only searched as long as previous component(s)
  56 ** instruct it.)
  57 */
  58 typedef struct sec_ASN1Template_struct {
  59     /*
  60     ** Kind of item being decoded/encoded, including tags and modifiers.
  61     */
  62     unsigned long kind;
  63
  64     /*
  65     ** The value is the offset from the base of the structure to the
  66     ** field that holds the value being decoded/encoded.
  67     */
  68     unsigned long offset;
  69
  70     /*
  71     ** When kind suggests it (SEC_ASN1_POINTER, SEC_ASN1_GROUP, SEC_ASN1_INLINE,
  72     ** or a component that is *not* a SEC_ASN1_UNIVERSAL), this points to
  73     ** a sub-template for nested encoding/decoding,
  74     ** OR, iff SEC_ASN1_DYNAMIC is set, then this is a pointer to a pointer
  75     ** to a function which will return the appropriate template when called
  76     ** at runtime.  NOTE! that explicit level of indirection, which is
  77     ** necessary because ANSI does not allow you to store a function
  78     ** pointer directly as a "void *" so we must store it separately and
  79     ** dereference it to get at the function pointer itself.
  80     */
  81     const void *sub;
  82
  83     /*
  84     ** In the first element of a template array, the value is the size
  85     ** of the structure to allocate when this template is being referenced
  86     ** by another template via SEC_ASN1_POINTER or SEC_ASN1_GROUP.
  87     ** In all other cases, the value is ignored.
  88     */
  89     unsigned int size;
  90 } SEC_ASN1Template;
  91
  92
  93 /* default size used for allocation of encoding/decoding stuff */
  94 /* XXX what is the best value here? */
  95 #define SEC_ASN1_DEFAULT_ARENA_SIZE     (2048)
  96
  97 /*
  98 ** BER/DER values for ASN.1 identifier octets.
  99 */
 100 #define SEC_ASN1_TAG_MASK               0xff
 101
 102 /*
 103  * BER/DER universal type tag numbers.
 104  * The values are defined by the X.208 standard; do not change them!
 105  * NOTE: if you add anything to this list, you must add code to secasn1d.c
 106  * to accept the tag, and probably also to secasn1e.c to encode it.
 107  * XXX It appears some have been added recently without being added to
 108  * the code; so need to go through the list now and double-check them all.
 109  * (Look especially at those added in revision 1.10.)
 110  */
 111 #define SEC_ASN1_TAGNUM_MASK            0x1f
 112 #define SEC_ASN1_BOOLEAN                0x01
 113 #define SEC_ASN1_INTEGER                0x02
 114 #define SEC_ASN1_BIT_STRING             0x03
 115 #define SEC_ASN1_OCTET_STRING           0x04
 116 #define SEC_ASN1_NULL                   0x05
 117 #define SEC_ASN1_OBJECT_ID              0x06
 118 #define SEC_ASN1_OBJECT_DESCRIPTOR      0x07
 119 /* External type and instance-of type   0x08 */
 120 #define SEC_ASN1_REAL                   0x09
 121 #define SEC_ASN1_ENUMERATED             0x0a
 122 #define SEC_ASN1_EMBEDDED_PDV           0x0b
 123 #define SEC_ASN1_UTF8_STRING            0x0c
 124 /*                                      0x0d */
 125 /*                                      0x0e */
 126 /*                                      0x0f */
 127 #define SEC_ASN1_SEQUENCE               0x10
 128 #define SEC_ASN1_SET                    0x11
 129 #define SEC_ASN1_NUMERIC_STRING         0x12
 130 #define SEC_ASN1_PRINTABLE_STRING       0x13
 131 #define SEC_ASN1_T61_STRING             0x14
 132 #define SEC_ASN1_VIDEOTEX_STRING        0x15
 133 #define SEC_ASN1_IA5_STRING             0x16
 134 #define SEC_ASN1_UTC_TIME               0x17
 135 #define SEC_ASN1_GENERALIZED_TIME       0x18
 136 #define SEC_ASN1_GRAPHIC_STRING         0x19
 137 #define SEC_ASN1_VISIBLE_STRING         0x1a
 138 #define SEC_ASN1_GENERAL_STRING         0x1b
 139 #define SEC_ASN1_UNIVERSAL_STRING       0x1c
 140 /*                                      0x1d */
 141 #define SEC_ASN1_BMP_STRING             0x1e
 142 #define SEC_ASN1_HIGH_TAG_NUMBER        0x1f
 143 #define SEC_ASN1_TELETEX_STRING         SEC_ASN1_T61_STRING
 144
 145 /*
 146 ** Modifiers to type tags.  These are also specified by a/the
 147 ** standard, and must not be changed.
 148 */
 149
 150 #define SEC_ASN1_METHOD_MASK            0x20
 151 #define SEC_ASN1_PRIMITIVE              0x00
 152 #define SEC_ASN1_CONSTRUCTED            0x20
 153
 154 #define SEC_ASN1_CLASS_MASK             0xc0
 155 #define SEC_ASN1_UNIVERSAL              0x00
 156 #define SEC_ASN1_APPLICATION            0x40
 157 #define SEC_ASN1_CONTEXT_SPECIFIC       0x80
 158 #define SEC_ASN1_PRIVATE                0xc0
 159
 160 /*
 161 ** Our additions, used for templates.
 162 ** These are not defined by any standard; the values are used internally only.
 163 ** Just be careful to keep them out of the low 8 bits.
 164 ** XXX finish comments
 165 */
 166 #define SEC_ASN1_OPTIONAL       0x00100
 167 #define SEC_ASN1_EXPLICIT       0x00200
 168 #define SEC_ASN1_ANY            0x00400
 169 #define SEC_ASN1_INLINE         0x00800
 170 #define SEC_ASN1_POINTER        0x01000
 171 #define SEC_ASN1_GROUP          0x02000 /* with SET or SEQUENCE means
 172                                          * SET OF or SEQUENCE OF */
 173 #define SEC_ASN1_DYNAMIC        0x04000 /* subtemplate is found by calling
 174                                          * a function at runtime */
 175 #define SEC_ASN1_SKIP           0x08000 /* skip a field; only for decoding */
 176 #define SEC_ASN1_INNER          0x10000 /* with ANY means capture the
 177                                          * contents only (not the id, len,
 178                                          * or eoc); only for decoding */
 179 #define SEC_ASN1_SAVE           0x20000 /* stash away the encoded bytes first;
 180                                          * only for decoding */
 181 #define SEC_ASN1_MAY_STREAM     0x40000 /* field or one of its sub-fields may
 182                                          * stream in and so should encode as
 183                                          * indefinite-length when streaming
 184                                          * has been indicated; only for
 185                                          * encoding */
 186 #define SEC_ASN1_SKIP_REST      0x80000 /* skip all following fields;
 187                                            only for decoding */
 188 #define SEC_ASN1_CHOICE        0x100000 /* pick one from a template */
 189 #define SEC_ASN1_NO_STREAM     0X200000 /* This entry will not stream
 190                                            even if the sub-template says
 191                                            streaming is possible.  Helps
 192                                            to solve ambiguities with potential
 193                                            streaming entries that are
 194                                            optional */
 195 #define SEC_ASN1_DEBUG_BREAK   0X400000 /* put this in your template and the
 196                                            decoder will assert when it
 197                                            processes it. Only for use with
 198                                            SEC_QuickDERDecodeItem */
 199
 200
 201
 202 /* Shorthand/Aliases */
 203 #define SEC_ASN1_SEQUENCE_OF    (SEC_ASN1_GROUP | SEC_ASN1_SEQUENCE)
 204 #define SEC_ASN1_SET_OF         (SEC_ASN1_GROUP | SEC_ASN1_SET)
 205 #define SEC_ASN1_ANY_CONTENTS   (SEC_ASN1_ANY | SEC_ASN1_INNER)
 206
 207 /* Maximum depth of nested SEQUENCEs and SETs */
 208 #define SEC_ASN1D_MAX_DEPTH 32
 209
 210 /*
 211 ** Function used for SEC_ASN1_DYNAMIC.
 212 ** "arg" is a pointer to the structure being encoded/decoded
 213 ** "enc", when true, means that we are encoding (false means decoding)
 214 */
 215 typedef const SEC_ASN1Template * SEC_ASN1TemplateChooser(void *arg, PRBool enc);
 216 typedef SEC_ASN1TemplateChooser * SEC_ASN1TemplateChooserPtr;
 217
 218 #if defined(_WIN32)
 219 #define SEC_ASN1_GET(x)        NSS_Get_##x(NULL, PR_FALSE)
 220 #define SEC_ASN1_SUB(x)        &p_NSS_Get_##x
 221 #define SEC_ASN1_XTRN          SEC_ASN1_DYNAMIC
 222 #define SEC_ASN1_MKSUB(x) \
 223 static const SEC_ASN1TemplateChooserPtr p_NSS_Get_##x = &NSS_Get_##x;
 224 #else
 225 #define SEC_ASN1_GET(x)        x
 226 #define SEC_ASN1_SUB(x)        x
 227 #define SEC_ASN1_XTRN          0
 228 #define SEC_ASN1_MKSUB(x)
 229 #endif
 230
 231 #define SEC_ASN1_CHOOSER_DECLARE(x) \
 232 extern const SEC_ASN1Template * NSS_Get_##x (void *arg, PRBool enc);
 233
 234 #define SEC_ASN1_CHOOSER_IMPLEMENT(x) \
 235 const SEC_ASN1Template * NSS_Get_##x(void * arg, PRBool enc) \
 236 { return x; }
 237
 238 /*
 239 ** Opaque object used by the decoder to store state.
 240 */
 241 typedef struct sec_DecoderContext_struct SEC_ASN1DecoderContext;
 242
 243 /*
 244 ** Opaque object used by the encoder to store state.
 245 */
 246 typedef struct sec_EncoderContext_struct SEC_ASN1EncoderContext;
 247
 248 /*
 249  * This is used to describe to a filter function the bytes that are
 250  * being passed to it.  This is only useful when the filter is an "outer"
 251  * one, meaning it expects to get *all* of the bytes not just the
 252  * contents octets.
 253  */
 254 typedef enum {
 255     SEC_ASN1_Identifier = 0,
 256     SEC_ASN1_Length = 1,
 257     SEC_ASN1_Contents = 2,
 258     SEC_ASN1_EndOfContents = 3
 259 } SEC_ASN1EncodingPart;
 260
 261 /*
 262  * Type of the function pointer used either for decoding or encoding,
 263  * when doing anything "funny" (e.g. manipulating the data stream)
 264  */
 265 typedef void (* SEC_ASN1NotifyProc)(void *arg, PRBool before,
 266                                     void *dest, int real_depth);
 267
 268 /*
 269  * Type of the function pointer used for grabbing encoded bytes.
 270  * This can be used during either encoding or decoding, as follows...
 271  *
 272  * When decoding, this can be used to filter the encoded bytes as they
 273  * are parsed.  This is what you would do if you wanted to process the data
 274  * along the way (like to decrypt it, or to perform a hash on it in order
 275  * to do a signature check later).  See SEC_ASN1DecoderSetFilterProc().
 276  * When processing only part of the encoded bytes is desired, you "watch"
 277  * for the field(s) you are interested in with a "notify proc" (see
 278  * SEC_ASN1DecoderSetNotifyProc()) and for even finer granularity (e.g. to
 279  * ignore all by the contents bytes) you pay attention to the "data_kind"
 280  * parameter.
 281  *
 282  * When encoding, this is the specification for the output function which
 283  * will receive the bytes as they are encoded.  The output function can
 284  * perform any postprocessing necessary (like hashing (some of) the data
 285  * to create a digest that gets included at the end) as well as shoving
 286  * the data off wherever it needs to go.  (In order to "tune" any processing,
 287  * you can set a "notify proc" as described above in the decoding case.)
 288  *
 289  * The parameters:
 290  * - "arg" is an opaque pointer that you provided at the same time you
 291  *   specified a function of this type
 292  * - "data" is a buffer of length "len", containing the encoded bytes
 293  * - "depth" is how deep in a nested encoding we are (it is not usually
 294  *   valuable, but can be useful sometimes so I included it)
 295  * - "data_kind" tells you if these bytes are part of the ASN.1 encoded
 296  *   octets for identifier, length, contents, or end-of-contents
 297  */
 298 typedef void (* SEC_ASN1WriteProc)(void *arg,
 299                                    const char *data, unsigned long len,
 300                                    int depth, SEC_ASN1EncodingPart data_kind);
 301
 302 #endif /* _SECASN1T_H_ */