Back to index

lightning-sunbird  0.9+nobinonly
secasn1.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  * Support for encoding/decoding of ASN.1 using BER/DER (Basic/Distinguished
00039  * Encoding Rules).  The routines are found in and used extensively by the
00040  * security library, but exported for other use.
00041  *
00042  * $Id: secasn1.h,v 1.14 2005/10/31 18:52:20 julien.pierre.bugs%sun.com Exp $
00043  */
00044 
00045 #ifndef _SECASN1_H_
00046 #define _SECASN1_H_
00047 
00048 #include "plarena.h"
00049 
00050 #include "seccomon.h"
00051 #include "secasn1t.h"
00052 
00053 
00054 /************************************************************************/
00055 SEC_BEGIN_PROTOS
00056 
00057 /*
00058  * XXX These function prototypes need full, explanatory comments.
00059  */
00060 
00061 /*
00062 ** Decoding.
00063 */
00064 
00065 extern SEC_ASN1DecoderContext *SEC_ASN1DecoderStart(PRArenaPool *pool,
00066                                               void *dest,
00067                                               const SEC_ASN1Template *t);
00068 
00069 /* XXX char or unsigned char? */
00070 extern SECStatus SEC_ASN1DecoderUpdate(SEC_ASN1DecoderContext *cx,
00071                                    const char *buf,
00072                                    unsigned long len);
00073 
00074 extern SECStatus SEC_ASN1DecoderFinish(SEC_ASN1DecoderContext *cx);
00075 
00076 /* Higher level code detected an error, abort the rest of the processing */
00077 extern void SEC_ASN1DecoderAbort(SEC_ASN1DecoderContext *cx, int error);
00078 
00079 extern void SEC_ASN1DecoderSetFilterProc(SEC_ASN1DecoderContext *cx,
00080                                     SEC_ASN1WriteProc fn,
00081                                     void *arg, PRBool no_store);
00082 
00083 extern void SEC_ASN1DecoderClearFilterProc(SEC_ASN1DecoderContext *cx);
00084 
00085 extern void SEC_ASN1DecoderSetNotifyProc(SEC_ASN1DecoderContext *cx,
00086                                     SEC_ASN1NotifyProc fn,
00087                                     void *arg);
00088 
00089 extern void SEC_ASN1DecoderClearNotifyProc(SEC_ASN1DecoderContext *cx);
00090 
00091 extern SECStatus SEC_ASN1Decode(PRArenaPool *pool, void *dest,
00092                             const SEC_ASN1Template *t,
00093                             const char *buf, long len);
00094 
00095 /* Both classic ASN.1 and QuickDER have a feature that removes leading zeroes
00096    out of SEC_ASN1_INTEGER if the caller sets siUnsignedInteger in the type
00097    field of the target SECItem prior to calling the decoder. Otherwise, the
00098    type field is ignored and untouched. For SECItem that are dynamically
00099    allocated (from POINTER, SET OF, SEQUENCE OF) the decoder sets the type
00100    field to siBuffer. */
00101 
00102 extern SECStatus SEC_ASN1DecodeItem(PRArenaPool *pool, void *dest,
00103                                 const SEC_ASN1Template *t,
00104                                 const SECItem *src);
00105 
00106 extern SECStatus SEC_QuickDERDecodeItem(PRArenaPool* arena, void* dest,
00107                      const SEC_ASN1Template* templateEntry,
00108                      const SECItem* src);
00109 
00110 /*
00111 ** Encoding.
00112 */
00113 
00114 extern SEC_ASN1EncoderContext *SEC_ASN1EncoderStart(const void *src,
00115                                               const SEC_ASN1Template *t,
00116                                               SEC_ASN1WriteProc fn,
00117                                               void *output_arg);
00118 
00119 /* XXX char or unsigned char? */
00120 extern SECStatus SEC_ASN1EncoderUpdate(SEC_ASN1EncoderContext *cx,
00121                                    const char *buf,
00122                                    unsigned long len);
00123 
00124 extern void SEC_ASN1EncoderFinish(SEC_ASN1EncoderContext *cx);
00125 
00126 /* Higher level code detected an error, abort the rest of the processing */
00127 extern void SEC_ASN1EncoderAbort(SEC_ASN1EncoderContext *cx, int error);
00128 
00129 extern void SEC_ASN1EncoderSetNotifyProc(SEC_ASN1EncoderContext *cx,
00130                                     SEC_ASN1NotifyProc fn,
00131                                     void *arg);
00132 
00133 extern void SEC_ASN1EncoderClearNotifyProc(SEC_ASN1EncoderContext *cx);
00134 
00135 extern void SEC_ASN1EncoderSetStreaming(SEC_ASN1EncoderContext *cx);
00136 
00137 extern void SEC_ASN1EncoderClearStreaming(SEC_ASN1EncoderContext *cx);
00138 
00139 extern void sec_ASN1EncoderSetDER(SEC_ASN1EncoderContext *cx);
00140 
00141 extern void sec_ASN1EncoderClearDER(SEC_ASN1EncoderContext *cx);
00142 
00143 extern void SEC_ASN1EncoderSetTakeFromBuf(SEC_ASN1EncoderContext *cx);
00144 
00145 extern void SEC_ASN1EncoderClearTakeFromBuf(SEC_ASN1EncoderContext *cx);
00146 
00147 extern SECStatus SEC_ASN1Encode(const void *src, const SEC_ASN1Template *t,
00148                             SEC_ASN1WriteProc output_proc,
00149                             void *output_arg);
00150 
00151 extern SECItem * SEC_ASN1EncodeItem(PRArenaPool *pool, SECItem *dest,
00152                                 const void *src, const SEC_ASN1Template *t);
00153 
00154 extern SECItem * SEC_ASN1EncodeInteger(PRArenaPool *pool,
00155                                    SECItem *dest, long value);
00156 
00157 extern SECItem * SEC_ASN1EncodeUnsignedInteger(PRArenaPool *pool,
00158                                           SECItem *dest,
00159                                           unsigned long value);
00160 
00161 extern SECStatus SEC_ASN1DecodeInteger(SECItem *src,
00162                                    unsigned long *value);
00163 
00164 /*
00165 ** Utilities.
00166 */
00167 
00168 /*
00169  * We have a length that needs to be encoded; how many bytes will the
00170  * encoding take?
00171  */
00172 extern int SEC_ASN1LengthLength (unsigned long len);
00173 
00174 /* encode the length and return the number of bytes we encoded. Buffer
00175  * must be pre allocated  */
00176 extern int SEC_ASN1EncodeLength(unsigned char *buf,int value);
00177 
00178 /*
00179  * Find the appropriate subtemplate for the given template.
00180  * This may involve calling a "chooser" function, or it may just
00181  * be right there.  In either case, it is expected to *have* a
00182  * subtemplate; this is asserted in debug builds (in non-debug
00183  * builds, NULL will be returned).
00184  *
00185  * "thing" is a pointer to the structure being encoded/decoded
00186  * "encoding", when true, means that we are in the process of encoding
00187  *     (as opposed to in the process of decoding)
00188  */
00189 extern const SEC_ASN1Template *
00190 SEC_ASN1GetSubtemplate (const SEC_ASN1Template *inTemplate, void *thing,
00191                      PRBool encoding);
00192 
00193 /* whether the template is for a primitive type or a choice of
00194  * primitive types
00195  */
00196 extern PRBool SEC_ASN1IsTemplateSimple(const SEC_ASN1Template *theTemplate);
00197 
00198 /************************************************************************/
00199 
00200 /*
00201  * Generic Templates
00202  * One for each of the simple types, plus a special one for ANY, plus:
00203  *     - a pointer to each one of those
00204  *     - a set of each one of those
00205  *     - a sequence of each one of those
00206  *
00207  * Note that these are alphabetical (case insensitive); please add new
00208  * ones in the appropriate place.
00209  */
00210 
00211 extern const SEC_ASN1Template SEC_AnyTemplate[];
00212 extern const SEC_ASN1Template SEC_BitStringTemplate[];
00213 extern const SEC_ASN1Template SEC_BMPStringTemplate[];
00214 extern const SEC_ASN1Template SEC_BooleanTemplate[];
00215 extern const SEC_ASN1Template SEC_EnumeratedTemplate[];
00216 extern const SEC_ASN1Template SEC_GeneralizedTimeTemplate[];
00217 extern const SEC_ASN1Template SEC_IA5StringTemplate[];
00218 extern const SEC_ASN1Template SEC_IntegerTemplate[];
00219 extern const SEC_ASN1Template SEC_NullTemplate[];
00220 extern const SEC_ASN1Template SEC_ObjectIDTemplate[];
00221 extern const SEC_ASN1Template SEC_OctetStringTemplate[];
00222 extern const SEC_ASN1Template SEC_PrintableStringTemplate[];
00223 extern const SEC_ASN1Template SEC_T61StringTemplate[];
00224 extern const SEC_ASN1Template SEC_UniversalStringTemplate[];
00225 extern const SEC_ASN1Template SEC_UTCTimeTemplate[];
00226 extern const SEC_ASN1Template SEC_UTF8StringTemplate[];
00227 extern const SEC_ASN1Template SEC_VisibleStringTemplate[];
00228 
00229 extern const SEC_ASN1Template SEC_PointerToAnyTemplate[];
00230 extern const SEC_ASN1Template SEC_PointerToBitStringTemplate[];
00231 extern const SEC_ASN1Template SEC_PointerToBMPStringTemplate[];
00232 extern const SEC_ASN1Template SEC_PointerToBooleanTemplate[];
00233 extern const SEC_ASN1Template SEC_PointerToEnumeratedTemplate[];
00234 extern const SEC_ASN1Template SEC_PointerToGeneralizedTimeTemplate[];
00235 extern const SEC_ASN1Template SEC_PointerToIA5StringTemplate[];
00236 extern const SEC_ASN1Template SEC_PointerToIntegerTemplate[];
00237 extern const SEC_ASN1Template SEC_PointerToNullTemplate[];
00238 extern const SEC_ASN1Template SEC_PointerToObjectIDTemplate[];
00239 extern const SEC_ASN1Template SEC_PointerToOctetStringTemplate[];
00240 extern const SEC_ASN1Template SEC_PointerToPrintableStringTemplate[];
00241 extern const SEC_ASN1Template SEC_PointerToT61StringTemplate[];
00242 extern const SEC_ASN1Template SEC_PointerToUniversalStringTemplate[];
00243 extern const SEC_ASN1Template SEC_PointerToUTCTimeTemplate[];
00244 extern const SEC_ASN1Template SEC_PointerToUTF8StringTemplate[];
00245 extern const SEC_ASN1Template SEC_PointerToVisibleStringTemplate[];
00246 
00247 extern const SEC_ASN1Template SEC_SequenceOfAnyTemplate[];
00248 extern const SEC_ASN1Template SEC_SequenceOfBitStringTemplate[];
00249 extern const SEC_ASN1Template SEC_SequenceOfBMPStringTemplate[];
00250 extern const SEC_ASN1Template SEC_SequenceOfBooleanTemplate[];
00251 extern const SEC_ASN1Template SEC_SequenceOfEnumeratedTemplate[];
00252 extern const SEC_ASN1Template SEC_SequenceOfGeneralizedTimeTemplate[];
00253 extern const SEC_ASN1Template SEC_SequenceOfIA5StringTemplate[];
00254 extern const SEC_ASN1Template SEC_SequenceOfIntegerTemplate[];
00255 extern const SEC_ASN1Template SEC_SequenceOfNullTemplate[];
00256 extern const SEC_ASN1Template SEC_SequenceOfObjectIDTemplate[];
00257 extern const SEC_ASN1Template SEC_SequenceOfOctetStringTemplate[];
00258 extern const SEC_ASN1Template SEC_SequenceOfPrintableStringTemplate[];
00259 extern const SEC_ASN1Template SEC_SequenceOfT61StringTemplate[];
00260 extern const SEC_ASN1Template SEC_SequenceOfUniversalStringTemplate[];
00261 extern const SEC_ASN1Template SEC_SequenceOfUTCTimeTemplate[];
00262 extern const SEC_ASN1Template SEC_SequenceOfUTF8StringTemplate[];
00263 extern const SEC_ASN1Template SEC_SequenceOfVisibleStringTemplate[];
00264 
00265 extern const SEC_ASN1Template SEC_SetOfAnyTemplate[];
00266 extern const SEC_ASN1Template SEC_SetOfBitStringTemplate[];
00267 extern const SEC_ASN1Template SEC_SetOfBMPStringTemplate[];
00268 extern const SEC_ASN1Template SEC_SetOfBooleanTemplate[];
00269 extern const SEC_ASN1Template SEC_SetOfEnumeratedTemplate[];
00270 extern const SEC_ASN1Template SEC_SetOfGeneralizedTimeTemplate[];
00271 extern const SEC_ASN1Template SEC_SetOfIA5StringTemplate[];
00272 extern const SEC_ASN1Template SEC_SetOfIntegerTemplate[];
00273 extern const SEC_ASN1Template SEC_SetOfNullTemplate[];
00274 extern const SEC_ASN1Template SEC_SetOfObjectIDTemplate[];
00275 extern const SEC_ASN1Template SEC_SetOfOctetStringTemplate[];
00276 extern const SEC_ASN1Template SEC_SetOfPrintableStringTemplate[];
00277 extern const SEC_ASN1Template SEC_SetOfT61StringTemplate[];
00278 extern const SEC_ASN1Template SEC_SetOfUniversalStringTemplate[];
00279 extern const SEC_ASN1Template SEC_SetOfUTCTimeTemplate[];
00280 extern const SEC_ASN1Template SEC_SetOfUTF8StringTemplate[];
00281 extern const SEC_ASN1Template SEC_SetOfVisibleStringTemplate[];
00282 
00283 /*
00284  * Template for skipping a subitem; this only makes sense when decoding.
00285  */
00286 extern const SEC_ASN1Template SEC_SkipTemplate[];
00287 
00288 /* These functions simply return the address of the above-declared templates.
00289 ** This is necessary for Windows DLLs.  Sigh.
00290 */
00291 SEC_ASN1_CHOOSER_DECLARE(SEC_AnyTemplate)
00292 SEC_ASN1_CHOOSER_DECLARE(SEC_BMPStringTemplate)
00293 SEC_ASN1_CHOOSER_DECLARE(SEC_BooleanTemplate)
00294 SEC_ASN1_CHOOSER_DECLARE(SEC_BitStringTemplate)
00295 SEC_ASN1_CHOOSER_DECLARE(SEC_GeneralizedTimeTemplate)
00296 SEC_ASN1_CHOOSER_DECLARE(SEC_IA5StringTemplate)
00297 SEC_ASN1_CHOOSER_DECLARE(SEC_IntegerTemplate)
00298 SEC_ASN1_CHOOSER_DECLARE(SEC_NullTemplate)
00299 SEC_ASN1_CHOOSER_DECLARE(SEC_ObjectIDTemplate)
00300 SEC_ASN1_CHOOSER_DECLARE(SEC_OctetStringTemplate)
00301 SEC_ASN1_CHOOSER_DECLARE(SEC_UTCTimeTemplate)
00302 SEC_ASN1_CHOOSER_DECLARE(SEC_UTF8StringTemplate)
00303 
00304 SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToAnyTemplate)
00305 SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToOctetStringTemplate)
00306 
00307 SEC_ASN1_CHOOSER_DECLARE(SEC_SetOfAnyTemplate)
00308 
00309 SEC_END_PROTOS
00310 #endif /* _SECASN1_H_ */