git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/asn1write.h

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