src/libpolarssl/asn1.h

   1 /**
   2  * \file asn1.h
   3  *
   4  * \brief Generic ASN.1 parsing
   5  *
   6  *  Copyright (C) 2006-2011, Brainspark B.V.
   7  *
   8  *  This file is part of PolarSSL (http://www.polarssl.org)
   9  *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
  10  *
  11  *  All rights reserved.
  12  *
  13  *  This program is free software; you can redistribute it and/or modify
  14  *  it under the terms of the GNU General Public License as published by
  15  *  the Free Software Foundation; either version 2 of the License, or
  16  *  (at your option) any later version.
  17  *
  18  *  This program is distributed in the hope that it will be useful,
  19  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  *  GNU General Public License for more details.
  22  *
  23  *  You should have received a copy of the GNU General Public License along
  24  *  with this program; if not, write to the Free Software Foundation, Inc.,
  25  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  26  */
  27 #ifndef POLARSSL_ASN1_H
  28 #define POLARSSL_ASN1_H
  29
  30 #include "config.h"
  31
  32 #if defined(POLARSSL_BIGNUM_C)
  33 #include "bignum.h"
  34 #endif
  35
  36 #include <string.h>
  37
  38 /**
  39  * \addtogroup asn1_module
  40  * \{
  41  */
  42
  43 /**
  44  * \name ASN1 Error codes
  45  * These error codes are OR'ed to X509 error codes for
  46  * higher error granularity.
  47  * ASN1 is a standard to specify data structures.
  48  * \{
  49  */
  50 #define POLARSSL_ERR_ASN1_OUT_OF_DATA                      -0x0060  /**< Out of data when parsing an ASN1 data structure. */
  51 #define POLARSSL_ERR_ASN1_UNEXPECTED_TAG                   -0x0062  /**< ASN1 tag was of an unexpected value. */
  52 #define POLARSSL_ERR_ASN1_INVALID_LENGTH                   -0x0064  /**< Error when trying to determine the length or invalid length. */
  53 #define POLARSSL_ERR_ASN1_LENGTH_MISMATCH                  -0x0066  /**< Actual length differs from expected length. */
  54 #define POLARSSL_ERR_ASN1_INVALID_DATA                     -0x0068  /**< Data is invalid. (not used) */
  55 #define POLARSSL_ERR_ASN1_MALLOC_FAILED                    -0x006A  /**< Memory allocation failed */
  56 #define POLARSSL_ERR_ASN1_BUF_TOO_SMALL                    -0x006C  /**< Buffer too small when writing ASN.1 data structure. */
  57
  58 /* \} name */
  59
  60 /**
  61  * \name DER constants
  62  * These constants comply with DER encoded the ANS1 type tags.
  63  * DER encoding uses hexadecimal representation.
  64  * An example DER sequence is:\n
  65  * - 0x02 -- tag indicating INTEGER
  66  * - 0x01 -- length in octets
  67  * - 0x05 -- value
  68  * Such sequences are typically read into \c ::x509_buf.
  69  * \{
  70  */
  71 #define ASN1_BOOLEAN                 0x01
  72 #define ASN1_INTEGER                 0x02
  73 #define ASN1_BIT_STRING              0x03
  74 #define ASN1_OCTET_STRING            0x04
  75 #define ASN1_NULL                    0x05
  76 #define ASN1_OID                     0x06
  77 #define ASN1_UTF8_STRING             0x0C
  78 #define ASN1_SEQUENCE                0x10
  79 #define ASN1_SET                     0x11
  80 #define ASN1_PRINTABLE_STRING        0x13
  81 #define ASN1_T61_STRING              0x14
  82 #define ASN1_IA5_STRING              0x16
  83 #define ASN1_UTC_TIME                0x17
  84 #define ASN1_GENERALIZED_TIME        0x18
  85 #define ASN1_UNIVERSAL_STRING        0x1C
  86 #define ASN1_BMP_STRING              0x1E
  87 #define ASN1_PRIMITIVE               0x00
  88 #define ASN1_CONSTRUCTED             0x20
  89 #define ASN1_CONTEXT_SPECIFIC        0x80
  90 /* \} name */
  91 /* \} addtogroup asn1_module */
  92
  93 /** Returns the size of the binary string, without the trailing \\0 */
  94 #define OID_SIZE(x) (sizeof(x) - 1)
  95
  96 #ifdef __cplusplus
  97 extern "C" {
  98 #endif
  99
 100 /**
 101  * \name Functions to parse ASN.1 data structures
 102  * \{
 103  */
 104
 105 /**
 106  * Type-length-value structure that allows for ASN1 using DER.
 107  */
 108 typedef struct _asn1_buf
 109 {
 110     int tag;                /**< ASN1 type, e.g. ASN1_UTF8_STRING. */
 111     size_t len;             /**< ASN1 length, e.g. in octets. */
 112     unsigned char *p;       /**< ASN1 data, e.g. in ASCII. */
 113 }
 114 asn1_buf;
 115
 116 /**
 117  * Container for ASN1 bit strings.
 118  */
 119 typedef struct _asn1_bitstring
 120 {
 121     size_t len;                 /**< ASN1 length, e.g. in octets. */
 122     unsigned char unused_bits;  /**< Number of unused bits at the end of the string */
 123     unsigned char *p;           /**< Raw ASN1 data for the bit string */
 124 }
 125 asn1_bitstring;
 126
 127 /**
 128  * Container for a sequence of ASN.1 items
 129  */
 130 typedef struct _asn1_sequence
 131 {
 132     asn1_buf buf;                   /**< Buffer containing the given ASN.1 item. */
 133     struct _asn1_sequence *next;    /**< The next entry in the sequence. */
 134 }
 135 asn1_sequence;
 136
 137 /**
 138  * Get the length of an ASN.1 element.
 139  * Updates the pointer to immediately behind the length.
 140  *
 141  * \param p     The position in the ASN.1 data
 142  * \param end   End of data
 143  * \param len   The variable that will receive the value
 144  *
 145  * \return      0 if successful, POLARSSL_ERR_ASN1_OUT_OF_DATA on reaching
 146  *              end of data, POLARSSL_ERR_ASN1_INVALID_LENGTH if length is
 147  *              unparseable.
 148  */
 149 int asn1_get_len( unsigned char **p,
 150                   const unsigned char *end,
 151                   size_t *len );
 152
 153 /**
 154  * Get the tag and length of the tag. Check for the requested tag.
 155  * Updates the pointer to immediately behind the tag and length.
 156  *
 157  * \param p     The position in the ASN.1 data
 158  * \param end   End of data
 159  * \param len   The variable that will receive the length
 160  * \param tag   The expected tag
 161  *
 162  * \return      0 if successful, POLARSSL_ERR_ASN1_UNEXPECTED_TAG if tag did
 163  *              not match requested tag, or another specific ASN.1 error code.
 164  */
 165 int asn1_get_tag( unsigned char **p,
 166                   const unsigned char *end,
 167                   size_t *len, int tag );
 168
 169 /**
 170  * Retrieve a boolean ASN.1 tag and its value.
 171  * Updates the pointer to immediately behind the full tag.
 172  *
 173  * \param p     The position in the ASN.1 data
 174  * \param end   End of data
 175  * \param val   The variable that will receive the value
 176  *
 177  * \return      0 if successful or a specific ASN.1 error code.
 178  */
 179 int asn1_get_bool( unsigned char **p,
 180                    const unsigned char *end,
 181                    int *val );
 182
 183 /**
 184  * Retrieve an integer ASN.1 tag and its value.
 185  * Updates the pointer to immediately behind the full tag.
 186  *
 187  * \param p     The position in the ASN.1 data
 188  * \param end   End of data
 189  * \param val   The variable that will receive the value
 190  *
 191  * \return      0 if successful or a specific ASN.1 error code.
 192  */
 193 int asn1_get_int( unsigned char **p,
 194                   const unsigned char *end,
 195                   int *val );
 196
 197 /**
 198  * Retrieve a bitstring ASN.1 tag and its value.
 199  * Updates the pointer to immediately behind the full tag.
 200  *
 201  * \param p     The position in the ASN.1 data
 202  * \param end   End of data
 203  * \param bs    The variable that will receive the value
 204  *
 205  * \return      0 if successful or a specific ASN.1 error code.
 206  */
 207 int asn1_get_bitstring( unsigned char **p, const unsigned char *end,
 208                         asn1_bitstring *bs);
 209
 210 /**
 211  * Parses and splits an ASN.1 "SEQUENCE OF <tag>"
 212  * Updated the pointer to immediately behind the full sequence tag.
 213  *
 214  * \param p     The position in the ASN.1 data
 215  * \param end   End of data
 216  * \param cur   First variable in the chain to fill
 217  * \param tag   Type of sequence
 218  *
 219  * \return      0 if successful or a specific ASN.1 error code.
 220  */
 221 int asn1_get_sequence_of( unsigned char **p,
 222                           const unsigned char *end,
 223                           asn1_sequence *cur,
 224                           int tag);
 225
 226 #if defined(POLARSSL_BIGNUM_C)
 227 /**
 228  * Retrieve a MPI value from an integer ASN.1 tag.
 229  * Updates the pointer to immediately behind the full tag.
 230  *
 231  * \param p     The position in the ASN.1 data
 232  * \param end   End of data
 233  * \param X     The MPI that will receive the value
 234  *
 235  * \return      0 if successful or a specific ASN.1 or MPI error code.
 236  */
 237 int asn1_get_mpi( unsigned char **p,
 238                   const unsigned char *end,
 239                   mpi *X );
 240 #endif
 241
 242 #ifdef __cplusplus
 243 }
 244 #endif
 245
 246 #endif /* asn1.h */