src/libstrongswan/asn1/asn1.h

   1 /*
   2  * Copyright (C) 2006 Martin Will
   3  * Copyright (C) 2000-2008 Andreas Steffen
   4  *
   5  * Hochschule fuer Technik Rapperswil
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup asn1i asn1
  20  * @{ @ingroup asn1
  21  */
  22
  23 #ifndef ASN1_H_
  24 #define ASN1_H_
  25
  26 #include <stdarg.h>
  27
  28 #include <library.h>
  29
  30 /**
  31  * Definition of some primitive ASN1 types
  32  */
  33 typedef enum {
  34         ASN1_EOC =                              0x00,
  35         ASN1_BOOLEAN =                  0x01,
  36         ASN1_INTEGER =                  0x02,
  37         ASN1_BIT_STRING =               0x03,
  38         ASN1_OCTET_STRING =             0x04,
  39         ASN1_NULL =                             0x05,
  40         ASN1_OID =                              0x06,
  41         ASN1_ENUMERATED =               0x0A,
  42         ASN1_UTF8STRING =               0x0C,
  43         ASN1_NUMERICSTRING =    0x12,
  44         ASN1_PRINTABLESTRING =  0x13,
  45         ASN1_T61STRING =                0x14,
  46         ASN1_VIDEOTEXSTRING =   0x15,
  47         ASN1_IA5STRING =                0x16,
  48         ASN1_UTCTIME =                  0x17,
  49         ASN1_GENERALIZEDTIME =  0x18,
  50         ASN1_GRAPHICSTRING =    0x19,
  51         ASN1_VISIBLESTRING =    0x1A,
  52         ASN1_GENERALSTRING =    0x1B,
  53         ASN1_UNIVERSALSTRING =  0x1C,
  54         ASN1_BMPSTRING =                0x1E,
  55
  56         ASN1_CONSTRUCTED =              0x20,
  57
  58         ASN1_SEQUENCE =                 0x30,
  59         ASN1_SET =                              0x31,
  60
  61         ASN1_CONTEXT_S_0 =              0x80,
  62         ASN1_CONTEXT_S_1 =              0x81,
  63         ASN1_CONTEXT_S_2 =              0x82,
  64         ASN1_CONTEXT_S_3 =              0x83,
  65         ASN1_CONTEXT_S_4 =              0x84,
  66         ASN1_CONTEXT_S_5 =              0x85,
  67         ASN1_CONTEXT_S_6 =              0x86,
  68         ASN1_CONTEXT_S_7 =              0x87,
  69         ASN1_CONTEXT_S_8 =              0x88,
  70
  71         ASN1_CONTEXT_C_0 =              0xA0,
  72         ASN1_CONTEXT_C_1 =              0xA1,
  73         ASN1_CONTEXT_C_2 =              0xA2,
  74         ASN1_CONTEXT_C_3 =              0xA3,
  75         ASN1_CONTEXT_C_4 =              0xA4,
  76         ASN1_CONTEXT_C_5 =              0xA5,
  77
  78         ASN1_INVALID =                  0x100,
  79 } asn1_t;
  80
  81 #define ASN1_INVALID_LENGTH     0xffffffff
  82
  83 /**
  84  * Some common prefabricated ASN.1 constants
  85  */
  86 extern const chunk_t ASN1_INTEGER_0;
  87 extern const chunk_t ASN1_INTEGER_1;
  88 extern const chunk_t ASN1_INTEGER_2;
  89
  90
  91 /** Some ASN.1 analysis functions */
  92
  93 /**
  94  * Build an algorithmIdentifier from a known OID.
  95  *
  96  * @param oid           known OID index
  97  * @return                      body of the corresponding OID, allocated
  98  */
  99 chunk_t asn1_algorithmIdentifier(int oid);
 100
 101 /**
 102  * Converts an ASN.1 OID into a known OID index
 103  *
 104  * @param object        body of an OID
 105  * @return                      index into the oid_names[] table or OID_UNKNOWN
 106  */
 107 int asn1_known_oid(chunk_t object);
 108
 109 /**
 110  * Converts a known OID index to an ASN.1 OID
 111  *
 112  * @param n                     index into the oid_names[] table
 113  * @return                      allocated OID chunk, chunk_empty if index out of range
 114  */
 115 chunk_t asn1_build_known_oid(int n);
 116
 117 /**
 118  * Convert human readable OID to ASN.1 DER encoding, without OID header.
 119  *
 120  * @param str           OID string (e.g. 1.2.345.67.8)
 121  * @return                      allocated ASN.1 encoded OID, chunk_empty on error
 122  */
 123 chunk_t asn1_oid_from_string(char *str);
 124
 125 /**
 126  * Convert a DER encoded ASN.1 OID to a human readable string.
 127  *
 128  * @param oid           DER encoded OID, without header
 129  * @return                      human readable OID string, allocated, NULL on error
 130  */
 131 char* asn1_oid_to_string(chunk_t oid);
 132
 133 /**
 134  * Returns the length of an ASN.1 object
 135  * The blob pointer is advanced past the tag length fields
 136  *
 137  * @param blob          pointer to an ASN.1 coded blob
 138  * @return                      length of ASN.1 object
 139  */
 140 size_t asn1_length(chunk_t *blob);
 141
 142 /**
 143  * Unwrap the inner content of an ASN.1 type/length wrapped object.
 144  *
 145  * @param blob          blob to parse header from, moved behind parsed content
 146  * @param content       inner content
 147  * @return                      parsed type, ASN1_INVALID if length parsing failed
 148  */
 149 int asn1_unwrap(chunk_t *blob, chunk_t *content);
 150
 151 /**
 152  * Parses an ASN.1 algorithmIdentifier object
 153  *
 154  * @param blob          ASN.1 coded blob
 155  * @param level0        top-most level offset
 156  * @param params        returns optional [ASN.1 coded] parameters
 157  * @return                      known OID index or OID_UNKNOWN
 158  */
 159 int asn1_parse_algorithmIdentifier(chunk_t blob, int level0, chunk_t *params);
 160
 161 /**
 162  * Parse the top-most level of an ASN.1 object
 163  *
 164  * @param object        ASN.1 coded object
 165  * @param type          Expected ASN.1 type
 166  * @param level0        top-most level offset
 167  * @param name          descriptive name of object
 168  * @return                      TRUE if parsing successful
 169  */
 170 bool asn1_parse_simple_object(chunk_t *object, asn1_t type, u_int level0,
 171                                                           const char* name);
 172
 173 /**
 174  * Converts an ASN.1 INTEGER object to an u_int64_t. If the INTEGER is longer
 175  * than 8 bytes only the 8 LSBs are returned.
 176  *
 177  * @param blob          body of an ASN.1 coded integer object
 178  * @return                      converted integer
 179  */
 180 u_int64_t asn1_parse_integer_uint64(chunk_t blob);
 181
 182 /**
 183  * Print the value of an ASN.1 simple object
 184  *
 185  * @param object        ASN.1 object to be printed
 186  * @param type          asn1_t type
 187  * @param private       ASN.1 data is confidential (use debug level 4)
 188  */
 189 void asn1_debug_simple_object(chunk_t object, asn1_t type, bool private);
 190
 191 /**
 192  * Converts an ASN.1 UTCTIME or GENERALIZEDTIME string to time_t
 193  *
 194  * On systems where sizeof(time_t) == 4 there will be an overflow
 195  * for dates
 196  *   > Tue, 19 Jan 2038 03:14:07 UTC (0x7fffffff)
 197  * and
 198  *   < Fri, 13 Dec 1901 20:45:52 UTC (0x80000000)
 199  * in both cases TIME_32_BIT_SIGNED_MAX is returned.
 200  *
 201  * @param utctime       body of an ASN.1 coded time object
 202  * @param type          ASN1_UTCTIME or ASN1_GENERALIZEDTIME
 203  * @return                      time_t in UTC
 204  */
 205 time_t asn1_to_time(const chunk_t *utctime, asn1_t type);
 206
 207 /**
 208  * Converts time_t to an ASN.1 UTCTIME or GENERALIZEDTIME string
 209  *
 210  * @note The type is automatically changed to GENERALIZEDTIME if needed
 211  *
 212  * @param time          time_t in UTC
 213  * @param type          ASN1_UTCTIME or ASN1_GENERALIZEDTIME
 214  * @return                      body of an ASN.1 code time object
 215  */
 216 chunk_t asn1_from_time(const time_t *time, asn1_t type);
 217
 218 /**
 219  * Parse an ASN.1 UTCTIME or GENERALIZEDTIME object
 220  *
 221  * @param blob          ASN.1 coded time object
 222  * @param level0        top-most level offset
 223  * @return                      time_t in UTC
 224  */
 225 time_t asn1_parse_time(chunk_t blob, int level0);
 226
 227 /**
 228  * Determines if a binary blob is ASN.1 coded
 229  *
 230  * @param blob          blob to be tested
 231  * @return                      TRUE if blob is ASN.1 coded (SEQUENCE or SET)
 232  */
 233 bool is_asn1(chunk_t blob);
 234
 235 /**
 236  * Determines if a character string can be coded as PRINTABLESTRING
 237  *
 238  * @param str           character string to be tested
 239  * @return                      TRUE if no special characters are contained
 240  */
 241 bool asn1_is_printablestring(chunk_t str);
 242
 243
 244 /** some ASN.1 synthesis functions */
 245
 246 /**
 247  * Build an empty ASN.1 object with tag and length fields already filled in
 248  *
 249  * @param object        returned object - memory is allocated by function
 250  * @param type          ASN.1 type to be created
 251  * @param datalen       size of the body to be created
 252  * @return                      points to the first position in the body
 253  */
 254 u_char* asn1_build_object(chunk_t *object, asn1_t type, size_t datalen);
 255
 256 /**
 257  * Build a simple ASN.1 object
 258  *
 259  * @param tag           ASN.1 type to be created
 260  * @param content       content of the ASN.1 object
 261  * @return                      chunk containing the ASN.1 coded object
 262  */
 263 chunk_t asn1_simple_object(asn1_t tag, chunk_t content);
 264
 265 /**
 266  * Build an ASN.1 BITSTRING object
 267  *
 268  * @param mode          'c' for copy or 'm' for move
 269  * @param content       content of the BITSTRING
 270  * @return                      chunk containing the ASN.1 coded BITSTRING
 271  */
 272 chunk_t asn1_bitstring(const char *mode, chunk_t content);
 273
 274 /**
 275  * Build an ASN.1 INTEGER object
 276  *
 277  * @param mode          'c' for copy or 'm' for move
 278  * @param content       content of the INTEGER
 279  * @return                      chunk containing the ASN.1 coded INTEGER
 280  */
 281 chunk_t asn1_integer(const char *mode, chunk_t content);
 282
 283 /**
 284  * Build an ASN.1 object from a variable number of individual chunks
 285  *
 286  * The mode string specifies the number of chunks, and how to handle each of
 287  * them with a single character: 'c' for copy (allocate new chunk), 'm' for move
 288  * (free given chunk) or 's' for sensitive-copy (clear given chunk, then free).
 289  *
 290  * @param type          ASN.1 type to be created
 291  * @param mode          for each list member: 'c', 'm' or 's'
 292  * @return                      chunk containing the ASN.1 coded object
 293  */
 294 chunk_t asn1_wrap(asn1_t type, const char *mode, ...);
 295
 296 #endif /** ASN1_H_ @}*/