doc/asn1.doc

   1 The ASN.1 Routines.
   2
   3 ASN.1 is a specification for how to encode structured 'data' in binary form.
   4 The approach I have take to the manipulation of structures and their encoding
   5 into ASN.1 is as follows.
   6
   7 For each distinct structure there are 4 function of the following form
   8 TYPE *TYPE_new(void);
   9 void TYPE_free(TYPE *);
  10 TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length);
  11 long i2d_TYPE(TYPE *a,unsigned char **pp);      /* CHECK RETURN VALUE */
  12
  13 where TYPE is the type of the 'object'.  The TYPE that have these functions
  14 can be in one of 2 forms, either the internal C malloc()ed data structure
  15 or in the DER (a variant of ASN.1 encoding) binary encoding which is just
  16 an array of unsigned bytes.  The 'i2d' functions converts from the internal
  17 form to the DER form and the 'd2i' functions convert from the DER form to
  18 the internal form.
  19
  20 The 'new' function returns a malloc()ed version of the structure with all
  21 substructures either created or left as NULL pointers.  For 'optional'
  22 fields, they are normally left as NULL to indicate no value.  For variable
  23 size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the
  24 STACK data type is used to hold the values.  Have a read of stack.doc
  25 and have a look at the relevant header files to see what I mean.  If there
  26 is an error while malloc()ing the structure, NULL is returned.
  27
  28 The 'free' function will free() all the sub components of a particular
  29 structure.  If any of those sub components have been 'removed', replace
  30 them with NULL pointers, the 'free' functions are tolerant of NULL fields.
  31
  32 The 'd2i' function copies a binary representation into a C structure.  It
  33 operates as follows.  'a' is a pointer to a pointer to
  34 the structure to populate, 'pp' is a pointer to a pointer to where the DER
  35 byte string is located and 'length' is the length of the '*pp' data.
  36 If there are no errors, a pointer to the populated structure is returned.
  37 If there is an error, NULL is returned.  Errors can occur because of
  38 malloc() failures but normally they will be due to syntax errors in the DER
  39 encoded data being parsed. It is also an error if there was an
  40 attempt to read more that 'length' bytes from '*p'.  If
  41 everything works correctly, the value in '*p' is updated
  42 to point at the location just beyond where the DER
  43 structure was read from.  In this way, chained calls to 'd2i' type
  44 functions can be made, with the pointer into the 'data' array being
  45 'walked' along the input byte array.
  46 Depending on the value passed for 'a', different things will be done.  If
  47 'a' is NULL, a new structure will be malloc()ed and returned.  If '*a' is
  48 NULL, a new structure will be malloc()ed and put into '*a' and returned.
  49 If '*a' is not NULL, the structure in '*a' will be populated, or in the
  50 case of an error, free()ed and then returned.
  51 Having these semantics means that a structure
  52 can call a 'd2i' function to populate a field and if the field is currently
  53 NULL, the structure will be created.
  54
  55 The 'i2d' function type is used to copy a C structure to a byte array.
  56 The parameter 'a' is the structure to convert and '*p' is where to put it.
  57 As for the 'd2i' type structure, 'p' is updated to point after the last
  58 byte written.  If p is NULL, no data is written.  The function also returns
  59 the number of bytes written.  Where this becomes useful is that if the
  60 function is called with a NULL 'p' value, the length is returned.  This can
  61 then be used to malloc() an array of bytes and then the same function can
  62 be recalled passing the malloced array to be written to. e.g.
  63
  64 int len;
  65 unsigned char *bytes,*p;
  66 len=i2d_X509(x,NULL);   /* get the size of the ASN1 encoding of 'x' */
  67 if ((bytes=(unsigned char *)malloc(len)) == NULL)
  68         goto err;
  69 p=bytes;
  70 i2d_X509(x,&p);
  71
  72 Please note that a new variable, 'p' was passed to i2d_X509.  After the
  73 call to i2d_X509 p has been incremented by len bytes.
  74
  75 Now the reason for this functional organisation is that it allows nested
  76 structures to be built up by calling these functions as required.  There
  77 are various macros used to help write the general 'i2d', 'd2i', 'new' and
  78 'free' functions.  They are discussed in another file and would only be
  79 used by some-one wanting to add new structures to the library.  As you
  80 might be able to guess, the process of writing ASN.1 files can be a bit CPU
  81 expensive for complex structures.  I'm willing to live with this since the
  82 simpler library code make my life easier and hopefully most programs using
  83 these routines will have their execution profiles dominated by cipher or
  84 message digest routines.
  85 What follows is a list of 'TYPE' values and the corresponding ASN.1
  86 structure and where it is used.
  87
  88 TYPE                    ASN.1
  89 ASN1_INTEGER            INTEGER
  90 ASN1_BIT_STRING         BIT STRING
  91 ASN1_OCTET_STRING       OCTET STRING
  92 ASN1_OBJECT             OBJECT IDENTIFIER
  93 ASN1_PRINTABLESTRING    PrintableString
  94 ASN1_T61STRING          T61String
  95 ASN1_IA5STRING          IA5String
  96 ASN1_UTCTIME            UTCTime
  97 ASN1_TYPE               Any of the above mentioned types plus SEQUENCE and SET
  98
  99 Most of the above mentioned types are actualled stored in the
 100 ASN1_BIT_STRING type and macros are used to differentiate between them.
 101 The 3 types used are
 102
 103 typedef struct asn1_object_st
 104         {
 105         /* both null if a dynamic ASN1_OBJECT, one is
 106          * defined if a 'static' ASN1_OBJECT */
 107         char *sn,*ln;
 108         int nid;
 109         int length;
 110         unsigned char *data;
 111         } ASN1_OBJECT;
 112 This is used to store ASN1 OBJECTS.  Read 'objects.doc' for details ono
 113 routines to manipulate this structure.  'sn' and 'ln' are used to hold text
 114 strings that represent the object (short name and long or lower case name).
 115 These are used by the 'OBJ' library.  'nid' is a number used by the OBJ
 116 library to uniquely identify objects.  The ASN1 routines will populate the
 117 'length' and 'data' fields which will contain the bit string representing
 118 the object.
 119
 120 typedef struct asn1_bit_string_st
 121         {
 122         int length;
 123         int type;
 124         unsigned char *data;
 125         } ASN1_BIT_STRING;
 126 This structure is used to hold all the other base ASN1 types except for
 127 ASN1_UTCTIME (which is really just a 'char *').  Length is the number of
 128 bytes held in data and type is the ASN1 type of the object (there is a list
 129 in asn1.h).
 130
 131 typedef struct asn1_type_st
 132         {
 133         int type;
 134         union   {
 135                 char *ptr;
 136                 ASN1_INTEGER *          integer;
 137                 ASN1_BIT_STRING *       bit_string;
 138                 ASN1_OCTET_STRING *     octet_string;
 139                 ASN1_OBJECT *           object;
 140                 ASN1_PRINTABLESTRING *  printablestring;
 141                 ASN1_T61STRING *        t61string;
 142                 ASN1_IA5STRING *        ia5string;
 143                 ASN1_UTCTIME *          utctime;
 144                 ASN1_BIT_STRING *       set;
 145                 ASN1_BIT_STRING *       sequence;
 146                 } value;
 147         } ASN1_TYPE;
 148 This structure is used in a few places when 'any' type of object can be
 149 expected.
 150
 151 X509                    Certificate
 152 X509_CINF               CertificateInfo
 153 X509_ALGOR              AlgorithmIdentifier
 154 X509_NAME               Name
 155 X509_NAME_ENTRY         A single sub component of the name.
 156 X509_VAL                Validity
 157 X509_PUBKEY             SubjectPublicKeyInfo
 158 The above mentioned types are declared in x509.h. They are all quite
 159 straight forward except for the X509_NAME/X509_NAME_ENTRY pair.
 160 A X509_NAME is a STACK (see stack.doc) of X509_NAME_ENTRY's.
 161 typedef struct X509_name_entry_st
 162         {
 163         ASN1_OBJECT *object;
 164         ASN1_BIT_STRING *value;
 165         int set;
 166         int size;       /* temp variable */
 167         } X509_NAME_ENTRY;
 168 The size is a temporary variable used by i2d_NAME and set is the set number
 169 for the particular NAME_ENTRY.  A X509_NAME is encoded as a sequence of
 170 sequence of sets.  Normally each set contains only a single item.
 171 Sometimes it contains more.  Normally throughout this library there will be
 172 only one item per set.  The set field contains the 'set' that this entry is
 173 a member of.  So if you have just created a X509_NAME structure and
 174 populated it with X509_NAME_ENTRYs, you should then traverse the X509_NAME
 175 (which is just a STACK) and set the 'set/' field to incrementing numbers.
 176 For more details on why this is done, read the ASN.1 spec for Distinguished
 177 Names.
 178
 179 X509_REQ                CertificateRequest
 180 X509_REQ_INFO           CertificateRequestInfo
 181 These are used to hold certificate requests.
 182
 183 X509_CRL                CertificateRevocationList
 184 These are used to hold a certificate revocation list
 185
 186 RSAPrivateKey           PrivateKeyInfo
 187 RSAPublicKey            PublicKeyInfo
 188 Both these 'function groups' operate on 'RSA' structures (see rsa.doc).
 189 The difference is that the RSAPublicKey operations only manipulate the m
 190 and e fields in the RSA structure.
 191
 192 DSAPrivateKey           DSS private key
 193 DSAPublicKey            DSS public key
 194 Both these 'function groups' operate on 'DSS' structures (see dsa.doc).
 195 The difference is that the RSAPublicKey operations only manipulate the
 196 XXX fields in the DSA structure.
 197
 198 DHparams                DHParameter
 199 This is used to hold the p and g value for The Diffie-Hellman operation.
 200 The function deal with the 'DH' strucure (see dh.doc).
 201
 202 Now all of these function types can be used with several other functions to give
 203 quite useful set of general manipulation routines.  Normally one would
 204 not uses these functions directly but use them via macros.
 205
 206 char *ASN1_dup(int (*i2d)(),char *(*d2i)(),char *x);
 207 'x' is the input structure case to a 'char *', 'i2d' is the 'i2d_TYPE'
 208 function for the type that 'x' is and d2i is the 'd2i_TYPE' function for the
 209 type that 'x' is.  As is obvious from the parameters, this function
 210 duplicates the strucutre by transforming it into the DER form and then
 211 re-loading it into a new strucutre and returning the new strucutre.  This
 212 is obviously a bit cpu intensive but when faced with a complex dynamic
 213 structure this is the simplest programming approach.  There are macros for
 214 duplicating the major data types but is simple to add extras.
 215
 216 char *ASN1_d2i_fp(char *(*new)(),char *(*d2i)(),FILE *fp,unsigned char **x);
 217 'x' is a pointer to a pointer of the 'desired type'.  new and d2i are the
 218 corresponding 'TYPE_new' and 'd2i_TYPE' functions for the type and 'fp' is
 219 an open file pointer to read from.  This function reads from 'fp' as much
 220 data as it can and then uses 'd2i' to parse the bytes to load and return
 221 the parsed strucutre in 'x' (if it was non-NULL) and to actually return the
 222 strucutre.  The behavior of 'x' is as per all the other d2i functions.
 223
 224 char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x);
 225 The 'BIO' is the new IO type being used in SSLeay (see bio.doc).  This
 226 function is the same as ASN1_d2i_fp() except for the BIO argument.
 227 ASN1_d2i_fp() actually calls this function.
 228
 229 int ASN1_i2d_fp(int (*i2d)(),FILE *out,unsigned char *x);
 230 'x' is converted to bytes by 'i2d' and then written to 'out'.  ASN1_i2d_fp
 231 and ASN1_d2i_fp are not really symetric since ASN1_i2d_fp will read all
 232 available data from the file pointer before parsing a single item while
 233 ASN1_i2d_fp can be used to write a sequence of data objects.  To read a
 234 series of objects from a file I would sugest loading the file into a buffer
 235 and calling the relevent 'd2i' functions.
 236
 237 char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x);
 238 This function is the same as ASN1_i2d_fp() except for the BIO argument.
 239 ASN1_i2d_fp() actually calls this function.
 240
 241 char *  PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
 242 This function will read the next PEM encoded (base64) object of the same
 243 type as 'x' (loaded by the d2i function).  'name' is the name that is in
 244 the '-----BEGIN name-----' that designates the start of that object type.
 245 If the data is encrypted, 'cb' will be called to prompt for a password.  If
 246 it is NULL a default function will be used to prompt from the password.
 247 'x' is delt with as per the standard 'd2i' function interface.  This
 248 function can be used to read a series of objects from a file.  While any
 249 data type can be encrypted (see PEM_ASN1_write) only RSA private keys tend
 250 to be encrypted.
 251
 252 char *  PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *fp,
 253         char **x,int (*cb)());
 254 Same as PEM_ASN1_read() except using a BIO.  This is called by
 255 PEM_ASN1_read().
 256
 257 int     PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,EVP_CIPHER *enc,
 258                 unsigned char *kstr,int klen,int (*callback)());
 259
 260 int     PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *fp,
 261                 char *x,EVP_CIPHER *enc,unsigned char *kstr,int klen,
 262                 int (*callback)());
 263
 264 int ASN1_sign(int (*i2d)(), X509_ALGOR *algor1, X509_ALGOR *algor2,
 265         ASN1_BIT_STRING *signature, char *data, RSA *rsa, EVP_MD *type);
 266 int ASN1_verify(int (*i2d)(), X509_ALGOR *algor1,
 267         ASN1_BIT_STRING *signature,char *data, RSA *rsa);
 268
 269 int ASN1_BIT_STRING_cmp(ASN1_BIT_STRING *a, ASN1_BIT_STRING *b);
 270 ASN1_BIT_STRING *ASN1_BIT_STRING_type_new(int type );
 271
 272 int ASN1_UTCTIME_check(ASN1_UTCTIME *a);
 273 void ASN1_UTCTIME_print(BIO *fp,ASN1_UTCTIME *a);
 274 ASN1_UTCTIME *ASN1_UTCTIME_dup(ASN1_UTCTIME *a);
 275
 276 ASN1_BIT_STRING *d2i_asn1_print_type(ASN1_BIT_STRING **a,unsigned char **pp,
 277                 long length,int type);
 278
 279 int             i2d_ASN1_SET(STACK *a, unsigned char **pp,
 280                         int (*func)(), int ex_tag, int ex_class);
 281 STACK *         d2i_ASN1_SET(STACK **a, unsigned char **pp, long length,
 282                         char *(*func)(), int ex_tag, int ex_class);
 283
 284 int i2a_ASN1_OBJECT(BIO *bp,ASN1_OBJECT *object);
 285 int i2a_ASN1_INTEGER(BIO *bp, ASN1_INTEGER *a);
 286 int a2i_ASN1_INTEGER(BIO *bp,ASN1_INTEGER *bs,char *buf,int size);
 287
 288 int ASN1_INTEGER_set(ASN1_INTEGER *a, long v);
 289 long ASN1_INTEGER_get(ASN1_INTEGER *a);
 290 ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai);
 291 BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn);
 292
 293 /* given a string, return the correct type.  Max is the maximum number
 294  * of bytes to parse.  It stops parsing when 'max' bytes have been
 295  * processed or a '\0' is hit */
 296 int ASN1_PRINTABLE_type(unsigned char *s,int max);
 297
 298 void ASN1_parse(BIO *fp,unsigned char *pp,long len);
 299
 300 int i2d_ASN1_bytes(ASN1_BIT_STRING *a, unsigned char **pp, int tag, int class);
 301 ASN1_BIT_STRING *d2i_ASN1_bytes(ASN1_OCTET_STRING **a, unsigned char **pp,
 302         long length, int Ptag, int Pclass);
 303
 304 /* PARSING */
 305 int asn1_Finish(ASN1_CTX *c);
 306
 307 /* SPECIALS */
 308 int ASN1_get_object(unsigned char **pp, long *plength, int *ptag,
 309         int *pclass, long omax);
 310 int ASN1_check_infinite_end(unsigned char **p,long len);
 311 void ASN1_put_object(unsigned char **pp, int constructed, int length,
 312         int tag, int class);
 313 int ASN1_object_size(int constructed, int length, int tag);
 314
 315 X509 *  X509_get_cert(CERTIFICATE_CTX *ctx,X509_NAME * name,X509 *tmp_x509);
 316 int     X509_add_cert(CERTIFICATE_CTX *ctx,X509 *);
 317
 318 char *  X509_cert_verify_error_string(int n);
 319 int     X509_add_cert_file(CERTIFICATE_CTX *c,char *file, int type);
 320 char *  X509_gmtime (char *s, long adj);
 321 int     X509_add_cert_dir (CERTIFICATE_CTX *c,char *dir, int type);
 322 int     X509_load_verify_locations (CERTIFICATE_CTX *ctx,
 323                 char *file_env, char *dir_env);
 324 int     X509_set_default_verify_paths(CERTIFICATE_CTX *cts);
 325 X509 *  X509_new_D2i_X509(int len, unsigned char *p);
 326 char *  X509_get_default_cert_area(void );
 327 char *  X509_get_default_cert_dir(void );
 328 char *  X509_get_default_cert_file(void );
 329 char *  X509_get_default_cert_dir_env(void );
 330 char *  X509_get_default_cert_file_env(void );
 331 char *  X509_get_default_private_dir(void );
 332 X509_REQ *X509_X509_TO_req(X509 *x, RSA *rsa);
 333 int     X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)());
 334
 335 CERTIFICATE_CTX *CERTIFICATE_CTX_new();
 336 void CERTIFICATE_CTX_free(CERTIFICATE_CTX *c);
 337
 338 void X509_NAME_print(BIO *fp, X509_NAME *name, int obase);
 339 int             X509_print_fp(FILE *fp,X509 *x);
 340 int             X509_print(BIO *fp,X509 *x);
 341
 342 X509_INFO *     X509_INFO_new(void);
 343 void            X509_INFO_free(X509_INFO *a);
 344
 345 char *          X509_NAME_oneline(X509_NAME *a);
 346
 347 #define X509_verify(x,rsa)
 348 #define X509_REQ_verify(x,rsa)
 349 #define X509_CRL_verify(x,rsa)
 350
 351 #define X509_sign(x,rsa,md)
 352 #define X509_REQ_sign(x,rsa,md)
 353 #define X509_CRL_sign(x,rsa,md)
 354
 355 #define X509_dup(x509)
 356 #define d2i_X509_fp(fp,x509)
 357 #define i2d_X509_fp(fp,x509)
 358 #define d2i_X509_bio(bp,x509)
 359 #define i2d_X509_bio(bp,x509)
 360
 361 #define X509_CRL_dup(crl)
 362 #define d2i_X509_CRL_fp(fp,crl)
 363 #define i2d_X509_CRL_fp(fp,crl)
 364 #define d2i_X509_CRL_bio(bp,crl)
 365 #define i2d_X509_CRL_bio(bp,crl)
 366
 367 #define X509_REQ_dup(req)
 368 #define d2i_X509_REQ_fp(fp,req)
 369 #define i2d_X509_REQ_fp(fp,req)
 370 #define d2i_X509_REQ_bio(bp,req)
 371 #define i2d_X509_REQ_bio(bp,req)
 372
 373 #define RSAPrivateKey_dup(rsa)
 374 #define d2i_RSAPrivateKey_fp(fp,rsa)
 375 #define i2d_RSAPrivateKey_fp(fp,rsa)
 376 #define d2i_RSAPrivateKey_bio(bp,rsa)
 377 #define i2d_RSAPrivateKey_bio(bp,rsa)
 378
 379 #define X509_NAME_dup(xn)
 380 #define X509_NAME_ENTRY_dup(ne)
 381
 382 void X509_REQ_print_fp(FILE *fp,X509_REQ *req);
 383 void X509_REQ_print(BIO *fp,X509_REQ *req);
 384
 385 RSA *X509_REQ_extract_key(X509_REQ *req);
 386 RSA *X509_extract_key(X509 *x509);
 387
 388 int             X509_issuer_and_serial_cmp(X509 *a, X509 *b);
 389 unsigned long   X509_issuer_and_serial_hash(X509 *a);
 390
 391 X509_NAME *     X509_get_issuer_name(X509 *a);
 392 int             X509_issuer_name_cmp(X509 *a, X509 *b);
 393 unsigned long   X509_issuer_name_hash(X509 *a);
 394
 395 X509_NAME *     X509_get_subject_name(X509 *a);
 396 int             X509_subject_name_cmp(X509 *a,X509 *b);
 397 unsigned long   X509_subject_name_hash(X509 *x);
 398
 399 int             X509_NAME_cmp (X509_NAME *a, X509_NAME *b);
 400 unsigned long   X509_NAME_hash(X509_NAME *x);
 401