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  * @param utctime       body of an ASN.1 coded time object
 195  * @param type          ASN1_UTCTIME or ASN1_GENERALIZEDTIME
 196  * @return                      time_t in UTC
 197  */
 198 time_t asn1_to_time(const chunk_t *utctime, asn1_t type);
 199
 200 /**
 201  * Converts time_t to an ASN.1 UTCTIME or GENERALIZEDTIME string
 202  *
 203  * @note The type is automatically changed to GENERALIZEDTIME if needed
 204  *
 205  * @param time          time_t in UTC
 206  * @param type          ASN1_UTCTIME or ASN1_GENERALIZEDTIME
 207  * @return                      body of an ASN.1 code time object
 208  */
 209 chunk_t asn1_from_time(const time_t *time, asn1_t type);
 210
 211 /**
 212  * Parse an ASN.1 UTCTIME or GENERALIZEDTIME object
 213  *
 214  * @param blob          ASN.1 coded time object
 215  * @param level0        top-most level offset
 216  * @return                      time_t in UTC
 217  */
 218 time_t asn1_parse_time(chunk_t blob, int level0);
 219
 220 /**
 221  * Determines if a binary blob is ASN.1 coded
 222  *
 223  * @param blob          blob to be tested
 224  * @return                      TRUE if blob is ASN.1 coded (SEQUENCE or SET)
 225  */
 226 bool is_asn1(chunk_t blob);
 227
 228 /**
 229  * Determines if a character string can be coded as PRINTABLESTRING
 230  *
 231  * @param str           character string to be tested
 232  * @return                      TRUE if no special characters are contained
 233  */
 234 bool asn1_is_printablestring(chunk_t str);
 235
 236
 237 /** some ASN.1 synthesis functions */
 238
 239 /**
 240  * Build an empty ASN.1 object with tag and length fields already filled in
 241  *
 242  * @param object        returned object - memory is allocated by function
 243  * @param type          ASN.1 type to be created
 244  * @param datalen       size of the body to be created
 245  * @return                      points to the first position in the body
 246  */
 247 u_char* asn1_build_object(chunk_t *object, asn1_t type, size_t datalen);
 248
 249 /**
 250  * Build a simple ASN.1 object
 251  *
 252  * @param tag           ASN.1 type to be created
 253  * @param content       content of the ASN.1 object
 254  * @return                      chunk containing the ASN.1 coded object
 255  */
 256 chunk_t asn1_simple_object(asn1_t tag, chunk_t content);
 257
 258 /**
 259  * Build an ASN.1 BITSTRING object
 260  *
 261  * @param mode          'c' for copy or 'm' for move
 262  * @param content       content of the BITSTRING
 263  * @return                      chunk containing the ASN.1 coded BITSTRING
 264  */
 265 chunk_t asn1_bitstring(const char *mode, chunk_t content);
 266
 267 /**
 268  * Build an ASN.1 INTEGER object
 269  *
 270  * @param mode          'c' for copy or 'm' for move
 271  * @param content       content of the INTEGER
 272  * @return                      chunk containing the ASN.1 coded INTEGER
 273  */
 274 chunk_t asn1_integer(const char *mode, chunk_t content);
 275
 276 /**
 277  * Build an ASN.1 object from a variable number of individual chunks
 278  *
 279  * The mode string specifies the number of chunks, and how to handle each of
 280  * them with a single character: 'c' for copy (allocate new chunk), 'm' for move
 281  * (free given chunk) or 's' for sensitive-copy (clear given chunk, then free).
 282  *
 283  * @param type          ASN.1 type to be created
 284  * @param mode          for each list member: 'c', 'm' or 's'
 285  * @return                      chunk containing the ASN.1 coded object
 286  */
 287 chunk_t asn1_wrap(asn1_t type, const char *mode, ...);
 288
 289 #endif /** ASN1_H_ @}*/