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