asn1write.h

00001 /**
00002  * \file asn1write.h
00003  *
00004  * \brief ASN.1 buffer writing functionality
00005  */
00006 /*
00007  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00008  *  SPDX-License-Identifier: Apache-2.0
00009  *
00010  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00011  *  not use this file except in compliance with the License.
00012  *  You may obtain a copy of the License at
00013  *
00014  *  http://www.apache.org/licenses/LICENSE-2.0
00015  *
00016  *  Unless required by applicable law or agreed to in writing, software
00017  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00018  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00019  *  See the License for the specific language governing permissions and
00020  *  limitations under the License.
00021  *
00022  *  This file is part of mbed TLS (https://tls.mbed.org)
00023  */
00024 #ifndef MBEDTLS_ASN1_WRITE_H
00025 #define MBEDTLS_ASN1_WRITE_H
00026 
00027 #if !defined(MBEDTLS_CONFIG_FILE)
00028 #include "mbedtls/config.h"
00029 #else
00030 #include MBEDTLS_CONFIG_FILE
00031 #endif
00032 
00033 #include "mbedtls/asn1.h"
00034 
00035 #define MBEDTLS_ASN1_CHK_ADD(g, f)                      \
00036     do                                                  \
00037     {                                                   \
00038         if( ( ret = (f) ) < 0 )                         \
00039             return( ret );                              \
00040         else                                            \
00041             (g) += ret;                                 \
00042     } while( 0 )
00043 
00044 #ifdef __cplusplus
00045 extern "C" {
00046 #endif
00047 
00048 /**
00049  * \brief           Write a length field in ASN.1 format.
00050  *
00051  * \note            This function works backwards in data buffer.
00052  *
00053  * \param p         The reference to the current position pointer.
00054  * \param start     The start of the buffer, for bounds-checking.
00055  * \param len       The length value to write.
00056  *
00057  * \return          The number of bytes written to \p p on success.
00058  * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00059  */
00060 int mbedtls_asn1_write_len( unsigned char **p, unsigned char *start,
00061                             size_t len );
00062 /**
00063  * \brief           Write an ASN.1 tag in ASN.1 format.
00064  *
00065  * \note            This function works backwards in data buffer.
00066  *
00067  * \param p         The reference to the current position pointer.
00068  * \param start     The start of the buffer, for bounds-checking.
00069  * \param tag       The tag to write.
00070  *
00071  * \return          The number of bytes written to \p p on success.
00072  * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00073  */
00074 int mbedtls_asn1_write_tag( unsigned char **p, unsigned char *start,
00075                             unsigned char tag );
00076 
00077 /**
00078  * \brief           Write raw buffer data.
00079  *
00080  * \note            This function works backwards in data buffer.
00081  *
00082  * \param p         The reference to the current position pointer.
00083  * \param start     The start of the buffer, for bounds-checking.
00084  * \param buf       The data buffer to write.
00085  * \param size      The length of the data buffer.
00086  *
00087  * \return          The number of bytes written to \p p on success.
00088  * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00089  */
00090 int mbedtls_asn1_write_raw_buffer( unsigned char **p, unsigned char *start,
00091                                    const unsigned char *buf, size_t size );
00092 
00093 #if defined(MBEDTLS_BIGNUM_C)
00094 /**
00095  * \brief           Write a arbitrary-precision number (#MBEDTLS_ASN1_INTEGER)
00096  *                  in ASN.1 format.
00097  *
00098  * \note            This function works backwards in data buffer.
00099  *
00100  * \param p         The reference to the current position pointer.
00101  * \param start     The start of the buffer, for bounds-checking.
00102  * \param X         The MPI to write.
00103  *                  It must be non-negative.
00104  *
00105  * \return          The number of bytes written to \p p on success.
00106  * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00107  */
00108 int mbedtls_asn1_write_mpi( unsigned char **p, unsigned char *start,
00109                             const mbedtls_mpi *X );
00110 #endif /* MBEDTLS_BIGNUM_C */
00111 
00112 /**
00113  * \brief           Write a NULL tag (#MBEDTLS_ASN1_NULL) with zero data
00114  *                  in ASN.1 format.
00115  *
00116  * \note            This function works backwards in data buffer.
00117  *
00118  * \param p         The reference to the current position pointer.
00119  * \param start     The start of the buffer, for bounds-checking.
00120  *
00121  * \return          The number of bytes written to \p p on success.
00122  * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00123  */
00124 int mbedtls_asn1_write_null( unsigned char **p, unsigned char *start );
00125 
00126 /**
00127  * \brief           Write an OID tag (#MBEDTLS_ASN1_OID) and data
00128  *                  in ASN.1 format.
00129  *
00130  * \note            This function works backwards in data buffer.
00131  *
00132  * \param p         The reference to the current position pointer.
00133  * \param start     The start of the buffer, for bounds-checking.
00134  * \param oid       The OID to write.
00135  * \param oid_len   The length of the OID.
00136  *
00137  * \return          The number of bytes written to \p p on success.
00138  * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00139  */
00140 int mbedtls_asn1_write_oid( unsigned char **p, unsigned char *start,
00141                             const char *oid, size_t oid_len );
00142 
00143 /**
00144  * \brief           Write an AlgorithmIdentifier sequence in ASN.1 format.
00145  *
00146  * \note            This function works backwards in data buffer.
00147  *
00148  * \param p         The reference to the current position pointer.
00149  * \param start     The start of the buffer, for bounds-checking.
00150  * \param oid       The OID of the algorithm to write.
00151  * \param oid_len   The length of the algorithm's OID.
00152  * \param par_len   The length of the parameters, which must be already written.
00153  *                  If 0, NULL parameters are added
00154  *
00155  * \return          The number of bytes written to \p p on success.
00156  * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00157  */
00158 int mbedtls_asn1_write_algorithm_identifier( unsigned char **p,
00159                                              unsigned char *start,
00160                                              const char *oid, size_t oid_len,
00161                                              size_t par_len );
00162 
00163 /**
00164  * \brief           Write a boolean tag (#MBEDTLS_ASN1_BOOLEAN) and value
00165  *                  in ASN.1 format.
00166  *
00167  * \note            This function works backwards in data buffer.
00168  *
00169  * \param p         The reference to the current position pointer.
00170  * \param start     The start of the buffer, for bounds-checking.
00171  * \param boolean   The boolean value to write, either \c 0 or \c 1.
00172  *
00173  * \return          The number of bytes written to \p p on success.
00174  * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00175  */
00176 int mbedtls_asn1_write_bool( unsigned char **p, unsigned char *start,
00177                              int boolean );
00178 
00179 /**
00180  * \brief           Write an int tag (#MBEDTLS_ASN1_INTEGER) and value
00181  *                  in ASN.1 format.
00182  *
00183  * \note            This function works backwards in data buffer.
00184  *
00185  * \param p         The reference to the current position pointer.
00186  * \param start     The start of the buffer, for bounds-checking.
00187  * \param val       The integer value to write.
00188  *                  It must be non-negative.
00189  *
00190  * \return          The number of bytes written to \p p on success.
00191  * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00192  */
00193 int mbedtls_asn1_write_int( unsigned char **p, unsigned char *start, int val );
00194 
00195 /**
00196  * \brief           Write a string in ASN.1 format using a specific
00197  *                  string encoding tag.
00198 
00199  * \note            This function works backwards in data buffer.
00200  *
00201  * \param p         The reference to the current position pointer.
00202  * \param start     The start of the buffer, for bounds-checking.
00203  * \param tag       The string encoding tag to write, e.g.
00204  *                  #MBEDTLS_ASN1_UTF8_STRING.
00205  * \param text      The string to write.
00206  * \param text_len  The length of \p text in bytes (which might
00207  *                  be strictly larger than the number of characters).
00208  *
00209  * \return          The number of bytes written to \p p on success.
00210  * \return          A negative error code on failure.
00211  */
00212 int mbedtls_asn1_write_tagged_string( unsigned char **p, unsigned char *start,
00213                                       int tag, const char *text,
00214                                       size_t text_len );
00215 
00216 /**
00217  * \brief           Write a string in ASN.1 format using the PrintableString
00218  *                  string encoding tag (#MBEDTLS_ASN1_PRINTABLE_STRING).
00219  *
00220  * \note            This function works backwards in data buffer.
00221  *
00222  * \param p         The reference to the current position pointer.
00223  * \param start     The start of the buffer, for bounds-checking.
00224  * \param text      The string to write.
00225  * \param text_len  The length of \p text in bytes (which might
00226  *                  be strictly larger than the number of characters).
00227  *
00228  * \return          The number of bytes written to \p p on success.
00229  * \return          A negative error code on failure.
00230  */
00231 int mbedtls_asn1_write_printable_string( unsigned char **p,
00232                                          unsigned char *start,
00233                                          const char *text, size_t text_len );
00234 
00235 /**
00236  * \brief           Write a UTF8 string in ASN.1 format using the UTF8String
00237  *                  string encoding tag (#MBEDTLS_ASN1_UTF8_STRING).
00238  *
00239  * \note            This function works backwards in data buffer.
00240  *
00241  * \param p         The reference to the current position pointer.
00242  * \param start     The start of the buffer, for bounds-checking.
00243  * \param text      The string to write.
00244  * \param text_len  The length of \p text in bytes (which might
00245  *                  be strictly larger than the number of characters).
00246  *
00247  * \return          The number of bytes written to \p p on success.
00248  * \return          A negative error code on failure.
00249  */
00250 int mbedtls_asn1_write_utf8_string( unsigned char **p, unsigned char *start,
00251                                     const char *text, size_t text_len );
00252 
00253 /**
00254  * \brief           Write a string in ASN.1 format using the IA5String
00255  *                  string encoding tag (#MBEDTLS_ASN1_IA5_STRING).
00256  *
00257  * \note            This function works backwards in data buffer.
00258  *
00259  * \param p         The reference to the current position pointer.
00260  * \param start     The start of the buffer, for bounds-checking.
00261  * \param text      The string to write.
00262  * \param text_len  The length of \p text in bytes (which might
00263  *                  be strictly larger than the number of characters).
00264  *
00265  * \return          The number of bytes written to \p p on success.
00266  * \return          A negative error code on failure.
00267  */
00268 int mbedtls_asn1_write_ia5_string( unsigned char **p, unsigned char *start,
00269                                    const char *text, size_t text_len );
00270 
00271 /**
00272  * \brief           Write a bitstring tag (#MBEDTLS_ASN1_BIT_STRING) and
00273  *                  value in ASN.1 format.
00274  *
00275  * \note            This function works backwards in data buffer.
00276  *
00277  * \param p         The reference to the current position pointer.
00278  * \param start     The start of the buffer, for bounds-checking.
00279  * \param buf       The bitstring to write.
00280  * \param bits      The total number of bits in the bitstring.
00281  *
00282  * \return          The number of bytes written to \p p on success.
00283  * \return          A negative error code on failure.
00284  */
00285 int mbedtls_asn1_write_bitstring( unsigned char **p, unsigned char *start,
00286                                   const unsigned char *buf, size_t bits );
00287 
00288 /**
00289  * \brief           This function writes a named bitstring tag
00290  *                  (#MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format.
00291  *
00292  *                  As stated in RFC 5280 Appendix B, trailing zeroes are
00293  *                  omitted when encoding named bitstrings in DER.
00294  *
00295  * \note            This function works backwards within the data buffer.
00296  *
00297  * \param p         The reference to the current position pointer.
00298  * \param start     The start of the buffer which is used for bounds-checking.
00299  * \param buf       The bitstring to write.
00300  * \param bits      The total number of bits in the bitstring.
00301  *
00302  * \return          The number of bytes written to \p p on success.
00303  * \return          A negative error code on failure.
00304  */
00305 int mbedtls_asn1_write_named_bitstring( unsigned char **p,
00306                                         unsigned char *start,
00307                                         const unsigned char *buf,
00308                                         size_t bits );
00309 
00310 /**
00311  * \brief           Write an octet string tag (#MBEDTLS_ASN1_OCTET_STRING)
00312  *                  and value in ASN.1 format.
00313  *
00314  * \note            This function works backwards in data buffer.
00315  *
00316  * \param p         The reference to the current position pointer.
00317  * \param start     The start of the buffer, for bounds-checking.
00318  * \param buf       The buffer holding the data to write.
00319  * \param size      The length of the data buffer \p buf.
00320  *
00321  * \return          The number of bytes written to \p p on success.
00322  * \return          A negative error code on failure.
00323  */
00324 int mbedtls_asn1_write_octet_string( unsigned char **p, unsigned char *start,
00325                                      const unsigned char *buf, size_t size );
00326 
00327 /**
00328  * \brief           Create or find a specific named_data entry for writing in a
00329  *                  sequence or list based on the OID. If not already in there,
00330  *                  a new entry is added to the head of the list.
00331  *                  Warning: Destructive behaviour for the val data!
00332  *
00333  * \param list      The pointer to the location of the head of the list to seek
00334  *                  through (will be updated in case of a new entry).
00335  * \param oid       The OID to look for.
00336  * \param oid_len   The size of the OID.
00337  * \param val       The associated data to store. If this is \c NULL,
00338  *                  no data is copied to the new or existing buffer.
00339  * \param val_len   The minimum length of the data buffer needed.
00340  *                  If this is 0, do not allocate a buffer for the associated
00341  *                  data.
00342  *                  If the OID was already present, enlarge, shrink or free
00343  *                  the existing buffer to fit \p val_len.
00344  *
00345  * \return          A pointer to the new / existing entry on success.
00346  * \return          \c NULL if if there was a memory allocation error.
00347  */
00348 mbedtls_asn1_named_data *mbedtls_asn1_store_named_data( mbedtls_asn1_named_data **list,
00349                                         const char *oid, size_t oid_len,
00350                                         const unsigned char *val,
00351                                         size_t val_len );
00352 
00353 #ifdef __cplusplus
00354 }
00355 #endif
00356 
00357 #endif /* MBEDTLS_ASN1_WRITE_H */