diff options
Diffstat (limited to 'doc/asn1.doc')
| -rw-r--r-- | doc/asn1.doc | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/doc/asn1.doc b/doc/asn1.doc new file mode 100644 index 0000000000..fdad17c05c --- /dev/null +++ b/doc/asn1.doc @@ -0,0 +1,401 @@ +The ASN.1 Routines. + +ASN.1 is a specification for how to encode structured 'data' in binary form. +The approach I have take to the manipulation of structures and their encoding +into ASN.1 is as follows. + +For each distinct structure there are 4 function of the following form +TYPE *TYPE_new(void); +void TYPE_free(TYPE *); +TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length); +long i2d_TYPE(TYPE *a,unsigned char **pp); /* CHECK RETURN VALUE */ + +where TYPE is the type of the 'object'. The TYPE that have these functions +can be in one of 2 forms, either the internal C malloc()ed data structure +or in the DER (a variant of ASN.1 encoding) binary encoding which is just +an array of unsigned bytes. The 'i2d' functions converts from the internal +form to the DER form and the 'd2i' functions convert from the DER form to +the internal form. + +The 'new' function returns a malloc()ed version of the structure with all +substructures either created or left as NULL pointers. For 'optional' +fields, they are normally left as NULL to indicate no value. For variable +size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the +STACK data type is used to hold the values. Have a read of stack.doc +and have a look at the relevant header files to see what I mean. If there +is an error while malloc()ing the structure, NULL is returned. + +The 'free' function will free() all the sub components of a particular +structure. If any of those sub components have been 'removed', replace +them with NULL pointers, the 'free' functions are tolerant of NULL fields. + +The 'd2i' function copies a binary representation into a C structure. It +operates as follows. 'a' is a pointer to a pointer to +the structure to populate, 'pp' is a pointer to a pointer to where the DER +byte string is located and 'length' is the length of the '*pp' data. +If there are no errors, a pointer to the populated structure is returned. +If there is an error, NULL is returned. Errors can occur because of +malloc() failures but normally they will be due to syntax errors in the DER +encoded data being parsed. It is also an error if there was an +attempt to read more that 'length' bytes from '*p'. If +everything works correctly, the value in '*p' is updated +to point at the location just beyond where the DER +structure was read from. In this way, chained calls to 'd2i' type +functions can be made, with the pointer into the 'data' array being +'walked' along the input byte array. +Depending on the value passed for 'a', different things will be done. If +'a' is NULL, a new structure will be malloc()ed and returned. If '*a' is +NULL, a new structure will be malloc()ed and put into '*a' and returned. +If '*a' is not NULL, the structure in '*a' will be populated, or in the +case of an error, free()ed and then returned. +Having these semantics means that a structure +can call a 'd2i' function to populate a field and if the field is currently +NULL, the structure will be created. + +The 'i2d' function type is used to copy a C structure to a byte array. +The parameter 'a' is the structure to convert and '*p' is where to put it. +As for the 'd2i' type structure, 'p' is updated to point after the last +byte written. If p is NULL, no data is written. The function also returns +the number of bytes written. Where this becomes useful is that if the +function is called with a NULL 'p' value, the length is returned. This can +then be used to malloc() an array of bytes and then the same function can +be recalled passing the malloced array to be written to. e.g. + +int len; +unsigned char *bytes,*p; +len=i2d_X509(x,NULL); /* get the size of the ASN1 encoding of 'x' */ +if ((bytes=(unsigned char *)malloc(len)) == NULL) + goto err; +p=bytes; +i2d_X509(x,&p); + +Please note that a new variable, 'p' was passed to i2d_X509. After the +call to i2d_X509 p has been incremented by len bytes. + +Now the reason for this functional organisation is that it allows nested +structures to be built up by calling these functions as required. There +are various macros used to help write the general 'i2d', 'd2i', 'new' and +'free' functions. They are discussed in another file and would only be +used by some-one wanting to add new structures to the library. As you +might be able to guess, the process of writing ASN.1 files can be a bit CPU +expensive for complex structures. I'm willing to live with this since the +simpler library code make my life easier and hopefully most programs using +these routines will have their execution profiles dominated by cipher or +message digest routines. +What follows is a list of 'TYPE' values and the corresponding ASN.1 +structure and where it is used. + +TYPE ASN.1 +ASN1_INTEGER INTEGER +ASN1_BIT_STRING BIT STRING +ASN1_OCTET_STRING OCTET STRING +ASN1_OBJECT OBJECT IDENTIFIER +ASN1_PRINTABLESTRING PrintableString +ASN1_T61STRING T61String +ASN1_IA5STRING IA5String +ASN1_UTCTIME UTCTime +ASN1_TYPE Any of the above mentioned types plus SEQUENCE and SET + +Most of the above mentioned types are actualled stored in the +ASN1_BIT_STRING type and macros are used to differentiate between them. +The 3 types used are + +typedef struct asn1_object_st + { + /* both null if a dynamic ASN1_OBJECT, one is + * defined if a 'static' ASN1_OBJECT */ + char *sn,*ln; + int nid; + int length; + unsigned char *data; + } ASN1_OBJECT; +This is used to store ASN1 OBJECTS. Read 'objects.doc' for details ono +routines to manipulate this structure. 'sn' and 'ln' are used to hold text +strings that represent the object (short name and long or lower case name). +These are used by the 'OBJ' library. 'nid' is a number used by the OBJ +library to uniquely identify objects. The ASN1 routines will populate the +'length' and 'data' fields which will contain the bit string representing +the object. + +typedef struct asn1_bit_string_st + { + int length; + int type; + unsigned char *data; + } ASN1_BIT_STRING; +This structure is used to hold all the other base ASN1 types except for +ASN1_UTCTIME (which is really just a 'char *'). Length is the number of +bytes held in data and type is the ASN1 type of the object (there is a list +in asn1.h). + +typedef struct asn1_type_st + { + int type; + union { + char *ptr; + ASN1_INTEGER * integer; + ASN1_BIT_STRING * bit_string; + ASN1_OCTET_STRING * octet_string; + ASN1_OBJECT * object; + ASN1_PRINTABLESTRING * printablestring; + ASN1_T61STRING * t61string; + ASN1_IA5STRING * ia5string; + ASN1_UTCTIME * utctime; + ASN1_BIT_STRING * set; + ASN1_BIT_STRING * sequence; + } value; + } ASN1_TYPE; +This structure is used in a few places when 'any' type of object can be +expected. + +X509 Certificate +X509_CINF CertificateInfo +X509_ALGOR AlgorithmIdentifier +X509_NAME Name +X509_NAME_ENTRY A single sub component of the name. +X509_VAL Validity +X509_PUBKEY SubjectPublicKeyInfo +The above mentioned types are declared in x509.h. They are all quite +straight forward except for the X509_NAME/X509_NAME_ENTRY pair. +A X509_NAME is a STACK (see stack.doc) of X509_NAME_ENTRY's. +typedef struct X509_name_entry_st + { + ASN1_OBJECT *object; + ASN1_BIT_STRING *value; + int set; + int size; /* temp variable */ + } X509_NAME_ENTRY; +The size is a temporary variable used by i2d_NAME and set is the set number +for the particular NAME_ENTRY. A X509_NAME is encoded as a sequence of +sequence of sets. Normally each set contains only a single item. +Sometimes it contains more. Normally throughout this library there will be +only one item per set. The set field contains the 'set' that this entry is +a member of. So if you have just created a X509_NAME structure and +populated it with X509_NAME_ENTRYs, you should then traverse the X509_NAME +(which is just a STACK) and set the 'set/' field to incrementing numbers. +For more details on why this is done, read the ASN.1 spec for Distinguished +Names. + +X509_REQ CertificateRequest +X509_REQ_INFO CertificateRequestInfo +These are used to hold certificate requests. + +X509_CRL CertificateRevocationList +These are used to hold a certificate revocation list + +RSAPrivateKey PrivateKeyInfo +RSAPublicKey PublicKeyInfo +Both these 'function groups' operate on 'RSA' structures (see rsa.doc). +The difference is that the RSAPublicKey operations only manipulate the m +and e fields in the RSA structure. + +DSAPrivateKey DSS private key +DSAPublicKey DSS public key +Both these 'function groups' operate on 'DSS' structures (see dsa.doc). +The difference is that the RSAPublicKey operations only manipulate the +XXX fields in the DSA structure. + +DHparams DHParameter +This is used to hold the p and g value for The Diffie-Hellman operation. +The function deal with the 'DH' strucure (see dh.doc). + +Now all of these function types can be used with several other functions to give +quite useful set of general manipulation routines. Normally one would +not uses these functions directly but use them via macros. + +char *ASN1_dup(int (*i2d)(),char *(*d2i)(),char *x); +'x' is the input structure case to a 'char *', 'i2d' is the 'i2d_TYPE' +function for the type that 'x' is and d2i is the 'd2i_TYPE' function for the +type that 'x' is. As is obvious from the parameters, this function +duplicates the strucutre by transforming it into the DER form and then +re-loading it into a new strucutre and returning the new strucutre. This +is obviously a bit cpu intensive but when faced with a complex dynamic +structure this is the simplest programming approach. There are macros for +duplicating the major data types but is simple to add extras. + +char *ASN1_d2i_fp(char *(*new)(),char *(*d2i)(),FILE *fp,unsigned char **x); +'x' is a pointer to a pointer of the 'desired type'. new and d2i are the +corresponding 'TYPE_new' and 'd2i_TYPE' functions for the type and 'fp' is +an open file pointer to read from. This function reads from 'fp' as much +data as it can and then uses 'd2i' to parse the bytes to load and return +the parsed strucutre in 'x' (if it was non-NULL) and to actually return the +strucutre. The behavior of 'x' is as per all the other d2i functions. + +char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x); +The 'BIO' is the new IO type being used in SSLeay (see bio.doc). This +function is the same as ASN1_d2i_fp() except for the BIO argument. +ASN1_d2i_fp() actually calls this function. + +int ASN1_i2d_fp(int (*i2d)(),FILE *out,unsigned char *x); +'x' is converted to bytes by 'i2d' and then written to 'out'. ASN1_i2d_fp +and ASN1_d2i_fp are not really symetric since ASN1_i2d_fp will read all +available data from the file pointer before parsing a single item while +ASN1_i2d_fp can be used to write a sequence of data objects. To read a +series of objects from a file I would sugest loading the file into a buffer +and calling the relevent 'd2i' functions. + +char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x); +This function is the same as ASN1_i2d_fp() except for the BIO argument. +ASN1_i2d_fp() actually calls this function. + +char * PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)()); +This function will read the next PEM encoded (base64) object of the same +type as 'x' (loaded by the d2i function). 'name' is the name that is in +the '-----BEGIN name-----' that designates the start of that object type. +If the data is encrypted, 'cb' will be called to prompt for a password. If +it is NULL a default function will be used to prompt from the password. +'x' is delt with as per the standard 'd2i' function interface. This +function can be used to read a series of objects from a file. While any +data type can be encrypted (see PEM_ASN1_write) only RSA private keys tend +to be encrypted. + +char * PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *fp, + char **x,int (*cb)()); +Same as PEM_ASN1_read() except using a BIO. This is called by +PEM_ASN1_read(). + +int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,EVP_CIPHER *enc, + unsigned char *kstr,int klen,int (*callback)()); + +int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *fp, + char *x,EVP_CIPHER *enc,unsigned char *kstr,int klen, + int (*callback)()); + +int ASN1_sign(int (*i2d)(), X509_ALGOR *algor1, X509_ALGOR *algor2, + ASN1_BIT_STRING *signature, char *data, RSA *rsa, EVP_MD *type); +int ASN1_verify(int (*i2d)(), X509_ALGOR *algor1, + ASN1_BIT_STRING *signature,char *data, RSA *rsa); + +int ASN1_BIT_STRING_cmp(ASN1_BIT_STRING *a, ASN1_BIT_STRING *b); +ASN1_BIT_STRING *ASN1_BIT_STRING_type_new(int type ); + +int ASN1_UTCTIME_check(ASN1_UTCTIME *a); +void ASN1_UTCTIME_print(BIO *fp,ASN1_UTCTIME *a); +ASN1_UTCTIME *ASN1_UTCTIME_dup(ASN1_UTCTIME *a); + +ASN1_BIT_STRING *d2i_asn1_print_type(ASN1_BIT_STRING **a,unsigned char **pp, + long length,int type); + +int i2d_ASN1_SET(STACK *a, unsigned char **pp, + int (*func)(), int ex_tag, int ex_class); +STACK * d2i_ASN1_SET(STACK **a, unsigned char **pp, long length, + char *(*func)(), int ex_tag, int ex_class); + +int i2a_ASN1_OBJECT(BIO *bp,ASN1_OBJECT *object); +int i2a_ASN1_INTEGER(BIO *bp, ASN1_INTEGER *a); +int a2i_ASN1_INTEGER(BIO *bp,ASN1_INTEGER *bs,char *buf,int size); + +int ASN1_INTEGER_set(ASN1_INTEGER *a, long v); +long ASN1_INTEGER_get(ASN1_INTEGER *a); +ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai); +BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn); + +/* given a string, return the correct type. Max is the maximum number + * of bytes to parse. It stops parsing when 'max' bytes have been + * processed or a '\0' is hit */ +int ASN1_PRINTABLE_type(unsigned char *s,int max); + +void ASN1_parse(BIO *fp,unsigned char *pp,long len); + +int i2d_ASN1_bytes(ASN1_BIT_STRING *a, unsigned char **pp, int tag, int class); +ASN1_BIT_STRING *d2i_ASN1_bytes(ASN1_OCTET_STRING **a, unsigned char **pp, + long length, int Ptag, int Pclass); + +/* PARSING */ +int asn1_Finish(ASN1_CTX *c); + +/* SPECIALS */ +int ASN1_get_object(unsigned char **pp, long *plength, int *ptag, + int *pclass, long omax); +int ASN1_check_infinite_end(unsigned char **p,long len); +void ASN1_put_object(unsigned char **pp, int constructed, int length, + int tag, int class); +int ASN1_object_size(int constructed, int length, int tag); + +X509 * X509_get_cert(CERTIFICATE_CTX *ctx,X509_NAME * name,X509 *tmp_x509); +int X509_add_cert(CERTIFICATE_CTX *ctx,X509 *); + +char * X509_cert_verify_error_string(int n); +int X509_add_cert_file(CERTIFICATE_CTX *c,char *file, int type); +char * X509_gmtime (char *s, long adj); +int X509_add_cert_dir (CERTIFICATE_CTX *c,char *dir, int type); +int X509_load_verify_locations (CERTIFICATE_CTX *ctx, + char *file_env, char *dir_env); +int X509_set_default_verify_paths(CERTIFICATE_CTX *cts); +X509 * X509_new_D2i_X509(int len, unsigned char *p); +char * X509_get_default_cert_area(void ); +char * X509_get_default_cert_dir(void ); +char * X509_get_default_cert_file(void ); +char * X509_get_default_cert_dir_env(void ); +char * X509_get_default_cert_file_env(void ); +char * X509_get_default_private_dir(void ); +X509_REQ *X509_X509_TO_req(X509 *x, RSA *rsa); +int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)()); + +CERTIFICATE_CTX *CERTIFICATE_CTX_new(); +void CERTIFICATE_CTX_free(CERTIFICATE_CTX *c); + +void X509_NAME_print(BIO *fp, X509_NAME *name, int obase); +int X509_print_fp(FILE *fp,X509 *x); +int X509_print(BIO *fp,X509 *x); + +X509_INFO * X509_INFO_new(void); +void X509_INFO_free(X509_INFO *a); + +char * X509_NAME_oneline(X509_NAME *a); + +#define X509_verify(x,rsa) +#define X509_REQ_verify(x,rsa) +#define X509_CRL_verify(x,rsa) + +#define X509_sign(x,rsa,md) +#define X509_REQ_sign(x,rsa,md) +#define X509_CRL_sign(x,rsa,md) + +#define X509_dup(x509) +#define d2i_X509_fp(fp,x509) +#define i2d_X509_fp(fp,x509) +#define d2i_X509_bio(bp,x509) +#define i2d_X509_bio(bp,x509) + +#define X509_CRL_dup(crl) +#define d2i_X509_CRL_fp(fp,crl) +#define i2d_X509_CRL_fp(fp,crl) +#define d2i_X509_CRL_bio(bp,crl) +#define i2d_X509_CRL_bio(bp,crl) + +#define X509_REQ_dup(req) +#define d2i_X509_REQ_fp(fp,req) +#define i2d_X509_REQ_fp(fp,req) +#define d2i_X509_REQ_bio(bp,req) +#define i2d_X509_REQ_bio(bp,req) + +#define RSAPrivateKey_dup(rsa) +#define d2i_RSAPrivateKey_fp(fp,rsa) +#define i2d_RSAPrivateKey_fp(fp,rsa) +#define d2i_RSAPrivateKey_bio(bp,rsa) +#define i2d_RSAPrivateKey_bio(bp,rsa) + +#define X509_NAME_dup(xn) +#define X509_NAME_ENTRY_dup(ne) + +void X509_REQ_print_fp(FILE *fp,X509_REQ *req); +void X509_REQ_print(BIO *fp,X509_REQ *req); + +RSA *X509_REQ_extract_key(X509_REQ *req); +RSA *X509_extract_key(X509 *x509); + +int X509_issuer_and_serial_cmp(X509 *a, X509 *b); +unsigned long X509_issuer_and_serial_hash(X509 *a); + +X509_NAME * X509_get_issuer_name(X509 *a); +int X509_issuer_name_cmp(X509 *a, X509 *b); +unsigned long X509_issuer_name_hash(X509 *a); + +X509_NAME * X509_get_subject_name(X509 *a); +int X509_subject_name_cmp(X509 *a,X509 *b); +unsigned long X509_subject_name_hash(X509 *x); + +int X509_NAME_cmp (X509_NAME *a, X509_NAME *b); +unsigned long X509_NAME_hash(X509_NAME *x); + |