/gecko_api/include/secasn1.h

http://firefox-mac-pdf.googlecode.com/ · C Header · 320 lines · 164 code · 54 blank · 102 comment · 0 complexity · 6770eb3f013a38ea412c017879100a9b MD5 · raw file 

    

  1. /* ***** BEGIN LICENSE BLOCK *****
    2. 

  2.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
    3. 

  3.  *
    4. 

  4.  * The contents of this file are subject to the Mozilla Public License Version
    5. 

  5.  * 1.1 (the "License"); you may not use this file except in compliance with
    6. 

  6.  * the License. You may obtain a copy of the License at
    7. 

  7.  * http://www.mozilla.org/MPL/
    8. 

  8.  *
    9. 

  9.  * Software distributed under the License is distributed on an "AS IS" basis,
    10. 

  10.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
    11. 

  11.  * for the specific language governing rights and limitations under the
    12. 

  12.  * License.
    13. 

  13.  *
    14. 

  14.  * The Original Code is the Netscape security libraries.
    15. 

  15.  *
    16. 

  16.  * The Initial Developer of the Original Code is
    17. 

  17.  * Netscape Communications Corporation.
    18. 

  18.  * Portions created by the Initial Developer are Copyright (C) 1994-2000
    19. 

  19.  * the Initial Developer. All Rights Reserved.
    20. 

  20.  *
    21. 

  21.  * Contributor(s):
    22. 

  22.  *
    23. 

  23.  * Alternatively, the contents of this file may be used under the terms of
    24. 

  24.  * either the GNU General Public License Version 2 or later (the "GPL"), or
    25. 

  25.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
    26. 

  26.  * in which case the provisions of the GPL or the LGPL are applicable instead
    27. 

  27.  * of those above. If you wish to allow use of your version of this file only
    28. 

  28.  * under the terms of either the GPL or the LGPL, and not to allow others to
    29. 

  29.  * use your version of this file under the terms of the MPL, indicate your
    30. 

  30.  * decision by deleting the provisions above and replace them with the notice
    31. 

  31.  * and other provisions required by the GPL or the LGPL. If you do not delete
    32. 

  32.  * the provisions above, a recipient may use your version of this file under
    33. 

  33.  * the terms of any one of the MPL, the GPL or the LGPL.
    34. 

  34.  *
    35. 

  35.  * ***** END LICENSE BLOCK ***** */
    36. 

  36. 

  37. /*
    38. 

  38.  * Support for encoding/decoding of ASN.1 using BER/DER (Basic/Distinguished
    39. 

  39.  * Encoding Rules).  The routines are found in and used extensively by the
    40. 

  40.  * security library, but exported for other use.
    41. 

  41.  *
    42. 

  42.  * $Id: secasn1.h,v 1.15 2007/10/12 01:44:51 julien.pierre.boogz%sun.com Exp $
    43. 

  43.  */
    44. 

  44. 

  45. #ifndef _SECASN1_H_
    46. 

  46. #define _SECASN1_H_
    47. 

  47. 

  48. #include "utilrename.h"
    49. 

  49. #include "plarena.h"
    50. 

  50. 

  51. #include "seccomon.h"
    52. 

  52. #include "secasn1t.h"
    53. 

  53. 

  54. 

  55. /************************************************************************/
    56. 

  56. SEC_BEGIN_PROTOS
    57. 

  57. 

  58. /*
    59. 

  59.  * XXX These function prototypes need full, explanatory comments.
    60. 

  60.  */
    61. 

  61. 

  62. /*
    63. 

  63. ** Decoding.
    64. 

  64. */
    65. 

  65. 

  66. extern SEC_ASN1DecoderContext *SEC_ASN1DecoderStart(PRArenaPool *pool,
    67. 

  67. 						    void *dest,
    68. 

  68. 						    const SEC_ASN1Template *t);
    69. 

  69. 

  70. /* XXX char or unsigned char? */
    71. 

  71. extern SECStatus SEC_ASN1DecoderUpdate(SEC_ASN1DecoderContext *cx,
    72. 

  72. 				       const char *buf,
    73. 

  73. 				       unsigned long len);
    74. 

  74. 

  75. extern SECStatus SEC_ASN1DecoderFinish(SEC_ASN1DecoderContext *cx);
    76. 

  76. 

  77. /* Higher level code detected an error, abort the rest of the processing */
    78. 

  78. extern void SEC_ASN1DecoderAbort(SEC_ASN1DecoderContext *cx, int error);
    79. 

  79. 

  80. extern void SEC_ASN1DecoderSetFilterProc(SEC_ASN1DecoderContext *cx,
    81. 

  81. 					 SEC_ASN1WriteProc fn,
    82. 

  82. 					 void *arg, PRBool no_store);
    83. 

  83. 

  84. extern void SEC_ASN1DecoderClearFilterProc(SEC_ASN1DecoderContext *cx);
    85. 

  85. 

  86. extern void SEC_ASN1DecoderSetNotifyProc(SEC_ASN1DecoderContext *cx,
    87. 

  87. 					 SEC_ASN1NotifyProc fn,
    88. 

  88. 					 void *arg);
    89. 

  89. 

  90. extern void SEC_ASN1DecoderClearNotifyProc(SEC_ASN1DecoderContext *cx);
    91. 

  91. 

  92. extern SECStatus SEC_ASN1Decode(PRArenaPool *pool, void *dest,
    93. 

  93. 				const SEC_ASN1Template *t,
    94. 

  94. 				const char *buf, long len);
    95. 

  95. 

  96. /* Both classic ASN.1 and QuickDER have a feature that removes leading zeroes
    97. 

  97.    out of SEC_ASN1_INTEGER if the caller sets siUnsignedInteger in the type
    98. 

  98.    field of the target SECItem prior to calling the decoder. Otherwise, the
    99. 

  99.    type field is ignored and untouched. For SECItem that are dynamically
    100. 

  100.    allocated (from POINTER, SET OF, SEQUENCE OF) the decoder sets the type
    101. 

  101.    field to siBuffer. */
    102. 

  102. 

  103. extern SECStatus SEC_ASN1DecodeItem(PRArenaPool *pool, void *dest,
    104. 

  104. 				    const SEC_ASN1Template *t,
    105. 

  105. 				    const SECItem *src);
    106. 

  106. 

  107. extern SECStatus SEC_QuickDERDecodeItem(PRArenaPool* arena, void* dest,
    108. 

  108.                      const SEC_ASN1Template* templateEntry,
    109. 

  109.                      const SECItem* src);
    110. 

  110. 

  111. /*
    112. 

  112. ** Encoding.
    113. 

  113. */
    114. 

  114. 

  115. extern SEC_ASN1EncoderContext *SEC_ASN1EncoderStart(const void *src,
    116. 

  116. 						    const SEC_ASN1Template *t,
    117. 

  117. 						    SEC_ASN1WriteProc fn,
    118. 

  118. 						    void *output_arg);
    119. 

  119. 

  120. /* XXX char or unsigned char? */
    121. 

  121. extern SECStatus SEC_ASN1EncoderUpdate(SEC_ASN1EncoderContext *cx,
    122. 

  122. 				       const char *buf,
    123. 

  123. 				       unsigned long len);
    124. 

  124. 

  125. extern void SEC_ASN1EncoderFinish(SEC_ASN1EncoderContext *cx);
    126. 

  126. 

  127. /* Higher level code detected an error, abort the rest of the processing */
    128. 

  128. extern void SEC_ASN1EncoderAbort(SEC_ASN1EncoderContext *cx, int error);
    129. 

  129. 

  130. extern void SEC_ASN1EncoderSetNotifyProc(SEC_ASN1EncoderContext *cx,
    131. 

  131. 					 SEC_ASN1NotifyProc fn,
    132. 

  132. 					 void *arg);
    133. 

  133. 

  134. extern void SEC_ASN1EncoderClearNotifyProc(SEC_ASN1EncoderContext *cx);
    135. 

  135. 

  136. extern void SEC_ASN1EncoderSetStreaming(SEC_ASN1EncoderContext *cx);
    137. 

  137. 

  138. extern void SEC_ASN1EncoderClearStreaming(SEC_ASN1EncoderContext *cx);
    139. 

  139. 

  140. extern void sec_ASN1EncoderSetDER(SEC_ASN1EncoderContext *cx);
    141. 

  141. 

  142. extern void sec_ASN1EncoderClearDER(SEC_ASN1EncoderContext *cx);
    143. 

  143. 

  144. extern void SEC_ASN1EncoderSetTakeFromBuf(SEC_ASN1EncoderContext *cx);
    145. 

  145. 

  146. extern void SEC_ASN1EncoderClearTakeFromBuf(SEC_ASN1EncoderContext *cx);
    147. 

  147. 

  148. extern SECStatus SEC_ASN1Encode(const void *src, const SEC_ASN1Template *t,
    149. 

  149. 				SEC_ASN1WriteProc output_proc,
    150. 

  150. 				void *output_arg);
    151. 

  151. 

  152. extern SECItem * SEC_ASN1EncodeItem(PRArenaPool *pool, SECItem *dest,
    153. 

  153. 				    const void *src, const SEC_ASN1Template *t);
    154. 

  154. 

  155. extern SECItem * SEC_ASN1EncodeInteger(PRArenaPool *pool,
    156. 

  156. 				       SECItem *dest, long value);
    157. 

  157. 

  158. extern SECItem * SEC_ASN1EncodeUnsignedInteger(PRArenaPool *pool,
    159. 

  159. 					       SECItem *dest,
    160. 

  160. 					       unsigned long value);
    161. 

  161. 

  162. extern SECStatus SEC_ASN1DecodeInteger(SECItem *src,
    163. 

  163. 				       unsigned long *value);
    164. 

  164. 

  165. /*
    166. 

  166. ** Utilities.
    167. 

  167. */
    168. 

  168. 

  169. /*
    170. 

  170.  * We have a length that needs to be encoded; how many bytes will the
    171. 

  171.  * encoding take?
    172. 

  172.  */
    173. 

  173. extern int SEC_ASN1LengthLength (unsigned long len);
    174. 

  174. 

  175. /* encode the length and return the number of bytes we encoded. Buffer
    176. 

  176.  * must be pre allocated  */
    177. 

  177. extern int SEC_ASN1EncodeLength(unsigned char *buf,int value);
    178. 

  178. 

  179. /*
    180. 

  180.  * Find the appropriate subtemplate for the given template.
    181. 

  181.  * This may involve calling a "chooser" function, or it may just
    182. 

  182.  * be right there.  In either case, it is expected to *have* a
    183. 

  183.  * subtemplate; this is asserted in debug builds (in non-debug
    184. 

  184.  * builds, NULL will be returned).
    185. 

  185.  *
    186. 

  186.  * "thing" is a pointer to the structure being encoded/decoded
    187. 

  187.  * "encoding", when true, means that we are in the process of encoding
    188. 

  188.  *	(as opposed to in the process of decoding)
    189. 

  189.  */
    190. 

  190. extern const SEC_ASN1Template *
    191. 

  191. SEC_ASN1GetSubtemplate (const SEC_ASN1Template *inTemplate, void *thing,
    192. 

  192. 			PRBool encoding);
    193. 

  193. 

  194. /* whether the template is for a primitive type or a choice of
    195. 

  195.  * primitive types
    196. 

  196.  */
    197. 

  197. extern PRBool SEC_ASN1IsTemplateSimple(const SEC_ASN1Template *theTemplate);
    198. 

  198. 

  199. /************************************************************************/
    200. 

  200. 

  201. /*
    202. 

  202.  * Generic Templates
    203. 

  203.  * One for each of the simple types, plus a special one for ANY, plus:
    204. 

  204.  *	- a pointer to each one of those
    205. 

  205.  *	- a set of each one of those
    206. 

  206.  *	- a sequence of each one of those
    207. 

  207.  *
    208. 

  208.  * Note that these are alphabetical (case insensitive); please add new
    209. 

  209.  * ones in the appropriate place.
    210. 

  210.  */
    211. 

  211. 

  212. extern const SEC_ASN1Template SEC_AnyTemplate[];
    213. 

  213. extern const SEC_ASN1Template SEC_BitStringTemplate[];
    214. 

  214. extern const SEC_ASN1Template SEC_BMPStringTemplate[];
    215. 

  215. extern const SEC_ASN1Template SEC_BooleanTemplate[];
    216. 

  216. extern const SEC_ASN1Template SEC_EnumeratedTemplate[];
    217. 

  217. extern const SEC_ASN1Template SEC_GeneralizedTimeTemplate[];
    218. 

  218. extern const SEC_ASN1Template SEC_IA5StringTemplate[];
    219. 

  219. extern const SEC_ASN1Template SEC_IntegerTemplate[];
    220. 

  220. extern const SEC_ASN1Template SEC_NullTemplate[];
    221. 

  221. extern const SEC_ASN1Template SEC_ObjectIDTemplate[];
    222. 

  222. extern const SEC_ASN1Template SEC_OctetStringTemplate[];
    223. 

  223. extern const SEC_ASN1Template SEC_PrintableStringTemplate[];
    224. 

  224. extern const SEC_ASN1Template SEC_T61StringTemplate[];
    225. 

  225. extern const SEC_ASN1Template SEC_UniversalStringTemplate[];
    226. 

  226. extern const SEC_ASN1Template SEC_UTCTimeTemplate[];
    227. 

  227. extern const SEC_ASN1Template SEC_UTF8StringTemplate[];
    228. 

  228. extern const SEC_ASN1Template SEC_VisibleStringTemplate[];
    229. 

  229. 

  230. extern const SEC_ASN1Template SEC_PointerToAnyTemplate[];
    231. 

  231. extern const SEC_ASN1Template SEC_PointerToBitStringTemplate[];
    232. 

  232. extern const SEC_ASN1Template SEC_PointerToBMPStringTemplate[];
    233. 

  233. extern const SEC_ASN1Template SEC_PointerToBooleanTemplate[];
    234. 

  234. extern const SEC_ASN1Template SEC_PointerToEnumeratedTemplate[];
    235. 

  235. extern const SEC_ASN1Template SEC_PointerToGeneralizedTimeTemplate[];
    236. 

  236. extern const SEC_ASN1Template SEC_PointerToIA5StringTemplate[];
    237. 

  237. extern const SEC_ASN1Template SEC_PointerToIntegerTemplate[];
    238. 

  238. extern const SEC_ASN1Template SEC_PointerToNullTemplate[];
    239. 

  239. extern const SEC_ASN1Template SEC_PointerToObjectIDTemplate[];
    240. 

  240. extern const SEC_ASN1Template SEC_PointerToOctetStringTemplate[];
    241. 

  241. extern const SEC_ASN1Template SEC_PointerToPrintableStringTemplate[];
    242. 

  242. extern const SEC_ASN1Template SEC_PointerToT61StringTemplate[];
    243. 

  243. extern const SEC_ASN1Template SEC_PointerToUniversalStringTemplate[];
    244. 

  244. extern const SEC_ASN1Template SEC_PointerToUTCTimeTemplate[];
    245. 

  245. extern const SEC_ASN1Template SEC_PointerToUTF8StringTemplate[];
    246. 

  246. extern const SEC_ASN1Template SEC_PointerToVisibleStringTemplate[];
    247. 

  247. 

  248. extern const SEC_ASN1Template SEC_SequenceOfAnyTemplate[];
    249. 

  249. extern const SEC_ASN1Template SEC_SequenceOfBitStringTemplate[];
    250. 

  250. extern const SEC_ASN1Template SEC_SequenceOfBMPStringTemplate[];
    251. 

  251. extern const SEC_ASN1Template SEC_SequenceOfBooleanTemplate[];
    252. 

  252. extern const SEC_ASN1Template SEC_SequenceOfEnumeratedTemplate[];
    253. 

  253. extern const SEC_ASN1Template SEC_SequenceOfGeneralizedTimeTemplate[];
    254. 

  254. extern const SEC_ASN1Template SEC_SequenceOfIA5StringTemplate[];
    255. 

  255. extern const SEC_ASN1Template SEC_SequenceOfIntegerTemplate[];
    256. 

  256. extern const SEC_ASN1Template SEC_SequenceOfNullTemplate[];
    257. 

  257. extern const SEC_ASN1Template SEC_SequenceOfObjectIDTemplate[];
    258. 

  258. extern const SEC_ASN1Template SEC_SequenceOfOctetStringTemplate[];
    259. 

  259. extern const SEC_ASN1Template SEC_SequenceOfPrintableStringTemplate[];
    260. 

  260. extern const SEC_ASN1Template SEC_SequenceOfT61StringTemplate[];
    261. 

  261. extern const SEC_ASN1Template SEC_SequenceOfUniversalStringTemplate[];
    262. 

  262. extern const SEC_ASN1Template SEC_SequenceOfUTCTimeTemplate[];
    263. 

  263. extern const SEC_ASN1Template SEC_SequenceOfUTF8StringTemplate[];
    264. 

  264. extern const SEC_ASN1Template SEC_SequenceOfVisibleStringTemplate[];
    265. 

  265. 

  266. extern const SEC_ASN1Template SEC_SetOfAnyTemplate[];
    267. 

  267. extern const SEC_ASN1Template SEC_SetOfBitStringTemplate[];
    268. 

  268. extern const SEC_ASN1Template SEC_SetOfBMPStringTemplate[];
    269. 

  269. extern const SEC_ASN1Template SEC_SetOfBooleanTemplate[];
    270. 

  270. extern const SEC_ASN1Template SEC_SetOfEnumeratedTemplate[];
    271. 

  271. extern const SEC_ASN1Template SEC_SetOfGeneralizedTimeTemplate[];
    272. 

  272. extern const SEC_ASN1Template SEC_SetOfIA5StringTemplate[];
    273. 

  273. extern const SEC_ASN1Template SEC_SetOfIntegerTemplate[];
    274. 

  274. extern const SEC_ASN1Template SEC_SetOfNullTemplate[];
    275. 

  275. extern const SEC_ASN1Template SEC_SetOfObjectIDTemplate[];
    276. 

  276. extern const SEC_ASN1Template SEC_SetOfOctetStringTemplate[];
    277. 

  277. extern const SEC_ASN1Template SEC_SetOfPrintableStringTemplate[];
    278. 

  278. extern const SEC_ASN1Template SEC_SetOfT61StringTemplate[];
    279. 

  279. extern const SEC_ASN1Template SEC_SetOfUniversalStringTemplate[];
    280. 

  280. extern const SEC_ASN1Template SEC_SetOfUTCTimeTemplate[];
    281. 

  281. extern const SEC_ASN1Template SEC_SetOfUTF8StringTemplate[];
    282. 

  282. extern const SEC_ASN1Template SEC_SetOfVisibleStringTemplate[];
    283. 

  283. 

  284. /*
    285. 

  285.  * Template for skipping a subitem; this only makes sense when decoding.
    286. 

  286.  */
    287. 

  287. extern const SEC_ASN1Template SEC_SkipTemplate[];
    288. 

  288. 

  289. /* These functions simply return the address of the above-declared templates.
    290. 

  290. ** This is necessary for Windows DLLs.  Sigh.
    291. 

  291. */
    292. 

  292. SEC_ASN1_CHOOSER_DECLARE(SEC_AnyTemplate)
    293. 

  293. SEC_ASN1_CHOOSER_DECLARE(SEC_BMPStringTemplate)
    294. 

  294. SEC_ASN1_CHOOSER_DECLARE(SEC_BooleanTemplate)
    295. 

  295. SEC_ASN1_CHOOSER_DECLARE(SEC_BitStringTemplate)
    296. 

  296. SEC_ASN1_CHOOSER_DECLARE(SEC_GeneralizedTimeTemplate)
    297. 

  297. SEC_ASN1_CHOOSER_DECLARE(SEC_IA5StringTemplate)
    298. 

  298. SEC_ASN1_CHOOSER_DECLARE(SEC_IntegerTemplate)
    299. 

  299. SEC_ASN1_CHOOSER_DECLARE(SEC_NullTemplate)
    300. 

  300. SEC_ASN1_CHOOSER_DECLARE(SEC_ObjectIDTemplate)
    301. 

  301. SEC_ASN1_CHOOSER_DECLARE(SEC_OctetStringTemplate)
    302. 

  302. SEC_ASN1_CHOOSER_DECLARE(SEC_UTCTimeTemplate)
    303. 

  303. SEC_ASN1_CHOOSER_DECLARE(SEC_UTF8StringTemplate)
    304. 

  304. 

  305. SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToAnyTemplate)
    306. 

  306. SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToOctetStringTemplate)
    307. 

  307. 

  308. SEC_ASN1_CHOOSER_DECLARE(SEC_SetOfAnyTemplate)
    309. 

  309. 

  310. SEC_ASN1_CHOOSER_DECLARE(SEC_EnumeratedTemplate)
    311. 

  311. SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToEnumeratedTemplate)
    312. 

  312. SEC_ASN1_CHOOSER_DECLARE(SEC_SequenceOfAnyTemplate)
    313. 

  313. SEC_ASN1_CHOOSER_DECLARE(SEC_SequenceOfObjectIDTemplate)
    314. 

  314. SEC_ASN1_CHOOSER_DECLARE(SEC_SkipTemplate)
    315. 

  315. SEC_ASN1_CHOOSER_DECLARE(SEC_UniversalStringTemplate)
    316. 

  316. SEC_ASN1_CHOOSER_DECLARE(SEC_PrintableStringTemplate)
    317. 

  317. SEC_ASN1_CHOOSER_DECLARE(SEC_T61StringTemplate)
    318. 

  318. SEC_ASN1_CHOOSER_DECLARE(SEC_PointerToGeneralizedTimeTemplate)
    319. 

  319. SEC_END_PROTOS
    320. 

  320. #endif /* _SECASN1_H_ */
    321.