diff options
Diffstat (limited to 'doc/ssleay.txt')
-rw-r--r-- | doc/ssleay.txt | 6607 |
1 files changed, 6607 insertions, 0 deletions
diff --git a/doc/ssleay.txt b/doc/ssleay.txt new file mode 100644 index 0000000000..c905f6a0d6 --- /dev/null +++ b/doc/ssleay.txt @@ -0,0 +1,6607 @@ + +Bundle of old SSLeay documentation files [OBSOLETE!] + +==== readme ======================================================== + +This is the old 0.6.6 docuementation. Most of the cipher stuff is still +relevent but I'm working (very slowly) on new docuemtation. +The current version can be found online at + +http://www.cryptsoft.com/ssleay/doc + +==== API.doc ======================================================== + +SSL - SSLv2/v3/v23 etc. + +BIO - methods and how they plug together + +MEM - memory allocation callback + +CRYPTO - locking for threads + +EVP - Ciphers/Digests/signatures + +RSA - methods + +X509 - certificate retrieval + +X509 - validation + +X509 - X509v3 extensions + +Objects - adding object identifiers + +ASN.1 - parsing + +PEM - parsing + +==== a_verify.doc ======================================================== + +From eay@mincom.com Fri Oct 4 18:29:06 1996 +Received: by orb.mincom.oz.au id AA29080 + (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000 +Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST) +From: Eric Young <eay@mincom.oz.au> +X-Sender: eay@orb +To: wplatzer <wplatzer@iaik.tu-graz.ac.at> +Cc: Eric Young <eay@mincom.oz.au>, SSL Mailing List <ssl-users@mincom.com> +Subject: Re: Netscape's Public Key +In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at> +Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb> +Mime-Version: 1.0 +Content-Type: TEXT/PLAIN; charset=US-ASCII +Status: RO +X-Status: + +On Thu, 3 Oct 1996, wplatzer wrote: +> I get Public Key from Netscape (Gold 3.0b4), but cannot do anything +> with it... It looks like (asn1parse): +> +> 0:d=0 hl=3 l=180 cons: SEQUENCE +> 3:d=1 hl=2 l= 96 cons: SEQUENCE +> 5:d=2 hl=2 l= 92 cons: SEQUENCE +> 7:d=3 hl=2 l= 13 cons: SEQUENCE +> 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption +> 20:d=4 hl=2 l= 0 prim: NULL +> 22:d=3 hl=2 l= 75 prim: BIT STRING +> 99:d=2 hl=2 l= 0 prim: IA5STRING : +> 101:d=1 hl=2 l= 13 cons: SEQUENCE +> 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption +> 114:d=2 hl=2 l= 0 prim: NULL +> 116:d=1 hl=2 l= 65 prim: BIT STRING +> +> The first BIT STRING is the public key and the second BIT STRING is +> the signature. +> But a public key consists of the public exponent and the modulus. Are +> both numbers in the first BIT STRING? +> Is there a document simply describing this coding stuff (checking +> signature, get the public key, etc.)? + +Minimal in SSLeay. If you want to see what the modulus and exponent are, +try asn1parse -offset 25 -length 75 <key.pem +asn1parse will currently stuff up on the 'length 75' part (fixed in next +release) but it will print the stuff. If you are after more +documentation on ASN.1, have a look at www.rsa.com and get their PKCS +documents, most of my initial work on SSLeay was done using them. + +As for SSLeay, +util/crypto.num and util/ssl.num are lists of all exported functions in +the library (but not macros :-(. + +The ones for extracting public keys from certificates and certificate +requests are EVP_PKEY * X509_REQ_extract_key(X509_REQ *req); +EVP_PKEY * X509_extract_key(X509 *x509); + +To verify a signature on a signed ASN.1 object +int X509_verify(X509 *a,EVP_PKEY *key); +int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key); +int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key); +int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key); + +I should mention that EVP_PKEY can be used to hold a public or a private key, +since for things like RSA and DSS, a public key is just a subset of what +is stored for the private key. + +To sign any of the above structures + +int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md); +int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md); +int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md); +int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md); + +where md is the message digest to sign with. + +There are all defined in x509.h and all the _sign and _verify functions are +actually macros to the ASN1_sign() and ASN1_verify() functions. +These functions will put the correct algorithm identifiers in the correct +places in the structures. + +eric +-- +Eric Young | BOOL is tri-state according to Bill Gates. +AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). + +==== verify ======================================================== + +X509_verify_cert_chain( + CERT_STORE *cert_store, + STACK /* X509 */ *certs, + int *verify_result, + int (*verify_error_callback)() + char *argument_to_callback, /* SSL */ + +app_verify_callback( + char *app_verify_arg, /* from SSL_CTX */ + STACK /* X509 */ *certs, + int *verify_result, + int (*verify_error_callback)() + SSL *s, + +int X509_verify_cert( + CERT_STORE *cert_store, + X509 *x509, + int *verify_result, + int (*verify_error_callback)(), + char *arg, + +==== apps.doc ======================================================== + +The applications + +Ok, where to begin.... +In the begining, when SSLeay was small (April 1995), there +were but few applications, they did happily cohabit in +the one bin directory. Then over time, they did multiply and grow, +and they started to look like microsoft software; 500k to print 'hello world'. +A new approach was needed. They were coalessed into one 'Monolithic' +application, ssleay. This one program is composed of many programs that +can all be compiled independantly. + +ssleay has 3 modes of operation. +1) If the ssleay binaray has the name of one of its component programs, it +executes that program and then exits. This can be achieve by using hard or +symbolic links, or failing that, just renaming the binary. +2) If the first argument to ssleay is the name of one of the component +programs, that program runs that program and then exits. +3) If there are no arguments, ssleay enters a 'command' mode. Each line is +interpreted as a program name plus arguments. After each 'program' is run, +ssleay returns to the comand line. + +dgst - message digests +enc - encryption and base64 encoding + +ans1parse - 'pulls' appart ASN.1 encoded objects like certificates. + +dh - Diffle-Hellman parameter manipulation. +rsa - RSA manipulations. +crl - Certificate revokion list manipulations +x509 - X509 cert fiddles, including signing. +pkcs7 - pkcs7 manipulation, only DER versions right now. + +genrsa - generate an RSA private key. +gendh - Generate a set of Diffle-Hellman parameters. +req - Generate a PKCS#10 object, a certificate request. + +s_client - SSL client program +s_server - SSL server program +s_time - A SSL protocol timing program +s_mult - Another SSL server, but it multiplexes + connections. +s_filter - under development + +errstr - Convert SSLeay error numbers to strings. +ca - Sign certificate requests, and generate + certificate revokion lists +crl2pkcs7 - put a crl and certifcates into a pkcs7 object. +speed - Benchmark the ciphers. +verify - Check certificates +hashdir - under development + +[ there a now a few more options, play with the program to see what they + are ] + +==== asn1.doc ======================================================== + +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); + + +==== bio.doc ======================================================== + +BIO Routines + +This documentation is rather sparse, you are probably best +off looking at the code for specific details. + +The BIO library is a IO abstraction that was originally +inspired by the need to have callbacks to perform IO to FILE +pointers when using Windows 3.1 DLLs. There are two types +of BIO; a source/sink type and a filter type. +The source/sink methods are as follows: +- BIO_s_mem() memory buffer - a read/write byte array that + grows until memory runs out :-). +- BIO_s_file() FILE pointer - A wrapper around the normal + 'FILE *' commands, good for use with stdin/stdout. +- BIO_s_fd() File descriptor - A wrapper around file + descriptors, often used with pipes. +- BIO_s_socket() Socket - Used around sockets. It is + mostly in the Microsoft world that sockets are different + from file descriptors and there are all those ugly winsock + commands. +- BIO_s_null() Null - read nothing and write nothing.; a + useful endpoint for filter type BIO's specifically things + like the message digest BIO. + +The filter types are +- BIO_f_buffer() IO buffering - does output buffering into + larger chunks and performs input buffering to allow gets() + type functions. +- BIO_f_md() Message digest - a transparent filter that can + be asked to return a message digest for the data that has + passed through it. +- BIO_f_cipher() Encrypt or decrypt all data passing + through the filter. +- BIO_f_base64() Base64 decode on read and encode on write. +- BIO_f_ssl() A filter that performs SSL encryption on the + data sent through it. + +Base BIO functions. +The BIO library has a set of base functions that are +implemented for each particular type. Filter BIOs will +normally call the equivalent function on the source/sink BIO +that they are layered on top of after they have performed +some modification to the data stream. Multiple filter BIOs +can be 'push' into a stack of modifers, so to read from a +file, unbase64 it, then decrypt it, a BIO_f_cipher, +BIO_f_base64 and a BIO_s_file would probably be used. If a +sha-1 and md5 message digest needed to be generated, a stack +two BIO_f_md() BIOs and a BIO_s_null() BIO could be used. +The base functions are +- BIO *BIO_new(BIO_METHOD *type); Create a new BIO of type 'type'. +- int BIO_free(BIO *a); Free a BIO structure. Depending on + the configuration, this will free the underlying data + object for a source/sink BIO. +- int BIO_read(BIO *b, char *data, int len); Read upto 'len' + bytes into 'data'. +- int BIO_gets(BIO *bp,char *buf, int size); Depending on + the BIO, this can either be a 'get special' or a get one + line of data, as per fgets(); +- int BIO_write(BIO *b, char *data, int len); Write 'len' + bytes from 'data' to the 'b' BIO. +- int BIO_puts(BIO *bp,char *buf); Either a 'put special' or + a write null terminated string as per fputs(). +- long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg); A + control function which is used to manipulate the BIO + structure and modify it's state and or report on it. This + function is just about never used directly, rather it + should be used in conjunction with BIO_METHOD specific + macros. +- BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the + top of the 'old' BIO list. new_top should be a filter BIO. + All writes will go through 'new_top' first and last on read. + 'old' is returned. +- BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if + there are no more. + +If a particular low level BIO method is not supported +(normally BIO_gets()), -2 will be returned if that method is +called. Otherwise the IO methods (read, write, gets, puts) +will return the number of bytes read or written, and 0 or -1 +for error (or end of input). For the -1 case, +BIO_should_retry(bio) can be called to determine if it was a +genuine error or a temporary problem. -2 will also be +returned if the BIO has not been initalised yet, in all +cases, the correct error codes are set (accessible via the +ERR library). + + +The following functions are convenience functions: +- int BIO_printf(BIO *bio, char * format, ..); printf but + to a BIO handle. +- long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a + convenience function to allow a different argument types + to be passed to BIO_ctrl(). +- int BIO_dump(BIO *b,char *bytes,int len); output 'len' + bytes from 'bytes' in a hex dump debug format. +- long BIO_debug_callback(BIO *bio, int cmd, char *argp, int + argi, long argl, long ret) - a default debug BIO callback, + this is mentioned below. To use this one normally has to + use the BIO_set_callback_arg() function to assign an + output BIO for the callback to use. +- BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack' + of BIOs, this function scan the list and returns the first + that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX. +- void BIO_free_all(BIO *bio); Free the bio and all other BIOs + in the list. It walks the bio->next_bio list. + + + +Extra commands are normally implemented as macros calling BIO_ctrl(). +- BIO_number_read(BIO *bio) - the number of bytes processed + by BIO_read(bio,.). +- BIO_number_written(BIO *bio) - the number of bytes written + by BIO_write(bio,.). +- BIO_reset(BIO *bio) - 'reset' the BIO. +- BIO_eof(BIO *bio) - non zero if we are at the current end + of input. +- BIO_set_close(BIO *bio, int close_flag) - set the close flag. +- BIO_get_close(BIO *bio) - return the close flag. + BIO_pending(BIO *bio) - return the number of bytes waiting + to be read (normally buffered internally). +- BIO_flush(BIO *bio) - output any data waiting to be output. +- BIO_should_retry(BIO *io) - after a BIO_read/BIO_write + operation returns 0 or -1, a call to this function will + return non zero if you should retry the call later (this + is for non-blocking IO). +- BIO_should_read(BIO *io) - we should retry when data can + be read. +- BIO_should_write(BIO *io) - we should retry when data can + be written. +- BIO_method_name(BIO *io) - return a string for the method name. +- BIO_method_type(BIO *io) - return the unique ID of the BIO method. +- BIO_set_callback(BIO *io, long (*callback)(BIO *io, int + cmd, char *argp, int argi, long argl, long ret); - sets + the debug callback. +- BIO_get_callback(BIO *io) - return the assigned function + as mentioned above. +- BIO_set_callback_arg(BIO *io, char *arg) - assign some + data against the BIO. This is normally used by the debug + callback but could in reality be used for anything. To + get an idea of how all this works, have a look at the code + in the default debug callback mentioned above. The + callback can modify the return values. + +Details of the BIO_METHOD structure. +typedef struct bio_method_st + { + int type; + char *name; + int (*bwrite)(); + int (*bread)(); + int (*bputs)(); + int (*bgets)(); + long (*ctrl)(); + int (*create)(); + int (*destroy)(); + } BIO_METHOD; + +The 'type' is the numeric type of the BIO, these are listed in buffer.h; +'Name' is a textual representation of the BIO 'type'. +The 7 function pointers point to the respective function +methods, some of which can be NULL if not implemented. +The BIO structure +typedef struct bio_st + { + BIO_METHOD *method; + long (*callback)(BIO * bio, int mode, char *argp, int + argi, long argl, long ret); + char *cb_arg; /* first argument for the callback */ + int init; + int shutdown; + int flags; /* extra storage */ + int num; + char *ptr; + struct bio_st *next_bio; /* used by filter BIOs */ + int references; + unsigned long num_read; + unsigned long num_write; + } BIO; + +- 'Method' is the BIO method. +- 'callback', when configured, is called before and after + each BIO method is called for that particular BIO. This + is intended primarily for debugging and of informational feedback. +- 'init' is 0 when the BIO can be used for operation. + Often, after a BIO is created, a number of operations may + need to be performed before it is available for use. An + example is for BIO_s_sock(). A socket needs to be + assigned to the BIO before it can be used. +- 'shutdown', this flag indicates if the underlying + comunication primative being used should be closed/freed + when the BIO is closed. +- 'flags' is used to hold extra state. It is primarily used + to hold information about why a non-blocking operation + failed and to record startup protocol information for the + SSL BIO. +- 'num' and 'ptr' are used to hold instance specific state + like file descriptors or local data structures. +- 'next_bio' is used by filter BIOs to hold the pointer of the + next BIO in the chain. written data is sent to this BIO and + data read is taken from it. +- 'references' is used to indicate the number of pointers to + this structure. This needs to be '1' before a call to + BIO_free() is made if the BIO_free() function is to + actually free() the structure, otherwise the reference + count is just decreased. The actual BIO subsystem does + not really use this functionality but it is useful when + used in more advanced applicaion. +- num_read and num_write are the total number of bytes + read/written via the 'read()' and 'write()' methods. + +BIO_ctrl operations. +The following is the list of standard commands passed as the +second parameter to BIO_ctrl() and should be supported by +all BIO as best as possible. Some are optional, some are +manditory, in any case, where is makes sense, a filter BIO +should pass such requests to underlying BIO's. +- BIO_CTRL_RESET - Reset the BIO back to an initial state. +- BIO_CTRL_EOF - return 0 if we are not at the end of input, + non 0 if we are. +- BIO_CTRL_INFO - BIO specific special command, normal + information return. +- BIO_CTRL_SET - set IO specific parameter. +- BIO_CTRL_GET - get IO specific parameter. +- BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one + of BIO_CLOSE or BIO_NOCLOSE. +- BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag. +- BIO_CTRL_PENDING - Return the number of bytes available + for instant reading +- BIO_CTRL_FLUSH - Output pending data, return number of bytes output. +- BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned) + should we 'retry' when IO is possible on the underlying IO object. +- BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on. + +The following command is a special BIO_s_file() specific option. +- BIO_CTRL_SET_FILENAME - specify a file to open for IO. + +The BIO_CTRL_RETRY_TYPE needs a little more explanation. +When performing non-blocking IO, or say reading on a memory +BIO, when no data is present (or cannot be written), +BIO_read() and/or BIO_write() will return -1. +BIO_should_retry(bio) will return true if this is due to an +IO condition rather than an actual error. In the case of +BIO_s_mem(), a read when there is no data will return -1 and +a should retry when there is more 'read' data. +The retry type is deduced from 2 macros +BIO_should_read(bio) and BIO_should_write(bio). +Now while it may appear obvious that a BIO_read() failure +should indicate that a retry should be performed when more +read data is available, this is often not true when using +things like an SSL BIO. During the SSL protocol startup +multiple reads and writes are performed, triggered by any +SSL_read or SSL_write. +So to write code that will transparently handle either a +socket or SSL BIO, + i=BIO_read(bio,..) + if (I == -1) + { + if (BIO_should_retry(bio)) + { + if (BIO_should_read(bio)) + { + /* call us again when BIO can be read */ + } + if (BIO_should_write(bio)) + { + /* call us again when BIO can be written */ + } + } + } + +At this point in time only read and write conditions can be +used but in the future I can see the situation for other +conditions, specifically with SSL there could be a condition +of a X509 certificate lookup taking place and so the non- +blocking BIO_read would require a retry when the certificate +lookup subsystem has finished it's lookup. This is all +makes more sense and is easy to use in a event loop type +setup. +When using the SSL BIO, either SSL_read() or SSL_write()s +can be called during the protocol startup and things will +still work correctly. +The nice aspect of the use of the BIO_should_retry() macro +is that all the errno codes that indicate a non-fatal error +are encapsulated in one place. The Windows specific error +codes and WSAGetLastError() calls are also hidden from the +application. + +Notes on each BIO method. +Normally buffer.h is just required but depending on the +BIO_METHOD, ssl.h or evp.h will also be required. + +BIO_METHOD *BIO_s_mem(void); +- BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) - + set the underlying BUF_MEM structure for the BIO to use. +- BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL, + set it to point to the memory array and return the number + of bytes available. +A read/write BIO. Any data written is appended to the +memory array and any read is read from the front. This BIO +can be used for read/write at the same time. BIO_gets() is +supported in the fgets() sense. +BIO_CTRL_INFO can be used to retrieve pointers to the memory +buffer and it's length. + +BIO_METHOD *BIO_s_file(void); +- BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use. +- BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in |