asn1.h 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607
  1. /**
  2. * \file asn1.h
  3. *
  4. * \brief Generic ASN.1 parsing
  5. */
  6. /*
  7. * Copyright The Mbed TLS Contributors
  8. * SPDX-License-Identifier: Apache-2.0
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  11. * not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. */
  22. #ifndef MBEDTLS_ASN1_H
  23. #define MBEDTLS_ASN1_H
  24. #if !defined(MBEDTLS_CONFIG_FILE)
  25. #include "mbedtls/config.h"
  26. #else
  27. #include MBEDTLS_CONFIG_FILE
  28. #endif
  29. #include <stddef.h>
  30. #if defined(MBEDTLS_BIGNUM_C)
  31. #include "mbedtls/bignum.h"
  32. #endif
  33. /**
  34. * \addtogroup asn1_module
  35. * \{
  36. */
  37. /**
  38. * \name ASN1 Error codes
  39. * These error codes are OR'ed to X509 error codes for
  40. * higher error granularity.
  41. * ASN1 is a standard to specify data structures.
  42. * \{
  43. */
  44. #define MBEDTLS_ERR_ASN1_OUT_OF_DATA -0x0060 /**< Out of data when parsing an ASN1 data structure. */
  45. #define MBEDTLS_ERR_ASN1_UNEXPECTED_TAG -0x0062 /**< ASN1 tag was of an unexpected value. */
  46. #define MBEDTLS_ERR_ASN1_INVALID_LENGTH -0x0064 /**< Error when trying to determine the length or invalid length. */
  47. #define MBEDTLS_ERR_ASN1_LENGTH_MISMATCH -0x0066 /**< Actual length differs from expected length. */
  48. #define MBEDTLS_ERR_ASN1_INVALID_DATA -0x0068 /**< Data is invalid. */
  49. #define MBEDTLS_ERR_ASN1_ALLOC_FAILED -0x006A /**< Memory allocation failed */
  50. #define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL -0x006C /**< Buffer too small when writing ASN.1 data structure. */
  51. /* \} name */
  52. /**
  53. * \name DER constants
  54. * These constants comply with the DER encoded ASN.1 type tags.
  55. * DER encoding uses hexadecimal representation.
  56. * An example DER sequence is:\n
  57. * - 0x02 -- tag indicating INTEGER
  58. * - 0x01 -- length in octets
  59. * - 0x05 -- value
  60. * Such sequences are typically read into \c ::mbedtls_x509_buf.
  61. * \{
  62. */
  63. #define MBEDTLS_ASN1_BOOLEAN 0x01
  64. #define MBEDTLS_ASN1_INTEGER 0x02
  65. #define MBEDTLS_ASN1_BIT_STRING 0x03
  66. #define MBEDTLS_ASN1_OCTET_STRING 0x04
  67. #define MBEDTLS_ASN1_NULL 0x05
  68. #define MBEDTLS_ASN1_OID 0x06
  69. #define MBEDTLS_ASN1_ENUMERATED 0x0A
  70. #define MBEDTLS_ASN1_UTF8_STRING 0x0C
  71. #define MBEDTLS_ASN1_SEQUENCE 0x10
  72. #define MBEDTLS_ASN1_SET 0x11
  73. #define MBEDTLS_ASN1_PRINTABLE_STRING 0x13
  74. #define MBEDTLS_ASN1_T61_STRING 0x14
  75. #define MBEDTLS_ASN1_IA5_STRING 0x16
  76. #define MBEDTLS_ASN1_UTC_TIME 0x17
  77. #define MBEDTLS_ASN1_GENERALIZED_TIME 0x18
  78. #define MBEDTLS_ASN1_UNIVERSAL_STRING 0x1C
  79. #define MBEDTLS_ASN1_BMP_STRING 0x1E
  80. #define MBEDTLS_ASN1_PRIMITIVE 0x00
  81. #define MBEDTLS_ASN1_CONSTRUCTED 0x20
  82. #define MBEDTLS_ASN1_CONTEXT_SPECIFIC 0x80
  83. /* Slightly smaller way to check if tag is a string tag
  84. * compared to canonical implementation. */
  85. #define MBEDTLS_ASN1_IS_STRING_TAG( tag ) \
  86. ( ( tag ) < 32u && ( \
  87. ( ( 1u << ( tag ) ) & ( ( 1u << MBEDTLS_ASN1_BMP_STRING ) | \
  88. ( 1u << MBEDTLS_ASN1_UTF8_STRING ) | \
  89. ( 1u << MBEDTLS_ASN1_T61_STRING ) | \
  90. ( 1u << MBEDTLS_ASN1_IA5_STRING ) | \
  91. ( 1u << MBEDTLS_ASN1_UNIVERSAL_STRING ) | \
  92. ( 1u << MBEDTLS_ASN1_PRINTABLE_STRING ) | \
  93. ( 1u << MBEDTLS_ASN1_BIT_STRING ) ) ) != 0 ) )
  94. /*
  95. * Bit masks for each of the components of an ASN.1 tag as specified in
  96. * ITU X.690 (08/2015), section 8.1 "General rules for encoding",
  97. * paragraph 8.1.2.2:
  98. *
  99. * Bit 8 7 6 5 1
  100. * +-------+-----+------------+
  101. * | Class | P/C | Tag number |
  102. * +-------+-----+------------+
  103. */
  104. #define MBEDTLS_ASN1_TAG_CLASS_MASK 0xC0
  105. #define MBEDTLS_ASN1_TAG_PC_MASK 0x20
  106. #define MBEDTLS_ASN1_TAG_VALUE_MASK 0x1F
  107. /* \} name */
  108. /* \} addtogroup asn1_module */
  109. /** Returns the size of the binary string, without the trailing \\0 */
  110. #define MBEDTLS_OID_SIZE(x) (sizeof(x) - 1)
  111. /**
  112. * Compares an mbedtls_asn1_buf structure to a reference OID.
  113. *
  114. * Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a
  115. * 'unsigned char *oid' here!
  116. */
  117. #define MBEDTLS_OID_CMP(oid_str, oid_buf) \
  118. ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf)->len ) || \
  119. memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) != 0 )
  120. #define MBEDTLS_OID_CMP_RAW(oid_str, oid_buf, oid_buf_len) \
  121. ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf_len) ) || \
  122. memcmp( (oid_str), (oid_buf), (oid_buf_len) ) != 0 )
  123. #ifdef __cplusplus
  124. extern "C" {
  125. #endif
  126. /**
  127. * \name Functions to parse ASN.1 data structures
  128. * \{
  129. */
  130. /**
  131. * Type-length-value structure that allows for ASN1 using DER.
  132. */
  133. typedef struct mbedtls_asn1_buf
  134. {
  135. int tag; /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */
  136. size_t len; /**< ASN1 length, in octets. */
  137. unsigned char *p; /**< ASN1 data, e.g. in ASCII. */
  138. }
  139. mbedtls_asn1_buf;
  140. /**
  141. * Container for ASN1 bit strings.
  142. */
  143. typedef struct mbedtls_asn1_bitstring
  144. {
  145. size_t len; /**< ASN1 length, in octets. */
  146. unsigned char unused_bits; /**< Number of unused bits at the end of the string */
  147. unsigned char *p; /**< Raw ASN1 data for the bit string */
  148. }
  149. mbedtls_asn1_bitstring;
  150. /**
  151. * Container for a sequence of ASN.1 items
  152. */
  153. typedef struct mbedtls_asn1_sequence
  154. {
  155. mbedtls_asn1_buf buf; /**< Buffer containing the given ASN.1 item. */
  156. struct mbedtls_asn1_sequence *next; /**< The next entry in the sequence. */
  157. }
  158. mbedtls_asn1_sequence;
  159. /**
  160. * Container for a sequence or list of 'named' ASN.1 data items
  161. */
  162. typedef struct mbedtls_asn1_named_data
  163. {
  164. mbedtls_asn1_buf oid; /**< The object identifier. */
  165. mbedtls_asn1_buf val; /**< The named value. */
  166. struct mbedtls_asn1_named_data *next; /**< The next entry in the sequence. */
  167. unsigned char next_merged; /**< Merge next item into the current one? */
  168. }
  169. mbedtls_asn1_named_data;
  170. /**
  171. * \brief Get the length of an ASN.1 element.
  172. * Updates the pointer to immediately behind the length.
  173. *
  174. * \param p On entry, \c *p points to the first byte of the length,
  175. * i.e. immediately after the tag.
  176. * On successful completion, \c *p points to the first byte
  177. * after the length, i.e. the first byte of the content.
  178. * On error, the value of \c *p is undefined.
  179. * \param end End of data.
  180. * \param len On successful completion, \c *len contains the length
  181. * read from the ASN.1 input.
  182. *
  183. * \return 0 if successful.
  184. * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
  185. * would end beyond \p end.
  186. * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable.
  187. */
  188. int mbedtls_asn1_get_len( unsigned char **p,
  189. const unsigned char *end,
  190. size_t *len );
  191. /**
  192. * \brief Get the tag and length of the element.
  193. * Check for the requested tag.
  194. * Updates the pointer to immediately behind the tag and length.
  195. *
  196. * \param p On entry, \c *p points to the start of the ASN.1 element.
  197. * On successful completion, \c *p points to the first byte
  198. * after the length, i.e. the first byte of the content.
  199. * On error, the value of \c *p is undefined.
  200. * \param end End of data.
  201. * \param len On successful completion, \c *len contains the length
  202. * read from the ASN.1 input.
  203. * \param tag The expected tag.
  204. *
  205. * \return 0 if successful.
  206. * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the data does not start
  207. * with the requested tag.
  208. * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
  209. * would end beyond \p end.
  210. * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable.
  211. */
  212. int mbedtls_asn1_get_tag( unsigned char **p,
  213. const unsigned char *end,
  214. size_t *len, int tag );
  215. /**
  216. * \brief Retrieve a boolean ASN.1 tag and its value.
  217. * Updates the pointer to immediately behind the full tag.
  218. *
  219. * \param p On entry, \c *p points to the start of the ASN.1 element.
  220. * On successful completion, \c *p points to the first byte
  221. * beyond the ASN.1 element.
  222. * On error, the value of \c *p is undefined.
  223. * \param end End of data.
  224. * \param val On success, the parsed value (\c 0 or \c 1).
  225. *
  226. * \return 0 if successful.
  227. * \return An ASN.1 error code if the input does not start with
  228. * a valid ASN.1 BOOLEAN.
  229. */
  230. int mbedtls_asn1_get_bool( unsigned char **p,
  231. const unsigned char *end,
  232. int *val );
  233. /**
  234. * \brief Retrieve an integer ASN.1 tag and its value.
  235. * Updates the pointer to immediately behind the full tag.
  236. *
  237. * \param p On entry, \c *p points to the start of the ASN.1 element.
  238. * On successful completion, \c *p points to the first byte
  239. * beyond the ASN.1 element.
  240. * On error, the value of \c *p is undefined.
  241. * \param end End of data.
  242. * \param val On success, the parsed value.
  243. *
  244. * \return 0 if successful.
  245. * \return An ASN.1 error code if the input does not start with
  246. * a valid ASN.1 INTEGER.
  247. * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
  248. * not fit in an \c int.
  249. */
  250. int mbedtls_asn1_get_int( unsigned char **p,
  251. const unsigned char *end,
  252. int *val );
  253. /**
  254. * \brief Retrieve an enumerated ASN.1 tag and its value.
  255. * Updates the pointer to immediately behind the full tag.
  256. *
  257. * \param p On entry, \c *p points to the start of the ASN.1 element.
  258. * On successful completion, \c *p points to the first byte
  259. * beyond the ASN.1 element.
  260. * On error, the value of \c *p is undefined.
  261. * \param end End of data.
  262. * \param val On success, the parsed value.
  263. *
  264. * \return 0 if successful.
  265. * \return An ASN.1 error code if the input does not start with
  266. * a valid ASN.1 ENUMERATED.
  267. * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
  268. * not fit in an \c int.
  269. */
  270. int mbedtls_asn1_get_enum( unsigned char **p,
  271. const unsigned char *end,
  272. int *val );
  273. /**
  274. * \brief Retrieve a bitstring ASN.1 tag and its value.
  275. * Updates the pointer to immediately behind the full tag.
  276. *
  277. * \param p On entry, \c *p points to the start of the ASN.1 element.
  278. * On successful completion, \c *p is equal to \p end.
  279. * On error, the value of \c *p is undefined.
  280. * \param end End of data.
  281. * \param bs On success, ::mbedtls_asn1_bitstring information about
  282. * the parsed value.
  283. *
  284. * \return 0 if successful.
  285. * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains
  286. * extra data after a valid BIT STRING.
  287. * \return An ASN.1 error code if the input does not start with
  288. * a valid ASN.1 BIT STRING.
  289. */
  290. int mbedtls_asn1_get_bitstring( unsigned char **p, const unsigned char *end,
  291. mbedtls_asn1_bitstring *bs );
  292. /**
  293. * \brief Retrieve a bitstring ASN.1 tag without unused bits and its
  294. * value.
  295. * Updates the pointer to the beginning of the bit/octet string.
  296. *
  297. * \param p On entry, \c *p points to the start of the ASN.1 element.
  298. * On successful completion, \c *p points to the first byte
  299. * of the content of the BIT STRING.
  300. * On error, the value of \c *p is undefined.
  301. * \param end End of data.
  302. * \param len On success, \c *len is the length of the content in bytes.
  303. *
  304. * \return 0 if successful.
  305. * \return #MBEDTLS_ERR_ASN1_INVALID_DATA if the input starts with
  306. * a valid BIT STRING with a nonzero number of unused bits.
  307. * \return An ASN.1 error code if the input does not start with
  308. * a valid ASN.1 BIT STRING.
  309. */
  310. int mbedtls_asn1_get_bitstring_null( unsigned char **p,
  311. const unsigned char *end,
  312. size_t *len );
  313. /**
  314. * \brief Parses and splits an ASN.1 "SEQUENCE OF <tag>".
  315. * Updates the pointer to immediately behind the full sequence tag.
  316. *
  317. * This function allocates memory for the sequence elements. You can free
  318. * the allocated memory with mbedtls_asn1_sequence_free().
  319. *
  320. * \note On error, this function may return a partial list in \p cur.
  321. * You must set `cur->next = NULL` before calling this function!
  322. * Otherwise it is impossible to distinguish a previously non-null
  323. * pointer from a pointer to an object allocated by this function.
  324. *
  325. * \note If the sequence is empty, this function does not modify
  326. * \c *cur. If the sequence is valid and non-empty, this
  327. * function sets `cur->buf.tag` to \p tag. This allows
  328. * callers to distinguish between an empty sequence and
  329. * a one-element sequence.
  330. *
  331. * \param p On entry, \c *p points to the start of the ASN.1 element.
  332. * On successful completion, \c *p is equal to \p end.
  333. * On error, the value of \c *p is undefined.
  334. * \param end End of data.
  335. * \param cur A ::mbedtls_asn1_sequence which this function fills.
  336. * When this function returns, \c *cur is the head of a linked
  337. * list. Each node in this list is allocated with
  338. * mbedtls_calloc() apart from \p cur itself, and should
  339. * therefore be freed with mbedtls_free().
  340. * The list describes the content of the sequence.
  341. * The head of the list (i.e. \c *cur itself) describes the
  342. * first element, `*cur->next` describes the second element, etc.
  343. * For each element, `buf.tag == tag`, `buf.len` is the length
  344. * of the content of the content of the element, and `buf.p`
  345. * points to the first byte of the content (i.e. immediately
  346. * past the length of the element).
  347. * Note that list elements may be allocated even on error.
  348. * \param tag Each element of the sequence must have this tag.
  349. *
  350. * \return 0 if successful.
  351. * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains
  352. * extra data after a valid SEQUENCE OF \p tag.
  353. * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts with
  354. * an ASN.1 SEQUENCE in which an element has a tag that
  355. * is different from \p tag.
  356. * \return #MBEDTLS_ERR_ASN1_ALLOC_FAILED if a memory allocation failed.
  357. * \return An ASN.1 error code if the input does not start with
  358. * a valid ASN.1 SEQUENCE.
  359. */
  360. int mbedtls_asn1_get_sequence_of( unsigned char **p,
  361. const unsigned char *end,
  362. mbedtls_asn1_sequence *cur,
  363. int tag );
  364. /**
  365. * \brief Free a heap-allocated linked list presentation of
  366. * an ASN.1 sequence, including the first element.
  367. *
  368. * There are two common ways to manage the memory used for the representation
  369. * of a parsed ASN.1 sequence:
  370. * - Allocate a head node `mbedtls_asn1_sequence *head` with mbedtls_calloc().
  371. * Pass this node as the `cur` argument to mbedtls_asn1_get_sequence_of().
  372. * When you have finished processing the sequence,
  373. * call mbedtls_asn1_sequence_free() on `head`.
  374. * - Allocate a head node `mbedtls_asn1_sequence *head` in any manner,
  375. * for example on the stack. Make sure that `head->next == NULL`.
  376. * Pass `head` as the `cur` argument to mbedtls_asn1_get_sequence_of().
  377. * When you have finished processing the sequence,
  378. * call mbedtls_asn1_sequence_free() on `head->cur`,
  379. * then free `head` itself in the appropriate manner.
  380. *
  381. * \param seq The address of the first sequence component. This may
  382. * be \c NULL, in which case this functions returns
  383. * immediately.
  384. */
  385. void mbedtls_asn1_sequence_free( mbedtls_asn1_sequence *seq );
  386. /**
  387. * \brief Traverse an ASN.1 SEQUENCE container and
  388. * call a callback for each entry.
  389. *
  390. * This function checks that the input is a SEQUENCE of elements that
  391. * each have a "must" tag, and calls a callback function on the elements
  392. * that have a "may" tag.
  393. *
  394. * For example, to validate that the input is a SEQUENCE of `tag1` and call
  395. * `cb` on each element, use
  396. * ```
  397. * mbedtls_asn1_traverse_sequence_of(&p, end, 0xff, tag1, 0, 0, cb, ctx);
  398. * ```
  399. *
  400. * To validate that the input is a SEQUENCE of ANY and call `cb` on
  401. * each element, use
  402. * ```
  403. * mbedtls_asn1_traverse_sequence_of(&p, end, 0, 0, 0, 0, cb, ctx);
  404. * ```
  405. *
  406. * To validate that the input is a SEQUENCE of CHOICE {NULL, OCTET STRING}
  407. * and call `cb` on each element that is an OCTET STRING, use
  408. * ```
  409. * mbedtls_asn1_traverse_sequence_of(&p, end, 0xfe, 0x04, 0xff, 0x04, cb, ctx);
  410. * ```
  411. *
  412. * The callback is called on the elements with a "may" tag from left to
  413. * right. If the input is not a valid SEQUENCE of elements with a "must" tag,
  414. * the callback is called on the elements up to the leftmost point where
  415. * the input is invalid.
  416. *
  417. * \warning This function is still experimental and may change
  418. * at any time.
  419. *
  420. * \param p The address of the pointer to the beginning of
  421. * the ASN.1 SEQUENCE header. This is updated to
  422. * point to the end of the ASN.1 SEQUENCE container
  423. * on a successful invocation.
  424. * \param end The end of the ASN.1 SEQUENCE container.
  425. * \param tag_must_mask A mask to be applied to the ASN.1 tags found within
  426. * the SEQUENCE before comparing to \p tag_must_value.
  427. * \param tag_must_val The required value of each ASN.1 tag found in the
  428. * SEQUENCE, after masking with \p tag_must_mask.
  429. * Mismatching tags lead to an error.
  430. * For example, a value of \c 0 for both \p tag_must_mask
  431. * and \p tag_must_val means that every tag is allowed,
  432. * while a value of \c 0xFF for \p tag_must_mask means
  433. * that \p tag_must_val is the only allowed tag.
  434. * \param tag_may_mask A mask to be applied to the ASN.1 tags found within
  435. * the SEQUENCE before comparing to \p tag_may_value.
  436. * \param tag_may_val The desired value of each ASN.1 tag found in the
  437. * SEQUENCE, after masking with \p tag_may_mask.
  438. * Mismatching tags will be silently ignored.
  439. * For example, a value of \c 0 for \p tag_may_mask and
  440. * \p tag_may_val means that any tag will be considered,
  441. * while a value of \c 0xFF for \p tag_may_mask means
  442. * that all tags with value different from \p tag_may_val
  443. * will be ignored.
  444. * \param cb The callback to trigger for each component
  445. * in the ASN.1 SEQUENCE that matches \p tag_may_val.
  446. * The callback function is called with the following
  447. * parameters:
  448. * - \p ctx.
  449. * - The tag of the current element.
  450. * - A pointer to the start of the current element's
  451. * content inside the input.
  452. * - The length of the content of the current element.
  453. * If the callback returns a non-zero value,
  454. * the function stops immediately,
  455. * forwarding the callback's return value.
  456. * \param ctx The context to be passed to the callback \p cb.
  457. *
  458. * \return \c 0 if successful the entire ASN.1 SEQUENCE
  459. * was traversed without parsing or callback errors.
  460. * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input
  461. * contains extra data after a valid SEQUENCE
  462. * of elements with an accepted tag.
  463. * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts
  464. * with an ASN.1 SEQUENCE in which an element has a tag
  465. * that is not accepted.
  466. * \return An ASN.1 error code if the input does not start with
  467. * a valid ASN.1 SEQUENCE.
  468. * \return A non-zero error code forwarded from the callback
  469. * \p cb in case the latter returns a non-zero value.
  470. */
  471. int mbedtls_asn1_traverse_sequence_of(
  472. unsigned char **p,
  473. const unsigned char *end,
  474. unsigned char tag_must_mask, unsigned char tag_must_val,
  475. unsigned char tag_may_mask, unsigned char tag_may_val,
  476. int (*cb)( void *ctx, int tag,
  477. unsigned char* start, size_t len ),
  478. void *ctx );
  479. #if defined(MBEDTLS_BIGNUM_C)
  480. /**
  481. * \brief Retrieve an integer ASN.1 tag and its value.
  482. * Updates the pointer to immediately behind the full tag.
  483. *
  484. * \param p On entry, \c *p points to the start of the ASN.1 element.
  485. * On successful completion, \c *p points to the first byte
  486. * beyond the ASN.1 element.
  487. * On error, the value of \c *p is undefined.
  488. * \param end End of data.
  489. * \param X On success, the parsed value.
  490. *
  491. * \return 0 if successful.
  492. * \return An ASN.1 error code if the input does not start with
  493. * a valid ASN.1 INTEGER.
  494. * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
  495. * not fit in an \c int.
  496. * \return An MPI error code if the parsed value is too large.
  497. */
  498. int mbedtls_asn1_get_mpi( unsigned char **p,
  499. const unsigned char *end,
  500. mbedtls_mpi *X );
  501. #endif /* MBEDTLS_BIGNUM_C */
  502. /**
  503. * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence.
  504. * Updates the pointer to immediately behind the full
  505. * AlgorithmIdentifier.
  506. *
  507. * \param p On entry, \c *p points to the start of the ASN.1 element.
  508. * On successful completion, \c *p points to the first byte
  509. * beyond the AlgorithmIdentifier element.
  510. * On error, the value of \c *p is undefined.
  511. * \param end End of data.
  512. * \param alg The buffer to receive the OID.
  513. * \param params The buffer to receive the parameters.
  514. * This is zeroized if there are no parameters.
  515. *
  516. * \return 0 if successful or a specific ASN.1 or MPI error code.
  517. */
  518. int mbedtls_asn1_get_alg( unsigned char **p,
  519. const unsigned char *end,
  520. mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params );
  521. /**
  522. * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no
  523. * params.
  524. * Updates the pointer to immediately behind the full
  525. * AlgorithmIdentifier.
  526. *
  527. * \param p On entry, \c *p points to the start of the ASN.1 element.
  528. * On successful completion, \c *p points to the first byte
  529. * beyond the AlgorithmIdentifier element.
  530. * On error, the value of \c *p is undefined.
  531. * \param end End of data.
  532. * \param alg The buffer to receive the OID.
  533. *
  534. * \return 0 if successful or a specific ASN.1 or MPI error code.
  535. */
  536. int mbedtls_asn1_get_alg_null( unsigned char **p,
  537. const unsigned char *end,
  538. mbedtls_asn1_buf *alg );
  539. /**
  540. * \brief Find a specific named_data entry in a sequence or list based on
  541. * the OID.
  542. *
  543. * \param list The list to seek through
  544. * \param oid The OID to look for
  545. * \param len Size of the OID
  546. *
  547. * \return NULL if not found, or a pointer to the existing entry.
  548. */
  549. mbedtls_asn1_named_data *mbedtls_asn1_find_named_data( mbedtls_asn1_named_data *list,
  550. const char *oid, size_t len );
  551. /**
  552. * \brief Free a mbedtls_asn1_named_data entry
  553. *
  554. * \param entry The named data entry to free.
  555. * This function calls mbedtls_free() on
  556. * `entry->oid.p` and `entry->val.p`.
  557. */
  558. void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry );
  559. /**
  560. * \brief Free all entries in a mbedtls_asn1_named_data list.
  561. *
  562. * \param head Pointer to the head of the list of named data entries to free.
  563. * This function calls mbedtls_asn1_free_named_data() and
  564. * mbedtls_free() on each list element and
  565. * sets \c *head to \c NULL.
  566. */
  567. void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head );
  568. #ifdef __cplusplus
  569. }
  570. #endif
  571. #endif /* asn1.h */