asn1write.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329
  1. /**
  2. * \file asn1write.h
  3. *
  4. * \brief ASN.1 buffer writing functionality
  5. */
  6. /*
  7. * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  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. * This file is part of mbed TLS (https://tls.mbed.org)
  23. */
  24. #ifndef MBEDTLS_ASN1_WRITE_H
  25. #define MBEDTLS_ASN1_WRITE_H
  26. #if !defined(MBEDTLS_CONFIG_FILE)
  27. #include "config.h"
  28. #else
  29. #include MBEDTLS_CONFIG_FILE
  30. #endif
  31. #include "asn1.h"
  32. #define MBEDTLS_ASN1_CHK_ADD(g, f) \
  33. do \
  34. { \
  35. if( ( ret = (f) ) < 0 ) \
  36. return( ret ); \
  37. else \
  38. (g) += ret; \
  39. } while( 0 )
  40. #ifdef __cplusplus
  41. extern "C" {
  42. #endif
  43. /**
  44. * \brief Write a length field in ASN.1 format.
  45. *
  46. * \note This function works backwards in data buffer.
  47. *
  48. * \param p The reference to the current position pointer.
  49. * \param start The start of the buffer, for bounds-checking.
  50. * \param len The length value to write.
  51. *
  52. * \return The number of bytes written to \p p on success.
  53. * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  54. */
  55. int mbedtls_asn1_write_len( unsigned char **p, unsigned char *start,
  56. size_t len );
  57. /**
  58. * \brief Write an ASN.1 tag in ASN.1 format.
  59. *
  60. * \note This function works backwards in data buffer.
  61. *
  62. * \param p The reference to the current position pointer.
  63. * \param start The start of the buffer, for bounds-checking.
  64. * \param tag The tag to write.
  65. *
  66. * \return The number of bytes written to \p p on success.
  67. * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  68. */
  69. int mbedtls_asn1_write_tag( unsigned char **p, unsigned char *start,
  70. unsigned char tag );
  71. /**
  72. * \brief Write raw buffer data.
  73. *
  74. * \note This function works backwards in data buffer.
  75. *
  76. * \param p The reference to the current position pointer.
  77. * \param start The start of the buffer, for bounds-checking.
  78. * \param buf The data buffer to write.
  79. * \param size The length of the data buffer.
  80. *
  81. * \return The number of bytes written to \p p on success.
  82. * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  83. */
  84. int mbedtls_asn1_write_raw_buffer( unsigned char **p, unsigned char *start,
  85. const unsigned char *buf, size_t size );
  86. #if defined(MBEDTLS_BIGNUM_C)
  87. /**
  88. * \brief Write a arbitrary-precision number (#MBEDTLS_ASN1_INTEGER)
  89. * in ASN.1 format.
  90. *
  91. * \note This function works backwards in data buffer.
  92. *
  93. * \param p The reference to the current position pointer.
  94. * \param start The start of the buffer, for bounds-checking.
  95. * \param X The MPI to write.
  96. *
  97. * \return The number of bytes written to \p p on success.
  98. * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  99. */
  100. int mbedtls_asn1_write_mpi( unsigned char **p, unsigned char *start,
  101. const mbedtls_mpi *X );
  102. #endif /* MBEDTLS_BIGNUM_C */
  103. /**
  104. * \brief Write a NULL tag (#MBEDTLS_ASN1_NULL) with zero data
  105. * in ASN.1 format.
  106. *
  107. * \note This function works backwards in data buffer.
  108. *
  109. * \param p The reference to the current position pointer.
  110. * \param start The start of the buffer, for bounds-checking.
  111. *
  112. * \return The number of bytes written to \p p on success.
  113. * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  114. */
  115. int mbedtls_asn1_write_null( unsigned char **p, unsigned char *start );
  116. /**
  117. * \brief Write an OID tag (#MBEDTLS_ASN1_OID) and data
  118. * in ASN.1 format.
  119. *
  120. * \note This function works backwards in data buffer.
  121. *
  122. * \param p The reference to the current position pointer.
  123. * \param start The start of the buffer, for bounds-checking.
  124. * \param oid The OID to write.
  125. * \param oid_len The length of the OID.
  126. *
  127. * \return The number of bytes written to \p p on success.
  128. * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  129. */
  130. int mbedtls_asn1_write_oid( unsigned char **p, unsigned char *start,
  131. const char *oid, size_t oid_len );
  132. /**
  133. * \brief Write an AlgorithmIdentifier sequence in ASN.1 format.
  134. *
  135. * \note This function works backwards in data buffer.
  136. *
  137. * \param p The reference to the current position pointer.
  138. * \param start The start of the buffer, for bounds-checking.
  139. * \param oid The OID of the algorithm to write.
  140. * \param oid_len The length of the algorithm's OID.
  141. * \param par_len The length of the parameters, which must be already written.
  142. * If 0, NULL parameters are added
  143. *
  144. * \return The number of bytes written to \p p on success.
  145. * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  146. */
  147. int mbedtls_asn1_write_algorithm_identifier( unsigned char **p,
  148. unsigned char *start,
  149. const char *oid, size_t oid_len,
  150. size_t par_len );
  151. /**
  152. * \brief Write a boolean tag (#MBEDTLS_ASN1_BOOLEAN) and value
  153. * in ASN.1 format.
  154. *
  155. * \note This function works backwards in data buffer.
  156. *
  157. * \param p The reference to the current position pointer.
  158. * \param start The start of the buffer, for bounds-checking.
  159. * \param boolean The boolean value to write, either \c 0 or \c 1.
  160. *
  161. * \return The number of bytes written to \p p on success.
  162. * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  163. */
  164. int mbedtls_asn1_write_bool( unsigned char **p, unsigned char *start,
  165. int boolean );
  166. /**
  167. * \brief Write an int tag (#MBEDTLS_ASN1_INTEGER) and value
  168. * in ASN.1 format.
  169. *
  170. * \note This function works backwards in data buffer.
  171. *
  172. * \param p The reference to the current position pointer.
  173. * \param start The start of the buffer, for bounds-checking.
  174. * \param val The integer value to write.
  175. *
  176. * \return The number of bytes written to \p p on success.
  177. * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  178. */
  179. int mbedtls_asn1_write_int( unsigned char **p, unsigned char *start, int val );
  180. /**
  181. * \brief Write a string in ASN.1 format using a specific
  182. * string encoding tag.
  183. * \note This function works backwards in data buffer.
  184. *
  185. * \param p The reference to the current position pointer.
  186. * \param start The start of the buffer, for bounds-checking.
  187. * \param tag The string encoding tag to write, e.g.
  188. * #MBEDTLS_ASN1_UTF8_STRING.
  189. * \param text The string to write.
  190. * \param text_len The length of \p text in bytes (which might
  191. * be strictly larger than the number of characters).
  192. *
  193. * \return The number of bytes written to \p p on success.
  194. * \return A negative error code on failure.
  195. */
  196. int mbedtls_asn1_write_tagged_string( unsigned char **p, unsigned char *start,
  197. int tag, const char *text,
  198. size_t text_len );
  199. /**
  200. * \brief Write a string in ASN.1 format using the PrintableString
  201. * string encoding tag (#MBEDTLS_ASN1_PRINTABLE_STRING).
  202. *
  203. * \note This function works backwards in data buffer.
  204. *
  205. * \param p The reference to the current position pointer.
  206. * \param start The start of the buffer, for bounds-checking.
  207. * \param text The string to write.
  208. * \param text_len The length of \p text in bytes (which might
  209. * be strictly larger than the number of characters).
  210. *
  211. * \return The number of bytes written to \p p on success.
  212. * \return A negative error code on failure.
  213. */
  214. int mbedtls_asn1_write_printable_string( unsigned char **p,
  215. unsigned char *start,
  216. const char *text, size_t text_len );
  217. /**
  218. * \brief Write a UTF8 string in ASN.1 format using the UTF8String
  219. * string encoding tag (#MBEDTLS_ASN1_PRINTABLE_STRING).
  220. *
  221. * \note This function works backwards in data buffer.
  222. *
  223. * \param p The reference to the current position pointer.
  224. * \param start The start of the buffer, for bounds-checking.
  225. * \param text The string to write.
  226. * \param text_len The length of \p text in bytes (which might
  227. * be strictly larger than the number of characters).
  228. *
  229. * \return The number of bytes written to \p p on success.
  230. * \return A negative error code on failure.
  231. */
  232. int mbedtls_asn1_write_utf8_string( unsigned char **p, unsigned char *start,
  233. const char *text, size_t text_len );
  234. /**
  235. * \brief Write a string in ASN.1 format using the IA5String
  236. * string encoding tag (#MBEDTLS_ASN1_IA5_STRING).
  237. *
  238. * \note This function works backwards in data buffer.
  239. *
  240. * \param p The reference to the current position pointer.
  241. * \param start The start of the buffer, for bounds-checking.
  242. * \param text The string to write.
  243. * \param text_len The length of \p text in bytes (which might
  244. * be strictly larger than the number of characters).
  245. *
  246. * \return The number of bytes written to \p p on success.
  247. * \return A negative error code on failure.
  248. */
  249. int mbedtls_asn1_write_ia5_string( unsigned char **p, unsigned char *start,
  250. const char *text, size_t text_len );
  251. /**
  252. * \brief Write a bitstring tag (#MBEDTLS_ASN1_BIT_STRING) and
  253. * value in ASN.1 format.
  254. *
  255. * \note This function works backwards in data buffer.
  256. *
  257. * \param p The reference to the current position pointer.
  258. * \param start The start of the buffer, for bounds-checking.
  259. * \param buf The bitstring to write.
  260. * \param bits The total number of bits in the bitstring.
  261. *
  262. * \return The number of bytes written to \p p on success.
  263. * \return A negative error code on failure.
  264. */
  265. int mbedtls_asn1_write_bitstring( unsigned char **p, unsigned char *start,
  266. const unsigned char *buf, size_t bits );
  267. /**
  268. * \brief Write an octet string tag (#MBEDTLS_ASN1_OCTET_STRING)
  269. * and value in ASN.1 format.
  270. *
  271. * \note This function works backwards in data buffer.
  272. *
  273. * \param p The reference to the current position pointer.
  274. * \param start The start of the buffer, for bounds-checking.
  275. * \param buf The buffer holding the data to write.
  276. * \param size The length of the data buffer \p buf.
  277. *
  278. * \return The number of bytes written to \p p on success.
  279. * \return A negative error code on failure.
  280. */
  281. int mbedtls_asn1_write_octet_string( unsigned char **p, unsigned char *start,
  282. const unsigned char *buf, size_t size );
  283. /**
  284. * \brief Create or find a specific named_data entry for writing in a
  285. * sequence or list based on the OID. If not already in there,
  286. * a new entry is added to the head of the list.
  287. * Warning: Destructive behaviour for the val data!
  288. *
  289. * \param list The pointer to the location of the head of the list to seek
  290. * through (will be updated in case of a new entry).
  291. * \param oid The OID to look for.
  292. * \param oid_len The size of the OID.
  293. * \param val The data to store (can be \c NULL if you want to fill
  294. * it by hand).
  295. * \param val_len The minimum length of the data buffer needed.
  296. *
  297. * \return A pointer to the new / existing entry on success.
  298. * \return \c NULL if if there was a memory allocation error.
  299. */
  300. mbedtls_asn1_named_data *mbedtls_asn1_store_named_data( mbedtls_asn1_named_data **list,
  301. const char *oid, size_t oid_len,
  302. const unsigned char *val,
  303. size_t val_len );
  304. #ifdef __cplusplus
  305. }
  306. #endif
  307. #endif /* MBEDTLS_ASN1_WRITE_H */