1 /** 2 * \file asn1write.h 3 * 4 * \brief ASN.1 buffer writing functionality 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 9 * 10 * This file is provided under the Apache License 2.0, or the 11 * GNU General Public License v2.0 or later. 12 * 13 * ********** 14 * Apache License 2.0: 15 * 16 * Licensed under the Apache License, Version 2.0 (the "License"); you may 17 * not use this file except in compliance with the License. 18 * You may obtain a copy of the License at 19 * 20 * http://www.apache.org/licenses/LICENSE-2.0 21 * 22 * Unless required by applicable law or agreed to in writing, software 23 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 24 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 * See the License for the specific language governing permissions and 26 * limitations under the License. 27 * 28 * ********** 29 * 30 * ********** 31 * GNU General Public License v2.0 or later: 32 * 33 * This program is free software; you can redistribute it and/or modify 34 * it under the terms of the GNU General Public License as published by 35 * the Free Software Foundation; either version 2 of the License, or 36 * (at your option) any later version. 37 * 38 * This program is distributed in the hope that it will be useful, 39 * but WITHOUT ANY WARRANTY; without even the implied warranty of 40 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 41 * GNU General Public License for more details. 42 * 43 * You should have received a copy of the GNU General Public License along 44 * with this program; if not, write to the Free Software Foundation, Inc., 45 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 46 * 47 * ********** 48 */ 49 #ifndef MBEDTLS_ASN1_WRITE_H 50 #define MBEDTLS_ASN1_WRITE_H 51 52 #if !defined(MBEDTLS_CONFIG_FILE) 53 #include "config.h" 54 #else 55 #include MBEDTLS_CONFIG_FILE 56 #endif 57 58 #include "asn1.h" 59 60 #define MBEDTLS_ASN1_CHK_ADD(g, f) \ 61 do \ 62 { \ 63 if( ( ret = (f) ) < 0 ) \ 64 return( ret ); \ 65 else \ 66 (g) += ret; \ 67 } while( 0 ) 68 69 #ifdef __cplusplus 70 extern "C" { 71 #endif 72 73 /** 74 * \brief Write a length field in ASN.1 format. 75 * 76 * \note This function works backwards in data buffer. 77 * 78 * \param p The reference to the current position pointer. 79 * \param start The start of the buffer, for bounds-checking. 80 * \param len The length value to write. 81 * 82 * \return The number of bytes written to \p p on success. 83 * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure. 84 */ 85 int mbedtls_asn1_write_len( unsigned char **p, unsigned char *start, 86 size_t len ); 87 /** 88 * \brief Write an ASN.1 tag in ASN.1 format. 89 * 90 * \note This function works backwards in data buffer. 91 * 92 * \param p The reference to the current position pointer. 93 * \param start The start of the buffer, for bounds-checking. 94 * \param tag The tag to write. 95 * 96 * \return The number of bytes written to \p p on success. 97 * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure. 98 */ 99 int mbedtls_asn1_write_tag( unsigned char **p, unsigned char *start, 100 unsigned char tag ); 101 102 /** 103 * \brief Write raw buffer data. 104 * 105 * \note This function works backwards in data buffer. 106 * 107 * \param p The reference to the current position pointer. 108 * \param start The start of the buffer, for bounds-checking. 109 * \param buf The data buffer to write. 110 * \param size The length of the data buffer. 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_raw_buffer( unsigned char **p, unsigned char *start, 116 const unsigned char *buf, size_t size ); 117 118 #if defined(MBEDTLS_BIGNUM_C) 119 /** 120 * \brief Write a arbitrary-precision number (#MBEDTLS_ASN1_INTEGER) 121 * in ASN.1 format. 122 * 123 * \note This function works backwards in data buffer. 124 * 125 * \param p The reference to the current position pointer. 126 * \param start The start of the buffer, for bounds-checking. 127 * \param X The MPI to write. 128 * 129 * \return The number of bytes written to \p p on success. 130 * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure. 131 */ 132 int mbedtls_asn1_write_mpi( unsigned char **p, unsigned char *start, 133 const mbedtls_mpi *X ); 134 #endif /* MBEDTLS_BIGNUM_C */ 135 136 /** 137 * \brief Write a NULL tag (#MBEDTLS_ASN1_NULL) with zero data 138 * in ASN.1 format. 139 * 140 * \note This function works backwards in data buffer. 141 * 142 * \param p The reference to the current position pointer. 143 * \param start The start of the buffer, for bounds-checking. 144 * 145 * \return The number of bytes written to \p p on success. 146 * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure. 147 */ 148 int mbedtls_asn1_write_null( unsigned char **p, unsigned char *start ); 149 150 /** 151 * \brief Write an OID tag (#MBEDTLS_ASN1_OID) and data 152 * in ASN.1 format. 153 * 154 * \note This function works backwards in data buffer. 155 * 156 * \param p The reference to the current position pointer. 157 * \param start The start of the buffer, for bounds-checking. 158 * \param oid The OID to write. 159 * \param oid_len The length of the OID. 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_oid( unsigned char **p, unsigned char *start, 165 const char *oid, size_t oid_len ); 166 167 /** 168 * \brief Write an AlgorithmIdentifier sequence 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 oid The OID of the algorithm to write. 175 * \param oid_len The length of the algorithm's OID. 176 * \param par_len The length of the parameters, which must be already written. 177 * If 0, NULL parameters are added 178 * 179 * \return The number of bytes written to \p p on success. 180 * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure. 181 */ 182 int mbedtls_asn1_write_algorithm_identifier( unsigned char **p, 183 unsigned char *start, 184 const char *oid, size_t oid_len, 185 size_t par_len ); 186 187 /** 188 * \brief Write a boolean tag (#MBEDTLS_ASN1_BOOLEAN) and value 189 * in ASN.1 format. 190 * 191 * \note This function works backwards in data buffer. 192 * 193 * \param p The reference to the current position pointer. 194 * \param start The start of the buffer, for bounds-checking. 195 * \param boolean The boolean value to write, either \c 0 or \c 1. 196 * 197 * \return The number of bytes written to \p p on success. 198 * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure. 199 */ 200 int mbedtls_asn1_write_bool( unsigned char **p, unsigned char *start, 201 int boolean ); 202 203 /** 204 * \brief Write an int tag (#MBEDTLS_ASN1_INTEGER) and value 205 * in ASN.1 format. 206 * 207 * \note This function works backwards in data buffer. 208 * 209 * \param p The reference to the current position pointer. 210 * \param start The start of the buffer, for bounds-checking. 211 * \param val The integer value to write. 212 * 213 * \return The number of bytes written to \p p on success. 214 * \return A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure. 215 */ 216 int mbedtls_asn1_write_int( unsigned char **p, unsigned char *start, int val ); 217 218 /** 219 * \brief Write a string in ASN.1 format using a specific 220 * string encoding tag. 221 222 * \note This function works backwards in data buffer. 223 * 224 * \param p The reference to the current position pointer. 225 * \param start The start of the buffer, for bounds-checking. 226 * \param tag The string encoding tag to write, e.g. 227 * #MBEDTLS_ASN1_UTF8_STRING. 228 * \param text The string to write. 229 * \param text_len The length of \p text in bytes (which might 230 * be strictly larger than the number of characters). 231 * 232 * \return The number of bytes written to \p p on success. 233 * \return A negative error code on failure. 234 */ 235 int mbedtls_asn1_write_tagged_string( unsigned char **p, unsigned char *start, 236 int tag, const char *text, 237 size_t text_len ); 238 239 /** 240 * \brief Write a string in ASN.1 format using the PrintableString 241 * string encoding tag (#MBEDTLS_ASN1_PRINTABLE_STRING). 242 * 243 * \note This function works backwards in data buffer. 244 * 245 * \param p The reference to the current position pointer. 246 * \param start The start of the buffer, for bounds-checking. 247 * \param text The string to write. 248 * \param text_len The length of \p text in bytes (which might 249 * be strictly larger than the number of characters). 250 * 251 * \return The number of bytes written to \p p on success. 252 * \return A negative error code on failure. 253 */ 254 int mbedtls_asn1_write_printable_string( unsigned char **p, 255 unsigned char *start, 256 const char *text, size_t text_len ); 257 258 /** 259 * \brief Write a UTF8 string in ASN.1 format using the UTF8String 260 * string encoding tag (#MBEDTLS_ASN1_PRINTABLE_STRING). 261 * 262 * \note This function works backwards in data buffer. 263 * 264 * \param p The reference to the current position pointer. 265 * \param start The start of the buffer, for bounds-checking. 266 * \param text The string to write. 267 * \param text_len The length of \p text in bytes (which might 268 * be strictly larger than the number of characters). 269 * 270 * \return The number of bytes written to \p p on success. 271 * \return A negative error code on failure. 272 */ 273 int mbedtls_asn1_write_utf8_string( unsigned char **p, unsigned char *start, 274 const char *text, size_t text_len ); 275 276 /** 277 * \brief Write a string in ASN.1 format using the IA5String 278 * string encoding tag (#MBEDTLS_ASN1_IA5_STRING). 279 * 280 * \note This function works backwards in data buffer. 281 * 282 * \param p The reference to the current position pointer. 283 * \param start The start of the buffer, for bounds-checking. 284 * \param text The string to write. 285 * \param text_len The length of \p text in bytes (which might 286 * be strictly larger than the number of characters). 287 * 288 * \return The number of bytes written to \p p on success. 289 * \return A negative error code on failure. 290 */ 291 int mbedtls_asn1_write_ia5_string( unsigned char **p, unsigned char *start, 292 const char *text, size_t text_len ); 293 294 /** 295 * \brief Write a bitstring tag (#MBEDTLS_ASN1_BIT_STRING) and 296 * value in ASN.1 format. 297 * 298 * \note This function works backwards in data buffer. 299 * 300 * \param p The reference to the current position pointer. 301 * \param start The start of the buffer, for bounds-checking. 302 * \param buf The bitstring to write. 303 * \param bits The total number of bits in the bitstring. 304 * 305 * \return The number of bytes written to \p p on success. 306 * \return A negative error code on failure. 307 */ 308 int mbedtls_asn1_write_bitstring( unsigned char **p, unsigned char *start, 309 const unsigned char *buf, size_t bits ); 310 311 /** 312 * \brief Write an octet string tag (#MBEDTLS_ASN1_OCTET_STRING) 313 * and value in ASN.1 format. 314 * 315 * \note This function works backwards in data buffer. 316 * 317 * \param p The reference to the current position pointer. 318 * \param start The start of the buffer, for bounds-checking. 319 * \param buf The buffer holding the data to write. 320 * \param size The length of the data buffer \p buf. 321 * 322 * \return The number of bytes written to \p p on success. 323 * \return A negative error code on failure. 324 */ 325 int mbedtls_asn1_write_octet_string( unsigned char **p, unsigned char *start, 326 const unsigned char *buf, size_t size ); 327 328 /** 329 * \brief Create or find a specific named_data entry for writing in a 330 * sequence or list based on the OID. If not already in there, 331 * a new entry is added to the head of the list. 332 * Warning: Destructive behaviour for the val data! 333 * 334 * \param list The pointer to the location of the head of the list to seek 335 * through (will be updated in case of a new entry). 336 * \param oid The OID to look for. 337 * \param oid_len The size of the OID. 338 * \param val The data to store (can be \c NULL if you want to fill 339 * it by hand). 340 * \param val_len The minimum length of the data buffer needed. 341 * 342 * \return A pointer to the new / existing entry on success. 343 * \return \c NULL if if there was a memory allocation error. 344 */ 345 mbedtls_asn1_named_data *mbedtls_asn1_store_named_data( mbedtls_asn1_named_data **list, 346 const char *oid, size_t oid_len, 347 const unsigned char *val, 348 size_t val_len ); 349 350 #ifdef __cplusplus 351 } 352 #endif 353 354 #endif /* MBEDTLS_ASN1_WRITE_H */ 355