1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/util/secasn1.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,292 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +/*
1.9 + * Support for encoding/decoding of ASN.1 using BER/DER (Basic/Distinguished
1.10 + * Encoding Rules). The routines are found in and used extensively by the
1.11 + * security library, but exported for other use.
1.12 + */
1.13 +
1.14 +#ifndef _SECASN1_H_
1.15 +#define _SECASN1_H_
1.16 +
1.17 +#include "utilrename.h"
1.18 +#include "plarena.h"
1.19 +
1.20 +#include "seccomon.h"
1.21 +#include "secasn1t.h"
1.22 +
1.23 +
1.24 +/************************************************************************/
1.25 +SEC_BEGIN_PROTOS
1.26 +
1.27 +/*
1.28 + * XXX These function prototypes need full, explanatory comments.
1.29 + */
1.30 +
1.31 +/*
1.32 +** Decoding.
1.33 +*/
1.34 +
1.35 +extern SEC_ASN1DecoderContext *SEC_ASN1DecoderStart(PLArenaPool *pool,
1.36 + void *dest,
1.37 + const SEC_ASN1Template *t);
1.38 +
1.39 +/* XXX char or unsigned char? */
1.40 +extern SECStatus SEC_ASN1DecoderUpdate(SEC_ASN1DecoderContext *cx,
1.41 + const char *buf,
1.42 + unsigned long len);
1.43 +
1.44 +extern SECStatus SEC_ASN1DecoderFinish(SEC_ASN1DecoderContext *cx);
1.45 +
1.46 +/* Higher level code detected an error, abort the rest of the processing */
1.47 +extern void SEC_ASN1DecoderAbort(SEC_ASN1DecoderContext *cx, int error);
1.48 +
1.49 +extern void SEC_ASN1DecoderSetFilterProc(SEC_ASN1DecoderContext *cx,
1.50 + SEC_ASN1WriteProc fn,
1.51 + void *arg, PRBool no_store);
1.52 +
1.53 +extern void SEC_ASN1DecoderClearFilterProc(SEC_ASN1DecoderContext *cx);
1.54 +
1.55 +extern void SEC_ASN1DecoderSetNotifyProc(SEC_ASN1DecoderContext *cx,
1.56 + SEC_ASN1NotifyProc fn,
1.57 + void *arg);
1.58 +
1.59 +extern void SEC_ASN1DecoderClearNotifyProc(SEC_ASN1DecoderContext *cx);
1.60 +
1.61 +extern SECStatus SEC_ASN1Decode(PLArenaPool *pool, void *dest,
1.62 + const SEC_ASN1Template *t,
1.63 + const char *buf, long len);
1.64 +
1.65 +/* Both classic ASN.1 and QuickDER have a feature that removes leading zeroes
1.66 + out of SEC_ASN1_INTEGER if the caller sets siUnsignedInteger in the type
1.67 + field of the target SECItem prior to calling the decoder. Otherwise, the
1.68 + type field is ignored and untouched. For SECItem that are dynamically
1.69 + allocated (from POINTER, SET OF, SEQUENCE OF) the decoder sets the type
1.70 + field to siBuffer. */
1.71 +
1.72 +extern SECStatus SEC_ASN1DecodeItem(PLArenaPool *pool, void *dest,
1.73 + const SEC_ASN1Template *t,
1.74 + const SECItem *src);
1.75 +
1.76 +extern SECStatus SEC_QuickDERDecodeItem(PLArenaPool* arena, void* dest,
1.77 + const SEC_ASN1Template* templateEntry,
1.78 + const SECItem* src);
1.79 +
1.80 +/*
1.81 +** Encoding.
1.82 +*/
1.83 +
1.84 +extern SEC_ASN1EncoderContext *SEC_ASN1EncoderStart(const void *src,
1.85 + const SEC_ASN1Template *t,
1.86 + SEC_ASN1WriteProc fn,
1.87 + void *output_arg);
1.88 +
1.89 +/* XXX char or unsigned char? */
1.90 +extern SECStatus SEC_ASN1EncoderUpdate(SEC_ASN1EncoderContext *cx,
1.91 + const char *buf,
1.92 + unsigned long len);
1.93 +
1.94 +extern void SEC_ASN1EncoderFinish(SEC_ASN1EncoderContext *cx);
1.95 +
1.96 +/* Higher level code detected an error, abort the rest of the processing */
1.97 +extern void SEC_ASN1EncoderAbort(SEC_ASN1EncoderContext *cx, int error);
1.98 +
1.99 +extern void SEC_ASN1EncoderSetNotifyProc(SEC_ASN1EncoderContext *cx,
1.100 + SEC_ASN1NotifyProc fn,
1.101 + void *arg);
1.102 +
1.103 +extern void SEC_ASN1EncoderClearNotifyProc(SEC_ASN1EncoderContext *cx);
1.104 +
1.105 +extern void SEC_ASN1EncoderSetStreaming(SEC_ASN1EncoderContext *cx);
1.106 +
1.107 +extern void SEC_ASN1EncoderClearStreaming(SEC_ASN1EncoderContext *cx);
1.108 +
1.109 +extern void sec_ASN1EncoderSetDER(SEC_ASN1EncoderContext *cx);
1.110 +
1.111 +extern void sec_ASN1EncoderClearDER(SEC_ASN1EncoderContext *cx);
1.112 +
1.113 +extern void SEC_ASN1EncoderSetTakeFromBuf(SEC_ASN1EncoderContext *cx);
1.114 +
1.115 +extern void SEC_ASN1EncoderClearTakeFromBuf(SEC_ASN1EncoderContext *cx);
1.116 +
1.117 +extern SECStatus SEC_ASN1Encode(const void *src, const SEC_ASN1Template *t,
1.118 + SEC_ASN1WriteProc output_proc,
1.119 + void *output_arg);
1.120 +
1.121 +/*
1.122 + * If both pool and dest are NULL, the caller should free the returned SECItem
1.123 + * with a SECITEM_FreeItem(..., PR_TRUE) call. If pool is NULL but dest is
1.124 + * not NULL, the caller should free the data buffer pointed to by dest with a
1.125 + * SECITEM_FreeItem(dest, PR_FALSE) or PORT_Free(dest->data) call.
1.126 + */
1.127 +extern SECItem * SEC_ASN1EncodeItem(PLArenaPool *pool, SECItem *dest,
1.128 + const void *src, const SEC_ASN1Template *t);
1.129 +
1.130 +extern SECItem * SEC_ASN1EncodeInteger(PLArenaPool *pool,
1.131 + SECItem *dest, long value);
1.132 +
1.133 +extern SECItem * SEC_ASN1EncodeUnsignedInteger(PLArenaPool *pool,
1.134 + SECItem *dest,
1.135 + unsigned long value);
1.136 +
1.137 +extern SECStatus SEC_ASN1DecodeInteger(SECItem *src,
1.138 + unsigned long *value);
1.139 +
1.140 +/*
1.141 +** Utilities.
1.142 +*/
1.143 +
1.144 +/*
1.145 + * We have a length that needs to be encoded; how many bytes will the
1.146 + * encoding take?
1.147 + */
1.148 +extern int SEC_ASN1LengthLength (unsigned long len);
1.149 +
1.150 +/* encode the length and return the number of bytes we encoded. Buffer
1.151 + * must be pre allocated */
1.152 +extern int SEC_ASN1EncodeLength(unsigned char *buf,int value);
1.153 +
1.154 +/*
1.155 + * Find the appropriate subtemplate for the given template.
1.156 + * This may involve calling a "chooser" function, or it may just
1.157 + * be right there. In either case, it is expected to *have* a
1.158 + * subtemplate; this is asserted in debug builds (in non-debug
1.159 + * builds, NULL will be returned).
1.160 + *
1.161 + * "thing" is a pointer to the structure being encoded/decoded
1.162 + * "encoding", when true, means that we are in the process of encoding
1.163 + * (as opposed to in the process of decoding)
1.164 + */
1.165 +extern const SEC_ASN1Template *
1.166 +SEC_ASN1GetSubtemplate (const SEC_ASN1Template *inTemplate, void *thing,
1.167 + PRBool encoding);
1.168 +
1.169 +/* whether the template is for a primitive type or a choice of
1.170 + * primitive types
1.171 + */
1.172 +extern PRBool SEC_ASN1IsTemplateSimple(const SEC_ASN1Template *theTemplate);
1.173 +
1.174 +/************************************************************************/
1.175 +
1.176 +/*
1.177 + * Generic Templates
1.178 + * One for each of the simple types, plus a special one for ANY, plus:
1.179 + * - a pointer to each one of those
1.180 + * - a set of each one of those
1.181 + * - a sequence of each one of those
1.182 + *
1.183 + * Note that these are alphabetical (case insensitive); please add new
1.184 + * ones in the appropriate place.
1.185 + */
1.186 +
1.187 +extern const SEC_ASN1Template SEC_AnyTemplate[];
1.188 +extern const SEC_ASN1Template SEC_BitStringTemplate[];
1.189 +extern const SEC_ASN1Template SEC_BMPStringTemplate[];
1.190 +extern const SEC_ASN1Template SEC_BooleanTemplate[];
1.191 +extern const SEC_ASN1Template SEC_EnumeratedTemplate[];
1.192 +extern const SEC_ASN1Template SEC_GeneralizedTimeTemplate[];
1.193 +extern const SEC_ASN1Template SEC_IA5StringTemplate[];
1.194 +extern const SEC_ASN1Template SEC_IntegerTemplate[];
1.195 +extern const SEC_ASN1Template SEC_NullTemplate[];
1.196 +extern const SEC_ASN1Template SEC_ObjectIDTemplate[];
1.197 +extern const SEC_ASN1Template SEC_OctetStringTemplate[];
1.198 +extern const SEC_ASN1Template SEC_PrintableStringTemplate[];
1.199 +extern const SEC_ASN1Template SEC_T61StringTemplate[];
1.200 +extern const SEC_ASN1Template SEC_UniversalStringTemplate[];
1.201 +extern const SEC_ASN1Template SEC_UTCTimeTemplate[];
1.202 +extern const SEC_ASN1Template SEC_UTF8StringTemplate[];
1.203 +extern const SEC_ASN1Template SEC_VisibleStringTemplate[];
1.204 +
1.205 +extern const SEC_ASN1Template SEC_PointerToAnyTemplate[];
1.206 +extern const SEC_ASN1Template SEC_PointerToBitStringTemplate[];
1.207 +extern const SEC_ASN1Template SEC_PointerToBMPStringTemplate[];
1.208 +extern const SEC_ASN1Template SEC_PointerToBooleanTemplate[];
1.209 +extern const SEC_ASN1Template SEC_PointerToEnumeratedTemplate[];
1.210 +extern const SEC_ASN1Template SEC_PointerToGeneralizedTimeTemplate[];
1.211 +extern const SEC_ASN1Template SEC_PointerToIA5StringTemplate[];
1.212 +extern const SEC_ASN1Template SEC_PointerToIntegerTemplate[];
1.213 +extern const SEC_ASN1Template SEC_PointerToNullTemplate[];
1.214 +extern const SEC_ASN1Template SEC_PointerToObjectIDTemplate[];
1.215 +extern const SEC_ASN1Template SEC_PointerToOctetStringTemplate[];
1.216 +extern const SEC_ASN1Template SEC_PointerToPrintableStringTemplate[];
1.217 +extern const SEC_ASN1Template SEC_PointerToT61StringTemplate[];
1.218 +extern const SEC_ASN1Template SEC_PointerToUniversalStringTemplate[];
1.219 +extern const SEC_ASN1Template SEC_PointerToUTCTimeTemplate[];
1.220 +extern const SEC_ASN1Template SEC_PointerToUTF8StringTemplate[];
1.221 +extern const SEC_ASN1Template SEC_PointerToVisibleStringTemplate[];
1.222 +
1.223 +extern const SEC_ASN1Template SEC_SequenceOfAnyTemplate[];
1.224 +extern const SEC_ASN1Template SEC_SequenceOfBitStringTemplate[];
1.225 +extern const SEC_ASN1Template SEC_SequenceOfBMPStringTemplate[];
1.226 +extern const SEC_ASN1Template SEC_SequenceOfBooleanTemplate[];
1.227 +extern const SEC_ASN1Template SEC_SequenceOfEnumeratedTemplate[];
1.228 +extern const SEC_ASN1Template SEC_SequenceOfGeneralizedTimeTemplate[];
1.229 +extern const SEC_ASN1Template SEC_SequenceOfIA5StringTemplate[];
1.230 +extern const SEC_ASN1Template SEC_SequenceOfIntegerTemplate[];
1.231 +extern const SEC_ASN1Template SEC_SequenceOfNullTemplate[];
1.232 +extern const SEC_ASN1Template SEC_SequenceOfObjectIDTemplate[];
1.233 +extern const SEC_ASN1Template SEC_SequenceOfOctetStringTemplate[];
1.234 +extern const SEC_ASN1Template SEC_SequenceOfPrintableStringTemplate[];
1.235 +extern const SEC_ASN1Template SEC_SequenceOfT61StringTemplate[];
1.236 +extern const SEC_ASN1Template SEC_SequenceOfUniversalStringTemplate[];
1.237 +extern const SEC_ASN1Template SEC_SequenceOfUTCTimeTemplate[];
1.238 +extern const SEC_ASN1Template SEC_SequenceOfUTF8StringTemplate[];
1.239 +extern const SEC_ASN1Template SEC_SequenceOfVisibleStringTemplate[];
1.240 +
1.241 +extern const SEC_ASN1Template SEC_SetOfAnyTemplate[];
1.242 +extern const SEC_ASN1Template SEC_SetOfBitStringTemplate[];
1.243 +extern const SEC_ASN1Template SEC_SetOfBMPStringTemplate[];
1.244 +extern const SEC_ASN1Template SEC_SetOfBooleanTemplate[];
1.245 +extern const SEC_ASN1Template SEC_SetOfEnumeratedTemplate[];
1.246 +extern const SEC_ASN1Template SEC_SetOfGeneralizedTimeTemplate[];
1.247 +extern const SEC_ASN1Template SEC_SetOfIA5StringTemplate[];
1.248 +extern const SEC_ASN1Template SEC_SetOfIntegerTemplate[];
1.249 +extern const SEC_ASN1Template SEC_SetOfNullTemplate[];
1.250 +extern const SEC_ASN1Template SEC_SetOfObjectIDTemplate[];
1.251 +extern const SEC_ASN1Template SEC_SetOfOctetStringTemplate[];
1.252 +extern const SEC_ASN1Template SEC_SetOfPrintableStringTemplate[];
1.253 +extern const SEC_ASN1Template SEC_SetOfT61StringTemplate[];
1.254 +extern const SEC_ASN1Template SEC_SetOfUniversalStringTemplate[];
1.255 +extern const SEC_ASN1Template SEC_SetOfUTCTimeTemplate[];
1.256 +extern const SEC_ASN1Template SEC_SetOfUTF8StringTemplate[];
1.257 +extern const SEC_ASN1Template SEC_SetOfVisibleStringTemplate[];
1.258 +
1.259 +/*
1.260 + * Template for skipping a subitem; this only makes sense when decoding.
1.261 + */
1.262 +extern const SEC_ASN1Template SEC_SkipTemplate[];
1.263 +
1.264 +/* These functions simply return the address of the above-declared templates.
1.265 +** This is necessary for Windows DLLs. Sigh.
1.266 +*/
1.267 +SEC_ASN1_CHOOSER_DECLARE(SEC_AnyTemplate)
1.268 +SEC_ASN1_CHOOSER_DECLARE(SEC_BMPStringTemplate)
1.269 +SEC_ASN1_CHOOSER_DECLARE(SEC_BooleanTemplate)
1.270 +SEC_ASN1_CHOOSER_DECLARE(SEC_BitStringTemplate)
1.271 +SEC_ASN1_CHOOSER_DECLARE(SEC_GeneralizedTimeTemplate)
1.272 +SEC_ASN1_CHOOSER_DECLARE(SEC_IA5StringTemplate)
1.273 +SEC_ASN1_CHOOSER_DECLARE(SEC_IntegerTemplate)
1.274 +SEC_ASN1_CHOOSER_DECLARE(SEC_NullTemplate)
1.275 +SEC_ASN1_CHOOSER_DECLARE(SEC_ObjectIDTemplate)
1.276 +SEC_ASN1_CHOOSER_DECLARE(SEC_OctetStringTemplate)
1.277 +SEC_ASN1_CHOOSER_DECLARE(SEC_UTCTimeTemplate)
1.278 +SEC_ASN1_CHOOSER_DECLARE(SEC_UTF8StringTemplate)
1.279 +
1.280 +SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToAnyTemplate)
1.281 +SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToOctetStringTemplate)
1.282 +
1.283 +SEC_ASN1_CHOOSER_DECLARE(SEC_SetOfAnyTemplate)
1.284 +
1.285 +SEC_ASN1_CHOOSER_DECLARE(SEC_EnumeratedTemplate)
1.286 +SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToEnumeratedTemplate)
1.287 +SEC_ASN1_CHOOSER_DECLARE(SEC_SequenceOfAnyTemplate)
1.288 +SEC_ASN1_CHOOSER_DECLARE(SEC_SequenceOfObjectIDTemplate)
1.289 +SEC_ASN1_CHOOSER_DECLARE(SEC_SkipTemplate)
1.290 +SEC_ASN1_CHOOSER_DECLARE(SEC_UniversalStringTemplate)
1.291 +SEC_ASN1_CHOOSER_DECLARE(SEC_PrintableStringTemplate)
1.292 +SEC_ASN1_CHOOSER_DECLARE(SEC_T61StringTemplate)
1.293 +SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToGeneralizedTimeTemplate)
1.294 +SEC_END_PROTOS
1.295 +#endif /* _SECASN1_H_ */
