src/libstrongswan/asn1/asn1.h

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