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