/gecko_api/include/secasn1.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 * Support for encoding/decoding of ASN.1 using BER/DER (Basic/Distinguished
 39 * Encoding Rules).  The routines are found in and used extensively by the
 40 * security library, but exported for other use.
 41 *
 42 * $Id: secasn1.h,v 1.15 2007/10/12 01:44:51 julien.pierre.boogz%sun.com Exp $
 43 */
 44
 45#ifndef _SECASN1_H_
 46#define _SECASN1_H_
 47
 48#include "utilrename.h"
 49#include "plarena.h"
 50
 51#include "seccomon.h"
 52#include "secasn1t.h"
 53
 54
 55/************************************************************************/
 56SEC_BEGIN_PROTOS
 57
 58/*
 59 * XXX These function prototypes need full, explanatory comments.
 60 */
 61
 62/*
 63** Decoding.
 64*/
 65
 66extern SEC_ASN1DecoderContext *SEC_ASN1DecoderStart(PRArenaPool *pool,
 67						    void *dest,
 68						    const SEC_ASN1Template *t);
 69
 70/* XXX char or unsigned char? */
 71extern SECStatus SEC_ASN1DecoderUpdate(SEC_ASN1DecoderContext *cx,
 72				       const char *buf,
 73				       unsigned long len);
 74
 75extern SECStatus SEC_ASN1DecoderFinish(SEC_ASN1DecoderContext *cx);
 76
 77/* Higher level code detected an error, abort the rest of the processing */
 78extern void SEC_ASN1DecoderAbort(SEC_ASN1DecoderContext *cx, int error);
 79
 80extern void SEC_ASN1DecoderSetFilterProc(SEC_ASN1DecoderContext *cx,
 81					 SEC_ASN1WriteProc fn,
 82					 void *arg, PRBool no_store);
 83
 84extern void SEC_ASN1DecoderClearFilterProc(SEC_ASN1DecoderContext *cx);
 85
 86extern void SEC_ASN1DecoderSetNotifyProc(SEC_ASN1DecoderContext *cx,
 87					 SEC_ASN1NotifyProc fn,
 88					 void *arg);
 89
 90extern void SEC_ASN1DecoderClearNotifyProc(SEC_ASN1DecoderContext *cx);
 91
 92extern SECStatus SEC_ASN1Decode(PRArenaPool *pool, void *dest,
 93				const SEC_ASN1Template *t,
 94				const char *buf, long len);
 95
 96/* Both classic ASN.1 and QuickDER have a feature that removes leading zeroes
 97   out of SEC_ASN1_INTEGER if the caller sets siUnsignedInteger in the type
 98   field of the target SECItem prior to calling the decoder. Otherwise, the
 99   type field is ignored and untouched. For SECItem that are dynamically
100   allocated (from POINTER, SET OF, SEQUENCE OF) the decoder sets the type
101   field to siBuffer. */
102
103extern SECStatus SEC_ASN1DecodeItem(PRArenaPool *pool, void *dest,
104				    const SEC_ASN1Template *t,
105				    const SECItem *src);
106
107extern SECStatus SEC_QuickDERDecodeItem(PRArenaPool* arena, void* dest,
108                     const SEC_ASN1Template* templateEntry,
109                     const SECItem* src);
110
111/*
112** Encoding.
113*/
114
115extern SEC_ASN1EncoderContext *SEC_ASN1EncoderStart(const void *src,
116						    const SEC_ASN1Template *t,
117						    SEC_ASN1WriteProc fn,
118						    void *output_arg);
119
120/* XXX char or unsigned char? */
121extern SECStatus SEC_ASN1EncoderUpdate(SEC_ASN1EncoderContext *cx,
122				       const char *buf,
123				       unsigned long len);
124
125extern void SEC_ASN1EncoderFinish(SEC_ASN1EncoderContext *cx);
126
127/* Higher level code detected an error, abort the rest of the processing */
128extern void SEC_ASN1EncoderAbort(SEC_ASN1EncoderContext *cx, int error);
129
130extern void SEC_ASN1EncoderSetNotifyProc(SEC_ASN1EncoderContext *cx,
131					 SEC_ASN1NotifyProc fn,
132					 void *arg);
133
134extern void SEC_ASN1EncoderClearNotifyProc(SEC_ASN1EncoderContext *cx);
135
136extern void SEC_ASN1EncoderSetStreaming(SEC_ASN1EncoderContext *cx);
137
138extern void SEC_ASN1EncoderClearStreaming(SEC_ASN1EncoderContext *cx);
139
140extern void sec_ASN1EncoderSetDER(SEC_ASN1EncoderContext *cx);
141
142extern void sec_ASN1EncoderClearDER(SEC_ASN1EncoderContext *cx);
143
144extern void SEC_ASN1EncoderSetTakeFromBuf(SEC_ASN1EncoderContext *cx);
145
146extern void SEC_ASN1EncoderClearTakeFromBuf(SEC_ASN1EncoderContext *cx);
147
148extern SECStatus SEC_ASN1Encode(const void *src, const SEC_ASN1Template *t,
149				SEC_ASN1WriteProc output_proc,
150				void *output_arg);
151
152extern SECItem * SEC_ASN1EncodeItem(PRArenaPool *pool, SECItem *dest,
153				    const void *src, const SEC_ASN1Template *t);
154
155extern SECItem * SEC_ASN1EncodeInteger(PRArenaPool *pool,
156				       SECItem *dest, long value);
157
158extern SECItem * SEC_ASN1EncodeUnsignedInteger(PRArenaPool *pool,
159					       SECItem *dest,
160					       unsigned long value);
161
162extern SECStatus SEC_ASN1DecodeInteger(SECItem *src,
163				       unsigned long *value);
164
165/*
166** Utilities.
167*/
168
169/*
170 * We have a length that needs to be encoded; how many bytes will the
171 * encoding take?
172 */
173extern int SEC_ASN1LengthLength (unsigned long len);
174
175/* encode the length and return the number of bytes we encoded. Buffer
176 * must be pre allocated  */
177extern int SEC_ASN1EncodeLength(unsigned char *buf,int value);
178
179/*
180 * Find the appropriate subtemplate for the given template.
181 * This may involve calling a "chooser" function, or it may just
182 * be right there.  In either case, it is expected to *have* a
183 * subtemplate; this is asserted in debug builds (in non-debug
184 * builds, NULL will be returned).
185 *
186 * "thing" is a pointer to the structure being encoded/decoded
187 * "encoding", when true, means that we are in the process of encoding
188 *	(as opposed to in the process of decoding)
189 */
190extern const SEC_ASN1Template *
191SEC_ASN1GetSubtemplate (const SEC_ASN1Template *inTemplate, void *thing,
192			PRBool encoding);
193
194/* whether the template is for a primitive type or a choice of
195 * primitive types
196 */
197extern PRBool SEC_ASN1IsTemplateSimple(const SEC_ASN1Template *theTemplate);
198
199/************************************************************************/
200
201/*
202 * Generic Templates
203 * One for each of the simple types, plus a special one for ANY, plus:
204 *	- a pointer to each one of those
205 *	- a set of each one of those
206 *	- a sequence of each one of those
207 *
208 * Note that these are alphabetical (case insensitive); please add new
209 * ones in the appropriate place.
210 */
211
212extern const SEC_ASN1Template SEC_AnyTemplate[];
213extern const SEC_ASN1Template SEC_BitStringTemplate[];
214extern const SEC_ASN1Template SEC_BMPStringTemplate[];
215extern const SEC_ASN1Template SEC_BooleanTemplate[];
216extern const SEC_ASN1Template SEC_EnumeratedTemplate[];
217extern const SEC_ASN1Template SEC_GeneralizedTimeTemplate[];
218extern const SEC_ASN1Template SEC_IA5StringTemplate[];
219extern const SEC_ASN1Template SEC_IntegerTemplate[];
220extern const SEC_ASN1Template SEC_NullTemplate[];
221extern const SEC_ASN1Template SEC_ObjectIDTemplate[];
222extern const SEC_ASN1Template SEC_OctetStringTemplate[];
223extern const SEC_ASN1Template SEC_PrintableStringTemplate[];
224extern const SEC_ASN1Template SEC_T61StringTemplate[];
225extern const SEC_ASN1Template SEC_UniversalStringTemplate[];
226extern const SEC_ASN1Template SEC_UTCTimeTemplate[];
227extern const SEC_ASN1Template SEC_UTF8StringTemplate[];
228extern const SEC_ASN1Template SEC_VisibleStringTemplate[];
229
230extern const SEC_ASN1Template SEC_PointerToAnyTemplate[];
231extern const SEC_ASN1Template SEC_PointerToBitStringTemplate[];
232extern const SEC_ASN1Template SEC_PointerToBMPStringTemplate[];
233extern const SEC_ASN1Template SEC_PointerToBooleanTemplate[];
234extern const SEC_ASN1Template SEC_PointerToEnumeratedTemplate[];
235extern const SEC_ASN1Template SEC_PointerToGeneralizedTimeTemplate[];
236extern const SEC_ASN1Template SEC_PointerToIA5StringTemplate[];
237extern const SEC_ASN1Template SEC_PointerToIntegerTemplate[];
238extern const SEC_ASN1Template SEC_PointerToNullTemplate[];
239extern const SEC_ASN1Template SEC_PointerToObjectIDTemplate[];
240extern const SEC_ASN1Template SEC_PointerToOctetStringTemplate[];
241extern const SEC_ASN1Template SEC_PointerToPrintableStringTemplate[];
242extern const SEC_ASN1Template SEC_PointerToT61StringTemplate[];
243extern const SEC_ASN1Template SEC_PointerToUniversalStringTemplate[];
244extern const SEC_ASN1Template SEC_PointerToUTCTimeTemplate[];
245extern const SEC_ASN1Template SEC_PointerToUTF8StringTemplate[];
246extern const SEC_ASN1Template SEC_PointerToVisibleStringTemplate[];
247
248extern const SEC_ASN1Template SEC_SequenceOfAnyTemplate[];
249extern const SEC_ASN1Template SEC_SequenceOfBitStringTemplate[];
250extern const SEC_ASN1Template SEC_SequenceOfBMPStringTemplate[];
251extern const SEC_ASN1Template SEC_SequenceOfBooleanTemplate[];
252extern const SEC_ASN1Template SEC_SequenceOfEnumeratedTemplate[];
253extern const SEC_ASN1Template SEC_SequenceOfGeneralizedTimeTemplate[];
254extern const SEC_ASN1Template SEC_SequenceOfIA5StringTemplate[];
255extern const SEC_ASN1Template SEC_SequenceOfIntegerTemplate[];
256extern const SEC_ASN1Template SEC_SequenceOfNullTemplate[];
257extern const SEC_ASN1Template SEC_SequenceOfObjectIDTemplate[];
258extern const SEC_ASN1Template SEC_SequenceOfOctetStringTemplate[];
259extern const SEC_ASN1Template SEC_SequenceOfPrintableStringTemplate[];
260extern const SEC_ASN1Template SEC_SequenceOfT61StringTemplate[];
261extern const SEC_ASN1Template SEC_SequenceOfUniversalStringTemplate[];
262extern const SEC_ASN1Template SEC_SequenceOfUTCTimeTemplate[];
263extern const SEC_ASN1Template SEC_SequenceOfUTF8StringTemplate[];
264extern const SEC_ASN1Template SEC_SequenceOfVisibleStringTemplate[];
265
266extern const SEC_ASN1Template SEC_SetOfAnyTemplate[];
267extern const SEC_ASN1Template SEC_SetOfBitStringTemplate[];
268extern const SEC_ASN1Template SEC_SetOfBMPStringTemplate[];
269extern const SEC_ASN1Template SEC_SetOfBooleanTemplate[];
270extern const SEC_ASN1Template SEC_SetOfEnumeratedTemplate[];
271extern const SEC_ASN1Template SEC_SetOfGeneralizedTimeTemplate[];
272extern const SEC_ASN1Template SEC_SetOfIA5StringTemplate[];
273extern const SEC_ASN1Template SEC_SetOfIntegerTemplate[];
274extern const SEC_ASN1Template SEC_SetOfNullTemplate[];
275extern const SEC_ASN1Template SEC_SetOfObjectIDTemplate[];
276extern const SEC_ASN1Template SEC_SetOfOctetStringTemplate[];
277extern const SEC_ASN1Template SEC_SetOfPrintableStringTemplate[];
278extern const SEC_ASN1Template SEC_SetOfT61StringTemplate[];
279extern const SEC_ASN1Template SEC_SetOfUniversalStringTemplate[];
280extern const SEC_ASN1Template SEC_SetOfUTCTimeTemplate[];
281extern const SEC_ASN1Template SEC_SetOfUTF8StringTemplate[];
282extern const SEC_ASN1Template SEC_SetOfVisibleStringTemplate[];
283
284/*
285 * Template for skipping a subitem; this only makes sense when decoding.
286 */
287extern const SEC_ASN1Template SEC_SkipTemplate[];
288
289/* These functions simply return the address of the above-declared templates.
290** This is necessary for Windows DLLs.  Sigh.
291*/
292SEC_ASN1_CHOOSER_DECLARE(SEC_AnyTemplate)
293SEC_ASN1_CHOOSER_DECLARE(SEC_BMPStringTemplate)
294SEC_ASN1_CHOOSER_DECLARE(SEC_BooleanTemplate)
295SEC_ASN1_CHOOSER_DECLARE(SEC_BitStringTemplate)
296SEC_ASN1_CHOOSER_DECLARE(SEC_GeneralizedTimeTemplate)
297SEC_ASN1_CHOOSER_DECLARE(SEC_IA5StringTemplate)
298SEC_ASN1_CHOOSER_DECLARE(SEC_IntegerTemplate)
299SEC_ASN1_CHOOSER_DECLARE(SEC_NullTemplate)
300SEC_ASN1_CHOOSER_DECLARE(SEC_ObjectIDTemplate)
301SEC_ASN1_CHOOSER_DECLARE(SEC_OctetStringTemplate)
302SEC_ASN1_CHOOSER_DECLARE(SEC_UTCTimeTemplate)
303SEC_ASN1_CHOOSER_DECLARE(SEC_UTF8StringTemplate)
304
305SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToAnyTemplate)
306SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToOctetStringTemplate)
307
308SEC_ASN1_CHOOSER_DECLARE(SEC_SetOfAnyTemplate)
309
310SEC_ASN1_CHOOSER_DECLARE(SEC_EnumeratedTemplate)
311SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToEnumeratedTemplate)
312SEC_ASN1_CHOOSER_DECLARE(SEC_SequenceOfAnyTemplate)
313SEC_ASN1_CHOOSER_DECLARE(SEC_SequenceOfObjectIDTemplate)
314SEC_ASN1_CHOOSER_DECLARE(SEC_SkipTemplate)
315SEC_ASN1_CHOOSER_DECLARE(SEC_UniversalStringTemplate)
316SEC_ASN1_CHOOSER_DECLARE(SEC_PrintableStringTemplate)
317SEC_ASN1_CHOOSER_DECLARE(SEC_T61StringTemplate)
318SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToGeneralizedTimeTemplate)
319SEC_END_PROTOS
320#endif /* _SECASN1_H_ */