PageRenderTime 84ms CodeModel.GetById 41ms app.highlight 6ms RepoModel.GetById 34ms app.codeStats 0ms

/gecko_api/include/secasn1t.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 302 lines | 99 code | 29 blank | 174 comment | 0 complexity | 0c0bb61a21fd6a2777ebe50308b5615b MD5 | raw file
  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*/
 58typedef 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*/
215typedef const SEC_ASN1Template * SEC_ASN1TemplateChooser(void *arg, PRBool enc);
216typedef 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) \
223static 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) \
232extern const SEC_ASN1Template * NSS_Get_##x (void *arg, PRBool enc);
233
234#define SEC_ASN1_CHOOSER_IMPLEMENT(x) \
235const 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*/
241typedef struct sec_DecoderContext_struct SEC_ASN1DecoderContext;
242
243/*
244** Opaque object used by the encoder to store state.
245*/
246typedef 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 */
254typedef 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 */ 
265typedef 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 */ 
298typedef void (* SEC_ASN1WriteProc)(void *arg,
299				   const char *data, unsigned long len,
300				   int depth, SEC_ASN1EncodingPart data_kind);
301
302#endif /* _SECASN1T_H_ */