diff options
Diffstat (limited to 'src/lib/libssl/src/doc')
56 files changed, 9205 insertions, 6293 deletions
diff --git a/src/lib/libssl/src/doc/API.doc b/src/lib/libssl/src/doc/API.doc deleted file mode 100644 index fe2820259a..0000000000 --- a/src/lib/libssl/src/doc/API.doc +++ /dev/null | |||
| @@ -1,24 +0,0 @@ | |||
| 1 | SSL - SSLv2/v3/v23 etc. | ||
| 2 | |||
| 3 | BIO - methods and how they plug together | ||
| 4 | |||
| 5 | MEM - memory allocation callback | ||
| 6 | |||
| 7 | CRYPTO - locking for threads | ||
| 8 | |||
| 9 | EVP - Ciphers/Digests/signatures | ||
| 10 | |||
| 11 | RSA - methods | ||
| 12 | |||
| 13 | X509 - certificate retrieval | ||
| 14 | |||
| 15 | X509 - validation | ||
| 16 | |||
| 17 | X509 - X509v3 extensions | ||
| 18 | |||
| 19 | Objects - adding object identifiers | ||
| 20 | |||
| 21 | ASN.1 - parsing | ||
| 22 | |||
| 23 | PEM - parsing | ||
| 24 | |||
diff --git a/src/lib/libssl/src/doc/README b/src/lib/libssl/src/doc/README new file mode 100644 index 0000000000..a9a588262a --- /dev/null +++ b/src/lib/libssl/src/doc/README | |||
| @@ -0,0 +1,10 @@ | |||
| 1 | |||
| 2 | openssl.pod ..... Documentation of OpenSSL `openssl' command | ||
| 3 | crypto.pod ...... Documentation of OpenSSL crypto.h+libcrypto.a | ||
| 4 | ssl.pod ......... Documentation of OpenSSL ssl.h+libssl.a | ||
| 5 | ssleay.txt ...... Assembled documentation files of ancestor SSLeay [obsolete] | ||
| 6 | openssl.txt ..... Assembled documentation files for OpenSSL [not final] | ||
| 7 | |||
| 8 | An archive of HTML documents for the SSLeay library is available from | ||
| 9 | http://www.columbia.edu/~ariel/ssleay/ | ||
| 10 | |||
diff --git a/src/lib/libssl/src/doc/a_verify.doc b/src/lib/libssl/src/doc/a_verify.doc deleted file mode 100644 index 06eec17c2b..0000000000 --- a/src/lib/libssl/src/doc/a_verify.doc +++ /dev/null | |||
| @@ -1,85 +0,0 @@ | |||
| 1 | From eay@mincom.com Fri Oct 4 18:29:06 1996 | ||
| 2 | Received: by orb.mincom.oz.au id AA29080 | ||
| 3 | (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000 | ||
| 4 | Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST) | ||
| 5 | From: Eric Young <eay@mincom.oz.au> | ||
| 6 | X-Sender: eay@orb | ||
| 7 | To: wplatzer <wplatzer@iaik.tu-graz.ac.at> | ||
| 8 | Cc: Eric Young <eay@mincom.oz.au>, SSL Mailing List <ssl-users@mincom.com> | ||
| 9 | Subject: Re: Netscape's Public Key | ||
| 10 | In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at> | ||
| 11 | Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb> | ||
| 12 | Mime-Version: 1.0 | ||
| 13 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 14 | Status: RO | ||
| 15 | X-Status: | ||
| 16 | |||
| 17 | On Thu, 3 Oct 1996, wplatzer wrote: | ||
| 18 | > I get Public Key from Netscape (Gold 3.0b4), but cannot do anything | ||
| 19 | > with it... It looks like (asn1parse): | ||
| 20 | > | ||
| 21 | > 0:d=0 hl=3 l=180 cons: SEQUENCE | ||
| 22 | > 3:d=1 hl=2 l= 96 cons: SEQUENCE | ||
| 23 | > 5:d=2 hl=2 l= 92 cons: SEQUENCE | ||
| 24 | > 7:d=3 hl=2 l= 13 cons: SEQUENCE | ||
| 25 | > 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption | ||
| 26 | > 20:d=4 hl=2 l= 0 prim: NULL | ||
| 27 | > 22:d=3 hl=2 l= 75 prim: BIT STRING | ||
| 28 | > 99:d=2 hl=2 l= 0 prim: IA5STRING : | ||
| 29 | > 101:d=1 hl=2 l= 13 cons: SEQUENCE | ||
| 30 | > 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption | ||
| 31 | > 114:d=2 hl=2 l= 0 prim: NULL | ||
| 32 | > 116:d=1 hl=2 l= 65 prim: BIT STRING | ||
| 33 | > | ||
| 34 | > The first BIT STRING is the public key and the second BIT STRING is | ||
| 35 | > the signature. | ||
| 36 | > But a public key consists of the public exponent and the modulus. Are | ||
| 37 | > both numbers in the first BIT STRING? | ||
| 38 | > Is there a document simply describing this coding stuff (checking | ||
| 39 | > signature, get the public key, etc.)? | ||
| 40 | |||
| 41 | Minimal in SSLeay. If you want to see what the modulus and exponent are, | ||
| 42 | try asn1parse -offset 25 -length 75 <key.pem | ||
| 43 | asn1parse will currently stuff up on the 'length 75' part (fixed in next | ||
| 44 | release) but it will print the stuff. If you are after more | ||
| 45 | documentation on ASN.1, have a look at www.rsa.com and get their PKCS | ||
| 46 | documents, most of my initial work on SSLeay was done using them. | ||
| 47 | |||
| 48 | As for SSLeay, | ||
| 49 | util/crypto.num and util/ssl.num are lists of all exported functions in | ||
| 50 | the library (but not macros :-(. | ||
| 51 | |||
| 52 | The ones for extracting public keys from certificates and certificate | ||
| 53 | requests are EVP_PKEY * X509_REQ_extract_key(X509_REQ *req); | ||
| 54 | EVP_PKEY * X509_extract_key(X509 *x509); | ||
| 55 | |||
| 56 | To verify a signature on a signed ASN.1 object | ||
| 57 | int X509_verify(X509 *a,EVP_PKEY *key); | ||
| 58 | int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key); | ||
| 59 | int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key); | ||
| 60 | int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key); | ||
| 61 | |||
| 62 | I should mention that EVP_PKEY can be used to hold a public or a private key, | ||
| 63 | since for things like RSA and DSS, a public key is just a subset of what | ||
| 64 | is stored for the private key. | ||
| 65 | |||
| 66 | To sign any of the above structures | ||
| 67 | |||
| 68 | int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md); | ||
| 69 | int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md); | ||
| 70 | int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md); | ||
| 71 | int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md); | ||
| 72 | |||
| 73 | where md is the message digest to sign with. | ||
| 74 | |||
| 75 | There are all defined in x509.h and all the _sign and _verify functions are | ||
| 76 | actually macros to the ASN1_sign() and ASN1_verify() functions. | ||
| 77 | These functions will put the correct algorithm identifiers in the correct | ||
| 78 | places in the structures. | ||
| 79 | |||
| 80 | eric | ||
| 81 | -- | ||
| 82 | Eric Young | BOOL is tri-state according to Bill Gates. | ||
| 83 | AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). | ||
| 84 | |||
| 85 | |||
diff --git a/src/lib/libssl/src/doc/apps.doc b/src/lib/libssl/src/doc/apps.doc deleted file mode 100644 index a2a4e0de72..0000000000 --- a/src/lib/libssl/src/doc/apps.doc +++ /dev/null | |||
| @@ -1,53 +0,0 @@ | |||
| 1 | The applications | ||
| 2 | |||
| 3 | Ok, where to begin.... | ||
| 4 | In the begining, when SSLeay was small (April 1995), there | ||
| 5 | were but few applications, they did happily cohabit in | ||
| 6 | the one bin directory. Then over time, they did multiply and grow, | ||
| 7 | and they started to look like microsoft software; 500k to print 'hello world'. | ||
| 8 | A new approach was needed. They were coalessed into one 'Monolithic' | ||
| 9 | application, ssleay. This one program is composed of many programs that | ||
| 10 | can all be compiled independantly. | ||
| 11 | |||
| 12 | ssleay has 3 modes of operation. | ||
| 13 | 1) If the ssleay binaray has the name of one of its component programs, it | ||
| 14 | executes that program and then exits. This can be achieve by using hard or | ||
| 15 | symbolic links, or failing that, just renaming the binary. | ||
| 16 | 2) If the first argument to ssleay is the name of one of the component | ||
| 17 | programs, that program runs that program and then exits. | ||
| 18 | 3) If there are no arguments, ssleay enters a 'command' mode. Each line is | ||
| 19 | interpreted as a program name plus arguments. After each 'program' is run, | ||
| 20 | ssleay returns to the comand line. | ||
| 21 | |||
| 22 | dgst - message digests | ||
| 23 | enc - encryption and base64 encoding | ||
| 24 | |||
| 25 | ans1parse - 'pulls' appart ASN.1 encoded objects like certificates. | ||
| 26 | |||
| 27 | dh - Diffle-Hellman parameter manipulation. | ||
| 28 | rsa - RSA manipulations. | ||
| 29 | crl - Certificate revokion list manipulations | ||
| 30 | x509 - X509 cert fiddles, including signing. | ||
| 31 | pkcs7 - pkcs7 manipulation, only DER versions right now. | ||
| 32 | |||
| 33 | genrsa - generate an RSA private key. | ||
| 34 | gendh - Generate a set of Diffle-Hellman parameters. | ||
| 35 | req - Generate a PKCS#10 object, a certificate request. | ||
| 36 | |||
| 37 | s_client - SSL client program | ||
| 38 | s_server - SSL server program | ||
| 39 | s_time - A SSL protocol timing program | ||
| 40 | s_mult - Another SSL server, but it multiplexes | ||
| 41 | connections. | ||
| 42 | s_filter - under development | ||
| 43 | |||
| 44 | errstr - Convert SSLeay error numbers to strings. | ||
| 45 | ca - Sign certificate requests, and generate | ||
| 46 | certificate revokion lists | ||
| 47 | crl2pkcs7 - put a crl and certifcates into a pkcs7 object. | ||
| 48 | speed - Benchmark the ciphers. | ||
| 49 | verify - Check certificates | ||
| 50 | hashdir - under development | ||
| 51 | |||
| 52 | [ there a now a few more options, play with the program to see what they | ||
| 53 | are ] | ||
diff --git a/src/lib/libssl/src/doc/asn1.doc b/src/lib/libssl/src/doc/asn1.doc deleted file mode 100644 index fdad17c05c..0000000000 --- a/src/lib/libssl/src/doc/asn1.doc +++ /dev/null | |||
| @@ -1,401 +0,0 @@ | |||
| 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 | |||
diff --git a/src/lib/libssl/src/doc/bio.doc b/src/lib/libssl/src/doc/bio.doc deleted file mode 100644 index 545a57cdff..0000000000 --- a/src/lib/libssl/src/doc/bio.doc +++ /dev/null | |||
| @@ -1,423 +0,0 @@ | |||
| 1 | BIO Routines | ||
| 2 | |||
| 3 | This documentation is rather sparse, you are probably best | ||
| 4 | off looking at the code for specific details. | ||
| 5 | |||
| 6 | The BIO library is a IO abstraction that was originally | ||
| 7 | inspired by the need to have callbacks to perform IO to FILE | ||
| 8 | pointers when using Windows 3.1 DLLs. There are two types | ||
| 9 | of BIO; a source/sink type and a filter type. | ||
| 10 | The source/sink methods are as follows: | ||
| 11 | - BIO_s_mem() memory buffer - a read/write byte array that | ||
| 12 | grows until memory runs out :-). | ||
| 13 | - BIO_s_file() FILE pointer - A wrapper around the normal | ||
| 14 | 'FILE *' commands, good for use with stdin/stdout. | ||
| 15 | - BIO_s_fd() File descriptor - A wrapper around file | ||
| 16 | descriptors, often used with pipes. | ||
| 17 | - BIO_s_socket() Socket - Used around sockets. It is | ||
| 18 | mostly in the Microsoft world that sockets are different | ||
| 19 | from file descriptors and there are all those ugly winsock | ||
| 20 | commands. | ||
| 21 | - BIO_s_null() Null - read nothing and write nothing.; a | ||
| 22 | useful endpoint for filter type BIO's specifically things | ||
| 23 | like the message digest BIO. | ||
| 24 | |||
| 25 | The filter types are | ||
| 26 | - BIO_f_buffer() IO buffering - does output buffering into | ||
| 27 | larger chunks and performs input buffering to allow gets() | ||
| 28 | type functions. | ||
| 29 | - BIO_f_md() Message digest - a transparent filter that can | ||
| 30 | be asked to return a message digest for the data that has | ||
| 31 | passed through it. | ||
| 32 | - BIO_f_cipher() Encrypt or decrypt all data passing | ||
| 33 | through the filter. | ||
| 34 | - BIO_f_base64() Base64 decode on read and encode on write. | ||
| 35 | - BIO_f_ssl() A filter that performs SSL encryption on the | ||
| 36 | data sent through it. | ||
| 37 | |||
| 38 | Base BIO functions. | ||
| 39 | The BIO library has a set of base functions that are | ||
| 40 | implemented for each particular type. Filter BIOs will | ||
| 41 | normally call the equivalent function on the source/sink BIO | ||
| 42 | that they are layered on top of after they have performed | ||
| 43 | some modification to the data stream. Multiple filter BIOs | ||
| 44 | can be 'push' into a stack of modifers, so to read from a | ||
| 45 | file, unbase64 it, then decrypt it, a BIO_f_cipher, | ||
| 46 | BIO_f_base64 and a BIO_s_file would probably be used. If a | ||
| 47 | sha-1 and md5 message digest needed to be generated, a stack | ||
| 48 | two BIO_f_md() BIOs and a BIO_s_null() BIO could be used. | ||
| 49 | The base functions are | ||
| 50 | - BIO *BIO_new(BIO_METHOD *type); Create a new BIO of type 'type'. | ||
| 51 | - int BIO_free(BIO *a); Free a BIO structure. Depending on | ||
| 52 | the configuration, this will free the underlying data | ||
| 53 | object for a source/sink BIO. | ||
| 54 | - int BIO_read(BIO *b, char *data, int len); Read upto 'len' | ||
| 55 | bytes into 'data'. | ||
| 56 | - int BIO_gets(BIO *bp,char *buf, int size); Depending on | ||
| 57 | the BIO, this can either be a 'get special' or a get one | ||
| 58 | line of data, as per fgets(); | ||
| 59 | - int BIO_write(BIO *b, char *data, int len); Write 'len' | ||
| 60 | bytes from 'data' to the 'b' BIO. | ||
| 61 | - int BIO_puts(BIO *bp,char *buf); Either a 'put special' or | ||
| 62 | a write null terminated string as per fputs(). | ||
| 63 | - long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg); A | ||
| 64 | control function which is used to manipulate the BIO | ||
| 65 | structure and modify it's state and or report on it. This | ||
| 66 | function is just about never used directly, rather it | ||
| 67 | should be used in conjunction with BIO_METHOD specific | ||
| 68 | macros. | ||
| 69 | - BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the | ||
| 70 | top of the 'old' BIO list. new_top should be a filter BIO. | ||
| 71 | All writes will go through 'new_top' first and last on read. | ||
| 72 | 'old' is returned. | ||
| 73 | - BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if | ||
| 74 | there are no more. | ||
| 75 | |||
| 76 | If a particular low level BIO method is not supported | ||
| 77 | (normally BIO_gets()), -2 will be returned if that method is | ||
| 78 | called. Otherwise the IO methods (read, write, gets, puts) | ||
| 79 | will return the number of bytes read or written, and 0 or -1 | ||
| 80 | for error (or end of input). For the -1 case, | ||
| 81 | BIO_should_retry(bio) can be called to determine if it was a | ||
| 82 | genuine error or a temporary problem. -2 will also be | ||
| 83 | returned if the BIO has not been initalised yet, in all | ||
| 84 | cases, the correct error codes are set (accessible via the | ||
| 85 | ERR library). | ||
| 86 | |||
| 87 | |||
| 88 | The following functions are convenience functions: | ||
| 89 | - int BIO_printf(BIO *bio, char * format, ..); printf but | ||
| 90 | to a BIO handle. | ||
| 91 | - long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a | ||
| 92 | convenience function to allow a different argument types | ||
| 93 | to be passed to BIO_ctrl(). | ||
| 94 | - int BIO_dump(BIO *b,char *bytes,int len); output 'len' | ||
| 95 | bytes from 'bytes' in a hex dump debug format. | ||
| 96 | - long BIO_debug_callback(BIO *bio, int cmd, char *argp, int | ||
| 97 | argi, long argl, long ret) - a default debug BIO callback, | ||
| 98 | this is mentioned below. To use this one normally has to | ||
| 99 | use the BIO_set_callback_arg() function to assign an | ||
| 100 | output BIO for the callback to use. | ||
| 101 | - BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack' | ||
| 102 | of BIOs, this function scan the list and returns the first | ||
| 103 | that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX. | ||
| 104 | - void BIO_free_all(BIO *bio); Free the bio and all other BIOs | ||
| 105 | in the list. It walks the bio->next_bio list. | ||
| 106 | |||
| 107 | |||
| 108 | |||
| 109 | Extra commands are normally implemented as macros calling BIO_ctrl(). | ||
| 110 | - BIO_number_read(BIO *bio) - the number of bytes processed | ||
| 111 | by BIO_read(bio,.). | ||
| 112 | - BIO_number_written(BIO *bio) - the number of bytes written | ||
| 113 | by BIO_write(bio,.). | ||
| 114 | - BIO_reset(BIO *bio) - 'reset' the BIO. | ||
| 115 | - BIO_eof(BIO *bio) - non zero if we are at the current end | ||
| 116 | of input. | ||
| 117 | - BIO_set_close(BIO *bio, int close_flag) - set the close flag. | ||
| 118 | - BIO_get_close(BIO *bio) - return the close flag. | ||
| 119 | BIO_pending(BIO *bio) - return the number of bytes waiting | ||
| 120 | to be read (normally buffered internally). | ||
| 121 | - BIO_flush(BIO *bio) - output any data waiting to be output. | ||
| 122 | - BIO_should_retry(BIO *io) - after a BIO_read/BIO_write | ||
| 123 | operation returns 0 or -1, a call to this function will | ||
| 124 | return non zero if you should retry the call later (this | ||
| 125 | is for non-blocking IO). | ||
| 126 | - BIO_should_read(BIO *io) - we should retry when data can | ||
| 127 | be read. | ||
| 128 | - BIO_should_write(BIO *io) - we should retry when data can | ||
| 129 | be written. | ||
| 130 | - BIO_method_name(BIO *io) - return a string for the method name. | ||
| 131 | - BIO_method_type(BIO *io) - return the unique ID of the BIO method. | ||
| 132 | - BIO_set_callback(BIO *io, long (*callback)(BIO *io, int | ||
| 133 | cmd, char *argp, int argi, long argl, long ret); - sets | ||
| 134 | the debug callback. | ||
| 135 | - BIO_get_callback(BIO *io) - return the assigned function | ||
| 136 | as mentioned above. | ||
| 137 | - BIO_set_callback_arg(BIO *io, char *arg) - assign some | ||
| 138 | data against the BIO. This is normally used by the debug | ||
| 139 | callback but could in reality be used for anything. To | ||
| 140 | get an idea of how all this works, have a look at the code | ||
| 141 | in the default debug callback mentioned above. The | ||
| 142 | callback can modify the return values. | ||
| 143 | |||
| 144 | Details of the BIO_METHOD structure. | ||
| 145 | typedef struct bio_method_st | ||
| 146 | { | ||
| 147 | int type; | ||
| 148 | char *name; | ||
| 149 | int (*bwrite)(); | ||
| 150 | int (*bread)(); | ||
| 151 | int (*bputs)(); | ||
| 152 | int (*bgets)(); | ||
| 153 | long (*ctrl)(); | ||
| 154 | int (*create)(); | ||
| 155 | int (*destroy)(); | ||
| 156 | } BIO_METHOD; | ||
| 157 | |||
| 158 | The 'type' is the numeric type of the BIO, these are listed in buffer.h; | ||
| 159 | 'Name' is a textual representation of the BIO 'type'. | ||
| 160 | The 7 function pointers point to the respective function | ||
| 161 | methods, some of which can be NULL if not implemented. | ||
| 162 | The BIO structure | ||
| 163 | typedef struct bio_st | ||
| 164 | { | ||
| 165 | BIO_METHOD *method; | ||
| 166 | long (*callback)(BIO * bio, int mode, char *argp, int | ||
| 167 | argi, long argl, long ret); | ||
| 168 | char *cb_arg; /* first argument for the callback */ | ||
| 169 | int init; | ||
| 170 | int shutdown; | ||
| 171 | int flags; /* extra storage */ | ||
| 172 | int num; | ||
| 173 | char *ptr; | ||
| 174 | struct bio_st *next_bio; /* used by filter BIOs */ | ||
| 175 | int references; | ||
| 176 | unsigned long num_read; | ||
| 177 | unsigned long num_write; | ||
| 178 | } BIO; | ||
| 179 | |||
| 180 | - 'Method' is the BIO method. | ||
| 181 | - 'callback', when configured, is called before and after | ||
| 182 | each BIO method is called for that particular BIO. This | ||
| 183 | is intended primarily for debugging and of informational feedback. | ||
| 184 | - 'init' is 0 when the BIO can be used for operation. | ||
| 185 | Often, after a BIO is created, a number of operations may | ||
| 186 | need to be performed before it is available for use. An | ||
| 187 | example is for BIO_s_sock(). A socket needs to be | ||
| 188 | assigned to the BIO before it can be used. | ||
| 189 | - 'shutdown', this flag indicates if the underlying | ||
| 190 | comunication primative being used should be closed/freed | ||
| 191 | when the BIO is closed. | ||
| 192 | - 'flags' is used to hold extra state. It is primarily used | ||
| 193 | to hold information about why a non-blocking operation | ||
| 194 | failed and to record startup protocol information for the | ||
| 195 | SSL BIO. | ||
| 196 | - 'num' and 'ptr' are used to hold instance specific state | ||
| 197 | like file descriptors or local data structures. | ||
| 198 | - 'next_bio' is used by filter BIOs to hold the pointer of the | ||
| 199 | next BIO in the chain. written data is sent to this BIO and | ||
| 200 | data read is taken from it. | ||
| 201 | - 'references' is used to indicate the number of pointers to | ||
| 202 | this structure. This needs to be '1' before a call to | ||
| 203 | BIO_free() is made if the BIO_free() function is to | ||
| 204 | actually free() the structure, otherwise the reference | ||
| 205 | count is just decreased. The actual BIO subsystem does | ||
| 206 | not really use this functionality but it is useful when | ||
| 207 | used in more advanced applicaion. | ||
| 208 | - num_read and num_write are the total number of bytes | ||
| 209 | read/written via the 'read()' and 'write()' methods. | ||
| 210 | |||
| 211 | BIO_ctrl operations. | ||
| 212 | The following is the list of standard commands passed as the | ||
| 213 | second parameter to BIO_ctrl() and should be supported by | ||
| 214 | all BIO as best as possible. Some are optional, some are | ||
| 215 | manditory, in any case, where is makes sense, a filter BIO | ||
| 216 | should pass such requests to underlying BIO's. | ||
| 217 | - BIO_CTRL_RESET - Reset the BIO back to an initial state. | ||
| 218 | - BIO_CTRL_EOF - return 0 if we are not at the end of input, | ||
| 219 | non 0 if we are. | ||
| 220 | - BIO_CTRL_INFO - BIO specific special command, normal | ||
| 221 | information return. | ||
| 222 | - BIO_CTRL_SET - set IO specific parameter. | ||
| 223 | - BIO_CTRL_GET - get IO specific parameter. | ||
| 224 | - BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one | ||
| 225 | of BIO_CLOSE or BIO_NOCLOSE. | ||
| 226 | - BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag. | ||
| 227 | - BIO_CTRL_PENDING - Return the number of bytes available | ||
| 228 | for instant reading | ||
| 229 | - BIO_CTRL_FLUSH - Output pending data, return number of bytes output. | ||
| 230 | - BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned) | ||
| 231 | should we 'retry' when IO is possible on the underlying IO object. | ||
| 232 | - BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on. | ||
| 233 | |||
| 234 | The following command is a special BIO_s_file() specific option. | ||
| 235 | - BIO_CTRL_SET_FILENAME - specify a file to open for IO. | ||
| 236 | |||
| 237 | The BIO_CTRL_RETRY_TYPE needs a little more explanation. | ||
| 238 | When performing non-blocking IO, or say reading on a memory | ||
| 239 | BIO, when no data is present (or cannot be written), | ||
| 240 | BIO_read() and/or BIO_write() will return -1. | ||
| 241 | BIO_should_retry(bio) will return true if this is due to an | ||
| 242 | IO condition rather than an actual error. In the case of | ||
| 243 | BIO_s_mem(), a read when there is no data will return -1 and | ||
| 244 | a should retry when there is more 'read' data. | ||
| 245 | The retry type is deduced from 2 macros | ||
| 246 | BIO_should_read(bio) and BIO_should_write(bio). | ||
| 247 | Now while it may appear obvious that a BIO_read() failure | ||
| 248 | should indicate that a retry should be performed when more | ||
| 249 | read data is available, this is often not true when using | ||
| 250 | things like an SSL BIO. During the SSL protocol startup | ||
| 251 | multiple reads and writes are performed, triggered by any | ||
| 252 | SSL_read or SSL_write. | ||
| 253 | So to write code that will transparently handle either a | ||
| 254 | socket or SSL BIO, | ||
| 255 | i=BIO_read(bio,..) | ||
| 256 | if (I == -1) | ||
| 257 | { | ||
| 258 | if (BIO_should_retry(bio)) | ||
| 259 | { | ||
| 260 | if (BIO_should_read(bio)) | ||
| 261 | { | ||
| 262 | /* call us again when BIO can be read */ | ||
| 263 | } | ||
| 264 | if (BIO_should_write(bio)) | ||
| 265 | { | ||
| 266 | /* call us again when BIO can be written */ | ||
| 267 | } | ||
| 268 | } | ||
| 269 | } | ||
| 270 | |||
| 271 | At this point in time only read and write conditions can be | ||
| 272 | used but in the future I can see the situation for other | ||
| 273 | conditions, specifically with SSL there could be a condition | ||
| 274 | of a X509 certificate lookup taking place and so the non- | ||
| 275 | blocking BIO_read would require a retry when the certificate | ||
| 276 | lookup subsystem has finished it's lookup. This is all | ||
| 277 | makes more sense and is easy to use in a event loop type | ||
| 278 | setup. | ||
| 279 | When using the SSL BIO, either SSL_read() or SSL_write()s | ||
| 280 | can be called during the protocol startup and things will | ||
| 281 | still work correctly. | ||
| 282 | The nice aspect of the use of the BIO_should_retry() macro | ||
| 283 | is that all the errno codes that indicate a non-fatal error | ||
| 284 | are encapsulated in one place. The Windows specific error | ||
| 285 | codes and WSAGetLastError() calls are also hidden from the | ||
| 286 | application. | ||
| 287 | |||
| 288 | Notes on each BIO method. | ||
| 289 | Normally buffer.h is just required but depending on the | ||
| 290 | BIO_METHOD, ssl.h or evp.h will also be required. | ||
| 291 | |||
| 292 | BIO_METHOD *BIO_s_mem(void); | ||
| 293 | - BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) - | ||
| 294 | set the underlying BUF_MEM structure for the BIO to use. | ||
| 295 | - BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL, | ||
| 296 | set it to point to the memory array and return the number | ||
| 297 | of bytes available. | ||
| 298 | A read/write BIO. Any data written is appended to the | ||
| 299 | memory array and any read is read from the front. This BIO | ||
| 300 | can be used for read/write at the same time. BIO_gets() is | ||
| 301 | supported in the fgets() sense. | ||
| 302 | BIO_CTRL_INFO can be used to retrieve pointers to the memory | ||
| 303 | buffer and it's length. | ||
| 304 | |||
| 305 | BIO_METHOD *BIO_s_file(void); | ||
| 306 | - BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use. | ||
| 307 | - BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use. | ||
| 308 | - BIO_read_filename(BIO *bio, char *name) - read from file. | ||
| 309 | - BIO_write_filename(BIO *bio, char *name) - write to file. | ||
| 310 | - BIO_append_filename(BIO *bio, char *name) - append to file. | ||
| 311 | This BIO sits over the normal system fread()/fgets() type | ||
| 312 | functions. Gets() is supported. This BIO in theory could be | ||
| 313 | used for read and write but it is best to think of each BIO | ||
| 314 | of this type as either a read or a write BIO, not both. | ||
| 315 | |||
| 316 | BIO_METHOD *BIO_s_socket(void); | ||
| 317 | BIO_METHOD *BIO_s_fd(void); | ||
| 318 | - BIO_sock_should_retry(int i) - the underlying function | ||
| 319 | used to determine if a call should be retried; the | ||
| 320 | argument is the '0' or '-1' returned by the previous BIO | ||
| 321 | operation. | ||
| 322 | - BIO_fd_should_retry(int i) - same as the | ||
| 323 | - BIO_sock_should_retry() except that it is different internally. | ||
| 324 | - BIO_set_fd(BIO *bio, int fd, int close_flag) - set the | ||
| 325 | file descriptor to use | ||
| 326 | - BIO_get_fd(BIO *bio, int *fd) - get the file descriptor. | ||
| 327 | These two methods are very similar. Gets() is not | ||
| 328 | supported, if you want this functionality, put a | ||
| 329 | BIO_f_buffer() onto it. This BIO is bi-directional if the | ||
| 330 | underlying file descriptor is. This is normally the case | ||
| 331 | for sockets but not the case for stdio descriptors. | ||
| 332 | |||
| 333 | BIO_METHOD *BIO_s_null(void); | ||
| 334 | Read and write as much data as you like, it all disappears | ||
| 335 | into this BIO. | ||
| 336 | |||
| 337 | BIO_METHOD *BIO_f_buffer(void); | ||
| 338 | - BIO_get_buffer_num_lines(BIO *bio) - return the number of | ||
| 339 | complete lines in the buffer. | ||
| 340 | - BIO_set_buffer_size(BIO *bio, long size) - set the size of | ||
| 341 | the buffers. | ||
| 342 | This type performs input and output buffering. It performs | ||
| 343 | both at the same time. The size of the buffer can be set | ||
| 344 | via the set buffer size option. Data buffered for output is | ||
| 345 | only written when the buffer fills. | ||
| 346 | |||
| 347 | BIO_METHOD *BIO_f_ssl(void); | ||
| 348 | - BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL | ||
| 349 | structure to use. | ||
| 350 | - BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure | ||
| 351 | in use. | ||
| 352 | The SSL bio is a little different from normal BIOs because | ||
| 353 | the underlying SSL structure is a little different. A SSL | ||
| 354 | structure performs IO via a read and write BIO. These can | ||
| 355 | be different and are normally set via the | ||
| 356 | SSL_set_rbio()/SSL_set_wbio() calls. The SSL_set_fd() calls | ||
| 357 | are just wrappers that create socket BIOs and then call | ||
| 358 | SSL_set_bio() where the read and write BIOs are the same. | ||
| 359 | The BIO_push() operation makes the SSLs IO BIOs the same, so | ||
| 360 | make sure the BIO pushed is capable of two directional | ||
| 361 | traffic. If it is not, you will have to install the BIOs | ||
| 362 | via the more conventional SSL_set_bio() call. BIO_pop() will retrieve | ||
| 363 | the 'SSL read' BIO. | ||
| 364 | |||
| 365 | BIO_METHOD *BIO_f_md(void); | ||
| 366 | - BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest | ||
| 367 | to use. | ||
| 368 | - BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest | ||
| 369 | method in use in mdp, return 0 if not set yet. | ||
| 370 | - BIO_reset() reinitializes the digest (EVP_DigestInit()) | ||
| 371 | and passes the reset to the underlying BIOs. | ||
| 372 | All data read or written via BIO_read() or BIO_write() to | ||
| 373 | this BIO will be added to the calculated digest. This | ||
| 374 | implies that this BIO is only one directional. If read and | ||
| 375 | write operations are performed, two separate BIO_f_md() BIOs | ||
| 376 | are reuqired to generate digests on both the input and the | ||
| 377 | output. BIO_gets(BIO *bio, char *md, int size) will place the | ||
| 378 | generated digest into 'md' and return the number of bytes. | ||
| 379 | The EVP_MAX_MD_SIZE should probably be used to size the 'md' | ||
| 380 | array. Reading the digest will also reset it. | ||
| 381 | |||
| 382 | BIO_METHOD *BIO_f_cipher(void); | ||
| 383 | - BIO_reset() reinitializes the cipher. | ||
| 384 | - BIO_flush() should be called when the last bytes have been | ||
| 385 | output to flush the final block of block ciphers. | ||
| 386 | - BIO_get_cipher_status(BIO *b), when called after the last | ||
| 387 | read from a cipher BIO, returns non-zero if the data | ||
| 388 | decrypted correctly, otherwise, 0. | ||
| 389 | - BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key, | ||
| 390 | unsigned char *iv, int encrypt) This function is used to | ||
| 391 | setup a cipher BIO. The length of key and iv are | ||
| 392 | specified by the choice of EVP_CIPHER. Encrypt is 1 to | ||
| 393 | encrypt and 0 to decrypt. | ||
| 394 | |||
| 395 | BIO_METHOD *BIO_f_base64(void); | ||
| 396 | - BIO_flush() should be called when the last bytes have been output. | ||
| 397 | This BIO base64 encodes when writing and base64 decodes when | ||
| 398 | reading. It will scan the input until a suitable begin line | ||
| 399 | is found. After reading data, BIO_reset() will reset the | ||
| 400 | BIO to start scanning again. Do not mix reading and writing | ||
| 401 | on the same base64 BIO. It is meant as a single stream BIO. | ||
| 402 | |||
| 403 | Directions type | ||
| 404 | both BIO_s_mem() | ||
| 405 | one/both BIO_s_file() | ||
| 406 | both BIO_s_fd() | ||
| 407 | both BIO_s_socket() | ||
| 408 | both BIO_s_null() | ||
| 409 | both BIO_f_buffer() | ||
| 410 | one BIO_f_md() | ||
| 411 | one BIO_f_cipher() | ||
| 412 | one BIO_f_base64() | ||
| 413 | both BIO_f_ssl() | ||
| 414 | |||
| 415 | It is easy to mix one and two directional BIOs, all one has | ||
| 416 | to do is to keep two separate BIO pointers for reading and | ||
| 417 | writing and be careful about usage of underlying BIOs. The | ||
| 418 | SSL bio by it's very nature has to be two directional but | ||
| 419 | the BIO_push() command will push the one BIO into the SSL | ||
| 420 | BIO for both reading and writing. | ||
| 421 | |||
| 422 | The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c. | ||
| 423 | |||
diff --git a/src/lib/libssl/src/doc/blowfish.doc b/src/lib/libssl/src/doc/blowfish.doc deleted file mode 100644 index 8a7f425b32..0000000000 --- a/src/lib/libssl/src/doc/blowfish.doc +++ /dev/null | |||
| @@ -1,146 +0,0 @@ | |||
| 1 | The Blowfish library. | ||
| 2 | |||
| 3 | Blowfish is a block cipher that operates on 64bit (8 byte) quantities. It | ||
| 4 | uses variable size key, but 128bit (16 byte) key would normally be considered | ||
| 5 | good. It can be used in all the modes that DES can be used. This | ||
| 6 | library implements the ecb, cbc, cfb64, ofb64 modes. | ||
| 7 | |||
| 8 | Blowfish is quite a bit faster that DES, and much faster than IDEA or | ||
| 9 | RC2. It is one of the faster block ciphers. | ||
| 10 | |||
| 11 | For all calls that have an 'input' and 'output' variables, they can be the | ||
| 12 | same. | ||
| 13 | |||
| 14 | This library requires the inclusion of 'blowfish.h'. | ||
| 15 | |||
| 16 | All of the encryption functions take what is called an BF_KEY as an | ||
| 17 | argument. An BF_KEY is an expanded form of the Blowfish key. | ||
| 18 | For all modes of the Blowfish algorithm, the BF_KEY used for | ||
| 19 | decryption is the same one that was used for encryption. | ||
| 20 | |||
| 21 | The define BF_ENCRYPT is passed to specify encryption for the functions | ||
| 22 | that require an encryption/decryption flag. BF_DECRYPT is passed to | ||
| 23 | specify decryption. | ||
| 24 | |||
| 25 | Please note that any of the encryption modes specified in my DES library | ||
| 26 | could be used with Blowfish. I have only implemented ecb, cbc, cfb64 and | ||
| 27 | ofb64 for the following reasons. | ||
| 28 | - ecb is the basic Blowfish encryption. | ||
| 29 | - cbc is the normal 'chaining' form for block ciphers. | ||
| 30 | - cfb64 can be used to encrypt single characters, therefore input and output | ||
| 31 | do not need to be a multiple of 8. | ||
| 32 | - ofb64 is similar to cfb64 but is more like a stream cipher, not as | ||
| 33 | secure (not cipher feedback) but it does not have an encrypt/decrypt mode. | ||
| 34 | - If you want triple Blowfish, thats 384 bits of key and you must be totally | ||
| 35 | obsessed with security. Still, if you want it, it is simple enough to | ||
| 36 | copy the function from the DES library and change the des_encrypt to | ||
| 37 | BF_encrypt; an exercise left for the paranoid reader :-). | ||
| 38 | |||
| 39 | The functions are as follows: | ||
| 40 | |||
| 41 | void BF_set_key( | ||
| 42 | BF_KEY *ks; | ||
| 43 | int len; | ||
| 44 | unsigned char *key; | ||
| 45 | BF_set_key converts an 'len' byte key into a BF_KEY. | ||
| 46 | A 'ks' is an expanded form of the 'key' which is used to | ||
| 47 | perform actual encryption. It can be regenerated from the Blowfish key | ||
| 48 | so it only needs to be kept when encryption or decryption is about | ||
| 49 | to occur. Don't save or pass around BF_KEY's since they | ||
| 50 | are CPU architecture dependent, 'key's are not. Blowfish is an | ||
| 51 | interesting cipher in that it can be used with a variable length | ||
| 52 | key. 'len' is the length of 'key' to be used as the key. | ||
| 53 | A 'len' of 16 is recomended by me, but blowfish can use upto | ||
| 54 | 72 bytes. As a warning, blowfish has a very very slow set_key | ||
| 55 | function, it actually runs BF_encrypt 521 times. | ||
| 56 | |||
| 57 | void BF_encrypt(unsigned long *data, BF_KEY *key); | ||
| 58 | void BF_decrypt(unsigned long *data, BF_KEY *key); | ||
| 59 | These are the Blowfish encryption function that gets called by just | ||
| 60 | about every other Blowfish routine in the library. You should not | ||
| 61 | use this function except to implement 'modes' of Blowfish. | ||
| 62 | I say this because the | ||
| 63 | functions that call this routine do the conversion from 'char *' to | ||
| 64 | long, and this needs to be done to make sure 'non-aligned' memory | ||
| 65 | access do not occur. | ||
| 66 | Data is a pointer to 2 unsigned long's and key is the | ||
| 67 | BF_KEY to use. | ||
| 68 | |||
| 69 | void BF_ecb_encrypt( | ||
| 70 | unsigned char *in, | ||
| 71 | unsigned char *out, | ||
| 72 | BF_KEY *key, | ||
| 73 | int encrypt); | ||
| 74 | This is the basic Electronic Code Book form of Blowfish (in DES this | ||
| 75 | mode is called Electronic Code Book so I'm going to use the term | ||
| 76 | for blowfish as well. | ||
| 77 | Input is encrypted into output using the key represented by | ||
| 78 | key. Depending on the encrypt, encryption or | ||
| 79 | decryption occurs. Input is 8 bytes long and output is 8 bytes. | ||
| 80 | |||
| 81 | void BF_cbc_encrypt( | ||
| 82 | unsigned char *in, | ||
| 83 | unsigned char *out, | ||
| 84 | long length, | ||
| 85 | BF_KEY *ks, | ||
| 86 | unsigned char *ivec, | ||
| 87 | int encrypt); | ||
| 88 | This routine implements Blowfish in Cipher Block Chaining mode. | ||
| 89 | Input, which should be a multiple of 8 bytes is encrypted | ||
| 90 | (or decrypted) to output which will also be a multiple of 8 bytes. | ||
| 91 | The number of bytes is in length (and from what I've said above, | ||
| 92 | should be a multiple of 8). If length is not a multiple of 8, bad | ||
| 93 | things will probably happen. ivec is the initialisation vector. | ||
| 94 | This function updates iv after each call so that it can be passed to | ||
| 95 | the next call to BF_cbc_encrypt(). | ||
| 96 | |||
| 97 | void BF_cfb64_encrypt( | ||
| 98 | unsigned char *in, | ||
| 99 | unsigned char *out, | ||
| 100 | long length, | ||
| 101 | BF_KEY *schedule, | ||
| 102 | unsigned char *ivec, | ||
| 103 | int *num, | ||
| 104 | int encrypt); | ||
| 105 | This is one of the more useful functions in this Blowfish library, it | ||
| 106 | implements CFB mode of Blowfish with 64bit feedback. | ||
| 107 | This allows you to encrypt an arbitrary number of bytes, | ||
| 108 | you do not require 8 byte padding. Each call to this | ||
| 109 | routine will encrypt the input bytes to output and then update ivec | ||
| 110 | and num. Num contains 'how far' we are though ivec. | ||
| 111 | 'Encrypt' is used to indicate encryption or decryption. | ||
| 112 | CFB64 mode operates by using the cipher to generate a stream | ||
| 113 | of bytes which is used to encrypt the plain text. | ||
| 114 | The cipher text is then encrypted to generate the next 64 bits to | ||
| 115 | be xored (incrementally) with the next 64 bits of plain | ||
| 116 | text. As can be seen from this, to encrypt or decrypt, | ||
| 117 | the same 'cipher stream' needs to be generated but the way the next | ||
| 118 | block of data is gathered for encryption is different for | ||
| 119 | encryption and decryption. | ||
| 120 | |||
| 121 | void BF_ofb64_encrypt( | ||
| 122 | unsigned char *in, | ||
| 123 | unsigned char *out, | ||
| 124 | long length, | ||
| 125 | BF_KEY *schedule, | ||
| 126 | unsigned char *ivec, | ||
| 127 | int *num); | ||
| 128 | This functions implements OFB mode of Blowfish with 64bit feedback. | ||
| 129 | This allows you to encrypt an arbitrary number of bytes, | ||
| 130 | you do not require 8 byte padding. Each call to this | ||
| 131 | routine will encrypt the input bytes to output and then update ivec | ||
| 132 | and num. Num contains 'how far' we are though ivec. | ||
| 133 | This is in effect a stream cipher, there is no encryption or | ||
| 134 | decryption mode. | ||
| 135 | |||
| 136 | For reading passwords, I suggest using des_read_pw_string() from my DES library. | ||
| 137 | To generate a password from a text string, I suggest using MD5 (or MD2) to | ||
| 138 | produce a 16 byte message digest that can then be passed directly to | ||
| 139 | BF_set_key(). | ||
| 140 | |||
| 141 | ===== | ||
| 142 | For more information about the specific Blowfish modes in this library | ||
| 143 | (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the | ||
| 144 | documentation on my DES library. What is said about DES is directly | ||
| 145 | applicable for Blowfish. | ||
| 146 | |||
diff --git a/src/lib/libssl/src/doc/bn.doc b/src/lib/libssl/src/doc/bn.doc deleted file mode 100644 index 47be23b6ea..0000000000 --- a/src/lib/libssl/src/doc/bn.doc +++ /dev/null | |||
| @@ -1,381 +0,0 @@ | |||
| 1 | The Big Number library. | ||
| 2 | |||
| 3 | #include "bn.h" when using this library. | ||
| 4 | |||
| 5 | This big number library was written for use in implementing the RSA and DH | ||
| 6 | public key encryption algorithms. As such, features such as negative | ||
| 7 | numbers have not been extensively tested but they should work as expected. | ||
| 8 | This library uses dynamic memory allocation for storing its data structures | ||
| 9 | and so there are no limit on the size of the numbers manipulated by these | ||
| 10 | routines but there is always the requirement to check return codes from | ||
| 11 | functions just in case a memory allocation error has occurred. | ||
| 12 | |||
| 13 | The basic object in this library is a BIGNUM. It is used to hold a single | ||
| 14 | large integer. This type should be considered opaque and fields should not | ||
| 15 | be modified or accessed directly. | ||
| 16 | typedef struct bignum_st | ||
| 17 | { | ||
| 18 | int top; /* Index of last used d. */ | ||
| 19 | BN_ULONG *d; /* Pointer to an array of 'BITS2' bit chunks. */ | ||
| 20 | int max; /* Size of the d array. */ | ||
| 21 | int neg; | ||
| 22 | } BIGNUM; | ||
| 23 | The big number is stored in a malloced array of BN_ULONG's. A BN_ULONG can | ||
| 24 | be either 16, 32 or 64 bits in size, depending on the 'number of bits' | ||
| 25 | specified in bn.h. | ||
| 26 | The 'd' field is this array. 'max' is the size of the 'd' array that has | ||
| 27 | been allocated. 'top' is the 'last' entry being used, so for a value of 4, | ||
| 28 | bn.d[0]=4 and bn.top=1. 'neg' is 1 if the number is negative. | ||
| 29 | When a BIGNUM is '0', the 'd' field can be NULL and top == 0. | ||
| 30 | |||
| 31 | Various routines in this library require the use of 'temporary' BIGNUM | ||
| 32 | variables during their execution. Due to the use of dynamic memory | ||
| 33 | allocation to create BIGNUMs being rather expensive when used in | ||
| 34 | conjunction with repeated subroutine calls, the BN_CTX structure is | ||
| 35 | used. This structure contains BN_CTX BIGNUMs. BN_CTX | ||
| 36 | is the maximum number of temporary BIGNUMs any publicly exported | ||
| 37 | function will use. | ||
| 38 | |||
| 39 | #define BN_CTX 12 | ||
| 40 | typedef struct bignum_ctx | ||
| 41 | { | ||
| 42 | int tos; /* top of stack */ | ||
| 43 | BIGNUM *bn[BN_CTX]; /* The variables */ | ||
| 44 | } BN_CTX; | ||
| 45 | |||
| 46 | The functions that follow have been grouped according to function. Most | ||
| 47 | arithmetic functions return a result in the first argument, sometimes this | ||
| 48 | first argument can also be an input parameter, sometimes it cannot. These | ||
| 49 | restrictions are documented. | ||
| 50 | |||
| 51 | extern BIGNUM *BN_value_one; | ||
| 52 | There is one variable defined by this library, a BIGNUM which contains the | ||
| 53 | number 1. This variable is useful for use in comparisons and assignment. | ||
| 54 | |||
| 55 | Get Size functions. | ||
| 56 | |||
| 57 | int BN_num_bits(BIGNUM *a); | ||
| 58 | This function returns the size of 'a' in bits. | ||
| 59 | |||
| 60 | int BN_num_bytes(BIGNUM *a); | ||
| 61 | This function (macro) returns the size of 'a' in bytes. | ||
| 62 | For conversion of BIGNUMs to byte streams, this is the number of | ||
| 63 | bytes the output string will occupy. If the output byte | ||
| 64 | format specifies that the 'top' bit indicates if the number is | ||
| 65 | signed, so an extra '0' byte is required if the top bit on a | ||
| 66 | positive number is being written, it is upto the application to | ||
| 67 | make this adjustment. Like I said at the start, I don't | ||
| 68 | really support negative numbers :-). | ||
| 69 | |||
| 70 | Creation/Destruction routines. | ||
| 71 | |||
| 72 | BIGNUM *BN_new(); | ||
| 73 | Return a new BIGNUM object. The number initially has a value of 0. If | ||
| 74 | there is an error, NULL is returned. | ||
| 75 | |||
| 76 | void BN_free(BIGNUM *a); | ||
| 77 | Free()s a BIGNUM. | ||
| 78 | |||
| 79 | void BN_clear(BIGNUM *a); | ||
| 80 | Sets 'a' to a value of 0 and also zeros all unused allocated | ||
| 81 | memory. This function is used to clear a variable of 'sensitive' | ||
| 82 | data that was held in it. | ||
| 83 | |||
| 84 | void BN_clear_free(BIGNUM *a); | ||
| 85 | This function zeros the memory used by 'a' and then free()'s it. | ||
| 86 | This function should be used to BN_free() BIGNUMS that have held | ||
| 87 | sensitive numeric values like RSA private key values. Both this | ||
| 88 | function and BN_clear tend to only be used by RSA and DH routines. | ||
| 89 | |||
| 90 | BN_CTX *BN_CTX_new(void); | ||
| 91 | Returns a new BN_CTX. NULL on error. | ||
| 92 | |||
| 93 | void BN_CTX_free(BN_CTX *c); | ||
| 94 | Free a BN_CTX structure. The BIGNUMs in 'c' are BN_clear_free()ed. | ||
| 95 | |||
| 96 | BIGNUM *bn_expand(BIGNUM *b, int bits); | ||
| 97 | This is an internal function that should not normally be used. It | ||
| 98 | ensures that 'b' has enough room for a 'bits' bit number. It is | ||
| 99 | mostly used by the various BIGNUM routines. If there is an error, | ||
| 100 | NULL is returned. if not, 'b' is returned. | ||
| 101 | |||
| 102 | BIGNUM *BN_copy(BIGNUM *to, BIGNUM *from); | ||
| 103 | The 'from' is copied into 'to'. NULL is returned if there is an | ||
| 104 | error, otherwise 'to' is returned. | ||
| 105 | |||
| 106 | BIGNUM *BN_dup(BIGNUM *a); | ||
| 107 | A new BIGNUM is created and returned containing the value of 'a'. | ||
| 108 | NULL is returned on error. | ||
| 109 | |||
| 110 | Comparison and Test Functions. | ||
| 111 | |||
| 112 | int BN_is_zero(BIGNUM *a) | ||
| 113 | Return 1 if 'a' is zero, else 0. | ||
| 114 | |||
| 115 | int BN_is_one(a) | ||
| 116 | Return 1 is 'a' is one, else 0. | ||
| 117 | |||
| 118 | int BN_is_word(a,w) | ||
| 119 | Return 1 if 'a' == w, else 0. 'w' is a BN_ULONG. | ||
| 120 | |||
| 121 | int BN_cmp(BIGNUM *a, BIGNUM *b); | ||
| 122 | Return -1 if 'a' is less than 'b', 0 if 'a' and 'b' are the same | ||
| 123 | and 1 is 'a' is greater than 'b'. This is a signed comparison. | ||
| 124 | |||
| 125 | int BN_ucmp(BIGNUM *a, BIGNUM *b); | ||
| 126 | This function is the same as BN_cmp except that the comparison | ||
| 127 | ignores the sign of the numbers. | ||
| 128 | |||
| 129 | Arithmetic Functions | ||
| 130 | For all of these functions, 0 is returned if there is an error and 1 is | ||
| 131 | returned for success. The return value should always be checked. eg. | ||
| 132 | if (!BN_add(r,a,b)) goto err; | ||
| 133 | Unless explicitly mentioned, the 'return' value can be one of the | ||
| 134 | 'parameters' to the function. | ||
| 135 | |||
| 136 | int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b); | ||
| 137 | Add 'a' and 'b' and return the result in 'r'. This is r=a+b. | ||
| 138 | |||
| 139 | int BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b); | ||
| 140 | Subtract 'a' from 'b' and put the result in 'r'. This is r=a-b. | ||
| 141 | |||
| 142 | int BN_lshift(BIGNUM *r, BIGNUM *a, int n); | ||
| 143 | Shift 'a' left by 'n' bits. This is r=a*(2^n). | ||
| 144 | |||
| 145 | int BN_lshift1(BIGNUM *r, BIGNUM *a); | ||
| 146 | Shift 'a' left by 1 bit. This form is more efficient than | ||
| 147 | BN_lshift(r,a,1). This is r=a*2. | ||
| 148 | |||
| 149 | int BN_rshift(BIGNUM *r, BIGNUM *a, int n); | ||
| 150 | Shift 'a' right by 'n' bits. This is r=int(a/(2^n)). | ||
| 151 | |||
| 152 | int BN_rshift1(BIGNUM *r, BIGNUM *a); | ||
| 153 | Shift 'a' right by 1 bit. This form is more efficient than | ||
| 154 | BN_rshift(r,a,1). This is r=int(a/2). | ||
| 155 | |||
| 156 | int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b); | ||
| 157 | Multiply a by b and return the result in 'r'. 'r' must not be | ||
| 158 | either 'a' or 'b'. It has to be a different BIGNUM. | ||
| 159 | This is r=a*b. | ||
| 160 | |||
| 161 | int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); | ||
| 162 | Multiply a by a and return the result in 'r'. 'r' must not be | ||
| 163 | 'a'. This function is alot faster than BN_mul(r,a,a). This is r=a*a. | ||
| 164 | |||
| 165 | int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); | ||
| 166 | Divide 'm' by 'd' and return the result in 'dv' and the remainder | ||
| 167 | in 'rem'. Either of 'dv' or 'rem' can be NULL in which case that | ||
| 168 | value is not returned. 'ctx' needs to be passed as a source of | ||
| 169 | temporary BIGNUM variables. | ||
| 170 | This is dv=int(m/d), rem=m%d. | ||
| 171 | |||
| 172 | int BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); | ||
| 173 | Find the remainder of 'm' divided by 'd' and return it in 'rem'. | ||
| 174 | 'ctx' holds the temporary BIGNUMs required by this function. | ||
| 175 | This function is more efficient than BN_div(NULL,rem,m,d,ctx); | ||
| 176 | This is rem=m%d. | ||
| 177 | |||
| 178 | int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BIGNUM *m,BN_CTX *ctx); | ||
| 179 | Multiply 'a' by 'b' and return the remainder when divided by 'm'. | ||
| 180 | 'ctx' holds the temporary BIGNUMs required by this function. | ||
| 181 | This is r=(a*b)%m. | ||
| 182 | |||
| 183 | int BN_mod_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx); | ||
| 184 | Raise 'a' to the 'p' power and return the remainder when divided by | ||
| 185 | 'm'. 'ctx' holds the temporary BIGNUMs required by this function. | ||
| 186 | This is r=(a^p)%m. | ||
| 187 | |||
| 188 | int BN_reciprocal(BIGNUM *r, BIGNUM *m, BN_CTX *ctx); | ||
| 189 | Return the reciprocal of 'm'. 'ctx' holds the temporary variables | ||
| 190 | required. This function returns -1 on error, otherwise it returns | ||
| 191 | the number of bits 'r' is shifted left to make 'r' into an integer. | ||
| 192 | This number of bits shifted is required in BN_mod_mul_reciprocal(). | ||
| 193 | This is r=(1/m)<<(BN_num_bits(m)+1). | ||
| 194 | |||
| 195 | int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y, BIGNUM *m, | ||
| 196 | BIGNUM *i, int nb, BN_CTX *ctx); | ||
| 197 | This function is used to perform an efficient BN_mod_mul() | ||
| 198 | operation. If one is going to repeatedly perform BN_mod_mul() with | ||
| 199 | the same modulus is worth calculating the reciprocal of the modulus | ||
| 200 | and then using this function. This operation uses the fact that | ||
| 201 | a/b == a*r where r is the reciprocal of b. On modern computers | ||
| 202 | multiplication is very fast and big number division is very slow. | ||
| 203 | 'x' is multiplied by 'y' and then divided by 'm' and the remainder | ||
| 204 | is returned. 'i' is the reciprocal of 'm' and 'nb' is the number | ||
| 205 | of bits as returned from BN_reciprocal(). Normal usage is as follows. | ||
| 206 | bn=BN_reciprocal(i,m); | ||
| 207 | for (...) | ||
| 208 | { BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); } | ||
| 209 | This is r=(x*y)%m. Internally it is approximately | ||
| 210 | r=(x*y)-m*(x*y/m) or r=(x*y)-m*((x*y*i) >> bn) | ||
| 211 | This function is used in BN_mod_exp() and BN_is_prime(). | ||
| 212 | |||
| 213 | Assignment Operations | ||
| 214 | |||
| 215 | int BN_one(BIGNUM *a) | ||
| 216 | Set 'a' to hold the value one. | ||
| 217 | This is a=1. | ||
| 218 | |||
| 219 | int BN_zero(BIGNUM *a) | ||
| 220 | Set 'a' to hold the value zero. | ||
| 221 | This is a=0. | ||
| 222 | |||
| 223 | int BN_set_word(BIGNUM *a, unsigned long w); | ||
| 224 | Set 'a' to hold the value of 'w'. 'w' is an unsigned long. | ||
| 225 | This is a=w. | ||
| 226 | |||
| 227 | unsigned long BN_get_word(BIGNUM *a); | ||
| 228 | Returns 'a' in an unsigned long. Not remarkably, often 'a' will | ||
| 229 | be biger than a word, in which case 0xffffffffL is returned. | ||
| 230 | |||
| 231 | Word Operations | ||
| 232 | These functions are much more efficient that the normal bignum arithmetic | ||
| 233 | operations. | ||
| 234 | |||
| 235 | BN_ULONG BN_mod_word(BIGNUM *a, unsigned long w); | ||
| 236 | Return the remainder of 'a' divided by 'w'. | ||
| 237 | This is return(a%w). | ||
| 238 | |||
| 239 | int BN_add_word(BIGNUM *a, unsigned long w); | ||
| 240 | Add 'w' to 'a'. This function does not take the sign of 'a' into | ||
| 241 | account. This is a+=w; | ||
| 242 | |||
| 243 | Bit operations. | ||
| 244 | |||
| 245 | int BN_is_bit_set(BIGNUM *a, int n); | ||
| 246 | This function return 1 if bit 'n' is set in 'a' else 0. | ||
| 247 | |||
| 248 | int BN_set_bit(BIGNUM *a, int n); | ||
| 249 | This function sets bit 'n' to 1 in 'a'. | ||
| 250 | This is a&= ~(1<<n); | ||
| 251 | |||
| 252 | int BN_clear_bit(BIGNUM *a, int n); | ||
| 253 | This function sets bit 'n' to zero in 'a'. Return 0 if less | ||
| 254 | than 'n' bits in 'a' else 1. This is a&= ~(1<<n); | ||
| 255 | |||
| 256 | int BN_mask_bits(BIGNUM *a, int n); | ||
| 257 | Truncate 'a' to n bits long. This is a&= ~((~0)<<n) | ||
| 258 | |||
| 259 | Format conversion routines. | ||
| 260 | |||
| 261 | BIGNUM *BN_bin2bn(unsigned char *s, int len,BIGNUM *ret); | ||
| 262 | This function converts 'len' bytes in 's' into a BIGNUM which | ||
| 263 | is put in 'ret'. If ret is NULL, a new BIGNUM is created. | ||
| 264 | Either this new BIGNUM or ret is returned. The number is | ||
| 265 | assumed to be in bigendian form in 's'. By this I mean that | ||
| 266 | to 'ret' is created as follows for 'len' == 5. | ||
| 267 | ret = s[0]*2^32 + s[1]*2^24 + s[2]*2^16 + s[3]*2^8 + s[4]; | ||
| 268 | This function cannot be used to convert negative numbers. It | ||
| 269 | is always assumed the number is positive. The application | ||
| 270 | needs to diddle the 'neg' field of th BIGNUM its self. | ||
| 271 | The better solution would be to save the numbers in ASN.1 format | ||
| 272 | since this is a defined standard for storing big numbers. | ||
| 273 | Look at the functions | ||
| 274 | |||
| 275 | ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai); | ||
| 276 | BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn); | ||
| 277 | int i2d_ASN1_INTEGER(ASN1_INTEGER *a,unsigned char **pp); | ||
| 278 | ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **a,unsigned char **pp, | ||
| 279 | long length; | ||
| 280 | |||
| 281 | int BN_bn2bin(BIGNUM *a, unsigned char *to); | ||
| 282 | This function converts 'a' to a byte string which is put into | ||
| 283 | 'to'. The representation is big-endian in that the most | ||
| 284 | significant byte of 'a' is put into to[0]. This function | ||
| 285 | returns the number of bytes used to hold 'a'. BN_num_bytes(a) | ||
| 286 | would return the same value and can be used to determine how | ||
| 287 | large 'to' needs to be. If the number is negative, this | ||
| 288 | information is lost. Since this library was written to | ||
| 289 | manipulate large positive integers, the inability to save and | ||
| 290 | restore them is not considered to be a problem by me :-). | ||
| 291 | As for BN_bin2bn(), look at the ASN.1 integer encoding funtions | ||
| 292 | for SSLeay. They use BN_bin2bn() and BN_bn2bin() internally. | ||
| 293 | |||
| 294 | char *BN_bn2ascii(BIGNUM *a); | ||
| 295 | This function returns a malloc()ed string that contains the | ||
| 296 | ascii hexadecimal encoding of 'a'. The number is in bigendian | ||
| 297 | format with a '-' in front if the number is negative. | ||
| 298 | |||
| 299 | int BN_ascii2bn(BIGNUM **bn, char *a); | ||
| 300 | The inverse of BN_bn2ascii. The function returns the number of | ||
| 301 | characters from 'a' were processed in generating a the bignum. | ||
| 302 | error is inticated by 0 being returned. The number is a | ||
| 303 | hex digit string, optionally with a leading '-'. If *bn | ||
| 304 | is null, a BIGNUM is created and returned via that variable. | ||
| 305 | |||
| 306 | int BN_print_fp(FILE *fp, BIGNUM *a); | ||
| 307 | 'a' is printed to file pointer 'fp'. It is in the same format | ||
| 308 | that is output from BN_bn2ascii(). 0 is returned on error, | ||
| 309 | 1 if things are ok. | ||
| 310 | |||
| 311 | int BN_print(BIO *bp, BIGNUM *a); | ||
| 312 | Same as BN_print except that the output is done to the SSLeay libraries | ||
| 313 | BIO routines. BN_print_fp() actually calls this function. | ||
| 314 | |||
| 315 | Miscellaneous Routines. | ||
| 316 | |||
| 317 | int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); | ||
| 318 | This function returns in 'rnd' a random BIGNUM that is bits | ||
| 319 | long. If bottom is 1, the number returned is odd. If top is set, | ||
| 320 | the top 2 bits of the number are set. This is useful because if | ||
| 321 | this is set, 2 'n; bit numbers multiplied together will return a 2n | ||
| 322 | bit number. If top was not set, they could produce a 2n-1 bit | ||
| 323 | number. | ||
| 324 | |||
| 325 | BIGNUM *BN_mod_inverse(BIGNUM *a, BIGNUM *n,BN_CTX *ctx); | ||
| 326 | This function create a new BIGNUM and returns it. This number | ||
| 327 | is the inverse mod 'n' of 'a'. By this it is meant that the | ||
| 328 | returned value 'r' satisfies (a*r)%n == 1. This function is | ||
| 329 | used in the generation of RSA keys. 'ctx', as per usual, | ||
| 330 | is used to hold temporary variables that are required by the | ||
| 331 | function. NULL is returned on error. | ||
| 332 | |||
| 333 | int BN_gcd(BIGNUM *r,BIGNUM *a,BIGNUM *b,BN_CTX *ctx); | ||
| 334 | 'r' has the greatest common divisor of 'a' and 'b'. 'ctx' is | ||
| 335 | used for temporary variables and 0 is returned on error. | ||
| 336 | |||
| 337 | int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(),BN_CTX *ctx, | ||
| 338 | char *cb_arg); | ||
| 339 | This function is used to check if a BIGNUM ('p') is prime. | ||
| 340 | It performs this test by using the Miller-Rabin randomised | ||
| 341 | primality test. This is a probalistic test that requires a | ||
| 342 | number of rounds to ensure the number is prime to a high | ||
| 343 | degree of probability. Since this can take quite some time, a | ||
| 344 | callback function can be passed and it will be called each | ||
| 345 | time 'p' passes a round of the prime testing. 'callback' will | ||
| 346 | be called as follows, callback(1,n,cb_arg) where n is the number of | ||
| 347 | the round, just passed. As per usual 'ctx' contains temporary | ||
| 348 | variables used. If ctx is NULL, it does not matter, a local version | ||
| 349 | will be malloced. This parameter is present to save some mallocing | ||
| 350 | inside the function but probably could be removed. | ||
| 351 | 0 is returned on error. | ||
| 352 | 'ncheck' is the number of Miller-Rabin tests to run. It is | ||
| 353 | suggested to use the value 'BN_prime_checks' by default. | ||
| 354 | |||
| 355 | BIGNUM *BN_generate_prime( | ||
| 356 | int bits, | ||
| 357 | int strong, | ||
| 358 | BIGNUM *a, | ||
| 359 | BIGNUM *rems, | ||
| 360 | void (*callback)()); | ||
| 361 | char *cb_arg | ||
| 362 | This function is used to generate prime numbers. It returns a | ||
| 363 | new BIGNUM that has a high probability of being a prime. | ||
| 364 | 'bits' is the number of bits that | ||
| 365 | are to be in the prime. If 'strong' is true, the returned prime | ||
| 366 | will also be a strong prime ((p-1)/2 is also prime). | ||
| 367 | While searching for the prime ('p'), we | ||
| 368 | can add the requirement that the prime fill the following | ||
| 369 | condition p%a == rem. This can be used to help search for | ||
| 370 | primes with specific features, which is required when looking | ||
| 371 | for primes suitable for use with certain 'g' values in the | ||
| 372 | Diffie-Hellman key exchange algorithm. If 'a' is NULL, | ||
| 373 | this condition is not checked. If rem is NULL, rem is assumed | ||
| 374 | to be 1. Since this search for a prime | ||
| 375 | can take quite some time, if callback is not NULL, it is called | ||
| 376 | in the following situations. | ||
| 377 | We have a suspected prime (from a quick sieve), | ||
| 378 | callback(0,sus_prime++,cb_arg). Each item to be passed to BN_is_prime(). | ||
| 379 | callback(1,round++,cb_arg). Each successful 'round' in BN_is_prime(). | ||
| 380 | callback(2,round,cb_arg). For each successful BN_is_prime() test. | ||
| 381 | |||
diff --git a/src/lib/libssl/src/doc/c-indentation.el b/src/lib/libssl/src/doc/c-indentation.el new file mode 100644 index 0000000000..9a4a0be598 --- /dev/null +++ b/src/lib/libssl/src/doc/c-indentation.el | |||
| @@ -0,0 +1,36 @@ | |||
| 1 | ; This Emacs Lisp file defines a C indentation style that closely | ||
| 2 | ; follows most aspects of the one that is used throughout SSLeay, | ||
| 3 | ; and hence in OpenSSL. | ||
| 4 | ; | ||
| 5 | ; This definition is for the "CC mode" package, which is the default | ||
| 6 | ; mode for editing C source files in Emacs 20, not for the older | ||
| 7 | ; c-mode.el (which was the default in less recent releaes of Emacs 19). | ||
| 8 | ; | ||
| 9 | ; Copy the definition in your .emacs file or use M-x eval-buffer. | ||
| 10 | ; To activate this indentation style, visit a C file, type | ||
| 11 | ; M-x c-set-style <RET> (or C-c . for short), and enter "eay". | ||
| 12 | ; To toggle the auto-newline feature of CC mode, type C-c C-a. | ||
| 13 | ; | ||
| 14 | ; Apparently statement blocks that are not introduced by a statement | ||
| 15 | ; such as "if" and that are not the body of a function cannot | ||
| 16 | ; be handled too well by CC mode with this indentation style. | ||
| 17 | ; The style defined below does not indent them at all. | ||
| 18 | ; To insert tabs manually, prefix them with ^Q (the "quoted-insert" | ||
| 19 | ; command of Emacs). If you know a solution to this problem | ||
| 20 | ; or find other problems with this indentation style definition, | ||
| 21 | ; please send e-mail to bodo@openssl.org. | ||
| 22 | |||
| 23 | (c-add-style "eay" | ||
| 24 | '((c-basic-offset . 8) | ||
| 25 | (c-comment-only-line-offset . 0) | ||
| 26 | (c-hanging-braces-alist) | ||
| 27 | (c-offsets-alist . ((defun-open . +) | ||
| 28 | (defun-block-intro . 0) | ||
| 29 | (block-open . 0) | ||
| 30 | (substatement-open . +) | ||
| 31 | (statement-block-intro . 0) | ||
| 32 | (statement-case-open . +) | ||
| 33 | (statement-case-intro . +) | ||
| 34 | (case-label . -) | ||
| 35 | (label . -) | ||
| 36 | (arglist-cont-nonempty . +))))) | ||
diff --git a/src/lib/libssl/src/doc/ca.1 b/src/lib/libssl/src/doc/ca.1 deleted file mode 100644 index e9e390a434..0000000000 --- a/src/lib/libssl/src/doc/ca.1 +++ /dev/null | |||
| @@ -1,121 +0,0 @@ | |||
| 1 | From eay@orb.mincom.oz.au Thu Dec 28 23:56:45 1995 | ||
| 2 | Received: by orb.mincom.oz.au id AA07374 | ||
| 3 | (5.65c/IDA-1.4.4 for eay); Thu, 28 Dec 1995 13:56:45 +1000 | ||
| 4 | Date: Thu, 28 Dec 1995 13:56:45 +1000 (EST) | ||
| 5 | From: Eric Young <eay@mincom.oz.au> | ||
| 6 | X-Sender: eay@orb | ||
| 7 | To: sameer <sameer@c2.org> | ||
| 8 | Cc: ssleay@mincom.oz.au | ||
| 9 | Subject: Re: 'ca' | ||
| 10 | In-Reply-To: <199512230440.UAA23410@infinity.c2.org> | ||
| 11 | Message-Id: <Pine.SOL.3.91.951228133525.7269A-100000@orb> | ||
| 12 | Mime-Version: 1.0 | ||
| 13 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 14 | Status: RO | ||
| 15 | X-Status: | ||
| 16 | |||
| 17 | On Fri, 22 Dec 1995, sameer wrote: | ||
| 18 | > I could use documentation on 'ca'. Thanks. | ||
| 19 | |||
| 20 | Very quickly. | ||
| 21 | The ca program uses the ssleay.conf file for most of its configuration | ||
| 22 | |||
| 23 | ./ca -help | ||
| 24 | |||
| 25 | -verbose - Talk alot while doing things | ||
| 26 | -config file - A config file. If you don't want to use the | ||
| 27 | default config file | ||
| 28 | -name arg - The particular CA definition to use | ||
| 29 | In the config file, the section to use for parameters. This lets | ||
| 30 | multiple setups to be contained in the one file. By default, the | ||
| 31 | default_ca variable is looked up in the [ ca ] section. So in the | ||
| 32 | shipped ssleay.conf, the CA definition used is CA_default. It could be | ||
| 33 | any other name. | ||
| 34 | -gencrl days - Generate a new CRL, days is when the next CRL is due | ||
| 35 | This will generate a new certificate revocion list. | ||
| 36 | -days arg - number of days to certify the certificate for | ||
| 37 | When certifying certificates, this is the number of days to use. | ||
| 38 | -md arg - md to use, one of md2, md5, sha or sha1 | ||
| 39 | -policy arg - The CA 'policy' to support | ||
| 40 | I'll describe this later, but there are 2 policies definied in the | ||
| 41 | shipped ssleay.conf | ||
| 42 | -keyfile arg - PEM RSA private key file | ||
| 43 | -key arg - key to decode the RSA private key if it is encrypted | ||
| 44 | since we need to keep the CA's RSA key encrypted | ||
| 45 | -cert - The CA certificate | ||
| 46 | -in file - The input PEM encoded certificate request(s) | ||
| 47 | -out file - Where to put the output file(s) | ||
| 48 | -outdir dir - Where to put output certificates | ||
| 49 | The -out options concatenates all the output | ||
| 50 | certificates to one file, -outdir puts them in a directory, | ||
| 51 | named by serial number. | ||
| 52 | -infiles .... - The last argument, requests to process | ||
| 53 | The certificate requests to process, -in is the same. | ||
| 54 | |||
| 55 | Just about all the above have default values defined in ssleay.conf. | ||
| 56 | |||
| 57 | The key variables in ssleay.conf are (for the particular '-name' being | ||
| 58 | used, in the default, it is CA_default). | ||
| 59 | |||
| 60 | dir is where all the CA database stuff is kept. | ||
| 61 | certs is where all the previously issued certificates are kept. | ||
| 62 | The database is a simple text database containing the following tab separated | ||
| 63 | fields. | ||
| 64 | status: a value of 'R' - revoked, 'E' -expired or 'V' valid. | ||
| 65 | issued date: When the certificate was certified. | ||
| 66 | revoked date: When it was revoked, blank if not revoked. | ||
| 67 | serial number: The certificate serial number. | ||
| 68 | certificate: Where the certificate is located. | ||
| 69 | CN: The name of the certificate. | ||
| 70 | |||
| 71 | The demo file has quite a few made up values it it. The last 2 were | ||
| 72 | added by the ca program and are acurate. | ||
| 73 | The CA program does not update the 'certificate' file correctly right now. | ||
| 74 | The serial field should be unique as should the CN/status combination. | ||
| 75 | The ca program checks these at startup. What still needs to be | ||
| 76 | wrtten is a program to 'regenerate' the data base file from the issued | ||
| 77 | certificate list (and a CRL list). | ||
| 78 | |||
| 79 | Back to the CA_default variables. | ||
| 80 | |||
| 81 | Most of the variables are commented. | ||
| 82 | |||
| 83 | policy is the default policy. | ||
| 84 | |||
| 85 | Ok for policies, they define the order and which fields must be present | ||
| 86 | in the certificate request and what gets filled in. | ||
| 87 | |||
| 88 | So a value of | ||
| 89 | countryName = match | ||
| 90 | means that the country name must match the CA certificate. | ||
| 91 | organizationalUnitName = optional | ||
| 92 | The org.Unit,Name does not have to be present and | ||
| 93 | commonName = supplied | ||
| 94 | commonName must be supplied in the certificate request. | ||
| 95 | |||
| 96 | For the 'policy_match' policy, the order of the attributes in the | ||
| 97 | generated certificate would be | ||
| 98 | countryName | ||
| 99 | stateOrProvinceName | ||
| 100 | organizationName | ||
| 101 | organizationalUnitName | ||
| 102 | commonName | ||
| 103 | emailAddress | ||
| 104 | |||
| 105 | Have a play, it sort of makes sense. If you think about how the persona | ||
| 106 | requests operate, it is similar to the 'policy_match' policy and the | ||
| 107 | 'policy_anything' is similar to what versign is doing. | ||
| 108 | |||
| 109 | I hope this helps a bit. Some backend scripts are definitly needed to | ||
| 110 | update the database and to make certificate revocion easy. All | ||
| 111 | certificates issued should also be kept forever (or until they expire?) | ||
| 112 | |||
| 113 | hope this helps | ||
| 114 | eric (who has to run off an buy some cheap knee pads for the caving in 4 | ||
| 115 | days time :-) | ||
| 116 | |||
| 117 | -- | ||
| 118 | Eric Young | Signature removed since it was generating | ||
| 119 | AARNet: eay@mincom.oz.au | more followups than the message contents :-) | ||
| 120 | |||
| 121 | |||
diff --git a/src/lib/libssl/src/doc/callback.doc b/src/lib/libssl/src/doc/callback.doc deleted file mode 100644 index 7ad0f7f7d2..0000000000 --- a/src/lib/libssl/src/doc/callback.doc +++ /dev/null | |||
| @@ -1,240 +0,0 @@ | |||
| 1 | Callback functions used in SSLeay. | ||
| 2 | |||
| 3 | -------------------------- | ||
| 4 | The BIO library. | ||
| 5 | |||
| 6 | Each BIO structure can have a callback defined against it. This callback is | ||
| 7 | called 2 times for each BIO 'function'. It is passed 6 parameters. | ||
| 8 | BIO_debug_callback() is an example callback which is defined in | ||
| 9 | crypto/buffer/bio_cb.c and is used in apps/dgst.c This is intended mostly | ||
| 10 | for debuging or to notify the application of IO. | ||
| 11 | |||
| 12 | long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl, | ||
| 13 | long ret); | ||
| 14 | bio is the BIO being called, cmd is the type of BIO function being called. | ||
| 15 | Look at the BIO_CB_* defines in buffer.h. Argp and argi are the arguments | ||
| 16 | passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts(). In the case of | ||
| 17 | BIO_ctrl(), argl is also defined. The first time the callback is called, | ||
| 18 | before the underlying function has been executed, 0 is passed as 'ret', and | ||
| 19 | if the return code from the callback is not > 0, the call is aborted | ||
| 20 | and the returned <= 0 value is returned. | ||
| 21 | The second time the callback is called, the 'cmd' value also has | ||
| 22 | BIO_CB_RETURN logically 'or'ed with it. The 'ret' value is the value returned | ||
| 23 | from the actuall function call and whatever the callback returns is returned | ||
| 24 | from the BIO function. | ||
| 25 | |||
| 26 | BIO_set_callback(b,cb) can be used to set the callback function | ||
| 27 | (b is a BIO), and BIO_set_callback_arg(b,arg) can be used to | ||
| 28 | set the cb_arg argument in the BIO strucutre. This field is only intended | ||
| 29 | to be used by application, primarily in the callback function since it is | ||
| 30 | accessable since the BIO is passed. | ||
| 31 | |||
| 32 | -------------------------- | ||
| 33 | The PEM library. | ||
| 34 | |||
| 35 | The pem library only really uses one type of callback, | ||
| 36 | static int def_callback(char *buf, int num, int verify); | ||
| 37 | which is used to return a password string if required. | ||
| 38 | 'buf' is the buffer to put the string in. 'num' is the size of 'buf' | ||
| 39 | and 'verify' is used to indicate that the password should be checked. | ||
| 40 | This last flag is mostly used when reading a password for encryption. | ||
| 41 | |||
| 42 | For all of these functions, a NULL callback will call the above mentioned | ||
| 43 | default callback. This default function does not work under Windows 3.1. | ||
| 44 | For other machines, it will use an application defined prompt string | ||
| 45 | (EVP_set_pw_prompt(), which defines a library wide prompt string) | ||
| 46 | if defined, otherwise it will use it's own PEM password prompt. | ||
| 47 | It will then call EVP_read_pw_string() to get a password from the console. | ||
| 48 | If your application wishes to use nice fancy windows to retrieve passwords, | ||
| 49 | replace this function. The callback should return the number of bytes read | ||
| 50 | into 'buf'. If the number of bytes <= 0, it is considered an error. | ||
| 51 | |||
| 52 | Functions that take this callback are listed below. For the 'read' type | ||
| 53 | functions, the callback will only be required if the PEM data is encrypted. | ||
| 54 | |||
| 55 | For the Write functions, normally a password can be passed in 'kstr', of | ||
| 56 | 'klen' bytes which will be used if the 'enc' cipher is not NULL. If | ||
| 57 | 'kstr' is NULL, the callback will be used to retrieve a password. | ||
| 58 | |||
| 59 | int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len, | ||
| 60 | int (*callback)()); | ||
| 61 | char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)()); | ||
| 62 | char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)()); | ||
| 63 | int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x, | ||
| 64 | EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)()); | ||
| 65 | int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x, | ||
| 66 | EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)()); | ||
| 67 | STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)()); | ||
| 68 | STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)()); | ||
| 69 | |||
| 70 | #define PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb) | ||
| 71 | #define PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb) | ||
| 72 | #define PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb) | ||
| 73 | #define PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb) | ||
| 74 | #define PEM_read_SSL_SESSION(fp,x,cb) | ||
| 75 | #define PEM_read_X509(fp,x,cb) | ||
| 76 | #define PEM_read_X509_REQ(fp,x,cb) | ||
| 77 | #define PEM_read_X509_CRL(fp,x,cb) | ||
| 78 | #define PEM_read_RSAPrivateKey(fp,x,cb) | ||
| 79 | #define PEM_read_DSAPrivateKey(fp,x,cb) | ||
| 80 | #define PEM_read_PrivateKey(fp,x,cb) | ||
| 81 | #define PEM_read_PKCS7(fp,x,cb) | ||
| 82 | #define PEM_read_DHparams(fp,x,cb) | ||
| 83 | #define PEM_read_bio_SSL_SESSION(bp,x,cb) | ||
| 84 | #define PEM_read_bio_X509(bp,x,cb) | ||
| 85 | #define PEM_read_bio_X509_REQ(bp,x,cb) | ||
| 86 | #define PEM_read_bio_X509_CRL(bp,x,cb) | ||
| 87 | #define PEM_read_bio_RSAPrivateKey(bp,x,cb) | ||
| 88 | #define PEM_read_bio_DSAPrivateKey(bp,x,cb) | ||
| 89 | #define PEM_read_bio_PrivateKey(bp,x,cb) | ||
| 90 | #define PEM_read_bio_PKCS7(bp,x,cb) | ||
| 91 | #define PEM_read_bio_DHparams(bp,x,cb) | ||
| 92 | int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); | ||
| 93 | RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)()); | ||
| 94 | |||
| 95 | Now you will notice that macros like | ||
| 96 | #define PEM_write_X509(fp,x) \ | ||
| 97 | PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \ | ||
| 98 | (char *)x, NULL,NULL,0,NULL) | ||
| 99 | Don't do encryption normally. If you want to PEM encrypt your X509 structure, | ||
| 100 | either just call PEM_ASN1_write directly or just define you own | ||
| 101 | macro variant. As you can see, this macro just sets all encryption related | ||
| 102 | parameters to NULL. | ||
| 103 | |||
| 104 | |||
| 105 | -------------------------- | ||
| 106 | The SSL library. | ||
| 107 | |||
| 108 | #define SSL_set_info_callback(ssl,cb) | ||
| 109 | #define SSL_CTX_set_info_callback(ctx,cb) | ||
| 110 | void callback(SSL *ssl,int location,int ret) | ||
| 111 | This callback is called each time around the SSL_connect()/SSL_accept() | ||
| 112 | state machine. So it will be called each time the SSL protocol progresses. | ||
| 113 | It is mostly present for use when debugging. When SSL_connect() or | ||
| 114 | SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or | ||
| 115 | SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned. | ||
| 116 | Have a look at the SSL_CB_* defines in ssl.h. If an info callback is defined | ||
| 117 | against the SSL_CTX, it is called unless there is one set against the SSL. | ||
| 118 | Have a look at | ||
| 119 | void client_info_callback() in apps/s_client() for an example. | ||
| 120 | |||
| 121 | Certificate verification. | ||
| 122 | void SSL_set_verify(SSL *s, int mode, int (*callback) ()); | ||
| 123 | void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)()); | ||
| 124 | This callback is used to help verify client and server X509 certificates. | ||
| 125 | It is actually passed to X509_cert_verify(), along with the SSL structure | ||
| 126 | so you have to read about X509_cert_verify() :-). The SSL_CTX version is used | ||
| 127 | if the SSL version is not defined. X509_cert_verify() is the function used | ||
| 128 | by the SSL part of the library to verify certificates. This function is | ||
| 129 | nearly always defined by the application. | ||
| 130 | |||
| 131 | void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg); | ||
| 132 | int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain); | ||
| 133 | This call is used to replace the SSLeay certificate verification code. | ||
| 134 | The 'arg' is kept in the SSL_CTX and is passed to the callback. | ||
| 135 | If the callback returns 0, the certificate is rejected, otherwise it | ||
| 136 | is accepted. The callback is replacing the X509_cert_verify() call. | ||
| 137 | This feature is not often used, but if you wished to implement | ||
| 138 | some totally different certificate authentication system, this 'hook' is | ||
| 139 | vital. | ||
| 140 | |||
| 141 | SSLeay keeps a cache of session-ids against each SSL_CTX. These callbacks can | ||
| 142 | be used to notify the application when a SSL_SESSION is added to the cache | ||
| 143 | or to retrieve a SSL_SESSION that is not in the cache from the application. | ||
| 144 | #define SSL_CTX_sess_set_get_cb(ctx,cb) | ||
| 145 | SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy); | ||
| 146 | If defined, this callback is called to return the SESSION_ID for the | ||
| 147 | session-id in 'session_id', of 'session_id_len' bytes. 'copy' is set to 1 | ||
| 148 | if the server is to 'take a copy' of the SSL_SESSION structure. It is 0 | ||
| 149 | if the SSL_SESSION is being 'passed in' so the SSLeay library is now | ||
| 150 | responsible for 'free()ing' the structure. Basically it is used to indicate | ||
| 151 | if the reference count on the SSL_SESSION structure needs to be incremented. | ||
| 152 | |||
| 153 | #define SSL_CTX_sess_set_new_cb(ctx,cb) | ||
| 154 | int callback(SSL *s, SSL_SESSION *sess); | ||
| 155 | When a new connection is established, if the SSL_SESSION is going to be added | ||
| 156 | to the cache, this callback is called. Return 1 if a 'copy' is required, | ||
| 157 | otherwise, return 0. This return value just causes the reference count | ||
| 158 | to be incremented (on return of a 1), this means the application does | ||
| 159 | not need to worry about incrementing the refernece count (and the | ||
| 160 | locking that implies in a multi-threaded application). | ||
| 161 | |||
| 162 | void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)()); | ||
| 163 | This sets the SSL password reading function. | ||
| 164 | It is mostly used for windowing applications | ||
| 165 | and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey() | ||
| 166 | calls inside the SSL library. The only reason this is present is because the | ||
| 167 | calls to PEM_* functions is hidden in the SSLeay library so you have to | ||
| 168 | pass in the callback some how. | ||
| 169 | |||
| 170 | #define SSL_CTX_set_client_cert_cb(ctx,cb) | ||
| 171 | int callback(SSL *s,X509 **x509, EVP_PKEY **pkey); | ||
| 172 | Called when a client certificate is requested but there is not one set | ||
| 173 | against the SSL_CTX or the SSL. If the callback returns 1, x509 and | ||
| 174 | pkey need to point to valid data. The library will free these when | ||
| 175 | required so if the application wants to keep these around, increment | ||
| 176 | their reference counts. If 0 is returned, no client cert is | ||
| 177 | available. If -1 is returned, it is assumed that the callback needs | ||
| 178 | to be called again at a later point in time. SSL_connect will return | ||
| 179 | -1 and SSL_want_x509_lookup(ssl) returns true. Remember that | ||
| 180 | application data can be attached to an SSL structure via the | ||
| 181 | SSL_set_app_data(SSL *ssl,char *data) call. | ||
| 182 | |||
| 183 | -------------------------- | ||
| 184 | The X509 library. | ||
| 185 | |||
| 186 | int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(), | ||
| 187 | int *error,char *arg,STACK *cert_chain); | ||
| 188 | int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg, | ||
| 189 | STACK *cert_chain); | ||
| 190 | |||
| 191 | X509_cert_verify() is used to authenticate X509 certificates. The 'ctx' holds | ||
| 192 | the details of the various caches and files used to locate certificates. | ||
| 193 | 'xs' is the certificate to verify and 'cb' is the application callback (more | ||
| 194 | detail later). 'error' will be set to the error code and 'arg' is passed | ||
| 195 | to the 'cb' callback. Look at the VERIFY_* defines in crypto/x509/x509.h | ||
| 196 | |||
| 197 | When ever X509_cert_verify() makes a 'negative' decision about a | ||
| 198 | certitificate, the callback is called. If everything checks out, the | ||
| 199 | callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self | ||
| 200 | signed cert that is not the passed certificate). | ||
| 201 | |||
| 202 | The callback is passed the X509_cert_verify opinion of the certificate | ||
| 203 | in 'ok', the certificate in 'xs', the issuer certificate in 'xi', | ||
| 204 | the 'depth' of the certificate in the verification 'chain', the | ||
| 205 | VERIFY_* code in 'error' and the argument passed to X509_cert_verify() | ||
| 206 | in 'arg'. cert_chain is a list of extra certs to use if they are not | ||
| 207 | in the cache. | ||
| 208 | |||
| 209 | The callback can be used to look at the error reason, and then return 0 | ||
| 210 | for an 'error' or '1' for ok. This will override the X509_cert_verify() | ||
| 211 | opinion of the certificates validity. Processing will continue depending on | ||
| 212 | the return value. If one just wishes to use the callback for informational | ||
| 213 | reason, just return the 'ok' parameter. | ||
| 214 | |||
| 215 | -------------------------- | ||
| 216 | The BN and DH library. | ||
| 217 | |||
| 218 | BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add, | ||
| 219 | BIGNUM *rem,void (*callback)(int,int)); | ||
| 220 | int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int), | ||
| 221 | |||
| 222 | Read doc/bn.doc for the description of these 2. | ||
| 223 | |||
| 224 | DH *DH_generate_parameters(int prime_len,int generator, | ||
| 225 | void (*callback)(int,int)); | ||
| 226 | Read doc/bn.doc for the description of the callback, since it is just passed | ||
| 227 | to BN_generate_prime(), except that it is also called as | ||
| 228 | callback(3,0) by this function. | ||
| 229 | |||
| 230 | -------------------------- | ||
| 231 | The CRYPTO library. | ||
| 232 | |||
| 233 | void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file, | ||
| 234 | int line)); | ||
| 235 | void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount, | ||
| 236 | int type,char *file, int line)); | ||
| 237 | void CRYPTO_set_id_callback(unsigned long (*func)(void)); | ||
| 238 | |||
| 239 | Read threads.doc for info on these ones. | ||
| 240 | |||
diff --git a/src/lib/libssl/src/doc/cipher.doc b/src/lib/libssl/src/doc/cipher.doc deleted file mode 100644 index d49ba78c5c..0000000000 --- a/src/lib/libssl/src/doc/cipher.doc +++ /dev/null | |||
| @@ -1,345 +0,0 @@ | |||
| 1 | The Cipher subroutines. | ||
| 2 | |||
| 3 | These routines require "evp.h" to be included. | ||
| 4 | |||
| 5 | These functions are a higher level interface to the various cipher | ||
| 6 | routines found in this library. As such, they allow the same code to be | ||
| 7 | used to encrypt and decrypt via different ciphers with only a change | ||
| 8 | in an initial parameter. These routines also provide buffering for block | ||
| 9 | ciphers. | ||
| 10 | |||
| 11 | These routines all take a pointer to the following structure to specify | ||
| 12 | which cipher to use. If you wish to use a new cipher with these routines, | ||
| 13 | you would probably be best off looking an how an existing cipher is | ||
| 14 | implemented and copying it. At this point in time, I'm not going to go | ||
| 15 | into many details. This structure should be considered opaque | ||
| 16 | |||
| 17 | typedef struct pem_cipher_st | ||
| 18 | { | ||
| 19 | int type; | ||
| 20 | int block_size; | ||
| 21 | int key_len; | ||
| 22 | int iv_len; | ||
| 23 | void (*enc_init)(); /* init for encryption */ | ||
| 24 | void (*dec_init)(); /* init for decryption */ | ||
| 25 | void (*do_cipher)(); /* encrypt data */ | ||
| 26 | } EVP_CIPHER; | ||
| 27 | |||
| 28 | The type field is the object NID of the cipher type | ||
| 29 | (read the section on Objects for an explanation of what a NID is). | ||
| 30 | The cipher block_size is how many bytes need to be passed | ||
| 31 | to the cipher at a time. Key_len is the | ||
| 32 | length of the key the cipher requires and iv_len is the length of the | ||
| 33 | initialisation vector required. enc_init is the function | ||
| 34 | called to initialise the ciphers context for encryption and dec_init is the | ||
| 35 | function to initialise for decryption (they need to be different, especially | ||
| 36 | for the IDEA cipher). | ||
| 37 | |||
| 38 | One reason for specifying the Cipher via a pointer to a structure | ||
| 39 | is that if you only use des-cbc, only the des-cbc routines will | ||
| 40 | be included when you link the program. If you passed an integer | ||
| 41 | that specified which cipher to use, the routine that mapped that | ||
| 42 | integer to a set of cipher functions would cause all the ciphers | ||
| 43 | to be link into the code. This setup also allows new ciphers | ||
| 44 | to be added by the application (with some restrictions). | ||
| 45 | |||
| 46 | The thirteen ciphers currently defined in this library are | ||
| 47 | |||
| 48 | EVP_CIPHER *EVP_des_ecb(); /* DES in ecb mode, iv=0, block=8, key= 8 */ | ||
| 49 | EVP_CIPHER *EVP_des_ede(); /* DES in ecb ede mode, iv=0, block=8, key=16 */ | ||
| 50 | EVP_CIPHER *EVP_des_ede3(); /* DES in ecb ede mode, iv=0, block=8, key=24 */ | ||
| 51 | EVP_CIPHER *EVP_des_cfb(); /* DES in cfb mode, iv=8, block=1, key= 8 */ | ||
| 52 | EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */ | ||
| 53 | EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */ | ||
| 54 | EVP_CIPHER *EVP_des_ofb(); /* DES in ofb mode, iv=8, block=1, key= 8 */ | ||
| 55 | EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */ | ||
| 56 | EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */ | ||
| 57 | EVP_CIPHER *EVP_des_cbc(); /* DES in cbc mode, iv=8, block=8, key= 8 */ | ||
| 58 | EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */ | ||
| 59 | EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */ | ||
| 60 | EVP_CIPHER *EVP_desx_cbc(); /* DES in desx cbc mode,iv=8, block=8, key=24 */ | ||
| 61 | EVP_CIPHER *EVP_rc4(); /* RC4, iv=0, block=1, key=16 */ | ||
| 62 | EVP_CIPHER *EVP_idea_ecb(); /* IDEA in ecb mode, iv=0, block=8, key=16 */ | ||
| 63 | EVP_CIPHER *EVP_idea_cfb(); /* IDEA in cfb mode, iv=8, block=1, key=16 */ | ||
| 64 | EVP_CIPHER *EVP_idea_ofb(); /* IDEA in ofb mode, iv=8, block=1, key=16 */ | ||
| 65 | EVP_CIPHER *EVP_idea_cbc(); /* IDEA in cbc mode, iv=8, block=8, key=16 */ | ||
| 66 | EVP_CIPHER *EVP_rc2_ecb(); /* RC2 in ecb mode, iv=0, block=8, key=16 */ | ||
| 67 | EVP_CIPHER *EVP_rc2_cfb(); /* RC2 in cfb mode, iv=8, block=1, key=16 */ | ||
| 68 | EVP_CIPHER *EVP_rc2_ofb(); /* RC2 in ofb mode, iv=8, block=1, key=16 */ | ||
| 69 | EVP_CIPHER *EVP_rc2_cbc(); /* RC2 in cbc mode, iv=8, block=8, key=16 */ | ||
| 70 | EVP_CIPHER *EVP_bf_ecb(); /* Blowfish in ecb mode,iv=0, block=8, key=16 */ | ||
| 71 | EVP_CIPHER *EVP_bf_cfb(); /* Blowfish in cfb mode,iv=8, block=1, key=16 */ | ||
| 72 | EVP_CIPHER *EVP_bf_ofb(); /* Blowfish in ofb mode,iv=8, block=1, key=16 */ | ||
| 73 | EVP_CIPHER *EVP_bf_cbc(); /* Blowfish in cbc mode,iv=8, block=8, key=16 */ | ||
| 74 | |||
| 75 | The meaning of the compound names is as follows. | ||
| 76 | des The base cipher is DES. | ||
| 77 | idea The base cipher is IDEA | ||
| 78 | rc4 The base cipher is RC4-128 | ||
| 79 | rc2 The base cipher is RC2-128 | ||
| 80 | ecb Electronic Code Book form of the cipher. | ||
| 81 | cbc Cipher Block Chaining form of the cipher. | ||
| 82 | cfb 64 bit Cipher Feedback form of the cipher. | ||
| 83 | ofb 64 bit Output Feedback form of the cipher. | ||
| 84 | ede The cipher is used in Encrypt, Decrypt, Encrypt mode. The first | ||
| 85 | and last keys are the same. | ||
| 86 | ede3 The cipher is used in Encrypt, Decrypt, Encrypt mode. | ||
| 87 | |||
| 88 | All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument. | ||
| 89 | The state of the cipher is kept in this structure. | ||
| 90 | |||
| 91 | typedef struct EVP_CIPHER_Ctx_st | ||
| 92 | { | ||
| 93 | EVP_CIPHER *cipher; | ||
| 94 | int encrypt; /* encrypt or decrypt */ | ||
| 95 | int buf_len; /* number we have left */ | ||
| 96 | unsigned char buf[8]; | ||
| 97 | union { | ||
| 98 | .... /* cipher specific stuff */ | ||
| 99 | } c; | ||
| 100 | } EVP_CIPHER_CTX; | ||
| 101 | |||
| 102 | Cipher is a pointer the the EVP_CIPHER for the current context. The encrypt | ||
| 103 | flag indicates encryption or decryption. buf_len is the number of bytes | ||
| 104 | currently being held in buf. | ||
| 105 | The 'c' union holds the cipher specify context. | ||
| 106 | |||
| 107 | The following functions are to be used. | ||
| 108 | |||
| 109 | int EVP_read_pw_string( | ||
| 110 | char *buf, | ||
| 111 | int len, | ||
| 112 | char *prompt, | ||
| 113 | int verify, | ||
| 114 | This function is the same as des_read_pw_string() (des.doc). | ||
| 115 | |||
| 116 | void EVP_set_pw_prompt(char *prompt); | ||
| 117 | This function sets the 'default' prompt to use to use in | ||
| 118 | EVP_read_pw_string when the prompt parameter is NULL. If the | ||
| 119 | prompt parameter is NULL, this 'default prompt' feature is turned | ||
| 120 | off. Be warned, this is a global variable so weird things | ||
| 121 | will happen if it is used under Win16 and care must be taken | ||
| 122 | with a multi-threaded version of the library. | ||
| 123 | |||
| 124 | char *EVP_get_pw_prompt(); | ||
| 125 | This returns a pointer to the default prompt string. NULL | ||
| 126 | if it is not set. | ||
| 127 | |||
| 128 | int EVP_BytesToKey( | ||
| 129 | EVP_CIPHER *type, | ||
| 130 | EVP_MD *md, | ||
| 131 | unsigned char *salt, | ||
| 132 | unsigned char *data, | ||
| 133 | int datal, | ||
| 134 | int count, | ||
| 135 | unsigned char *key, | ||
| 136 | unsigned char *iv); | ||
| 137 | This function is used to generate a key and an initialisation vector | ||
| 138 | for a specified cipher from a key string and a salt. Type | ||
| 139 | specifies the cipher the 'key' is being generated for. Md is the | ||
| 140 | message digest algorithm to use to generate the key and iv. The salt | ||
| 141 | is an optional 8 byte object that is used to help seed the key | ||
| 142 | generator. | ||
| 143 | If the salt value is NULL, it is just not used. Datal is the | ||
| 144 | number of bytes to use from 'data' in the key generation. | ||
| 145 | This function returns the key size for the specified cipher, if | ||
| 146 | data is NULL, this value is returns and no other | ||
| 147 | computation is performed. Count is | ||
| 148 | the number of times to loop around the key generator. I would | ||
| 149 | suggest leaving it's value as 1. Key and iv are the structures to | ||
| 150 | place the returning iv and key in. If they are NULL, no value is | ||
| 151 | generated for that particular value. | ||
| 152 | The algorithm used is as follows | ||
| 153 | |||
| 154 | /* M[] is an array of message digests | ||
| 155 | * MD() is the message digest function */ | ||
| 156 | M[0]=MD(data . salt); | ||
| 157 | for (i=1; i<count; i++) M[0]=MD(M[0]); | ||
| 158 | |||
| 159 | i=1 | ||
| 160 | while (data still needed for key and iv) | ||
| 161 | { | ||
| 162 | M[i]=MD(M[i-1] . data . salt); | ||
| 163 | for (i=1; i<count; i++) M[i]=MD(M[i]); | ||
| 164 | i++; | ||
| 165 | } | ||
| 166 | |||
| 167 | If the salt is NULL, it is not used. | ||
| 168 | The digests are concatenated together. | ||
| 169 | M = M[0] . M[1] . M[2] ....... | ||
| 170 | |||
| 171 | For key= 8, iv=8 => key=M[0.. 8], iv=M[ 9 .. 16]. | ||
| 172 | For key=16, iv=0 => key=M[0..16]. | ||
| 173 | For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24]. | ||
| 174 | For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32]. | ||
| 175 | |||
| 176 | This routine will produce DES-CBC keys and iv that are compatible | ||
| 177 | with the PKCS-5 standard when md2 or md5 are used. If md5 is | ||
| 178 | used, the salt is NULL and count is 1, this routine will produce | ||
| 179 | the password to key mapping normally used with RC4. | ||
| 180 | I have attempted to logically extend the PKCS-5 standard to | ||
| 181 | generate keys and iv for ciphers that require more than 16 bytes, | ||
| 182 | if anyone knows what the correct standard is, please inform me. | ||
| 183 | When using sha or sha1, things are a bit different under this scheme, | ||
| 184 | since sha produces a 20 byte digest. So for ciphers requiring | ||
| 185 | 24 bits of data, 20 will come from the first MD and 4 will | ||
| 186 | come from the second. | ||
| 187 | |||
| 188 | I have considered having a separate function so this 'routine' | ||
| 189 | can be used without the requirement of passing a EVP_CIPHER *, | ||
| 190 | but I have decided to not bother. If you wish to use the | ||
| 191 | function without official EVP_CIPHER structures, just declare | ||
| 192 | a local one and set the key_len and iv_len fields to the | ||
| 193 | length you desire. | ||
| 194 | |||
| 195 | The following routines perform encryption and decryption 'by parts'. By | ||
| 196 | this I mean that there are groups of 3 routines. An Init function that is | ||
| 197 | used to specify a cipher and initialise data structures. An Update routine | ||
| 198 | that does encryption/decryption, one 'chunk' at a time. And finally a | ||
| 199 | 'Final' function that finishes the encryption/decryption process. | ||
| 200 | All these functions take a EVP_CIPHER pointer to specify which cipher to | ||
| 201 | encrypt/decrypt with. They also take a EVP_CIPHER_CTX object as an | ||
| 202 | argument. This structure is used to hold the state information associated | ||
| 203 | with the operation in progress. | ||
| 204 | |||
| 205 | void EVP_EncryptInit( | ||
| 206 | EVP_CIPHER_CTX *ctx, | ||
| 207 | EVP_CIPHER *type, | ||
| 208 | unsigned char *key, | ||
| 209 | unsigned char *iv); | ||
| 210 | This function initialise a EVP_CIPHER_CTX for encryption using the | ||
| 211 | cipher passed in the 'type' field. The cipher is initialised to use | ||
| 212 | 'key' as the key and 'iv' for the initialisation vector (if one is | ||
| 213 | required). If the type, key or iv is NULL, the value currently in the | ||
| 214 | EVP_CIPHER_CTX is reused. So to perform several decrypt | ||
| 215 | using the same cipher, key and iv, initialise with the cipher, | ||
| 216 | key and iv the first time and then for subsequent calls, | ||
| 217 | reuse 'ctx' but pass NULL for type, key and iv. You must make sure | ||
| 218 | to pass a key that is large enough for a particular cipher. I | ||
| 219 | would suggest using the EVP_BytesToKey() function. | ||
| 220 | |||
| 221 | void EVP_EncryptUpdate( | ||
| 222 | EVP_CIPHER_CTX *ctx, | ||
| 223 | unsigned char *out, | ||
| 224 | int *outl, | ||
| 225 | unsigned char *in, | ||
| 226 | int inl); | ||
| 227 | This function takes 'inl' bytes from 'in' and outputs bytes | ||
| 228 | encrypted by the cipher 'ctx' was initialised with into 'out'. The | ||
| 229 | number of bytes written to 'out' is put into outl. If a particular | ||
| 230 | cipher encrypts in blocks, less or more bytes than input may be | ||
| 231 | output. Currently the largest block size used by supported ciphers | ||
| 232 | is 8 bytes, so 'out' should have room for 'inl+7' bytes. Normally | ||
| 233 | EVP_EncryptInit() is called once, followed by lots and lots of | ||
| 234 | calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal | ||
| 235 | call. | ||
| 236 | |||
| 237 | void EVP_EncryptFinal( | ||
| 238 | EVP_CIPHER_CTX *ctx, | ||
| 239 | unsigned char *out, | ||
| 240 | int *outl); | ||
| 241 | Because quite a large number of ciphers are block ciphers, there is | ||
| 242 | often an incomplete block to write out at the end of the | ||
| 243 | encryption. EVP_EncryptFinal() performs processing on this last | ||
| 244 | block. The last block in encoded in such a way that it is possible | ||
| 245 | to determine how many bytes in the last block are valid. For 8 byte | ||
| 246 | block size ciphers, if only 5 bytes in the last block are valid, the | ||
| 247 | last three bytes will be filled with the value 3. If only 2 were | ||
| 248 | valid, the other 6 would be filled with sixes. If all 8 bytes are | ||
| 249 | valid, a extra 8 bytes are appended to the cipher stream containing | ||
| 250 | nothing but 8 eights. These last bytes are output into 'out' and | ||
| 251 | the number of bytes written is put into 'outl' These last bytes | ||
| 252 | are output into 'out' and the number of bytes written is put into | ||
| 253 | 'outl'. This form of block cipher finalisation is compatible with | ||
| 254 | PKCS-5. Please remember that even if you are using ciphers like | ||
| 255 | RC4 that has no blocking and so the function will not write | ||
| 256 | anything into 'out', it would still be a good idea to pass a | ||
| 257 | variable for 'out' that can hold 8 bytes just in case the cipher is | ||
| 258 | changed some time in the future. It should also be remembered | ||
| 259 | that the EVP_CIPHER_CTX contains the password and so when one has | ||
| 260 | finished encryption with a particular EVP_CIPHER_CTX, it is good | ||
| 261 | practice to zero the structure | ||
| 262 | (ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)). | ||
| 263 | |||
| 264 | void EVP_DecryptInit( | ||
| 265 | EVP_CIPHER_CTX *ctx, | ||
| 266 | EVP_CIPHER *type, | ||
| 267 | unsigned char *key, | ||
| 268 | unsigned char *iv); | ||
| 269 | This function is basically the same as EVP_EncryptInit() accept that | ||
| 270 | is prepares the EVP_CIPHER_CTX for decryption. | ||
| 271 | |||
| 272 | void EVP_DecryptUpdate( | ||
| 273 | EVP_CIPHER_CTX *ctx, | ||
| 274 | unsigned char *out, | ||
| 275 | int *outl, | ||
| 276 | unsigned char *in, | ||
| 277 | int inl); | ||
| 278 | This function is basically the same as EVP_EncryptUpdate() | ||
| 279 | except that it performs decryption. There is one | ||
| 280 | fundamental difference though. 'out' can not be the same as | ||
| 281 | 'in' for any ciphers with a block size greater than 1 if more | ||
| 282 | than one call to EVP_DecryptUpdate() will be made. This | ||
| 283 | is because this routine can hold a 'partial' block between | ||
| 284 | calls. When a partial block is decrypted (due to more bytes | ||
| 285 | being passed via this function, they will be written to 'out' | ||
| 286 | overwriting the input bytes in 'in' that have not been read | ||
| 287 | yet. From this it should also be noted that 'out' should | ||
| 288 | be at least one 'block size' larger than 'inl'. This problem | ||
| 289 | only occurs on the second and subsequent call to | ||
| 290 | EVP_DecryptUpdate() when using a block cipher. | ||
| 291 | |||
| 292 | int EVP_DecryptFinal( | ||
| 293 | EVP_CIPHER_CTX *ctx, | ||
| 294 | unsigned char *out, | ||
| 295 | int *outl); | ||
| 296 | This function is different to EVP_EncryptFinal in that it 'removes' | ||
| 297 | any padding bytes appended when the data was encrypted. Due to the | ||
| 298 | way in which 1 to 8 bytes may have been appended when encryption | ||
| 299 | using a block cipher, 'out' can end up with 0 to 7 bytes being put | ||
| 300 | into it. When decoding the padding bytes, it is possible to detect | ||
| 301 | an incorrect decryption. If the decryption appears to be wrong, 0 | ||
| 302 | is returned. If everything seems ok, 1 is returned. For ciphers | ||
| 303 | with a block size of 1 (RC4), this function would normally not | ||
| 304 | return any bytes and would always return 1. Just because this | ||
| 305 | function returns 1 does not mean the decryption was correct. It | ||
| 306 | would normally be wrong due to either the wrong key/iv or | ||
| 307 | corruption of the cipher data fed to EVP_DecryptUpdate(). | ||
| 308 | As for EVP_EncryptFinal, it is a good idea to zero the | ||
| 309 | EVP_CIPHER_CTX after use since the structure contains the key used | ||
| 310 | to decrypt the data. | ||
| 311 | |||
| 312 | The following Cipher routines are convenience routines that call either | ||
| 313 | EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX | ||
| 314 | was setup to encrypt or decrypt. | ||
| 315 | |||
| 316 | void EVP_CipherInit( | ||
| 317 | EVP_CIPHER_CTX *ctx, | ||
| 318 | EVP_CIPHER *type, | ||
| 319 | unsigned char *key, | ||
| 320 | unsigned char *iv, | ||
| 321 | int enc); | ||
| 322 | This function take arguments that are the same as EVP_EncryptInit() | ||
| 323 | and EVP_DecryptInit() except for the extra 'enc' flag. If 1, the | ||
| 324 | EVP_CIPHER_CTX is setup for encryption, if 0, decryption. | ||
| 325 | |||
| 326 | void EVP_CipherUpdate( | ||
| 327 | EVP_CIPHER_CTX *ctx, | ||
| 328 | unsigned char *out, | ||
| 329 | int *outl, | ||
| 330 | unsigned char *in, | ||
| 331 | int inl); | ||
| 332 | Again this function calls either EVP_EncryptUpdate() or | ||
| 333 | EVP_DecryptUpdate() depending on state in the 'ctx' structure. | ||
| 334 | As noted for EVP_DecryptUpdate(), when this routine is used | ||
| 335 | for decryption with block ciphers, 'out' should not be the | ||
| 336 | same as 'in'. | ||
| 337 | |||
| 338 | int EVP_CipherFinal( | ||
| 339 | EVP_CIPHER_CTX *ctx, | ||
| 340 | unsigned char *outm, | ||
| 341 | int *outl); | ||
| 342 | This routine call EVP_EncryptFinal() or EVP_DecryptFinal() | ||
| 343 | depending on the state information in 'ctx'. 1 is always returned | ||
| 344 | if the mode is encryption, otherwise the return value is the return | ||
| 345 | value of EVP_DecryptFinal(). | ||
diff --git a/src/lib/libssl/src/doc/cipher.m b/src/lib/libssl/src/doc/cipher.m deleted file mode 100644 index 9f74917135..0000000000 --- a/src/lib/libssl/src/doc/cipher.m +++ /dev/null | |||
| @@ -1,128 +0,0 @@ | |||
| 1 | From ssl-lists-owner@mincom.com Tue Oct 15 18:16:14 1996 | ||
| 2 | Received: from cygnus.mincom.oz.au by orb.mincom.oz.au with SMTP id AA11550 | ||
| 3 | (5.65c/IDA-1.4.4 for eay); Tue, 15 Oct 1996 08:17:41 +1000 | ||
| 4 | Received: (from daemon@localhost) by cygnus.mincom.oz.au (8.7.5/8.7.3) id IAA12472 for ssl-users-outgoing; Tue, 15 Oct 1996 08:16:35 +1000 (EST) | ||
| 5 | Received: from orb.mincom.oz.au (eay@orb.mincom.oz.au [192.55.197.1]) by cygnus.mincom.oz.au (8.7.5/8.7.3) with SMTP id IAA12463 for <ssl-users@listserv.mincom.oz.au>; Tue, 15 Oct 1996 08:16:32 +1000 (EST) | ||
| 6 | Received: by orb.mincom.oz.au id AA11544 | ||
| 7 | (5.65c/IDA-1.4.4 for ssl-users@listserv.mincom.oz.au); Tue, 15 Oct 1996 08:16:15 +1000 | ||
| 8 | Date: Tue, 15 Oct 1996 08:16:14 +1000 (EST) | ||
| 9 | From: Eric Young <eay@mincom.com> | ||
| 10 | X-Sender: eay@orb | ||
| 11 | To: Roland Haring <rharing@tandem.cl> | ||
| 12 | Cc: ssl-users@mincom.com | ||
| 13 | Subject: Re: Symmetric encryption with ssleay | ||
| 14 | In-Reply-To: <m0vBpyq-00001aC@tandemnet.tandem.cl> | ||
| 15 | Message-Id: <Pine.SOL.3.91.961015075623.11394A-100000@orb> | ||
| 16 | Mime-Version: 1.0 | ||
| 17 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 18 | Sender: ssl-lists-owner@mincom.com | ||
| 19 | Precedence: bulk | ||
| 20 | Status: RO | ||
| 21 | X-Status: | ||
| 22 | |||
| 23 | |||
| 24 | On Fri, 11 Oct 1996, Roland Haring wrote: | ||
| 25 | > THE_POINT: | ||
| 26 | > Would somebody be so kind to give me the minimum basic | ||
| 27 | > calls I need to do to libcrypto.a to get some text encrypted | ||
| 28 | > and decrypted again? ...hopefully with code included to do | ||
| 29 | > base64 encryption and decryption ... e.g. that sign-it.c code | ||
| 30 | > posted some while ago was a big help :-) (please, do not point | ||
| 31 | > me to apps/enc.c where I suspect my Heissenbug to be hidden :-) | ||
| 32 | |||
| 33 | Ok, the base64 encoding stuff in 'enc.c' does the wrong thing sometimes | ||
| 34 | when the data is less than a line long (this is for decoding). I'll dig | ||
| 35 | up the exact fix today and post it. I am taking longer on 0.6.5 than I | ||
| 36 | intended so I'll just post this patch. | ||
| 37 | |||
| 38 | The documentation to read is in | ||
| 39 | doc/cipher.doc, | ||
| 40 | doc/encode.doc (very sparse :-). | ||
| 41 | and perhaps | ||
| 42 | doc/digest.doc, | ||
| 43 | |||
| 44 | The basic calls to encrypt with say triple DES are | ||
| 45 | |||
| 46 | Given | ||
| 47 | char key[EVP_MAX_KEY_LENGTH]; | ||
| 48 | char iv[EVP_MAX_IV_LENGTH]; | ||
| 49 | EVP_CIPHER_CTX ctx; | ||
| 50 | unsigned char out[512+8]; | ||
| 51 | int outl; | ||
| 52 | |||
| 53 | /* optional generation of key/iv data from text password using md5 | ||
| 54 | * via an upward compatable verson of PKCS#5. */ | ||
| 55 | EVP_BytesToKey(EVP_des_ede3_cbc,EVP_md5,NULL,passwd,strlen(passwd), | ||
| 56 | key,iv); | ||
| 57 | |||
| 58 | /* Initalise the EVP_CIPHER_CTX */ | ||
| 59 | EVP_EncryptInit(ctx,EVP_des_ede3_cbc,key,iv); | ||
| 60 | |||
| 61 | while (....) | ||
| 62 | { | ||
| 63 | /* This is processing 512 bytes at a time, the bytes are being | ||
| 64 | * copied into 'out', outl bytes are output. 'out' should not be the | ||
| 65 | * same as 'in' for reasons mentioned in the documentation. */ | ||
| 66 | EVP_EncryptUpdate(ctx,out,&outl,in,512); | ||
| 67 | } | ||
| 68 | |||
| 69 | /* Output the last 'block'. If the cipher is a block cipher, the last | ||
| 70 | * block is encoded in such a way so that a wrong decryption will normally be | ||
| 71 | * detected - again, one of the PKCS standards. */ | ||
| 72 | |||
| 73 | EVP_EncryptFinal(ctx,out,&outl); | ||
| 74 | |||
| 75 | To decrypt, use the EVP_DecryptXXXXX functions except that EVP_DecryptFinal() | ||
| 76 | will return 0 if the decryption fails (only detectable on block ciphers). | ||
| 77 | |||
| 78 | You can also use | ||
| 79 | EVP_CipherInit() | ||
| 80 | EVP_CipherUpdate() | ||
| 81 | EVP_CipherFinal() | ||
| 82 | which does either encryption or decryption depending on an extra | ||
| 83 | parameter to EVP_CipherInit(). | ||
| 84 | |||
| 85 | |||
| 86 | To do the base64 encoding, | ||
| 87 | EVP_EncodeInit() | ||
| 88 | EVP_EncodeUpdate() | ||
| 89 | EVP_EncodeFinal() | ||
| 90 | |||
| 91 | EVP_DecodeInit() | ||
| 92 | EVP_DecodeUpdate() | ||
| 93 | EVP_DecodeFinal() | ||
| 94 | |||
| 95 | where the encoding is quite simple, but the decoding can be a bit more | ||
| 96 | fun (due to dud input). | ||
| 97 | |||
| 98 | EVP_DecodeUpdate() returns -1 for an error on an input line, 0 if the | ||
| 99 | 'last line' was just processed, and 1 if more lines should be submitted. | ||
| 100 | |||
| 101 | EVP_DecodeFinal() returns -1 for an error or 1 if things are ok. | ||
| 102 | |||
| 103 | So the loop becomes | ||
| 104 | EVP_DecodeInit(....) | ||
| 105 | for (;;) | ||
| 106 | { | ||
| 107 | i=EVP_DecodeUpdate(....); | ||
| 108 | if (i < 0) goto err; | ||
| 109 | |||
| 110 | /* process the data */ | ||
| 111 | |||
| 112 | if (i == 0) break; | ||
| 113 | } | ||
| 114 | EVP_DecodeFinal(....); | ||
| 115 | /* process the data */ | ||
| 116 | |||
| 117 | The problem in 'enc.c' is that I was stuff the processing up after the | ||
| 118 | EVP_DecodeFinal(...) when the for(..) loop was not being run (one line of | ||
| 119 | base64 data) and this was because 'enc.c' tries to scan over a file until | ||
| 120 | it hits the first valid base64 encoded line. | ||
| 121 | |||
| 122 | hope this helps a bit. | ||
| 123 | eric | ||
| 124 | -- | ||
| 125 | Eric Young | BOOL is tri-state according to Bill Gates. | ||
| 126 | AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). | ||
| 127 | |||
| 128 | |||
diff --git a/src/lib/libssl/src/doc/conf.doc b/src/lib/libssl/src/doc/conf.doc deleted file mode 100644 index f12fe884f5..0000000000 --- a/src/lib/libssl/src/doc/conf.doc +++ /dev/null | |||
| @@ -1,89 +0,0 @@ | |||
| 1 | The CONF library. | ||
| 2 | |||
| 3 | The CONF library is a simple set of routines that can be used to configure | ||
| 4 | programs. It is a superset of the genenv() function with some extra | ||
| 5 | structure. | ||
| 6 | |||
| 7 | The library consists of 5 functions. | ||
| 8 | |||
| 9 | LHASH *CONF_load(LHASH *config,char *file); | ||
| 10 | This function is called to load in a configuration file. Multiple | ||
| 11 | configuration files can be loaded, with each subsequent 'load' overwriting | ||
| 12 | any already defined 'variables'. If there is an error, NULL is returned. | ||
| 13 | If config is NULL, a new LHASH structure is created and returned, otherwise | ||
| 14 | the new data in the 'file' is loaded into the 'config' structure. | ||
| 15 | |||
| 16 | void CONF_free(LHASH *config); | ||
| 17 | This function free()s the data in config. | ||
| 18 | |||
| 19 | char *CONF_get_string(LHASH *config,char *section,char *name); | ||
| 20 | This function returns the string found in 'config' that corresponds to the | ||
| 21 | 'section' and 'name' specified. Classes and the naming system used will be | ||
| 22 | discussed later in this document. If the variable is not defined, an NULL | ||
| 23 | is returned. | ||
| 24 | |||
| 25 | long CONF_get_long(LHASH *config,char *section, char *name); | ||
| 26 | This function is the same as CONF_get_string() except that it converts the | ||
| 27 | string to an long and returns it. If variable is not a number or the | ||
| 28 | variable does not exist, 0 is returned. This is a little problematic but I | ||
| 29 | don't know of a simple way around it. | ||
| 30 | |||
| 31 | STACK *CONF_get_section(LHASH *config, char *section); | ||
| 32 | This function returns a 'stack' of CONF_VALUE items that are all the | ||
| 33 | items defined in a particular section. DO NOT free() any of the | ||
| 34 | variable returned. They will disappear when CONF_free() is called. | ||
| 35 | |||
| 36 | The 'lookup' model. | ||
| 37 | The configuration file is divided into 'sections'. Each section is started by | ||
| 38 | a line of the form '[ section ]'. All subsequent variable definitions are | ||
| 39 | of this section. A variable definition is a simple alpha-numeric name | ||
| 40 | followed by an '=' and then the data. A section or variable name can be | ||
| 41 | described by a regular expression of the following form '[A-Za-z0-9_]+'. | ||
| 42 | The value of the variable is the text after the '=' until the end of the | ||
| 43 | line, stripped of leading and trailing white space. | ||
| 44 | At this point I should mention that a '#' is a comment character, \ is the | ||
| 45 | escape character, and all three types of quote can be used to stop any | ||
| 46 | special interpretation of the data. | ||
| 47 | Now when the data is being loaded, variable expansion can occur. This is | ||
| 48 | done by expanding any $NAME sequences into the value represented by the | ||
| 49 | variable NAME. If the variable is not in the current section, the different | ||
| 50 | section can be specified by using the $SECTION::NAME form. The ${NAME} form | ||
| 51 | also works and is very useful for expanding variables inside strings. | ||
| 52 | |||
| 53 | When a variable is looked up, there are 2 special section. 'default', which | ||
| 54 | is the initial section, and 'ENV' which is the processes environment | ||
| 55 | variables (accessed via getenv()). When a variable is looked up, it is | ||
| 56 | first 'matched' with it's section (if one was specified), if this fails, the | ||
| 57 | 'default' section is matched. | ||
| 58 | If the 'lhash' variable passed was NULL, the environment is searched. | ||
| 59 | |||
| 60 | Now why do we bother with sections? So we can have multiple programs using | ||
| 61 | the same configuration file, or multiple instances of the same program | ||
| 62 | using different variables. It also provides a nice mechanism to override | ||
| 63 | the processes environment variables (eg ENV::HOME=/tmp). If there is a | ||
| 64 | program specific variable missing, we can have default values. | ||
| 65 | Multiple configuration files can be loaded, with each new value clearing | ||
| 66 | any predefined values. A system config file can provide 'default' values, | ||
| 67 | and application/usr specific files can provide overriding values. | ||
| 68 | |||
| 69 | Examples | ||
| 70 | |||
| 71 | # This is a simple example | ||
| 72 | SSLEAY_HOME = /usr/local/ssl | ||
| 73 | ENV::PATH = $SSLEAY_HOME/bin:$PATH # override my path | ||
| 74 | |||
| 75 | [X509] | ||
| 76 | cert_dir = $SSLEAY_HOME/certs # /usr/local/ssl/certs | ||
| 77 | |||
| 78 | [SSL] | ||
| 79 | CIPHER = DES-EDE-MD5:RC4-MD5 | ||
| 80 | USER_CERT = $HOME/${USER}di'r 5' # /home/eay/eaydir 5 | ||
| 81 | USER_CERT = $HOME/\${USER}di\'r # /home/eay/${USER}di'r | ||
| 82 | USER_CERT = "$HOME/${US"ER}di\'r # $HOME/${USER}di'r | ||
| 83 | |||
| 84 | TEST = 1234\ | ||
| 85 | 5678\ | ||
| 86 | 9ab # TEST=123456789ab | ||
| 87 | TTT = 1234\n\n # TTT=1234<nl><nl> | ||
| 88 | |||
| 89 | |||
diff --git a/src/lib/libssl/src/doc/crypto.pod b/src/lib/libssl/src/doc/crypto.pod new file mode 100644 index 0000000000..9c8a143b09 --- /dev/null +++ b/src/lib/libssl/src/doc/crypto.pod | |||
| @@ -0,0 +1,27 @@ | |||
| 1 | |||
| 2 | =pod | ||
| 3 | |||
| 4 | =head1 NAME | ||
| 5 | |||
| 6 | Crypto - OpenSSL Cryptography library | ||
| 7 | |||
| 8 | =head1 SYNOPSIS | ||
| 9 | |||
| 10 | =head1 DESCRIPTION | ||
| 11 | |||
| 12 | The OpenSSL B<crypto> library implements various cryptography standards | ||
| 13 | related to the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security | ||
| 14 | (TLS v1) protocols. It provides a rich API which is documented here. | ||
| 15 | |||
| 16 | ... | ||
| 17 | |||
| 18 | =head1 SEE ALSO | ||
| 19 | |||
| 20 | openssl(1), ssl(3) | ||
| 21 | |||
| 22 | =head1 HISTORY | ||
| 23 | |||
| 24 | The crypto(3) document appeared in OpenSSL 0.9.2 | ||
| 25 | |||
| 26 | =cut | ||
| 27 | |||
diff --git a/src/lib/libssl/src/doc/des.doc b/src/lib/libssl/src/doc/des.doc deleted file mode 100644 index 5879d968f3..0000000000 --- a/src/lib/libssl/src/doc/des.doc +++ /dev/null | |||
| @@ -1,505 +0,0 @@ | |||
| 1 | The DES library. | ||
| 2 | |||
| 3 | Please note that this library was originally written to operate with | ||
| 4 | eBones, a version of Kerberos that had had encryption removed when it left | ||
| 5 | the USA and then put back in. As such there are some routines that I will | ||
| 6 | advise not using but they are still in the library for historical reasons. | ||
| 7 | For all calls that have an 'input' and 'output' variables, they can be the | ||
| 8 | same. | ||
| 9 | |||
| 10 | This library requires the inclusion of 'des.h'. | ||
| 11 | |||
| 12 | All of the encryption functions take what is called a des_key_schedule as an | ||
| 13 | argument. A des_key_schedule is an expanded form of the des key. | ||
| 14 | A des_key is 8 bytes of odd parity, the type used to hold the key is a | ||
| 15 | des_cblock. A des_cblock is an array of 8 bytes, often in this library | ||
| 16 | description I will refer to input bytes when the function specifies | ||
| 17 | des_cblock's as input or output, this just means that the variable should | ||
| 18 | be a multiple of 8 bytes. | ||
| 19 | |||
| 20 | The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to | ||
| 21 | specify decryption. The functions and global variable are as follows: | ||
| 22 | |||
| 23 | int des_check_key; | ||
| 24 | DES keys are supposed to be odd parity. If this variable is set to | ||
| 25 | a non-zero value, des_set_key() will check that the key has odd | ||
| 26 | parity and is not one of the known weak DES keys. By default this | ||
| 27 | variable is turned off; | ||
| 28 | |||
| 29 | void des_set_odd_parity( | ||
| 30 | des_cblock *key ); | ||
| 31 | This function takes a DES key (8 bytes) and sets the parity to odd. | ||
| 32 | |||
| 33 | int des_is_weak_key( | ||
| 34 | des_cblock *key ); | ||
| 35 | This function returns a non-zero value if the DES key passed is a | ||
| 36 | weak, DES key. If it is a weak key, don't use it, try a different | ||
| 37 | one. If you are using 'random' keys, the chances of hitting a weak | ||
| 38 | key are 1/2^52 so it is probably not worth checking for them. | ||
| 39 | |||
| 40 | int des_set_key( | ||
| 41 | des_cblock *key, | ||
| 42 | des_key_schedule schedule); | ||
| 43 | Des_set_key converts an 8 byte DES key into a des_key_schedule. | ||
| 44 | A des_key_schedule is an expanded form of the key which is used to | ||
| 45 | perform actual encryption. It can be regenerated from the DES key | ||
| 46 | so it only needs to be kept when encryption or decryption is about | ||
| 47 | to occur. Don't save or pass around des_key_schedule's since they | ||
| 48 | are CPU architecture dependent, DES keys are not. If des_check_key | ||
| 49 | is non zero, zero is returned if the key has the wrong parity or | ||
| 50 | the key is a weak key, else 1 is returned. | ||
| 51 | |||
| 52 | int des_key_sched( | ||
| 53 | des_cblock *key, | ||
| 54 | des_key_schedule schedule); | ||
| 55 | An alternative name for des_set_key(). | ||
| 56 | |||
| 57 | int des_rw_mode; /* defaults to DES_PCBC_MODE */ | ||
| 58 | This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default). | ||
| 59 | This specifies the function to use in the enc_read() and enc_write() | ||
| 60 | functions. | ||
| 61 | |||
| 62 | void des_encrypt( | ||
| 63 | unsigned long *data, | ||
| 64 | des_key_schedule ks, | ||
| 65 | int enc); | ||
| 66 | This is the DES encryption function that gets called by just about | ||
| 67 | every other DES routine in the library. You should not use this | ||
| 68 | function except to implement 'modes' of DES. I say this because the | ||
| 69 | functions that call this routine do the conversion from 'char *' to | ||
| 70 | long, and this needs to be done to make sure 'non-aligned' memory | ||
| 71 | access do not occur. The characters are loaded 'little endian', | ||
| 72 | have a look at my source code for more details on how I use this | ||
| 73 | function. | ||
| 74 | Data is a pointer to 2 unsigned long's and ks is the | ||
| 75 | des_key_schedule to use. enc, is non zero specifies encryption, | ||
| 76 | zero if decryption. | ||
| 77 | |||
| 78 | void des_encrypt2( | ||
| 79 | unsigned long *data, | ||
| 80 | des_key_schedule ks, | ||
| 81 | int enc); | ||
| 82 | This functions is the same as des_encrypt() except that the DES | ||
| 83 | initial permutation (IP) and final permutation (FP) have been left | ||
| 84 | out. As for des_encrypt(), you should not use this function. | ||
| 85 | It is used by the routines in my library that implement triple DES. | ||
| 86 | IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same | ||
| 87 | as des_encrypt() des_encrypt() des_encrypt() except faster :-). | ||
| 88 | |||
| 89 | void des_ecb_encrypt( | ||
| 90 | des_cblock *input, | ||
| 91 | des_cblock *output, | ||
| 92 | des_key_schedule ks, | ||
| 93 | int enc); | ||
| 94 | This is the basic Electronic Code Book form of DES, the most basic | ||
| 95 | form. Input is encrypted into output using the key represented by | ||
| 96 | ks. If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise | ||
| 97 | decryption occurs. Input is 8 bytes long and output is 8 bytes. | ||
| 98 | (the des_cblock structure is 8 chars). | ||
| 99 | |||
| 100 | void des_ecb3_encrypt( | ||
| 101 | des_cblock *input, | ||
| 102 | des_cblock *output, | ||
| 103 | des_key_schedule ks1, | ||
| 104 | des_key_schedule ks2, | ||
| 105 | des_key_schedule ks3, | ||
| 106 | int enc); | ||
| 107 | This is the 3 key EDE mode of ECB DES. What this means is that | ||
| 108 | the 8 bytes of input is encrypted with ks1, decrypted with ks2 and | ||
| 109 | then encrypted again with ks3, before being put into output; | ||
| 110 | C=E(ks3,D(ks2,E(ks1,M))). There is a macro, des_ecb2_encrypt() | ||
| 111 | that only takes 2 des_key_schedules that implements, | ||
| 112 | C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1. | ||
| 113 | |||
| 114 | void des_cbc_encrypt( | ||
| 115 | des_cblock *input, | ||
| 116 | des_cblock *output, | ||
| 117 | long length, | ||
| 118 | des_key_schedule ks, | ||
| 119 | des_cblock *ivec, | ||
| 120 | int enc); | ||
| 121 | This routine implements DES in Cipher Block Chaining mode. | ||
| 122 | Input, which should be a multiple of 8 bytes is encrypted | ||
| 123 | (or decrypted) to output which will also be a multiple of 8 bytes. | ||
| 124 | The number of bytes is in length (and from what I've said above, | ||
| 125 | should be a multiple of 8). If length is not a multiple of 8, I'm | ||
| 126 | not being held responsible :-). ivec is the initialisation vector. | ||
| 127 | This function does not modify this variable. To correctly implement | ||
| 128 | cbc mode, you need to do one of 2 things; copy the last 8 bytes of | ||
| 129 | cipher text for use as the next ivec in your application, | ||
| 130 | or use des_ncbc_encrypt(). | ||
| 131 | Only this routine has this problem with updating the ivec, all | ||
| 132 | other routines that are implementing cbc mode update ivec. | ||
| 133 | |||
| 134 | void des_ncbc_encrypt( | ||
| 135 | des_cblock *input, | ||
| 136 | des_cblock *output, | ||
| 137 | long length, | ||
| 138 | des_key_schedule sk, | ||
| 139 | des_cblock *ivec, | ||
| 140 | int enc); | ||
| 141 | For historical reasons, des_cbc_encrypt() did not update the | ||
| 142 | ivec with the value requires so that subsequent calls to | ||
| 143 | des_cbc_encrypt() would 'chain'. This was needed so that the same | ||
| 144 | 'length' values would not need to be used when decrypting. | ||
| 145 | des_ncbc_encrypt() does the right thing. It is the same as | ||
| 146 | des_cbc_encrypt accept that ivec is updates with the correct value | ||
| 147 | to pass in subsequent calls to des_ncbc_encrypt(). I advise using | ||
| 148 | des_ncbc_encrypt() instead of des_cbc_encrypt(); | ||
| 149 | |||
| 150 | void des_xcbc_encrypt( | ||
| 151 | des_cblock *input, | ||
| 152 | des_cblock *output, | ||
| 153 | long length, | ||
| 154 | des_key_schedule sk, | ||
| 155 | des_cblock *ivec, | ||
| 156 | des_cblock *inw, | ||
| 157 | des_cblock *outw, | ||
| 158 | int enc); | ||
| 159 | This is RSA's DESX mode of DES. It uses inw and outw to | ||
| 160 | 'whiten' the encryption. inw and outw are secret (unlike the iv) | ||
| 161 | and are as such, part of the key. So the key is sort of 24 bytes. | ||
| 162 | This is much better than cbc des. | ||
| 163 | |||
| 164 | void des_3cbc_encrypt( | ||
| 165 | des_cblock *input, | ||
| 166 | des_cblock *output, | ||
| 167 | long length, | ||
| 168 | des_key_schedule sk1, | ||
| 169 | des_key_schedule sk2, | ||
| 170 | des_cblock *ivec1, | ||
| 171 | des_cblock *ivec2, | ||
| 172 | int enc); | ||
| 173 | This function is flawed, do not use it. I have left it in the | ||
| 174 | library because it is used in my des(1) program and will function | ||
| 175 | correctly when used by des(1). If I removed the function, people | ||
| 176 | could end up unable to decrypt files. | ||
| 177 | This routine implements outer triple cbc encryption using 2 ks and | ||
| 178 | 2 ivec's. Use des_ede2_cbc_encrypt() instead. | ||
| 179 | |||
| 180 | void des_ede3_cbc_encrypt( | ||
| 181 | des_cblock *input, | ||
| 182 | des_cblock *output, | ||
| 183 | long length, | ||
| 184 | des_key_schedule ks1, | ||
| 185 | des_key_schedule ks2, | ||
| 186 | des_key_schedule ks3, | ||
| 187 | des_cblock *ivec, | ||
| 188 | int enc); | ||
| 189 | This function implements outer triple CBC DES encryption with 3 | ||
| 190 | keys. What this means is that each 'DES' operation | ||
| 191 | inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))). | ||
| 192 | Again, this is cbc mode so an ivec is requires. | ||
| 193 | This mode is used by SSL. | ||
| 194 | There is also a des_ede2_cbc_encrypt() that only uses 2 | ||
| 195 | des_key_schedule's, the first being reused for the final | ||
| 196 | encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of triple DES | ||
| 197 | is used by the RSAref library. | ||
| 198 | |||
| 199 | void des_pcbc_encrypt( | ||
| 200 | des_cblock *input, | ||
| 201 | des_cblock *output, | ||
| 202 | long length, | ||
| 203 | des_key_schedule ks, | ||
| 204 | des_cblock *ivec, | ||
| 205 | int enc); | ||
| 206 | This is Propagating Cipher Block Chaining mode of DES. It is used | ||
| 207 | by Kerberos v4. It's parameters are the same as des_ncbc_encrypt(). | ||
| 208 | |||
| 209 | void des_cfb_encrypt( | ||
| 210 | unsigned char *in, | ||
| 211 | unsigned char *out, | ||
| 212 | int numbits, | ||
| 213 | long length, | ||
| 214 | des_key_schedule ks, | ||
| 215 | des_cblock *ivec, | ||
| 216 | int enc); | ||
| 217 | Cipher Feedback Back mode of DES. This implementation 'feeds back' | ||
| 218 | in numbit blocks. The input (and output) is in multiples of numbits | ||
| 219 | bits. numbits should to be a multiple of 8 bits. Length is the | ||
| 220 | number of bytes input. If numbits is not a multiple of 8 bits, | ||
| 221 | the extra bits in the bytes will be considered padding. So if | ||
| 222 | numbits is 12, for each 2 input bytes, the 4 high bits of the | ||
| 223 | second byte will be ignored. So to encode 72 bits when using | ||
| 224 | a numbits of 12 take 12 bytes. To encode 72 bits when using | ||
| 225 | numbits of 9 will take 16 bytes. To encode 80 bits when using | ||
| 226 | numbits of 16 will take 10 bytes. etc, etc. This padding will | ||
| 227 | apply to both input and output. | ||
| 228 | |||
| 229 | |||
| 230 | void des_cfb64_encrypt( | ||
| 231 | unsigned char *in, | ||
| 232 | unsigned char *out, | ||
| 233 | long length, | ||
| 234 | des_key_schedule ks, | ||
| 235 | des_cblock *ivec, | ||
| 236 | int *num, | ||
| 237 | int enc); | ||
| 238 | This is one of the more useful functions in this DES library, it | ||
| 239 | implements CFB mode of DES with 64bit feedback. Why is this | ||
| 240 | useful you ask? Because this routine will allow you to encrypt an | ||
| 241 | arbitrary number of bytes, no 8 byte padding. Each call to this | ||
| 242 | routine will encrypt the input bytes to output and then update ivec | ||
| 243 | and num. num contains 'how far' we are though ivec. If this does | ||
| 244 | not make much sense, read more about cfb mode of DES :-). | ||
| 245 | |||
| 246 | void des_ede3_cfb64_encrypt( | ||
| 247 | unsigned char *in, | ||
| 248 | unsigned char *out, | ||
| 249 | long length, | ||
| 250 | des_key_schedule ks1, | ||
| 251 | des_key_schedule ks2, | ||
| 252 | des_key_schedule ks3, | ||
| 253 | des_cblock *ivec, | ||
| 254 | int *num, | ||
| 255 | int enc); | ||
| 256 | Same as des_cfb64_encrypt() accept that the DES operation is | ||
| 257 | triple DES. As usual, there is a macro for | ||
| 258 | des_ede2_cfb64_encrypt() which reuses ks1. | ||
| 259 | |||
| 260 | void des_ofb_encrypt( | ||
| 261 | unsigned char *in, | ||
| 262 | unsigned char *out, | ||
| 263 | int numbits, | ||
| 264 | long length, | ||
| 265 | des_key_schedule ks, | ||
| 266 | des_cblock *ivec); | ||
| 267 | This is a implementation of Output Feed Back mode of DES. It is | ||
| 268 | the same as des_cfb_encrypt() in that numbits is the size of the | ||
| 269 | units dealt with during input and output (in bits). | ||
| 270 | |||
| 271 | void des_ofb64_encrypt( | ||
| 272 | unsigned char *in, | ||
| 273 | unsigned char *out, | ||
| 274 | long length, | ||
| 275 | des_key_schedule ks, | ||
| 276 | des_cblock *ivec, | ||
| 277 | int *num); | ||
| 278 | The same as des_cfb64_encrypt() except that it is Output Feed Back | ||
| 279 | mode. | ||
| 280 | |||
| 281 | void des_ede3_ofb64_encrypt( | ||
| 282 | unsigned char *in, | ||
| 283 | unsigned char *out, | ||
| 284 | long length, | ||
| 285 | des_key_schedule ks1, | ||
| 286 | des_key_schedule ks2, | ||
| 287 | des_key_schedule ks3, | ||
| 288 | des_cblock *ivec, | ||
| 289 | int *num); | ||
| 290 | Same as des_ofb64_encrypt() accept that the DES operation is | ||
| 291 | triple DES. As usual, there is a macro for | ||
| 292 | des_ede2_ofb64_encrypt() which reuses ks1. | ||
| 293 | |||
| 294 | int des_read_pw_string( | ||
| 295 | char *buf, | ||
| 296 | int length, | ||
| 297 | char *prompt, | ||
| 298 | int verify); | ||
| 299 | This routine is used to get a password from the terminal with echo | ||
| 300 | turned off. Buf is where the string will end up and length is the | ||
| 301 | size of buf. Prompt is a string presented to the 'user' and if | ||
| 302 | verify is set, the key is asked for twice and unless the 2 copies | ||
| 303 | match, an error is returned. A return code of -1 indicates a | ||
| 304 | system error, 1 failure due to use interaction, and 0 is success. | ||
| 305 | |||
| 306 | unsigned long des_cbc_cksum( | ||
| 307 | des_cblock *input, | ||
| 308 | des_cblock *output, | ||
| 309 | long length, | ||
| 310 | des_key_schedule ks, | ||
| 311 | des_cblock *ivec); | ||
| 312 | This function produces an 8 byte checksum from input that it puts in | ||
| 313 | output and returns the last 4 bytes as a long. The checksum is | ||
| 314 | generated via cbc mode of DES in which only the last 8 byes are | ||
| 315 | kept. I would recommend not using this function but instead using | ||
| 316 | the EVP_Digest routines, or at least using MD5 or SHA. This | ||
| 317 | function is used by Kerberos v4 so that is why it stays in the | ||
| 318 | library. | ||
| 319 | |||
| 320 | char *des_fcrypt( | ||
| 321 | const char *buf, | ||
| 322 | const char *salt | ||
| 323 | char *ret); | ||
| 324 | This is my fast version of the unix crypt(3) function. This version | ||
| 325 | takes only a small amount of space relative to other fast | ||
| 326 | crypt() implementations. This is different to the normal crypt | ||
| 327 | in that the third parameter is the buffer that the return value | ||
| 328 | is written into. It needs to be at least 14 bytes long. This | ||
| 329 | function is thread safe, unlike the normal crypt. | ||
| 330 | |||
| 331 | char *crypt( | ||
| 332 | const char *buf, | ||
| 333 | const char *salt); | ||
| 334 | This function calls des_fcrypt() with a static array passed as the | ||
| 335 | third parameter. This emulates the normal non-thread safe semantics | ||
| 336 | of crypt(3). | ||
| 337 | |||
| 338 | void des_string_to_key( | ||
| 339 | char *str, | ||
| 340 | des_cblock *key); | ||
| 341 | This function takes str and converts it into a DES key. I would | ||
| 342 | recommend using MD5 instead and use the first 8 bytes of output. | ||
| 343 | When I wrote the first version of these routines back in 1990, MD5 | ||
| 344 | did not exist but I feel these routines are still sound. This | ||
| 345 | routines is compatible with the one in MIT's libdes. | ||
| 346 | |||
| 347 | void des_string_to_2keys( | ||
| 348 | char *str, | ||
| 349 | des_cblock *key1, | ||
| 350 | des_cblock *key2); | ||
| 351 | This function takes str and converts it into 2 DES keys. | ||
| 352 | I would recommend using MD5 and using the 16 bytes as the 2 keys. | ||
| 353 | I have nothing against these 2 'string_to_key' routines, it's just | ||
| 354 | that if you say that your encryption key is generated by using the | ||
| 355 | 16 bytes of an MD5 hash, every-one knows how you generated your | ||
| 356 | keys. | ||
| 357 | |||
| 358 | int des_read_password( | ||
| 359 | des_cblock *key, | ||
| 360 | char *prompt, | ||
| 361 | int verify); | ||
| 362 | This routine combines des_read_pw_string() with des_string_to_key(). | ||
| 363 | |||
| 364 | int des_read_2passwords( | ||
| 365 | des_cblock *key1, | ||
| 366 | des_cblock *key2, | ||
| 367 | char *prompt, | ||
| 368 | int verify); | ||
| 369 | This routine combines des_read_pw_string() with des_string_to_2key(). | ||
| 370 | |||
| 371 | void des_random_seed( | ||
| 372 | des_cblock key); | ||
| 373 | This routine sets a starting point for des_random_key(). | ||
| 374 | |||
| 375 | void des_random_key( | ||
| 376 | des_cblock ret); | ||
| 377 | This function return a random key. Make sure to 'seed' the random | ||
| 378 | number generator (with des_random_seed()) before using this function. | ||
| 379 | I personally now use a MD5 based random number system. | ||
| 380 | |||
| 381 | int des_enc_read( | ||
| 382 | int fd, | ||
| 383 | char *buf, | ||
| 384 | int len, | ||
| 385 | des_key_schedule ks, | ||
| 386 | des_cblock *iv); | ||
| 387 | This function will write to a file descriptor the encrypted data | ||
| 388 | from buf. This data will be preceded by a 4 byte 'byte count' and | ||
| 389 | will be padded out to 8 bytes. The encryption is either CBC of | ||
| 390 | PCBC depending on the value of des_rw_mode. If it is DES_PCBC_MODE, | ||
| 391 | pcbc is used, if DES_CBC_MODE, cbc is used. The default is to use | ||
| 392 | DES_PCBC_MODE. | ||
| 393 | |||
| 394 | int des_enc_write( | ||
| 395 | int fd, | ||
| 396 | char *buf, | ||
| 397 | int len, | ||
| 398 | des_key_schedule ks, | ||
| 399 | des_cblock *iv); | ||
| 400 | This routines read stuff written by des_enc_read() and decrypts it. | ||
| 401 | I have used these routines quite a lot but I don't believe they are | ||
| 402 | suitable for non-blocking io. If you are after a full | ||
| 403 | authentication/encryption over networks, have a look at SSL instead. | ||
| 404 | |||
| 405 | unsigned long des_quad_cksum( | ||
| 406 | des_cblock *input, | ||
| 407 | des_cblock *output, | ||
| 408 | long length, | ||
| 409 | int out_count, | ||
| 410 | des_cblock *seed); | ||
| 411 | This is a function from Kerberos v4 that is not anything to do with | ||
| 412 | DES but was needed. It is a cksum that is quicker to generate than | ||
| 413 | des_cbc_cksum(); I personally would use MD5 routines now. | ||
| 414 | ===== | ||
| 415 | Modes of DES | ||
| 416 | Quite a bit of the following information has been taken from | ||
| 417 | AS 2805.5.2 | ||
| 418 | Australian Standard | ||
| 419 | Electronic funds transfer - Requirements for interfaces, | ||
| 420 | Part 5.2: Modes of operation for an n-bit block cipher algorithm | ||
| 421 | Appendix A | ||
| 422 | |||
| 423 | There are several different modes in which DES can be used, they are | ||
| 424 | as follows. | ||
| 425 | |||
| 426 | Electronic Codebook Mode (ECB) (des_ecb_encrypt()) | ||
| 427 | - 64 bits are enciphered at a time. | ||
| 428 | - The order of the blocks can be rearranged without detection. | ||
| 429 | - The same plaintext block always produces the same ciphertext block | ||
| 430 | (for the same key) making it vulnerable to a 'dictionary attack'. | ||
| 431 | - An error will only affect one ciphertext block. | ||
| 432 | |||
| 433 | Cipher Block Chaining Mode (CBC) (des_cbc_encrypt()) | ||
| 434 | - a multiple of 64 bits are enciphered at a time. | ||
| 435 | - The CBC mode produces the same ciphertext whenever the same | ||
| 436 | plaintext is encrypted using the same key and starting variable. | ||
| 437 | - The chaining operation makes the ciphertext blocks dependent on the | ||
| 438 | current and all preceding plaintext blocks and therefore blocks can not | ||
| 439 | be rearranged. | ||
| 440 | - The use of different starting variables prevents the same plaintext | ||
| 441 | enciphering to the same ciphertext. | ||
| 442 | - An error will affect the current and the following ciphertext blocks. | ||
| 443 | |||
| 444 | Cipher Feedback Mode (CFB) (des_cfb_encrypt()) | ||
| 445 | - a number of bits (j) <= 64 are enciphered at a time. | ||
| 446 | - The CFB mode produces the same ciphertext whenever the same | ||
| 447 | plaintext is encrypted using the same key and starting variable. | ||
| 448 | - The chaining operation makes the ciphertext variables dependent on the | ||
| 449 | current and all preceding variables and therefore j-bit variables are | ||
| 450 | chained together and can not be rearranged. | ||
| 451 | - The use of different starting variables prevents the same plaintext | ||
| 452 | enciphering to the same ciphertext. | ||
| 453 | - The strength of the CFB mode depends on the size of k (maximal if | ||
| 454 | j == k). In my implementation this is always the case. | ||
| 455 | - Selection of a small value for j will require more cycles through | ||
| 456 | the encipherment algorithm per unit of plaintext and thus cause | ||
| 457 | greater processing overheads. | ||
| 458 | - Only multiples of j bits can be enciphered. | ||
| 459 | - An error will affect the current and the following ciphertext variables. | ||
| 460 | |||
| 461 | Output Feedback Mode (OFB) (des_ofb_encrypt()) | ||
| 462 | - a number of bits (j) <= 64 are enciphered at a time. | ||
| 463 | - The OFB mode produces the same ciphertext whenever the same | ||
| 464 | plaintext enciphered using the same key and starting variable. More | ||
| 465 | over, in the OFB mode the same key stream is produced when the same | ||
| 466 | key and start variable are used. Consequently, for security reasons | ||
| 467 | a specific start variable should be used only once for a given key. | ||
| 468 | - The absence of chaining makes the OFB more vulnerable to specific attacks. | ||
| 469 | - The use of different start variables values prevents the same | ||
| 470 | plaintext enciphering to the same ciphertext, by producing different | ||
| 471 | key streams. | ||
| 472 | - Selection of a small value for j will require more cycles through | ||
| 473 | the encipherment algorithm per unit of plaintext and thus cause | ||
| 474 | greater processing overheads. | ||
| 475 | - Only multiples of j bits can be enciphered. | ||
| 476 | - OFB mode of operation does not extend ciphertext errors in the | ||
| 477 | resultant plaintext output. Every bit error in the ciphertext causes | ||
| 478 | only one bit to be in error in the deciphered plaintext. | ||
| 479 | - OFB mode is not self-synchronising. If the two operation of | ||
| 480 | encipherment and decipherment get out of synchronism, the system needs | ||
| 481 | to be re-initialised. | ||
| 482 | - Each re-initialisation should use a value of the start variable | ||
| 483 | different from the start variable values used before with the same | ||
| 484 | key. The reason for this is that an identical bit stream would be | ||
| 485 | produced each time from the same parameters. This would be | ||
| 486 | susceptible to a ' known plaintext' attack. | ||
| 487 | |||
| 488 | Triple ECB Mode (des_ecb3_encrypt()) | ||
| 489 | - Encrypt with key1, decrypt with key2 and encrypt with key3 again. | ||
| 490 | - As for ECB encryption but increases the key length to 168 bits. | ||
| 491 | There are theoretic attacks that can be used that make the effective | ||
| 492 | key length 112 bits, but this attack also requires 2^56 blocks of | ||
| 493 | memory, not very likely, even for the NSA. | ||
| 494 | - If both keys are the same it is equivalent to encrypting once with | ||
| 495 | just one key. | ||
| 496 | - If the first and last key are the same, the key length is 112 bits. | ||
| 497 | There are attacks that could reduce the key space to 55 bit's but it | ||
| 498 | requires 2^56 blocks of memory. | ||
| 499 | - If all 3 keys are the same, this is effectively the same as normal | ||
| 500 | ecb mode. | ||
| 501 | |||
| 502 | Triple CBC Mode (des_ede3_cbc_encrypt()) | ||
| 503 | - Encrypt with key1, decrypt with key2 and then encrypt with key3. | ||
| 504 | - As for CBC encryption but increases the key length to 168 bits with | ||
| 505 | the same restrictions as for triple ecb mode. | ||
diff --git a/src/lib/libssl/src/doc/digest.doc b/src/lib/libssl/src/doc/digest.doc deleted file mode 100644 index d2fb987591..0000000000 --- a/src/lib/libssl/src/doc/digest.doc +++ /dev/null | |||
| @@ -1,94 +0,0 @@ | |||
| 1 | |||
| 2 | The Message Digest subroutines. | ||
| 3 | |||
| 4 | These routines require "evp.h" to be included. | ||
| 5 | |||
| 6 | These functions are a higher level interface to the various message digest | ||
| 7 | routines found in this library. As such, they allow the same code to be | ||
| 8 | used to digest via different algorithms with only a change in an initial | ||
| 9 | parameter. They are basically just a front-end to the MD2, MD5, SHA | ||
| 10 | and SHA1 | ||
| 11 | routines. | ||
| 12 | |||
| 13 | These routines all take a pointer to the following structure to specify | ||
| 14 | which message digest algorithm to use. | ||
| 15 | typedef struct evp_md_st | ||
| 16 | { | ||
| 17 | int type; | ||
| 18 | int pkey_type; | ||
| 19 | int md_size; | ||
| 20 | void (*init)(); | ||
| 21 | void (*update)(); | ||
| 22 | void (*final)(); | ||
| 23 | |||
| 24 | int required_pkey_type; /*EVP_PKEY_xxx */ | ||
| 25 | int (*sign)(); | ||
| 26 | int (*verify)(); | ||
| 27 | } EVP_MD; | ||
| 28 | |||
| 29 | If additional message digest algorithms are to be supported, a structure of | ||
| 30 | this type needs to be declared and populated and then the Digest routines | ||
| 31 | can be used with that algorithm. The type field is the object NID of the | ||
| 32 | digest type (read the section on Objects for an explanation). The pkey_type | ||
| 33 | is the Object type to use when the a message digest is generated by there | ||
| 34 | routines and then is to be signed with the pkey algorithm. Md_size is | ||
| 35 | the size of the message digest returned. Init, update | ||
| 36 | and final are the relevant functions to perform the message digest function | ||
| 37 | by parts. One reason for specifying the message digest to use via this | ||
| 38 | mechanism is that if you only use md5, only the md5 routines will | ||
| 39 | be included in you linked program. If you passed an integer | ||
| 40 | that specified which message digest to use, the routine that mapped that | ||
| 41 | integer to a set of message digest functions would cause all the message | ||
| 42 | digests functions to be link into the code. This setup also allows new | ||
| 43 | message digest functions to be added by the application. | ||
| 44 | |||
| 45 | The six message digests defined in this library are | ||
| 46 | |||
| 47 | EVP_MD *EVP_md2(void); /* RSA sign/verify */ | ||
| 48 | EVP_MD *EVP_md5(void); /* RSA sign/verify */ | ||
| 49 | EVP_MD *EVP_sha(void); /* RSA sign/verify */ | ||
| 50 | EVP_MD *EVP_sha1(void); /* RSA sign/verify */ | ||
| 51 | EVP_MD *EVP_dss(void); /* DSA sign/verify */ | ||
| 52 | EVP_MD *EVP_dss1(void); /* DSA sign/verify */ | ||
| 53 | |||
| 54 | All the message digest routines take a EVP_MD_CTX pointer as an argument. | ||
| 55 | The state of the message digest is kept in this structure. | ||
| 56 | |||
| 57 | typedef struct pem_md_ctx_st | ||
| 58 | { | ||
| 59 | EVP_MD *digest; | ||
| 60 | union { | ||
| 61 | unsigned char base[4]; /* this is used in my library as a | ||
| 62 | * 'pointer' to all union elements | ||
| 63 | * structures. */ | ||
| 64 | MD2_CTX md2; | ||
| 65 | MD5_CTX md5; | ||
| 66 | SHA_CTX sha; | ||
| 67 | } md; | ||
| 68 | } EVP_MD_CTX; | ||
| 69 | |||
| 70 | The Digest functions are as follows. | ||
| 71 | |||
| 72 | void EVP_DigestInit( | ||
| 73 | EVP_MD_CTX *ctx, | ||
| 74 | EVP_MD *type); | ||
| 75 | This function is used to initialise the EVP_MD_CTX. The message | ||
| 76 | digest that will associated with 'ctx' is specified by 'type'. | ||
| 77 | |||
| 78 | void EVP_DigestUpdate( | ||
| 79 | EVP_MD_CTX *ctx, | ||
| 80 | unsigned char *data, | ||
| 81 | unsigned int cnt); | ||
| 82 | This function is used to pass more data to the message digest | ||
| 83 | function. 'cnt' bytes are digested from 'data'. | ||
| 84 | |||
| 85 | void EVP_DigestFinal( | ||
| 86 | EVP_MD_CTX *ctx, | ||
| 87 | unsigned char *md, | ||
| 88 | unsigned int *len); | ||
| 89 | This function finishes the digestion and puts the message digest | ||
| 90 | into 'md'. The length of the message digest is put into len; | ||
| 91 | EVP_MAX_MD_SIZE is the size of the largest message digest that | ||
| 92 | can be returned from this function. Len can be NULL if the | ||
| 93 | size of the digest is not required. | ||
| 94 | |||
diff --git a/src/lib/libssl/src/doc/encode.doc b/src/lib/libssl/src/doc/encode.doc deleted file mode 100644 index af17549289..0000000000 --- a/src/lib/libssl/src/doc/encode.doc +++ /dev/null | |||
| @@ -1,15 +0,0 @@ | |||
| 1 | |||
| 2 | void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); | ||
| 3 | void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out, | ||
| 4 | int *outl,unsigned char *in,int inl); | ||
| 5 | void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl); | ||
| 6 | int EVP_EncodeBlock(unsigned char *t, unsigned char *f, int n); | ||
| 7 | |||
| 8 | void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); | ||
| 9 | int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl, | ||
| 10 | unsigned char *in, int inl); | ||
| 11 | int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned | ||
| 12 | char *out, int *outl); | ||
| 13 | int EVP_DecodeBlock(unsigned char *t, unsigned | ||
| 14 | char *f, int n); | ||
| 15 | |||
diff --git a/src/lib/libssl/src/doc/envelope.doc b/src/lib/libssl/src/doc/envelope.doc deleted file mode 100644 index 483e4fca6b..0000000000 --- a/src/lib/libssl/src/doc/envelope.doc +++ /dev/null | |||
| @@ -1,67 +0,0 @@ | |||
| 1 | The following routines are use to create 'digital' envelopes. | ||
| 2 | By this I mean that they perform various 'higher' level cryptographic | ||
| 3 | functions. Have a read of 'cipher.doc' and 'digest.doc' since those | ||
| 4 | routines are used by these functions. | ||
| 5 | cipher.doc contains documentation about the cipher part of the | ||
| 6 | envelope library and digest.doc contatins the description of the | ||
| 7 | message digests supported. | ||
| 8 | |||
| 9 | To 'sign' a document involves generating a message digest and then encrypting | ||
| 10 | the digest with an private key. | ||
| 11 | |||
| 12 | #define EVP_SignInit(a,b) EVP_DigestInit(a,b) | ||
| 13 | #define EVP_SignUpdate(a,b,c) EVP_DigestUpdate(a,b,c) | ||
| 14 | Due to the fact this operation is basically just an extended message | ||
| 15 | digest, the first 2 functions are macro calls to Digest generating | ||
| 16 | functions. | ||
| 17 | |||
| 18 | int EVP_SignFinal( | ||
| 19 | EVP_MD_CTX *ctx, | ||
| 20 | unsigned char *md, | ||
| 21 | unsigned int *s, | ||
| 22 | EVP_PKEY *pkey); | ||
| 23 | This finalisation function finishes the generation of the message | ||
| 24 | digest and then encrypts the digest (with the correct message digest | ||
| 25 | object identifier) with the EVP_PKEY private key. 'ctx' is the message digest | ||
| 26 | context. 'md' will end up containing the encrypted message digest. This | ||
| 27 | array needs to be EVP_PKEY_size(pkey) bytes long. 's' will actually | ||
| 28 | contain the exact length. 'pkey' of course is the private key. It is | ||
| 29 | one of EVP_PKEY_RSA or EVP_PKEY_DSA type. | ||
| 30 | If there is an error, 0 is returned, otherwise 1. | ||
| 31 | |||
| 32 | Verify is used to check an signed message digest. | ||
| 33 | |||
| 34 | #define EVP_VerifyInit(a,b) EVP_DigestInit(a,b) | ||
| 35 | #define EVP_VerifyUpdate(a,b,c) EVP_DigestUpdate(a,b,c) | ||
| 36 | Since the first step is to generate a message digest, the first 2 functions | ||
| 37 | are macros. | ||
| 38 | |||
| 39 | int EVP_VerifyFinal( | ||
| 40 | EVP_MD_CTX *ctx, | ||
| 41 | unsigned char *md, | ||
| 42 | unsigned int s, | ||
| 43 | EVP_PKEY *pkey); | ||
| 44 | This function finishes the generation of the message digest and then | ||
| 45 | compares it with the supplied encrypted message digest. 'md' contains the | ||
| 46 | 's' bytes of encrypted message digest. 'pkey' is used to public key decrypt | ||
| 47 | the digest. It is then compared with the message digest just generated. | ||
| 48 | If they match, 1 is returned else 0. | ||
| 49 | |||
| 50 | int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek, | ||
| 51 | int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk); | ||
| 52 | Must have at least one public key, error is 0. I should also mention that | ||
| 53 | the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size. | ||
| 54 | |||
| 55 | #define EVP_SealUpdate(a,b,c,d,e) EVP_EncryptUpdate(a,b,c,d,e) | ||
| 56 | void EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl); | ||
| 57 | |||
| 58 | |||
| 59 | int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek, | ||
| 60 | int ekl,unsigned char *iv,EVP_PKEY *priv); | ||
| 61 | 0 on failure | ||
| 62 | |||
| 63 | #define EVP_OpenUpdate(a,b,c,d,e) EVP_DecryptUpdate(a,b,c,d,e) | ||
| 64 | |||
| 65 | int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); | ||
| 66 | Decrypt final return code | ||
| 67 | |||
diff --git a/src/lib/libssl/src/doc/error.doc b/src/lib/libssl/src/doc/error.doc deleted file mode 100644 index a91654999a..0000000000 --- a/src/lib/libssl/src/doc/error.doc +++ /dev/null | |||
| @@ -1,115 +0,0 @@ | |||
| 1 | The error routines. | ||
| 2 | |||
| 3 | The 'error' system I've implemented is intended to server 2 purpose, to | ||
| 4 | record the reason why a command failed and to record where in the libraries | ||
| 5 | the failure occurred. It is more or less setup to record a 'trace' of which | ||
| 6 | library components were being traversed when the error occurred. | ||
| 7 | |||
| 8 | When an error is recorded, it is done so a as single unsigned long which is | ||
| 9 | composed of three parts. The top byte is the 'library' number, the middle | ||
| 10 | 12 bytes is the function code, and the bottom 12 bits is the 'reason' code. | ||
| 11 | |||
| 12 | Each 'library', or should a say, 'section' of the SSLeay library has a | ||
| 13 | different unique 'library' error number. Each function in the library has | ||
| 14 | a number that is unique for that library. Each 'library' also has a number | ||
| 15 | for each 'error reason' that is only unique for that 'library'. | ||
| 16 | |||
| 17 | Due to the way these error routines record a 'error trace', there is an | ||
| 18 | array per thread that is used to store the error codes. | ||
| 19 | The various functions in this library are used to access | ||
| 20 | and manipulate this array. | ||
| 21 | |||
| 22 | void ERR_put_error(int lib, int func,int reason); | ||
| 23 | This routine records an error in library 'lib', function 'func' | ||
| 24 | and reason 'reason'. As errors get 'put' into the buffer, they wrap | ||
| 25 | around and overwrite old errors if too many are written. It is assumed | ||
| 26 | that the last errors are the most important. | ||
| 27 | |||
| 28 | unsigned long ERR_get_error(void ); | ||
| 29 | This function returns the last error added to the error buffer. | ||
| 30 | In effect it is popping the value off the buffer so repeated calls will | ||
| 31 | continue to return values until there are no more errors to return in which | ||
| 32 | case 0 is returned. | ||
| 33 | |||
| 34 | unsigned long ERR_peek_error(void ); | ||
| 35 | This function returns the value of the last error added to the | ||
| 36 | error buffer but does not 'pop' it from the buffer. | ||
| 37 | |||
| 38 | void ERR_clear_error(void ); | ||
| 39 | This function clears the error buffer, discarding all unread | ||
| 40 | errors. | ||
| 41 | |||
| 42 | While the above described error system obviously produces lots of different | ||
| 43 | error number, a method for 'reporting' these errors in a human readable | ||
| 44 | form is required. To achieve this, each library has the option of | ||
| 45 | 'registering' error strings. | ||
| 46 | |||
| 47 | typedef struct ERR_string_data_st | ||
| 48 | { | ||
| 49 | unsigned long error; | ||
| 50 | char *string; | ||
| 51 | } ERR_STRING_DATA; | ||
| 52 | |||
| 53 | The 'ERR_STRING_DATA' contains an error code and the corresponding text | ||
| 54 | string. To add new function error strings for a library, the | ||
| 55 | ERR_STRING_DATA needs to be 'registered' with the library. | ||
| 56 | |||
| 57 | void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err); | ||
| 58 | This function 'registers' the array of ERR_STRING_DATA pointed to by | ||
| 59 | 'err' as error text strings for the error library 'lib'. | ||
| 60 | |||
| 61 | void ERR_free_strings(void); | ||
| 62 | This function free()s all the loaded error strings. | ||
| 63 | |||
| 64 | char *ERR_error_string(unsigned long error,char *buf); | ||
| 65 | This function returns a text string that is a human readable | ||
| 66 | version of the error represented by 'error'. Buff should be at least 120 | ||
| 67 | bytes long and if it is NULL, the return value is a pointer to a static | ||
| 68 | variable that will contain the error string, otherwise 'buf' is returned. | ||
| 69 | If there is not a text string registered for a particular error, a text | ||
| 70 | string containing the error number is returned instead. | ||
| 71 | |||
| 72 | void ERR_print_errors(BIO *bp); | ||
| 73 | void ERR_print_errors_fp(FILE *fp); | ||
| 74 | This function is a convenience routine that prints the error string | ||
| 75 | for each error until all errors have been accounted for. | ||
| 76 | |||
| 77 | char *ERR_lib_error_string(unsigned long e); | ||
| 78 | char *ERR_func_error_string(unsigned long e); | ||
| 79 | char *ERR_reason_error_string(unsigned long e); | ||
| 80 | The above three functions return the 3 different components strings for the | ||
| 81 | error 'e'. ERR_error_string() uses these functions. | ||
| 82 | |||
| 83 | void ERR_load_ERR_strings(void ); | ||
| 84 | This function 'registers' the error strings for the 'ERR' module. | ||
| 85 | |||
| 86 | void ERR_load_crypto_strings(void ); | ||
| 87 | This function 'register' the error strings for just about every | ||
| 88 | library in the SSLeay package except for the SSL routines. There is no | ||
| 89 | need to ever register any error text strings and you will probably save in | ||
| 90 | program size. If on the other hand you do 'register' all errors, it is | ||
| 91 | quite easy to determine why a particular routine failed. | ||
| 92 | |||
| 93 | As a final footnote as to why the error system is designed as it is. | ||
| 94 | 1) I did not want a single 'global' error code. | ||
| 95 | 2) I wanted to know which subroutine a failure occurred in. | ||
| 96 | 3) For Windows NT etc, it should be simple to replace the 'key' routines | ||
| 97 | with code to pass error codes back to the application. | ||
| 98 | 4) I wanted the option of meaningful error text strings. | ||
| 99 | |||
| 100 | Late breaking news - the changes to support threads. | ||
| 101 | |||
| 102 | Each 'thread' has an 'ERR_STATE' state associated with it. | ||
| 103 | ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling | ||
| 104 | thread/process. | ||
| 105 | |||
| 106 | ERR_remove_state(unsigned long pid); will 'free()' this state. If pid == 0 | ||
| 107 | the current 'thread/process' will have it's error state removed. | ||
| 108 | If you do not remove the error state of a thread, this could be considered a | ||
| 109 | form of memory leak, so just after 'reaping' a thread that has died, | ||
| 110 | call ERR_remove_state(pid). | ||
| 111 | |||
| 112 | Have a read of thread.doc for more details for what is required for | ||
| 113 | multi-threading support. All the other error routines will | ||
| 114 | work correctly when using threads. | ||
| 115 | |||
diff --git a/src/lib/libssl/src/doc/legal.doc b/src/lib/libssl/src/doc/legal.doc deleted file mode 100644 index b55ed5ce6a..0000000000 --- a/src/lib/libssl/src/doc/legal.doc +++ /dev/null | |||
| @@ -1,117 +0,0 @@ | |||
| 1 | From eay@mincom.com Thu Jun 27 00:25:45 1996 | ||
| 2 | Received: by orb.mincom.oz.au id AA15821 | ||
| 3 | (5.65c/IDA-1.4.4 for eay); Wed, 26 Jun 1996 14:25:45 +1000 | ||
| 4 | Date: Wed, 26 Jun 1996 14:25:45 +1000 (EST) | ||
| 5 | From: Eric Young <eay@mincom.oz.au> | ||
| 6 | X-Sender: eay@orb | ||
| 7 | To: Ken Toll <ktoll@ren.digitalage.com> | ||
| 8 | Cc: Eric Young <eay@mincom.oz.au>, ssl-talk@netscape.com | ||
| 9 | Subject: Re: Unidentified subject! | ||
| 10 | In-Reply-To: <9606261950.ZM28943@ren.digitalage.com> | ||
| 11 | Message-Id: <Pine.SOL.3.91.960626131156.28573K-100000@orb> | ||
| 12 | Mime-Version: 1.0 | ||
| 13 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 14 | Status: O | ||
| 15 | X-Status: | ||
| 16 | |||
| 17 | |||
| 18 | This is a little off topic but since SSLeay is a free implementation of | ||
| 19 | the SSLv2 protocol, I feel it is worth responding on the topic of if it | ||
| 20 | is actually legal for Americans to use free cryptographic software. | ||
| 21 | |||
| 22 | On Wed, 26 Jun 1996, Ken Toll wrote: | ||
| 23 | > Is the U.S the only country that SSLeay cannot be used commercially | ||
| 24 | > (because of RSAref) or is that going to be an issue with every country | ||
| 25 | > that a client/server application (non-web browser/server) is deployed | ||
| 26 | > and sold? | ||
| 27 | |||
| 28 | >From what I understand, the software patents that apply to algorithms | ||
| 29 | like RSA and DH only apply in the USA. The IDEA algorithm I believe is | ||
| 30 | patened in europe (USA?), but considing how little it is used by other SSL | ||
| 31 | implementations, it quite easily be left out of the SSLeay build | ||
| 32 | (this can be done with a compile flag). | ||
| 33 | |||
| 34 | Actually if the RSA patent did apply outside the USA, it could be rather | ||
| 35 | interesting since RSA is not alowed to let RSA toolkits outside of the USA | ||
| 36 | [1], and since these are the only forms that they will alow the algorithm | ||
| 37 | to be used in, it would mean that non-one outside of the USA could produce | ||
| 38 | public key software which would be a very strong statment for | ||
| 39 | international patent law to make :-). This logic is a little flawed but | ||
| 40 | it still points out some of the more interesting permutations of USA | ||
| 41 | patent law and ITAR restrictions. | ||
| 42 | |||
| 43 | Inside the USA there is also the unresolved issue of RC4/RC2 which were | ||
| 44 | made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2). I have | ||
| 45 | copies of the origional postings if people are interested. RSA I believe | ||
| 46 | claim that they were 'trade-secrets' and that some-one broke an NDA in | ||
| 47 | revealing them. Other claim they reverse engineered the algorithms from | ||
| 48 | compiled binaries. If the algorithms were reverse engineered, I belive | ||
| 49 | RSA had no legal leg to stand on. If an NDA was broken, I don't know. | ||
| 50 | Regardless, RSA, I belive, is willing to go to court over the issue so | ||
| 51 | licencing is probably the best idea, or at least talk to them. | ||
| 52 | If there are people who actually know more about this, pease let me know, I | ||
| 53 | don't want to vilify or spread miss-information if I can help it. | ||
| 54 | |||
| 55 | If you are not producing a web browser, it is easy to build SSLeay with | ||
| 56 | RC2/RC4 removed. Since RC4 is the defacto standard cipher in | ||
| 57 | all web software (and it is damn fast) it is more or less required for | ||
| 58 | www use. For non www use of SSL, especially for an application where | ||
| 59 | interoperability with other vendors is not critical just leave it out. | ||
| 60 | |||
| 61 | Removing IDEA, RC2 and RC4 would only leave DES and Triple DES but | ||
| 62 | they should be ok. Considing that Triple DES can encrypt at rates of | ||
| 63 | 410k/sec on a pentium 100, and 940k/sec on a P6/200, this is quite | ||
| 64 | reasonable performance. Single DES clocks in at 1160k/s and 2467k/s | ||
| 65 | respectivly is actually quite fast for those not so paranoid (56 bit key).[1] | ||
| 66 | |||
| 67 | > Is it possible to get a certificate for commercial use outside of the U.S.? | ||
| 68 | yes. | ||
| 69 | |||
| 70 | Thawte Consulting issues certificates (they are the people who sell the | ||
| 71 | Sioux httpd server and are based in South Africa) | ||
| 72 | Verisign will issue certificates for Sioux (sold from South Africa), so this | ||
| 73 | proves that they will issue certificate for OS use if they are | ||
| 74 | happy with the quality of the software. | ||
| 75 | |||
| 76 | (The above mentioned companies just the ones that I know for sure are issuing | ||
| 77 | certificates outside the USA). | ||
| 78 | |||
| 79 | There is always the point that if you are using SSL for an intra net, | ||
| 80 | SSLeay provides programs that can be used so you can issue your own | ||
| 81 | certificates. They need polishing but at least it is a good starting point. | ||
| 82 | |||
| 83 | I am not doing anything outside Australian law by implementing these | ||
| 84 | algorithms (to the best of my knowedge). It is another example of how | ||
| 85 | the world legal system does not cope with the internet very well. | ||
| 86 | |||
| 87 | I may start making shared libraries available (I have now got DLL's for | ||
| 88 | Windows). This will mean that distributions into the usa could be | ||
| 89 | shipped with a version with a reduced cipher set and the versions outside | ||
| 90 | could use the DLL/shared library with all the ciphers (and without RSAref). | ||
| 91 | |||
| 92 | This could be completly hidden from the application, so this would not | ||
| 93 | even require a re-linking. | ||
| 94 | |||
| 95 | This is the reverse of what people were talking about doing to get around | ||
| 96 | USA export regulations :-) | ||
| 97 | |||
| 98 | eric | ||
| 99 | |||
| 100 | [1]: The RSAref2.0 tookit is available on at least 3 ftp sites in Europe | ||
| 101 | and one in South Africa. | ||
| 102 | |||
| 103 | [2]: Since I always get questions when I post benchmark numbers :-), | ||
| 104 | DES performace figures are in 1000's of bytes per second in cbc | ||
| 105 | mode using an 8192 byte buffer. The pentium 100 was running Windows NT | ||
| 106 | 3.51 DLLs and the 686/200 was running NextStep. | ||
| 107 | I quote pentium 100 benchmarks because it is basically the | ||
| 108 | 'entry level' computer that most people buy for personal use. | ||
| 109 | Windows 95 is the OS shipping on those boxes, so I'll give | ||
| 110 | NT numbers (the same Win32 runtime environment). The 686 | ||
| 111 | numbers are present as an indication of where we will be in a | ||
| 112 | few years. | ||
| 113 | -- | ||
| 114 | Eric Young | BOOL is tri-state according to Bill Gates. | ||
| 115 | AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). | ||
| 116 | |||
| 117 | |||
diff --git a/src/lib/libssl/src/doc/lhash.doc b/src/lib/libssl/src/doc/lhash.doc deleted file mode 100644 index 5a2aeb4b38..0000000000 --- a/src/lib/libssl/src/doc/lhash.doc +++ /dev/null | |||
| @@ -1,151 +0,0 @@ | |||
| 1 | The LHASH library. | ||
| 2 | |||
| 3 | I wrote this library in 1991 and have since forgotten why I called it lhash. | ||
| 4 | It implements a hash table from an article I read at the | ||
| 5 | time from 'Communications of the ACM'. What makes this hash | ||
| 6 | table different is that as the table fills, the hash table is | ||
| 7 | increased (or decreased) in size via realloc(). | ||
| 8 | When a 'resize' is done, instead of all hashes being redistributed over | ||
| 9 | twice as many 'buckets', one bucket is split. So when an 'expand' is done, | ||
| 10 | there is only a minimal cost to redistribute some values. Subsequent | ||
| 11 | inserts will cause more single 'bucket' redistributions but there will | ||
| 12 | never be a sudden large cost due to redistributing all the 'buckets'. | ||
| 13 | |||
| 14 | The state for a particular hash table is kept in the LHASH structure. | ||
| 15 | The LHASH structure also records statistics about most aspects of accessing | ||
| 16 | the hash table. This is mostly a legacy of my writing this library for | ||
| 17 | the reasons of implementing what looked like a nice algorithm rather than | ||
| 18 | for a particular software product. | ||
| 19 | |||
| 20 | Internal stuff you probably don't want to know about. | ||
| 21 | The decision to increase or decrease the hash table size is made depending | ||
| 22 | on the 'load' of the hash table. The load is the number of items in the | ||
| 23 | hash table divided by the size of the hash table. The default values are | ||
| 24 | as follows. If (hash->up_load < load) => expand. | ||
| 25 | if (hash->down_load > load) => contract. The 'up_load' has a default value of | ||
| 26 | 1 and 'down_load' has a default value of 2. These numbers can be modified | ||
| 27 | by the application by just playing with the 'up_load' and 'down_load' | ||
| 28 | variables. The 'load' is kept in a form which is multiplied by 256. So | ||
| 29 | hash->up_load=8*256; will cause a load of 8 to be set. | ||
| 30 | |||
| 31 | If you are interested in performance the field to watch is | ||
| 32 | num_comp_calls. The hash library keeps track of the 'hash' value for | ||
| 33 | each item so when a lookup is done, the 'hashes' are compared, if | ||
| 34 | there is a match, then a full compare is done, and | ||
| 35 | hash->num_comp_calls is incremented. If num_comp_calls is not equal | ||
| 36 | to num_delete plus num_retrieve it means that your hash function is | ||
| 37 | generating hashes that are the same for different values. It is | ||
| 38 | probably worth changing your hash function if this is the case because | ||
| 39 | even if your hash table has 10 items in a 'bucked', it can be searched | ||
| 40 | with 10 'unsigned long' compares and 10 linked list traverses. This | ||
| 41 | will be much less expensive that 10 calls to you compare function. | ||
| 42 | |||
| 43 | LHASH *lh_new( | ||
| 44 | unsigned long (*hash)(), | ||
| 45 | int (*cmp)()); | ||
| 46 | This function is used to create a new LHASH structure. It is passed | ||
| 47 | function pointers that are used to store and retrieve values passed | ||
| 48 | into the hash table. The 'hash' | ||
| 49 | function is a hashing function that will return a hashed value of | ||
| 50 | it's passed structure. 'cmp' is passed 2 parameters, it returns 0 | ||
| 51 | is they are equal, otherwise, non zero. | ||
| 52 | If there are any problems (usually malloc failures), NULL is | ||
| 53 | returned, otherwise a new LHASH structure is returned. The | ||
| 54 | hash value is normally truncated to a power of 2, so make sure | ||
| 55 | that your hash function returns well mixed low order bits. | ||
| 56 | |||
| 57 | void lh_free( | ||
| 58 | LHASH *lh); | ||
| 59 | This function free()s a LHASH structure. If there is malloced | ||
| 60 | data in the hash table, it will not be freed. Consider using the | ||
| 61 | lh_doall function to deallocate any remaining entries in the hash | ||
| 62 | table. | ||
| 63 | |||
| 64 | char *lh_insert( | ||
| 65 | LHASH *lh, | ||
| 66 | char *data); | ||
| 67 | This function inserts the data pointed to by data into the lh hash | ||
| 68 | table. If there is already and entry in the hash table entry, the | ||
| 69 | value being replaced is returned. A NULL is returned if the new | ||
| 70 | entry does not clash with an entry already in the table (the normal | ||
| 71 | case) or on a malloc() failure (perhaps I should change this....). | ||
| 72 | The 'char *data' is exactly what is passed to the hash and | ||
| 73 | comparison functions specified in lh_new(). | ||
| 74 | |||
| 75 | char *lh_delete( | ||
| 76 | LHASH *lh, | ||
| 77 | char *data); | ||
| 78 | This routine deletes an entry from the hash table. The value being | ||
| 79 | deleted is returned. NULL is returned if there is no such value in | ||
| 80 | the hash table. | ||
| 81 | |||
| 82 | char *lh_retrieve( | ||
| 83 | LHASH *lh, | ||
| 84 | char *data); | ||
| 85 | If 'data' is in the hash table it is returned, else NULL is | ||
| 86 | returned. The way these routines would normally be uses is that a | ||
| 87 | dummy structure would have key fields populated and then | ||
| 88 | ret=lh_retrieve(hash,&dummy);. Ret would now be a pointer to a fully | ||
| 89 | populated structure. | ||
| 90 | |||
| 91 | void lh_doall( | ||
| 92 | LHASH *lh, | ||
| 93 | void (*func)(char *a)); | ||
| 94 | This function will, for every entry in the hash table, call function | ||
| 95 | 'func' with the data item as parameters. | ||
| 96 | This function can be quite useful when used as follows. | ||
| 97 | void cleanup(STUFF *a) | ||
| 98 | { STUFF_free(a); } | ||
| 99 | lh_doall(hash,cleanup); | ||
| 100 | lh_free(hash); | ||
| 101 | This can be used to free all the entries, lh_free() then | ||
| 102 | cleans up the 'buckets' that point to nothing. Be careful | ||
| 103 | when doing this. If you delete entries from the hash table, | ||
| 104 | in the call back function, the table may decrease in size, | ||
| 105 | moving item that you are | ||
| 106 | currently on down lower in the hash table. This could cause | ||
| 107 | some entries to be skipped. The best solution to this problem | ||
| 108 | is to set lh->down_load=0 before you start. This will stop | ||
| 109 | the hash table ever being decreased in size. | ||
| 110 | |||
| 111 | void lh_doall_arg( | ||
| 112 | LHASH *lh; | ||
| 113 | void(*func)(char *a,char *arg)); | ||
| 114 | char *arg; | ||
| 115 | This function is the same as lh_doall except that the function | ||
| 116 | called will be passed 'arg' as the second argument. | ||
| 117 | |||
| 118 | unsigned long lh_strhash( | ||
| 119 | char *c); | ||
| 120 | This function is a demo string hashing function. Since the LHASH | ||
| 121 | routines would normally be passed structures, this routine would | ||
| 122 | not normally be passed to lh_new(), rather it would be used in the | ||
| 123 | function passed to lh_new(). | ||
| 124 | |||
| 125 | The next three routines print out various statistics about the state of the | ||
| 126 | passed hash table. These numbers are all kept in the lhash structure. | ||
| 127 | |||
| 128 | void lh_stats( | ||
| 129 | LHASH *lh, | ||
| 130 | FILE *out); | ||
| 131 | This function prints out statistics on the size of the hash table, | ||
| 132 | how many entries are in it, and the number and result of calls to | ||
| 133 | the routines in this library. | ||
| 134 | |||
| 135 | void lh_node_stats( | ||
| 136 | LHASH *lh, | ||
| 137 | FILE *out); | ||
| 138 | For each 'bucket' in the hash table, the number of entries is | ||
| 139 | printed. | ||
| 140 | |||
| 141 | void lh_node_usage_stats( | ||
| 142 | LHASH *lh, | ||
| 143 | FILE *out); | ||
| 144 | This function prints out a short summary of the state of the hash | ||
| 145 | table. It prints what I call the 'load' and the 'actual load'. | ||
| 146 | The load is the average number of data items per 'bucket' in the | ||
| 147 | hash table. The 'actual load' is the average number of items per | ||
| 148 | 'bucket', but only for buckets which contain entries. So the | ||
| 149 | 'actual load' is the average number of searches that will need to | ||
| 150 | find an item in the hash table, while the 'load' is the average number | ||
| 151 | that will be done to record a miss. | ||
diff --git a/src/lib/libssl/src/doc/md2.doc b/src/lib/libssl/src/doc/md2.doc deleted file mode 100644 index b106bc675d..0000000000 --- a/src/lib/libssl/src/doc/md2.doc +++ /dev/null | |||
| @@ -1,49 +0,0 @@ | |||
| 1 | The MD2 library. | ||
| 2 | MD2 is a message digest algorithm that can be used to condense an arbitrary | ||
| 3 | length message down to a 16 byte hash. The functions all need to be passed | ||
| 4 | a MD2_CTX which is used to hold the MD2 context during multiple MD2_Update() | ||
| 5 | function calls. The normal method of use for this library is as follows | ||
| 6 | |||
| 7 | MD2_Init(...); | ||
| 8 | MD2_Update(...); | ||
| 9 | ... | ||
| 10 | MD2_Update(...); | ||
| 11 | MD2_Final(...); | ||
| 12 | |||
| 13 | This library requires the inclusion of 'md2.h'. | ||
| 14 | |||
| 15 | The main negative about MD2 is that it is slow, especially when compared | ||
| 16 | to MD5. | ||
| 17 | |||
| 18 | The functions are as follows: | ||
| 19 | |||
| 20 | void MD2_Init( | ||
| 21 | MD2_CTX *c); | ||
| 22 | This function needs to be called to initiate a MD2_CTX structure for | ||
| 23 | use. | ||
| 24 | |||
| 25 | void MD2_Update( | ||
| 26 | MD2_CTX *c; | ||
| 27 | unsigned char *data; | ||
| 28 | unsigned long len); | ||
| 29 | This updates the message digest context being generated with 'len' | ||
| 30 | bytes from the 'data' pointer. The number of bytes can be any | ||
| 31 | length. | ||
| 32 | |||
| 33 | void MD2_Final( | ||
| 34 | unsigned char *md; | ||
| 35 | MD2_CTX *c; | ||
| 36 | This function is called when a message digest of the data digested | ||
| 37 | with MD2_Update() is wanted. The message digest is put in the 'md' | ||
| 38 | array and is MD2_DIGEST_LENGTH (16) bytes long. | ||
| 39 | |||
| 40 | unsigned char *MD2( | ||
| 41 | unsigned long n; | ||
| 42 | unsigned char *d; | ||
| 43 | unsigned char *md; | ||
| 44 | This function performs a MD2_Init(), followed by a MD2_Update() | ||
| 45 | followed by a MD2_Final() (using a local MD2_CTX). | ||
| 46 | The resulting digest is put into 'md' if it is not NULL. | ||
| 47 | Regardless of the value of 'md', the message | ||
| 48 | digest is returned from the function. If 'md' was NULL, the message | ||
| 49 | digest returned is being stored in a static structure. | ||
diff --git a/src/lib/libssl/src/doc/md5.doc b/src/lib/libssl/src/doc/md5.doc deleted file mode 100644 index 519dbdc61a..0000000000 --- a/src/lib/libssl/src/doc/md5.doc +++ /dev/null | |||
| @@ -1,50 +0,0 @@ | |||
| 1 | The MD5 library. | ||
| 2 | MD5 is a message digest algorithm that can be used to condense an arbitrary | ||
| 3 | length message down to a 16 byte hash. The functions all need to be passed | ||
| 4 | a MD5_CTX which is used to hold the MD5 context during multiple MD5_Update() | ||
| 5 | function calls. This library also contains random number routines that are | ||
| 6 | based on MD5 | ||
| 7 | |||
| 8 | The normal method of use for this library is as follows | ||
| 9 | |||
| 10 | MD5_Init(...); | ||
| 11 | MD5_Update(...); | ||
| 12 | ... | ||
| 13 | MD5_Update(...); | ||
| 14 | MD5_Final(...); | ||
| 15 | |||
| 16 | This library requires the inclusion of 'md5.h'. | ||
| 17 | |||
| 18 | The functions are as follows: | ||
| 19 | |||
| 20 | void MD5_Init( | ||
| 21 | MD5_CTX *c); | ||
| 22 | This function needs to be called to initiate a MD5_CTX structure for | ||
| 23 | use. | ||
| 24 | |||
| 25 | void MD5_Update( | ||
| 26 | MD5_CTX *c; | ||
| 27 | unsigned char *data; | ||
| 28 | unsigned long len); | ||
| 29 | This updates the message digest context being generated with 'len' | ||
| 30 | bytes from the 'data' pointer. The number of bytes can be any | ||
| 31 | length. | ||
| 32 | |||
| 33 | void MD5_Final( | ||
| 34 | unsigned char *md; | ||
| 35 | MD5_CTX *c; | ||
| 36 | This function is called when a message digest of the data digested | ||
| 37 | with MD5_Update() is wanted. The message digest is put in the 'md' | ||
| 38 | array and is MD5_DIGEST_LENGTH (16) bytes long. | ||
| 39 | |||
| 40 | unsigned char *MD5( | ||
| 41 | unsigned char *d; | ||
| 42 | unsigned long n; | ||
| 43 | unsigned char *md; | ||
| 44 | This function performs a MD5_Init(), followed by a MD5_Update() | ||
| 45 | followed by a MD5_Final() (using a local MD5_CTX). | ||
| 46 | The resulting digest is put into 'md' if it is not NULL. | ||
| 47 | Regardless of the value of 'md', the message | ||
| 48 | digest is returned from the function. If 'md' was NULL, the message | ||
| 49 | digest returned is being stored in a static structure. | ||
| 50 | |||
diff --git a/src/lib/libssl/src/doc/memory.doc b/src/lib/libssl/src/doc/memory.doc deleted file mode 100644 index b9aa33ace0..0000000000 --- a/src/lib/libssl/src/doc/memory.doc +++ /dev/null | |||
| @@ -1,27 +0,0 @@ | |||
| 1 | In the interests of debugging SSLeay, there is an option to compile | ||
| 2 | using some simple memory leak checking. | ||
| 3 | |||
| 4 | All malloc(), free() and realloc() calls in SSLeay now go via | ||
| 5 | Malloc(), Free() and Realloc() (except those in crypto/lhash). | ||
| 6 | |||
| 7 | If CRYPTO_MDEBUG is defined, these calls are #defined to | ||
| 8 | CRYPTO_malloc(), CRYPTO_free() and CRYPTO_realloc(). | ||
| 9 | If it is not defined, they are #defined to malloc(), free() and realloc(). | ||
| 10 | |||
| 11 | the CRYPTO_malloc() routines by default just call the underlying library | ||
| 12 | functons. | ||
| 13 | |||
| 14 | If CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON) is called, memory leak detection is | ||
| 15 | turned on. CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_OFF) turns it off. | ||
| 16 | |||
| 17 | When turned on, each Malloc() or Realloc() call is recored along with the file | ||
| 18 | and line number from where the call was made. (This is done using the | ||
| 19 | lhash library which always uses normal system malloc(3) routines). | ||
| 20 | |||
| 21 | void CRYPTO_mem_leaks(BIO *b); | ||
| 22 | void CRYPTO_mem_leaks_fp(FILE *fp); | ||
| 23 | These both print out the list of memory that has not been free()ed. | ||
| 24 | This will probably be rather hard to read, but if you look for the 'top level' | ||
| 25 | structure allocation, this will often give an idea as to what is not being | ||
| 26 | free()ed. I don't expect people to use this stuff normally. | ||
| 27 | |||
diff --git a/src/lib/libssl/src/doc/ms3-ca.doc b/src/lib/libssl/src/doc/ms3-ca.doc deleted file mode 100644 index f8350aadc2..0000000000 --- a/src/lib/libssl/src/doc/ms3-ca.doc +++ /dev/null | |||
| @@ -1,398 +0,0 @@ | |||
| 1 | Date: Mon, 9 Jun 97 08:00:33 +0200 | ||
| 2 | From: Holger.Reif@PrakInf.TU-Ilmenau.DE (Holger Reif) | ||
| 3 | Subject: ms3-ca.doc | ||
| 4 | Organization: TU Ilmenau, Fak. IA, FG Telematik | ||
| 5 | Content-Length: 14575 | ||
| 6 | Status: RO | ||
| 7 | X-Status: | ||
| 8 | |||
| 9 | Loading client certs into MSIE 3.01 | ||
| 10 | =================================== | ||
| 11 | |||
| 12 | This document conatains all the information necessary to succesfully set up | ||
| 13 | some scripts to issue client certs to Microsoft Internet Explorer. It | ||
| 14 | includes the required knowledge about the model MSIE uses for client | ||
| 15 | certification and includes complete sample scripts ready to play with. The | ||
| 16 | scripts were tested against a modified ca program of SSLeay 0.6.6 and should | ||
| 17 | work with the regular ca program that comes with version 0.8.0. I haven't | ||
| 18 | tested against MSIE 4.0 | ||
| 19 | |||
| 20 | You can use the information contained in this document in either way you | ||
| 21 | want. However if you feel it saved you a lot of time I ask you to be as fair | ||
| 22 | as to mention my name: Holger Reif <reif@prakinf.tu-ilmenau.de>. | ||
| 23 | |||
| 24 | 1.) The model used by MSIE | ||
| 25 | -------------------------- | ||
| 26 | |||
| 27 | The Internet Explorer doesn't come with a embedded engine for installing | ||
| 28 | client certs like Netscape's Navigator. It rather uses the CryptoAPI (CAPI) | ||
| 29 | defined by Microsoft. CAPI comes with WindowsNT 4.0 or is installed together | ||
| 30 | with Internet Explorer since 3.01. The advantage of this approach is a higher | ||
| 31 | flexibility because the certificates in the (per user) system open | ||
| 32 | certificate store may be used by other applications as well. The drawback | ||
| 33 | however is that you need to do a bit more work to get a client cert issued. | ||
| 34 | |||
| 35 | CAPI defines functions which will handle basic cryptographic work, eg. | ||
| 36 | generating keys, encrypting some data, signing text or building a certificate | ||
| 37 | request. The procedure is as follows: A CAPI function generates you a key | ||
| 38 | pair and saves it into the certificate store. After that one builds a | ||
| 39 | Distinguished Name. Together with that key pair another CAPI function forms a | ||
| 40 | PKCS#10 request which you somehow need to submit to a CA. Finally the issued | ||
| 41 | cert is given to a yet another CAPI function which saves it into the | ||
| 42 | certificate store. | ||
| 43 | |||
| 44 | The certificate store with the user's keys and certs is in the registry. You | ||
| 45 | will find it under HKEY_CURRENT_USER/Software/Microsoft/Cryptography/ (I | ||
| 46 | leave it to you as a little exercise to figure out what all the entries mean | ||
| 47 | ;-). Note that the keys are protected only with the user's usual Windows | ||
| 48 | login password. | ||
| 49 | |||
| 50 | 2.) The practical usage | ||
| 51 | ----------------------- | ||
| 52 | |||
| 53 | Unfortunatly since CAPI is a system API you can't access its functions from | ||
| 54 | HTML code directly. For this purpose Microsoft provides a wrapper called | ||
| 55 | certenr3.dll. This DLL accesses the CAPI functions and provides an interface | ||
| 56 | usable from Visual Basic Script. One needs to install that library on the | ||
| 57 | computer which wants to have client cert. The easiest way is to load it as an | ||
| 58 | ActiveX control (certenr3.dll is properly authenticode signed by MS ;-). If | ||
| 59 | you have ever enrolled e cert request at a CA you will have installed it. | ||
| 60 | |||
| 61 | At time of writing certenr3.dll is contained in | ||
| 62 | http://www.microsoft.com/workshop/prog/security/csa/certenr3.exe. It comes | ||
| 63 | with an README file which explains the available functions. It is labeled | ||
| 64 | beta but every CA seems to use it anyway. The license.txt allows you the | ||
| 65 | usage for your own purposes (as far as I understood) and a somehow limited | ||
| 66 | distribution. | ||
| 67 | |||
| 68 | The two functions of main interest are GenerateKeyPair and AcceptCredentials. | ||
| 69 | For complete explanation of all possible parameters see the README file. Here | ||
| 70 | are only minimal required parameters and their values. | ||
| 71 | |||
| 72 | GenerateKeyPair(sessionID, FASLE, szName, 0, "ClientAuth", TRUE, FALSE, 1) | ||
| 73 | - sessionID is a (locally to that computer) unique string to correlate the | ||
| 74 | generated key pair with a cert installed later. | ||
| 75 | - szName is the DN of the form "C=DE; S=Thueringen; L=Ilmenau; CN=Holger | ||
| 76 | Reif; 1.2.840.113549.1.9.1=reif@prakinf.tu-ilmenau.de". Note that S is the | ||
| 77 | abreviation for StateOrProvince. The recognized abreviation include CN, O, C, | ||
| 78 | OU, G, I, L, S, T. If the abreviation is unknown (eg. for PKCS#9 email addr) | ||
| 79 | you need to use the full object identifier. The starting point for searching | ||
| 80 | them could be crypto/objects.h since all OIDs know to SSLeay are listed | ||
| 81 | there. | ||
| 82 | - note: the possible ninth parameter which should give a default name to the | ||
| 83 | certificate storage location doesn't seem to work. Changes to the constant | ||
| 84 | values in the call above doesn't seem to make sense. You can't generate | ||
| 85 | PKCS#10 extensions with that function. | ||
| 86 | |||
| 87 | The result of GenerateKeyPair is the base64 encoded PKCS#10 request. However | ||
| 88 | it has a little strange format that SSLeay doesn't accept. (BTW I feel the | ||
| 89 | decision of rejecting that format as standard conforming.) It looks like | ||
| 90 | follows: | ||
| 91 | 1st line with 76 chars | ||
| 92 | 2nd line with 76 chars | ||
| 93 | ... | ||
| 94 | (n-2)th line with 76 chars | ||
| 95 | (n-1)th line contains a multiple of 4 chars less then 76 (possible | ||
| 96 | empty) | ||
| 97 | (n)th line has zero or 4 chars (then with 1 or 2 equal signs - the | ||
| 98 | original text's lenght wasn'T a multiple of 3) | ||
| 99 | The line separator has two chars: 0x0d 0x0a | ||
| 100 | |||
| 101 | AcceptCredentials(sessionID, credentials, 0, FALSE) | ||
| 102 | - sessionID needs to be the same as while generating the key pair | ||
| 103 | - credentials is the base64 encoded PKCS#7 object containing the cert. | ||
| 104 | |||
| 105 | CRL's and CA certs are not required simply just the client cert. (It seems to | ||
| 106 | me that both are not even checked somehow.) The only format of the base64 | ||
| 107 | encoded object I succesfully used was all characters in a very long string | ||
| 108 | without line feeds or carriage returns. (Hey, it doesn't matter, only a | ||
| 109 | computer reads it!) | ||
| 110 | |||
| 111 | The result should be S_OK. For error handling see the example that comes with | ||
| 112 | certenr3.dll. | ||
| 113 | |||
| 114 | A note about ASN.1 character encodings. certenr3.dll seems to know only about | ||
| 115 | 2 of them: UniversalString and PrintableString. First it is definitely wrong | ||
| 116 | for an email address which is IA5STRING (checked by ssleay's ca). Second | ||
| 117 | unfortunately MSIE (at least until version 3.02) can't handle UniversalString | ||
| 118 | correctly - they just blow up you cert store! Therefore ssleay's ca (starting | ||
| 119 | from version 0.8.0) tries to convert the encodings automatically to IA5STRING | ||
| 120 | or TeletexString. The beef is it will work only for the latin-1 (western) | ||
| 121 | charset. Microsoft still has to do abit of homework... | ||
| 122 | |||
| 123 | 3.) An example | ||
| 124 | -------------- | ||
| 125 | |||
| 126 | At least you need two steps: generating the key & request and then installing | ||
| 127 | the certificate. A real world CA would have some more steps involved, eg. | ||
| 128 | accepting some license. Note that both scripts shown below are just | ||
| 129 | experimental state without any warrenty! | ||
| 130 | |||
| 131 | First how to generate a request. Note that we can't use a static page because | ||
| 132 | of the sessionID. I generate it from system time plus pid and hope it is | ||
| 133 | unique enough. Your are free to feed it through md5 to get more impressive | ||
| 134 | ID's ;-) Then the intended text is read in with sed which inserts the | ||
| 135 | sessionID. | ||
| 136 | |||
| 137 | -----BEGIN ms-enroll.cgi----- | ||
| 138 | #!/bin/sh | ||
| 139 | SESSION_ID=`date '+%y%m%d%H%M%S'`$$ | ||
| 140 | echo Content-type: text/html | ||
| 141 | echo | ||
| 142 | sed s/template_for_sessId/$SESSION_ID/ <<EOF | ||
| 143 | <HTML><HEAD> | ||
| 144 | <TITLE>Certificate Enrollment Test Page</TITLE> | ||
| 145 | </HEAD><BODY> | ||
| 146 | |||
| 147 | <OBJECT | ||
| 148 | classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43" | ||
| 149 | codebase=certenr3.dll | ||
| 150 | id=certHelper | ||
| 151 | > | ||
| 152 | </OBJECT> | ||
| 153 | |||
| 154 | <CENTER> | ||
| 155 | <H2>enrollment for a personal cert</H2> | ||
| 156 | <BR><HR WIDTH=50%><BR><P> | ||
| 157 | <FORM NAME="MSIE_Enrollment" ACTION="ms-gencert.cgi" ENCTYPE=x-www-form- | ||
| 158 | encoded METHOD=POST> | ||
| 159 | <TABLE> | ||
| 160 | <TR><TD>Country</TD><TD><INPUT NAME="Country" VALUE=""></TD></TR> | ||
| 161 | <TR><TD>State</TD><TD><INPUT NAME="StateOrProvince" VALUE=""></TD></TR> | ||
| 162 | <TR><TD>Location</TD><TD><INPUT NAME="Location" VALUE=""></TD></TR> | ||
| 163 | <TR><TD>Organization</TD><TD><INPUT NAME="Organization" | ||
| 164 | VALUE=""></TD></TR> | ||
| 165 | <TR><TD>Organizational Unit</TD> | ||
| 166 | <TD><INPUT NAME="OrganizationalUnit" VALUE=""></TD></TR> | ||
| 167 | <TR><TD>Name</TD><TD><INPUT NAME="CommonName" VALUE=""></TD></TR> | ||
| 168 | <TR><TD>eMail Address</TD> | ||
| 169 | <TD><INPUT NAME="EmailAddress" VALUE=""></TD></TR> | ||
| 170 | <TR><TD></TD> | ||
| 171 | <TD><INPUT TYPE="BUTTON" NAME="submit" VALUE="Beantragen"></TD></TR> | ||
| 172 | </TABLE> | ||
| 173 | <INPUT TYPE="hidden" NAME="SessionId" VALUE="template_for_sessId"> | ||
| 174 | <INPUT TYPE="hidden" NAME="Request" VALUE=""> | ||
| 175 | </FORM> | ||
| 176 | <BR><HR WIDTH=50%><BR><P> | ||
| 177 | </CENTER> | ||
| 178 | |||
| 179 | <SCRIPT LANGUAGE=VBS> | ||
| 180 | Dim DN | ||
| 181 | |||
| 182 | Sub Submit_OnClick | ||
| 183 | Dim TheForm | ||
| 184 | Set TheForm = Document.MSIE_Enrollment | ||
| 185 | sessionId = TheForm.SessionId.value | ||
| 186 | reqHardware = FALSE | ||
| 187 | C = TheForm.Country.value | ||
| 188 | SP = TheForm.StateOrProvince.value | ||
| 189 | L = TheForm.Location.value | ||
| 190 | O = TheForm.Organization.value | ||
| 191 | OU = TheForm.OrganizationalUnit.value | ||
| 192 | CN = TheForm.CommonName.value | ||
| 193 | Email = TheForm.EmailAddress.value | ||
| 194 | szPurpose = "ClientAuth" | ||
| 195 | doAcceptanceUINow = FALSE | ||
| 196 | doOnline = TRUE | ||
| 197 | |||
| 198 | DN = "" | ||
| 199 | |||
| 200 | Call Add_RDN("C", C) | ||
| 201 | Call Add_RDN("S", SP) | ||
| 202 | Call Add_RDN("L", L) | ||
| 203 | Call Add_RDN("O", O) | ||
| 204 | Call Add_RDN("OU", OU) | ||
| 205 | Call Add_RDN("CN", CN) | ||
| 206 | Call Add_RDN("1.2.840.113549.1.9.1", Email) | ||
| 207 | ' rsadsi | ||
| 208 | ' pkcs | ||
| 209 | ' pkcs9 | ||
| 210 | ' eMailAddress | ||
| 211 | On Error Resume Next | ||
| 212 | sz10 = certHelper.GenerateKeyPair(sessionId, _ | ||
| 213 | FALSE, DN, 0, ClientAuth, FASLE, TRUE, 1)_ | ||
| 214 | theError = Err.Number | ||
| 215 | On Error Goto 0 | ||
| 216 | if (sz10 = Empty OR theError <> 0) Then | ||
| 217 | sz = "The error '" & Hex(theError) & "' occurred." & chr(13) & _ | ||
| 218 | chr(10) & "Your credentials could not be generated." | ||
| 219 | result = MsgBox(sz, 0, "Credentials Enrollment") | ||
| 220 | Exit Sub | ||
| 221 | else | ||
| 222 | TheForm.Request.value = sz10 | ||
| 223 | TheForm.Submit | ||
| 224 | end if | ||
| 225 | End Sub | ||
| 226 | |||
| 227 | Sub Add_RDN(sn, value) | ||
| 228 | if (value <> "") then | ||
| 229 | if (DN <> "") then | ||
| 230 | DN = DN & "; " | ||
| 231 | end if | ||
| 232 | DN = DN & sn & "=" & value | ||
| 233 | end if | ||
| 234 | End Sub | ||
| 235 | </SCRIPT> | ||
| 236 | </BODY> | ||
| 237 | </HTML> | ||
| 238 | EOF | ||
| 239 | -----END ms-enroll.cgi----- | ||
| 240 | |||
| 241 | Second, how to extract the request and feed the certificate back? We need to | ||
| 242 | "normalize" the base64 encoding of the PKCS#10 format which means | ||
| 243 | regenerating the lines and wrapping with BEGIN and END line. This is done by | ||
| 244 | gawk. The request is taken by ca the normal way. Then the cert needs to be | ||
| 245 | packed into a PKCS#7 structure (note: the use of a CRL is necessary for | ||
| 246 | crl2pkcs7 as of version 0.6.6. Starting with 0.8.0 it it might probably be | ||
| 247 | ommited). Finally we need to format the PKCS#7 object and generate the HTML | ||
| 248 | text. I use two templates to have a clearer script. | ||
| 249 | |||
| 250 | 1st note: postit2 is slightly modified from a program I found at ncsa's ftp | ||
| 251 | site. Grab it from http://www.easterngraphics.com/certs/IX9704/postit2.c. You | ||
| 252 | need utils.c from there too. | ||
| 253 | |||
| 254 | 2nd note: I'm note quite sure wether the gawk script really handles all | ||
| 255 | possible inputs for the request right! Today I don't use this construction | ||
| 256 | anymore myself. | ||
| 257 | |||
| 258 | 3d note: the cert must be of version 3! This could be done with the nsComment | ||
| 259 | line in ssleay.cnf... | ||
| 260 | |||
| 261 | ------BEGIN ms-gencert.cgi----- | ||
| 262 | #!/bin/sh | ||
| 263 | FILE="/tmp/"`date '+%y%m%d%H%M%S'-`$$ | ||
| 264 | rm -f "$FILE".* | ||
| 265 | |||
| 266 | HOME=`pwd`; export HOME # as ssleay.cnf insists on having such an env var | ||
| 267 | cd /usr/local/ssl #where demoCA (as named in ssleay.conf) is located | ||
| 268 | |||
| 269 | postit2 -s " " -i 0x0d > "$FILE".inp # process the FORM vars | ||
| 270 | |||
| 271 | SESSION_ID=`gawk '$1 == "SessionId" { print $2; exit }' "$FILE".inp` | ||
| 272 | |||
| 273 | gawk \ | ||
| 274 | 'BEGIN { \ | ||
| 275 | OFS = ""; \ | ||
| 276 | print "-----BEGIN CERTIFICATE REQUEST-----"; \ | ||
| 277 | req_seen=0 \ | ||
| 278 | } \ | ||
| 279 | $1 == "Request" { \ | ||
| 280 | req_seen=1; \ | ||
| 281 | if (length($2) == 72) print($2); \ | ||
| 282 | lastline=$2; \ | ||
| 283 | next; \ | ||
| 284 | } \ | ||
| 285 | { \ | ||
| 286 | if (req_seen == 1) { \ | ||
| 287 | if (length($1) >= 72) print($1); \ | ||
| 288 | else if (length(lastline) < 72) { \ | ||
| 289 | req_seen=0; \ | ||
| 290 | print (lastline,$1); \ | ||
| 291 | } \ | ||
| 292 | lastline=$1; \ | ||
| 293 | } \ | ||
| 294 | } \ | ||
| 295 | END { \ | ||
| 296 | print "-----END CERTIFICATE REQUEST-----"; \ | ||
| 297 | }' > "$FILE".pem < "$FILE".inp | ||
| 298 | |||
| 299 | ssleay ca -batch -in "$FILE".pem -key passwd -out "$FILE".out | ||
| 300 | ssleay crl2pkcs7 -certfile "$FILE".out -out "$FILE".pkcs7 -in demoCA/crl.pem | ||
| 301 | |||
| 302 | sed s/template_for_sessId/$SESSION_ID/ <ms-enroll2a.html >"$FILE".cert | ||
| 303 | /usr/local/bin/gawk \ | ||
| 304 | 'BEGIN { \ | ||
| 305 | OFS = ""; \ | ||
| 306 | dq = sprintf("%c",34); \ | ||
| 307 | } \ | ||
| 308 | $0 ~ "PKCS7" { next; } \ | ||
| 309 | { \ | ||
| 310 | print dq$0dq" & _"; \ | ||
| 311 | }' <"$FILE".pkcs7 >> "$FILE".cert | ||
| 312 | cat ms-enroll2b.html >>"$FILE".cert | ||
| 313 | |||
| 314 | echo Content-type: text/html | ||
| 315 | echo Content-length: `wc -c "$FILE".cert` | ||
| 316 | echo | ||
| 317 | cat "$FILE".cert | ||
| 318 | rm -f "$FILE".* | ||
| 319 | -----END ms-gencert.cgi----- | ||
| 320 | |||
| 321 | ----BEGIN ms-enroll2a.html---- | ||
| 322 | <HTML><HEAD><TITLE>Certificate Acceptance Test Page</TITLE></HEAD><BODY> | ||
| 323 | |||
| 324 | <OBJECT | ||
| 325 | classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43" | ||
| 326 | codebase=certenr3.dll | ||
| 327 | id=certHelper | ||
| 328 | > | ||
| 329 | </OBJECT> | ||
| 330 | |||
| 331 | <CENTER> | ||
| 332 | <H2>Your personal certificate</H2> | ||
| 333 | <BR><HR WIDTH=50%><BR><P> | ||
| 334 | Press the button! | ||
| 335 | <P><INPUT TYPE=BUTTON VALUE="Nimm mich!" NAME="InstallCert"> | ||
| 336 | </CENTER> | ||
| 337 | <BR><HR WIDTH=50%><BR> | ||
| 338 | |||
| 339 | <SCRIPT LANGUAGE=VBS> | ||
| 340 | Sub InstallCert_OnClick | ||
| 341 | |||
| 342 | sessionId = "template_for_sessId" | ||
| 343 | credentials = "" & _ | ||
| 344 | ----END ms-enroll2a.html---- | ||
| 345 | |||
| 346 | ----BEGIN ms-enroll2b.html---- | ||
| 347 | "" | ||
| 348 | On Error Resume Next | ||
| 349 | result = certHelper.AcceptCredentials(sessionId, credentials, 0, | ||
| 350 | FALSE) | ||
| 351 | if (IsEmpty(result)) Then | ||
| 352 | sz = "The error '" & Err.Number & "' occurred." & chr(13) & | ||
| 353 | chr(10) & "This Digital ID could not be registered." | ||
| 354 | msgOut = MsgBox(sz, 0, "Credentials Registration Error") | ||
| 355 | navigate "error.html" | ||
| 356 | else | ||
| 357 | sz = "Digital ID successfully registered." | ||
| 358 | msgOut = MsgBox(sz, 0, "Credentials Registration") | ||
| 359 | navigate "success.html" | ||
| 360 | end if | ||
| 361 | Exit Sub | ||
| 362 | End Sub | ||
| 363 | </SCRIPT> | ||
| 364 | </BODY> | ||
| 365 | </HTML> | ||
| 366 | ----END ms-enroll2b.html---- | ||
| 367 | |||
| 368 | 4.) What do do with the cert? | ||
| 369 | ----------------------------- | ||
| 370 | |||
| 371 | The cert is visible (without restarting MSIE) under the following menu: | ||
| 372 | View->Options->Security->Personal certs. You can examine it's contents at | ||
| 373 | least partially. | ||
| 374 | |||
| 375 | To use it for client authentication you need to use SSL3.0 (fortunately | ||
| 376 | SSLeay supports it with 0.8.0). Furthermore MSIE is told to only supports a | ||
| 377 | kind of automatic selection of certs (I personally wasn't able to test it | ||
| 378 | myself). But there is a requirement that the issuer of the server cert and | ||
| 379 | the issuer of the client cert needs to be the same (according to a developer | ||
| 380 | from MS). Which means: you need may more then one cert to talk to all | ||
| 381 | servers... | ||
| 382 | |||
| 383 | I'm sure we will get a bit more experience after ApacheSSL is available for | ||
| 384 | SSLeay 0.8.8. | ||
| 385 | |||
| 386 | |||
| 387 | I hope you enjoyed reading and that in future questions on this topic will | ||
| 388 | rarely appear on ssl-users@moncom.com ;-) | ||
| 389 | |||
| 390 | Ilmenau, 9th of June 1997 | ||
| 391 | Holger Reif <reif@prakinf.tu-ilmenau.de> | ||
| 392 | -- | ||
| 393 | read you later - Holger Reif | ||
| 394 | ---------------------------------------- Signaturprojekt Deutsche Einheit | ||
| 395 | TU Ilmenau - Informatik - Telematik (Verdamp lang her) | ||
| 396 | Holger.Reif@PrakInf.TU-Ilmenau.DE Alt wie ein Baum werden, um ueber | ||
| 397 | http://Remus.PrakInf.TU-Ilmenau.DE/Reif/ alle 7 Bruecken gehen zu koennen | ||
| 398 | |||
diff --git a/src/lib/libssl/src/doc/ns-ca.doc b/src/lib/libssl/src/doc/ns-ca.doc deleted file mode 100644 index 836883e1a0..0000000000 --- a/src/lib/libssl/src/doc/ns-ca.doc +++ /dev/null | |||
| @@ -1,154 +0,0 @@ | |||
| 1 | The following documentation was supplied by Jeff Barber, who provided the | ||
| 2 | patch to the CA program to add this functionality. | ||
| 3 | |||
| 4 | eric | ||
| 5 | -- | ||
| 6 | Jeff Barber Email: jeffb@issl.atl.hp.com | ||
| 7 | |||
| 8 | Hewlett Packard Phone: (404) 648-9503 | ||
| 9 | Internet and System Security Lab Fax: (404) 648-9516 | ||
| 10 | |||
| 11 | oo | ||
| 12 | ---------------------cut /\ here for ns-ca.doc ------------------------------ | ||
| 13 | |||
| 14 | This document briefly describes how to use SSLeay to implement a | ||
| 15 | certificate authority capable of dynamically serving up client | ||
| 16 | certificates for version 3.0 beta 5 (and presumably later) versions of | ||
| 17 | the Netscape Navigator. Before describing how this is done, it's | ||
| 18 | important to understand a little about how the browser implements its | ||
| 19 | client certificate support. This is documented in some detail in the | ||
| 20 | URLs based at <URL:http://home.netscape.com/eng/security/certs.html>. | ||
| 21 | Here's a brief overview: | ||
| 22 | |||
| 23 | - The Navigator supports a new HTML tag "KEYGEN" which will cause | ||
| 24 | the browser to generate an RSA key pair when you submit a form | ||
| 25 | containing the tag. The public key, along with an optional | ||
| 26 | challenge (supposedly provided for use in certificate revocation | ||
| 27 | but I don't use it) is signed, DER-encoded, base-64 encoded | ||
| 28 | and sent to the web server as the value of the variable | ||
| 29 | whose NAME is provided in the KEYGEN tag. The private key is | ||
| 30 | stored by the browser in a local key database. | ||
| 31 | |||
| 32 | This "Signed Public Key And Challenge" (SPKAC) arrives formatted | ||
| 33 | into 64 character lines (which are of course URL-encoded when | ||
| 34 | sent via HTTP -- i.e. spaces, newlines and most punctuatation are | ||
| 35 | encoded as "%HH" where HH is the hex equivalent of the ASCII code). | ||
| 36 | Note that the SPKAC does not contain the other usual attributes | ||
| 37 | of a certificate request, especially the subject name fields. | ||
| 38 | These must be otherwise encoded in the form for submission along | ||
| 39 | with the SPKAC. | ||
| 40 | |||
| 41 | - Either immediately (in response to this form submission), or at | ||
| 42 | some later date (a real CA will probably verify your identity in | ||
| 43 | some way before issuing the certificate), a web server can send a | ||
| 44 | certificate based on the public key and other attributes back to | ||
| 45 | the browser by encoding it in DER (the binary form) and sending it | ||
| 46 | to the browser as MIME type: | ||
| 47 | "Content-type: application/x-x509-user-cert" | ||
| 48 | |||
| 49 | The browser uses the public key encoded in the certificate to | ||
| 50 | associate the certificate with the appropriate private key in | ||
| 51 | its local key database. Now, the certificate is "installed". | ||
| 52 | |||
| 53 | - When a server wants to require authentication based on client | ||
| 54 | certificates, it uses the right signals via the SSL protocol to | ||
| 55 | trigger the Navigator to ask you which certificate you want to | ||
| 56 | send. Whether the certificate is accepted is dependent on CA | ||
| 57 | certificates and so forth installed in the server and is beyond | ||
| 58 | the scope of this document. | ||
| 59 | |||
| 60 | |||
| 61 | Now, here's how the SSLeay package can be used to provide client | ||
| 62 | certficates: | ||
| 63 | |||
| 64 | - You prepare a file for input to the SSLeay ca application. | ||
| 65 | The file contains a number of "name = value" pairs that identify | ||
| 66 | the subject. The names here are the same subject name component | ||
| 67 | identifiers used in the CA section of the lib/ssleay.conf file, | ||
| 68 | such as "emailAddress", "commonName" "organizationName" and so | ||
| 69 | forth. Both the long version and the short version (e.g. "Email", | ||
| 70 | "CN", "O") can be used. | ||
| 71 | |||
| 72 | One more name is supported: this one is "SPKAC". Its value | ||
| 73 | is simply the value of the base-64 encoded SPKAC sent by the | ||
| 74 | browser (with all the newlines and other space charaters | ||
| 75 | removed -- and newline escapes are NOT supported). | ||
| 76 | |||
| 77 | [ As of SSLeay 0.6.4, multiple lines are supported. | ||
| 78 | Put a \ at the end of each line and it will be joined with the | ||
| 79 | previous line with the '\n' removed - eay ] | ||
| 80 | |||
| 81 | Here's a sample input file: | ||
| 82 | |||
| 83 | C = US | ||
| 84 | SP = Georgia | ||
| 85 | O = Some Organization, Inc. | ||
| 86 | OU = Netscape Compatibility Group | ||
| 87 | CN = John X. Doe | ||
| 88 | Email = jxdoe@someorg.com | ||
| 89 | SPKAC = MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwmk6FMJ4uAVIYbcvIOx5+bDGTfvL8X5gE+R67ccMk6rCSGbVQz2cetyQtnI+VIs0NwdD6wjuSuVtVFbLoHonowIDAQABFgAwDQYJKoZIhvcNAQEEBQADQQBFZDUWFl6BJdomtN1Bi53mwijy1rRgJ4YirF15yBEDM3DjAQkKXHYOIX+qpz4KXKnl6EYxTnGSFL5wWt8X2iyx | ||
| 90 | |||
| 91 | - You execute the ca command (either from a CGI program run out of | ||
| 92 | the web server, or as a later manual task) giving it the above | ||
| 93 | file as input. For example, if the file were named /tmp/cert.req, | ||
| 94 | you'd run: | ||
| 95 | $SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert | ||
| 96 | |||
| 97 | The output is in DER format (binary) if a -out argument is | ||
| 98 | provided, as above; otherwise, it's in the PEM format (base-64 | ||
| 99 | encoded DER). Also, the "-batch" switch is implied by the | ||
| 100 | "-spkac" so you don't get asked whether to complete the signing | ||
| 101 | (probably it shouldn't work this way but I was only interested | ||
| 102 | in hacking together an online CA that could be used for issuing | ||
| 103 | test certificates). | ||
| 104 | |||
| 105 | The "-spkac" capability doesn't support multiple files (I think). | ||
| 106 | |||
| 107 | Any CHALLENGE provided in the SPKAC is simply ignored. | ||
| 108 | |||
| 109 | The interactions between the identification fields you provide | ||
| 110 | and those identified in your lib/ssleay.conf are the same as if | ||
| 111 | you did an ordinary "ca -in infile -out outfile" -- that is, if | ||
| 112 | something is marked as required in the ssleay.conf file and it | ||
| 113 | isn't found in the -spkac file, the certificate won't be issued. | ||
| 114 | |||
| 115 | - Now, you pick up the output from /tmp/cert and pass it back to | ||
| 116 | the Navigator prepending the Content-type string described earlier. | ||
| 117 | |||
| 118 | - In order to run the ca command out of a CGI program, you must | ||
| 119 | provide a password to decrypt the CA's private key. You can | ||
| 120 | do this by using "echo MyKeyPassword | $SSLDIR/bin/ca ..." | ||
| 121 | I think there's a way to not encrypt the key file in the first | ||
| 122 | place, but I didn't see how to do that, so I made a small change | ||
| 123 | to the library that allows the password to be accepted from a pipe. | ||
| 124 | Either way is UTTERLY INSECURE and a real CA would never do that. | ||
| 125 | |||
| 126 | [ You can use the 'ssleay rsa' command to remove the password | ||
| 127 | from the private key, or you can use the '-key' option to the | ||
| 128 | ca command to specify the decryption key on the command line | ||
| 129 | or use the -nodes option when generating the key. | ||
| 130 | ca will try to clear the command line version of the password | ||
| 131 | but for quite a few operating systems, this is not possible. | ||
| 132 | - eric ] | ||
| 133 | |||
| 134 | So, what do you have to do to make use of this stuff to create an online | ||
| 135 | demo CA capability with SSLeay? | ||
| 136 | |||
| 137 | 1 Create an HTML form for your users. The form should contain | ||
| 138 | fields for all of the required or optional fields in ssleay.conf. | ||
| 139 | The form must contain a KEYGEN tag somewhere with at least a NAME | ||
| 140 | attribute. | ||
| 141 | |||
| 142 | 2 Create a CGI program to process the form input submitted by the | ||
| 143 | browser. The CGI program must URL-decode the variables and create | ||
| 144 | the file described above, containing subject identification info | ||
| 145 | as well as the SPKAC block. It should then run the the ca program | ||
| 146 | with the -spkac option. If it works (check the exit status), | ||
| 147 | return the new certificate with the appropriate MIME type. If not, | ||
| 148 | return the output of the ca command with MIME type "text/plain". | ||
| 149 | |||
| 150 | 3 Set up your web server to accept connections signed by your demo | ||
| 151 | CA. This probably involves obtaining the PEM-encoded CA certificate | ||
| 152 | (ordinarily in $SSLDIR/CA/cacert.pem) and installing it into a | ||
| 153 | server database. See your server manual for instructions. | ||
| 154 | |||
diff --git a/src/lib/libssl/src/doc/obj.doc b/src/lib/libssl/src/doc/obj.doc deleted file mode 100644 index bad347c936..0000000000 --- a/src/lib/libssl/src/doc/obj.doc +++ /dev/null | |||
| @@ -1,69 +0,0 @@ | |||
| 1 | The Object library. | ||
| 2 | |||
| 3 | As part of my Crypto library, I found I required a method of identifying various | ||
| 4 | objects. These objects normally had 3 different values associated with | ||
| 5 | them, a short text name, a long (or lower case) text name, and an | ||
| 6 | ASN.1 Object Identifier (which is a sequence of numbers). | ||
| 7 | This library contains a static list of objects and functions to lookup | ||
| 8 | according to one type and to return the other types. | ||
| 9 | |||
| 10 | To use these routines, 'Object.h' needs to be included. | ||
| 11 | |||
| 12 | For each supported object, #define entries are defined as follows | ||
| 13 | #define SN_Algorithm "Algorithm" | ||
| 14 | #define LN_algorithm "algorithm" | ||
| 15 | #define NID_algorithm 38 | ||
| 16 | #define OBJ_algorithm 1L,3L,14L,3L,2L | ||
| 17 | |||
| 18 | SN_ stands for short name. | ||
| 19 | LN_ stands for either long name or lowercase name. | ||
| 20 | NID_ stands for Numeric ID. I each object has a unique NID and this | ||
| 21 | should be used internally to identify objects. | ||
| 22 | OBJ_ stands for ASN.1 Object Identifier or ASN1_OBJECT as defined in the | ||
| 23 | ASN1 routines. These values are used in ASN1 encoding. | ||
| 24 | |||
| 25 | The following functions are to be used to return pointers into a static | ||
| 26 | definition of these types. What this means is "don't try to free() any | ||
| 27 | pointers returned from these functions. | ||
| 28 | |||
| 29 | ASN1_OBJECT *OBJ_nid2obj( | ||
| 30 | int n); | ||
| 31 | Return the ASN1_OBJECT that corresponds to a NID of n. | ||
| 32 | |||
| 33 | char *OBJ_nid2ln( | ||
| 34 | int n); | ||
| 35 | Return the long/lower case name of the object represented by the | ||
| 36 | NID of n. | ||
| 37 | |||
| 38 | char *OBJ_nid2sn( | ||
| 39 | int n); | ||
| 40 | Return the short name for the object represented by the NID of n. | ||
| 41 | |||
| 42 | ASN1_OBJECT *OBJ_dup( | ||
| 43 | ASN1_OBJECT *o); | ||
| 44 | Duplicate and return a new ASN1_OBJECT that is the same as the | ||
| 45 | passed parameter. | ||
| 46 | |||
| 47 | int OBJ_obj2nid( | ||
| 48 | ASN1_OBJECT *o); | ||
| 49 | Given ASN1_OBJECT o, return the NID that corresponds. | ||
| 50 | |||
| 51 | int OBJ_ln2nid( | ||
| 52 | char *s); | ||
| 53 | Given the long/lower case name 's', return the NID of the object. | ||
| 54 | |||
| 55 | int OBJ_sn2nid( | ||
| 56 | char *s); | ||
| 57 | Given the short name 's', return the NID of the object. | ||
| 58 | |||
| 59 | char *OBJ_bsearch( | ||
| 60 | char *key, | ||
| 61 | char *base, | ||
| 62 | int num, | ||
| 63 | int size, | ||
| 64 | int (*cmp)()); | ||
| 65 | Since I have come across a few platforms that do not have the | ||
| 66 | bsearch() function, OBJ_bsearch is my version of that function. | ||
| 67 | Feel free to use this function, but you may as well just use the | ||
| 68 | normal system bsearch(3) if it is present. This version also | ||
| 69 | has tolerance of being passed NULL pointers. | ||
diff --git a/src/lib/libssl/src/doc/openssl.pod b/src/lib/libssl/src/doc/openssl.pod new file mode 100644 index 0000000000..561f01e0ca --- /dev/null +++ b/src/lib/libssl/src/doc/openssl.pod | |||
| @@ -0,0 +1,304 @@ | |||
| 1 | |||
| 2 | =pod | ||
| 3 | |||
| 4 | =head1 NAME | ||
| 5 | |||
| 6 | openssl - OpenSSL command line tool | ||
| 7 | |||
| 8 | =head1 SYNOPSIS | ||
| 9 | |||
| 10 | B<openssl> | ||
| 11 | I<command> | ||
| 12 | [ I<command_opts> ] | ||
| 13 | [ I<command_args> ] | ||
| 14 | |||
| 15 | =head1 DESCRIPTION | ||
| 16 | |||
| 17 | OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL | ||
| 18 | v2/v3) and Transport Layer Security (TLS v1) network protocols and related | ||
| 19 | cryptography standards required by them. | ||
| 20 | |||
| 21 | The B<openssl> program is a command line tool for using the various | ||
| 22 | cryptography functions of OpenSSL's B<crypto> library from the shell. | ||
| 23 | It can be used for | ||
| 24 | |||
| 25 | o Creation of RSA, DH and DSA key parameters | ||
| 26 | o Creation of X.509 certificates, CSRs and CRLs | ||
| 27 | o Calculation of Message Digests | ||
| 28 | o Encryption and Decryption with Ciphers | ||
| 29 | o SSL/TLS Client and Server Tests | ||
| 30 | |||
| 31 | =head1 COMMAND SUMMARY | ||
| 32 | |||
| 33 | The B<openssl> program provides a rich variety of commands (I<command> in the | ||
| 34 | SYNOPSIS above), each of which often has a wealth of options and arguments | ||
| 35 | (I<command_opts> and I<command_args> in the SYNOPSIS). | ||
| 36 | |||
| 37 | =head2 STANDARD COMMANDS | ||
| 38 | |||
| 39 | =over 10 | ||
| 40 | |||
| 41 | =item B<asn1parse> | ||
| 42 | |||
| 43 | Parse an ASN.1 sequence. | ||
| 44 | |||
| 45 | =item B<ca> | ||
| 46 | |||
| 47 | Certificate Authority (CA) Management. | ||
| 48 | |||
| 49 | =item B<ciphers> | ||
| 50 | |||
| 51 | Cipher Suite Description Determination. | ||
| 52 | |||
| 53 | =item B<crl> | ||
| 54 | |||
| 55 | Certificate Revocation List (CRL) Management. | ||
| 56 | |||
| 57 | =item B<crl2pkcs7> | ||
| 58 | |||
| 59 | CRL2 to PKCS#7 Conversion. | ||
| 60 | |||
| 61 | =item B<dgst> | ||
| 62 | |||
| 63 | Message Digest Calculation. | ||
| 64 | |||
| 65 | =item B<dh> | ||
| 66 | |||
| 67 | Diffie-Hellman Data Management. | ||
| 68 | |||
| 69 | =item B<dsa> | ||
| 70 | |||
| 71 | DSA Data Management. | ||
| 72 | |||
| 73 | =item B<dsaparam> | ||
| 74 | |||
| 75 | DSA Parameter Generation. | ||
| 76 | |||
| 77 | =item B<enc> | ||
| 78 | |||
| 79 | Encoding with Ciphers. | ||
| 80 | |||
| 81 | =item B<errstr> | ||
| 82 | |||
| 83 | Error Number to Error String Conversion. | ||
| 84 | |||
| 85 | =item B<gendh> | ||
| 86 | |||
| 87 | Generation of Diffie-Hellman Parameters. | ||
| 88 | |||
| 89 | =item B<gendsa> | ||
| 90 | |||
| 91 | Generation of DSA Parameters. | ||
| 92 | |||
| 93 | =item B<genrsa> | ||
| 94 | |||
| 95 | Generation of RSA Parameters. | ||
| 96 | |||
| 97 | =item B<pkcs7> | ||
| 98 | |||
| 99 | PKCS#7 Data Management. | ||
| 100 | |||
| 101 | =item B<req> | ||
| 102 | |||
| 103 | X.509 Certificate Signing Request (CSR) Management. | ||
| 104 | |||
| 105 | =item B<rsa> | ||
| 106 | |||
| 107 | RSA Data Management. | ||
| 108 | |||
| 109 | =item B<s_client> | ||
| 110 | |||
| 111 | This implements a generic SSL/TLS client which can establish a transparent | ||
| 112 | connection to a remote server speaking SSL/TLS. It's intended for testing | ||
| 113 | purposes only and provides only rudimentary interface functionality but | ||
| 114 | internally uses mostly all functionality of the OpenSSL B<ssl> library. | ||
| 115 | |||
| 116 | =item B<s_server> | ||
| 117 | |||
| 118 | This implements a generic SSL/TLS server which accepts connections from remote | ||
| 119 | clients speaking SSL/TLS. It's intended for testing purposes only and provides | ||
| 120 | only rudimentary interface functionality but internally uses mostly all | ||
| 121 | functionality of the OpenSSL B<ssl> library. It provides both an own command | ||
| 122 | line oriented protocol for testing SSL functions and a simple HTTP response | ||
| 123 | facility to emulate an SSL/TLS-aware webserver. | ||
| 124 | |||
| 125 | =item B<s_time> | ||
| 126 | |||
| 127 | SSL Connection Timer. | ||
| 128 | |||
| 129 | =item B<sess_id> | ||
| 130 | |||
| 131 | SSL Session Data Management. | ||
| 132 | |||
| 133 | =item B<speed> | ||
| 134 | |||
| 135 | Algorithm Speed Measurement. | ||
| 136 | |||
| 137 | =item B<verify> | ||
| 138 | |||
| 139 | X.509 Certificate Verification. | ||
| 140 | |||
| 141 | =item B<version> | ||
| 142 | |||
| 143 | OpenSSL Version Information. | ||
| 144 | |||
| 145 | =item B<x509> | ||
| 146 | |||
| 147 | X.509 Certificate Data Management. | ||
| 148 | |||
| 149 | =back | ||
| 150 | |||
| 151 | =head2 MESSAGE DIGEST COMMANDS | ||
| 152 | |||
| 153 | =over 10 | ||
| 154 | |||
| 155 | =item B<md2> | ||
| 156 | |||
| 157 | MD2 Digest | ||
| 158 | |||
| 159 | =item B<md5> | ||
| 160 | |||
| 161 | MD5 Digest | ||
| 162 | |||
| 163 | =item B<mdc2> | ||
| 164 | |||
| 165 | MDC2 Digest | ||
| 166 | |||
| 167 | =item B<rmd160> | ||
| 168 | |||
| 169 | RMD-160 Digest | ||
| 170 | |||
| 171 | =item B<sha> | ||
| 172 | |||
| 173 | SHA Digest | ||
| 174 | |||
| 175 | =item B<sha1> | ||
| 176 | |||
| 177 | SHA-1 Digest | ||
| 178 | |||
| 179 | =back | ||
| 180 | |||
| 181 | =head2 ENCODING AND CIPHER COMMANDS | ||
| 182 | |||
| 183 | =over 10 | ||
| 184 | |||
| 185 | =item B<base64> | ||
| 186 | |||
| 187 | Base64 Encoding | ||
| 188 | |||
| 189 | =item B<bf bf-cbc bf-cfb bf-ecb bf-ofb> | ||
| 190 | |||
| 191 | Blowfish Cipher | ||
| 192 | |||
| 193 | =item B<cast cast-cbc> | ||
| 194 | |||
| 195 | CAST Cipher | ||
| 196 | |||
| 197 | =item B<cast5-cbc cast5-cfb cast5-ecb cast5-ofb> | ||
| 198 | |||
| 199 | CAST5 Cipher | ||
| 200 | |||
| 201 | =item B<des des-cbc des-cfb des-ecb des-ede des-ede-cbc des-ede-cfb des-ede-ofb des-ofb> | ||
| 202 | |||
| 203 | DES Cipher | ||
| 204 | |||
| 205 | =item B<des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb> | ||
| 206 | |||
| 207 | Triple-DES Cipher | ||
| 208 | |||
| 209 | =item B<idea idea-cbc idea-cfb idea-ecb idea-ofb> | ||
| 210 | |||
| 211 | IDEA Cipher | ||
| 212 | |||
| 213 | =item B<rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb> | ||
| 214 | |||
| 215 | RC2 Cipher | ||
| 216 | |||
| 217 | =item B<rc4> | ||
| 218 | |||
| 219 | RC4 Cipher | ||
| 220 | |||
| 221 | =item B<rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb> | ||
| 222 | |||
| 223 | RC5 Cipher | ||
| 224 | |||
| 225 | =back | ||
| 226 | |||
| 227 | =head1 DETAILED COMMAND DESCRIPTION | ||
| 228 | |||
| 229 | The following is a detailed description of every B<openssl> I<command>. | ||
| 230 | |||
| 231 | =over 4 | ||
| 232 | |||
| 233 | =item B<openssl> B<s_client> | ||
| 234 | [B<-connect> I<host>B<:>I<port>] | ||
| 235 | [B<-verify> I<arg>] | ||
| 236 | [B<-cert> I<arg>] | ||
| 237 | [B<-key> I<arg>] | ||
| 238 | [B<-CApath> I<arg>] | ||
| 239 | [B<-CAfile> I<arg>] | ||
| 240 | [B<-reconnect>] | ||
| 241 | [B<-pause>] | ||
| 242 | [B<-debug>] | ||
| 243 | [B<-nbio_test>] | ||
| 244 | [B<-state>] | ||
| 245 | [B<-nbio>] | ||
| 246 | [B<-quiet>] | ||
| 247 | [B<-ssl2>] | ||
| 248 | [B<-ssl3>] | ||
| 249 | [B<-tls1>] | ||
| 250 | [B<-no_ssl2>] | ||
| 251 | [B<-no_ssl3>] | ||
| 252 | [B<-no_tls1>] | ||
| 253 | [B<-bugs>] | ||
| 254 | [B<-cipher>] | ||
| 255 | |||
| 256 | The B<s_client> command implements a generic SSL/TLS client which can | ||
| 257 | establish a transparent connection to a remote I<host> and I<port> speaking | ||
| 258 | SSL/TLS. | ||
| 259 | |||
| 260 | =item B<openssl> B<s_server> | ||
| 261 | [B<-accept> I<port>] | ||
| 262 | [B<-verify> I<arg>] | ||
| 263 | [B<-Verify> I<arg>] | ||
| 264 | [B<-cert> I<arg>] | ||
| 265 | [B<-key> I<arg>] | ||
| 266 | [B<-dcert> I<arg>] | ||
| 267 | [B<-dkey> I<arg>] | ||
| 268 | [B<-nbio>] | ||
| 269 | [B<-nbio_test>] | ||
| 270 | [B<-debug>] | ||
| 271 | [B<-state>] | ||
| 272 | [B<-CApath> I<arg>] | ||
| 273 | [B<-CAfile> I<arg>] | ||
| 274 | [B<-nocert>] | ||
| 275 | [B<-cipher> I<arg>] | ||
| 276 | [B<-quiet>] | ||
| 277 | [B<-no_tmp_rsa>] | ||
| 278 | [B<-ssl2>] | ||
| 279 | [B<-ssl3>] | ||
| 280 | [B<-tls1>] | ||
| 281 | [B<-no_ssl2>] | ||
| 282 | [B<-no_ssl3>] | ||
| 283 | [B<-no_tls1>] | ||
| 284 | [B<-bugs>] | ||
| 285 | [B<-www>] | ||
| 286 | [B<-WWW>] | ||
| 287 | |||
| 288 | The B<s_server> command implements a generic SSL/TLS server which accepts | ||
| 289 | connections from remote clients on I<port> speaking SSL/TLS. | ||
| 290 | |||
| 291 | =back | ||
| 292 | |||
| 293 | ... | ||
| 294 | |||
| 295 | =head1 SEE ALSO | ||
| 296 | |||
| 297 | crypto(3), ssl(3) | ||
| 298 | |||
| 299 | =head1 HISTORY | ||
| 300 | |||
| 301 | The openssl(3) document appeared in OpenSSL 0.9.2 | ||
| 302 | |||
| 303 | =cut | ||
| 304 | |||
diff --git a/src/lib/libssl/src/doc/openssl.txt b/src/lib/libssl/src/doc/openssl.txt new file mode 100644 index 0000000000..91b85e5f14 --- /dev/null +++ b/src/lib/libssl/src/doc/openssl.txt | |||
| @@ -0,0 +1,1174 @@ | |||
| 1 | |||
| 2 | This is some preliminary documentation for OpenSSL. | ||
| 3 | |||
| 4 | ============================================================================== | ||
| 5 | BUFFER Library | ||
| 6 | ============================================================================== | ||
| 7 | |||
| 8 | The buffer library handles simple character arrays. Buffers are used for | ||
| 9 | various purposes in the library, most notably memory BIOs. | ||
| 10 | |||
| 11 | The library uses the BUF_MEM structure defined in buffer.h: | ||
| 12 | |||
| 13 | typedef struct buf_mem_st | ||
| 14 | { | ||
| 15 | int length; /* current number of bytes */ | ||
| 16 | char *data; | ||
| 17 | int max; /* size of buffer */ | ||
| 18 | } BUF_MEM; | ||
| 19 | |||
| 20 | 'length' is the current size of the buffer in bytes, 'max' is the amount of | ||
| 21 | memory allocated to the buffer. There are three functions which handle these | ||
| 22 | and one "miscellaneous" function. | ||
| 23 | |||
| 24 | BUF_MEM *BUF_MEM_new() | ||
| 25 | |||
| 26 | This allocates a new buffer of zero size. Returns the buffer or NULL on error. | ||
| 27 | |||
| 28 | void BUF_MEM_free(BUF_MEM *a) | ||
| 29 | |||
| 30 | This frees up an already existing buffer. The data is zeroed before freeing | ||
| 31 | up in case the buffer contains sensitive data. | ||
| 32 | |||
| 33 | int BUF_MEM_grow(BUF_MEM *str, int len) | ||
| 34 | |||
| 35 | This changes the size of an already existing buffer. It returns zero on error | ||
| 36 | or the new size (i.e. 'len'). Any data already in the buffer is preserved if | ||
| 37 | it increases in size. | ||
| 38 | |||
| 39 | char * BUF_strdup(char *str) | ||
| 40 | |||
| 41 | This is the previously mentioned strdup function: like the standard library | ||
| 42 | strdup() it copies a null terminated string into a block of allocated memory | ||
| 43 | and returns a pointer to the allocated block. | ||
| 44 | |||
| 45 | Unlike the standard C library strdup() this function uses Malloc() and so | ||
| 46 | should be used in preference to the standard library strdup() because it can | ||
| 47 | be used for memory leak checking or replacing the malloc() function. | ||
| 48 | |||
| 49 | The memory allocated from BUF_strdup() should be freed up using the Free() | ||
| 50 | function. | ||
| 51 | |||
| 52 | ============================================================================== | ||
| 53 | OpenSSL X509V3 extension configuration | ||
| 54 | ============================================================================== | ||
| 55 | |||
| 56 | OpenSSL X509V3 extension configuration: preliminary documentation. | ||
| 57 | |||
| 58 | INTRODUCTION. | ||
| 59 | |||
| 60 | For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now | ||
| 61 | possible to add and print out common X509 V3 certificate and CRL extensions. | ||
| 62 | |||
| 63 | BEGINNERS NOTE | ||
| 64 | |||
| 65 | For most simple applications you don't need to know too much about extensions: | ||
| 66 | the default openssl.cnf values will usually do sensible things. | ||
| 67 | |||
| 68 | If you want to know more you can initially quickly look through the sections | ||
| 69 | describing how the standard OpenSSL utilities display and add extensions and | ||
| 70 | then the list of supported extensions. | ||
| 71 | |||
| 72 | For more technical information about the meaning of extensions see: | ||
| 73 | |||
| 74 | http://www.imc.org/ietf-pkix/ | ||
| 75 | http://home.netscape.com/eng/security/certs.html | ||
| 76 | |||
| 77 | PRINTING EXTENSIONS. | ||
| 78 | |||
| 79 | Extension values are automatically printed out for supported extensions. | ||
| 80 | |||
| 81 | openssl x509 -in cert.pem -text | ||
| 82 | openssl crl -in crl.pem -text | ||
| 83 | |||
| 84 | will give information in the extension printout, for example: | ||
| 85 | |||
| 86 | X509v3 extensions: | ||
| 87 | X509v3 Basic Constraints: | ||
| 88 | CA:TRUE | ||
| 89 | X509v3 Subject Key Identifier: | ||
| 90 | 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15 | ||
| 91 | X509v3 Authority Key Identifier: | ||
| 92 | keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00 | ||
| 93 | X509v3 Key Usage: | ||
| 94 | Certificate Sign, CRL Sign | ||
| 95 | X509v3 Subject Alternative Name: | ||
| 96 | email:email@1.address, email:email@2.address | ||
| 97 | |||
| 98 | CONFIGURATION FILES. | ||
| 99 | |||
| 100 | The OpenSSL utilities 'ca' and 'req' can now have extension sections listing | ||
| 101 | which certificate extensions to include. In each case a line: | ||
| 102 | |||
| 103 | x509_extensions = extension_section | ||
| 104 | |||
| 105 | indicates which section contains the extensions. In the case of 'req' the | ||
| 106 | extension section is used when the -x509 option is present to create a | ||
| 107 | self signed root certificate. | ||
| 108 | |||
| 109 | The 'x509' utility also supports extensions when it signs a certificate. | ||
| 110 | The -extfile option is used to set the configuration file containing the | ||
| 111 | extensions. In this case a line with: | ||
| 112 | |||
| 113 | extensions = extension_section | ||
| 114 | |||
| 115 | in the nameless (default) section is used. If no such line is included then | ||
| 116 | it uses the default section. | ||
| 117 | |||
| 118 | You can also add extensions to CRLs: a line | ||
| 119 | |||
| 120 | crl_extensions = crl_extension_section | ||
| 121 | |||
| 122 | will include extensions when the -gencrl option is used with the 'ca' utility. | ||
| 123 | You can add any extension to a CRL but of the supported extensions only | ||
| 124 | issuerAltName and authorityKeyIdentifier make any real sense. Note: these are | ||
| 125 | CRL extensions NOT CRL *entry* extensions which cannot currently be generated. | ||
| 126 | CRL entry extensions can be displayed. | ||
| 127 | |||
| 128 | NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL | ||
| 129 | you should not include a crl_extensions line in the configuration file. | ||
| 130 | |||
| 131 | As with all configuration files you can use the inbuilt environment expansion | ||
| 132 | to allow the values to be passed in the environment. Therefore if you have | ||
| 133 | several extension sections used for different purposes you can have a line: | ||
| 134 | |||
| 135 | x509_extensions = $ENV::ENV_EXT | ||
| 136 | |||
| 137 | and set the ENV_EXT environment variable before calling the relevant utility. | ||
| 138 | |||
| 139 | EXTENSION SYNTAX. | ||
| 140 | |||
| 141 | Extensions have the basic form: | ||
| 142 | |||
| 143 | extension_name=[critical,] extension_options | ||
| 144 | |||
| 145 | the use of the critical option makes the extension critical. Extreme caution | ||
| 146 | should be made when using the critical flag. If an extension is marked | ||
| 147 | as critical then any client that does not understand the extension should | ||
| 148 | reject it as invalid. Some broken software will reject certificates which | ||
| 149 | have *any* critical extensions (these violates PKIX but we have to live | ||
| 150 | with it). | ||
| 151 | |||
| 152 | There are three main types of extension: string extensions, multi-valued | ||
| 153 | extensions, and raw extensions. | ||
| 154 | |||
| 155 | String extensions simply have a string which contains either the value itself | ||
| 156 | or how it is obtained. | ||
| 157 | |||
| 158 | For example: | ||
| 159 | |||
| 160 | nsComment="This is a Comment" | ||
| 161 | |||
| 162 | Multi-valued extensions have a short form and a long form. The short form | ||
| 163 | is a list of names and values: | ||
| 164 | |||
| 165 | basicConstraints=critical,CA:true,pathlen:1 | ||
| 166 | |||
| 167 | The long form allows the values to be placed in a separate section: | ||
| 168 | |||
| 169 | basicConstraints=critical,@bs_section | ||
| 170 | |||
| 171 | [bs_section] | ||
| 172 | |||
| 173 | CA=true | ||
| 174 | pathlen=1 | ||
| 175 | |||
| 176 | Both forms are equivalent. However it should be noted that in some cases the | ||
| 177 | same name can appear multiple times, for example, | ||
| 178 | |||
| 179 | subjectAltName=email:steve@here,email:steve@there | ||
| 180 | |||
| 181 | in this case an equivalent long form is: | ||
| 182 | |||
| 183 | subjectAltName=@alt_section | ||
| 184 | |||
| 185 | [alt_section] | ||
| 186 | |||
| 187 | email.1=steve@here | ||
| 188 | email.2=steve@there | ||
| 189 | |||
| 190 | This is because the configuration file code cannot handle the same name | ||
| 191 | occurring twice in the same extension. | ||
| 192 | |||
| 193 | The syntax of raw extensions is governed by the extension code: it can | ||
| 194 | for example contain data in multiple sections. The correct syntax to | ||
| 195 | use is defined by the extension code itself: check out the certificate | ||
| 196 | policies extension for an example. | ||
| 197 | |||
| 198 | In addition it is also possible to use the word DER to include arbitrary | ||
| 199 | data in any extension. | ||
| 200 | |||
| 201 | 1.2.3.4=critical,DER:01:02:03:04 | ||
| 202 | 1.2.3.4=DER:01020304 | ||
| 203 | |||
| 204 | The value following DER is a hex dump of the DER encoding of the extension | ||
| 205 | Any extension can be placed in this form to override the default behaviour. | ||
| 206 | For example: | ||
| 207 | |||
| 208 | basicConstraints=critical,DER:00:01:02:03 | ||
| 209 | |||
| 210 | WARNING: DER should be used with caution. It is possible to create totally | ||
| 211 | invalid extensions unless care is taken. | ||
| 212 | |||
| 213 | CURRENTLY SUPPORTED EXTENSIONS. | ||
| 214 | |||
| 215 | If you aren't sure about extensions then they can be largely ignored: its only | ||
| 216 | when you want to do things like restrict certificate usage when you need to | ||
| 217 | worry about them. | ||
| 218 | |||
| 219 | The only extension that a beginner might want to look at is Basic Constraints. | ||
| 220 | If in addition you want to try Netscape object signing the you should also | ||
| 221 | look at Netscape Certificate Type. | ||
| 222 | |||
| 223 | Literal String extensions. | ||
| 224 | |||
| 225 | In each case the 'value' of the extension is placed directly in the | ||
| 226 | extension. Currently supported extensions in this category are: nsBaseUrl, | ||
| 227 | nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, | ||
| 228 | nsSslServerName and nsComment. | ||
| 229 | |||
| 230 | For example: | ||
| 231 | |||
| 232 | nsComment="This is a test comment" | ||
| 233 | |||
| 234 | Bit Strings. | ||
| 235 | |||
| 236 | Bit string extensions just consist of a list of supported bits, currently | ||
| 237 | two extensions are in this category: PKIX keyUsage and the Netscape specific | ||
| 238 | nsCertType. | ||
| 239 | |||
| 240 | nsCertType (netscape certificate type) takes the flags: client, server, email, | ||
| 241 | objsign, reserved, sslCA, emailCA, objCA. | ||
| 242 | |||
| 243 | keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation, | ||
| 244 | keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, | ||
| 245 | encipherOnly, decipherOnly. | ||
| 246 | |||
| 247 | For example: | ||
| 248 | |||
| 249 | nsCertType=server | ||
| 250 | |||
| 251 | keyUsage=digitalSignature, nonRepudiation | ||
| 252 | |||
| 253 | Hints on Netscape Certificate Type. | ||
| 254 | |||
| 255 | Other than Basic Constraints this is the only extension a beginner might | ||
| 256 | want to use, if you want to try Netscape object signing, otherwise it can | ||
| 257 | be ignored. | ||
| 258 | |||
| 259 | If you want a certificate that can be used just for object signing then: | ||
| 260 | |||
| 261 | nsCertType=objsign | ||
| 262 | |||
| 263 | will do the job. If you want to use it as a normal end user and server | ||
| 264 | certificate as well then | ||
| 265 | |||
| 266 | nsCertType=objsign,email,server | ||
| 267 | |||
| 268 | is more appropriate. You cannot use a self signed certificate for object | ||
| 269 | signing (well Netscape signtool can but it cheats!) so you need to create | ||
| 270 | a CA certificate and sign an end user certificate with it. | ||
| 271 | |||
| 272 | Side note: If you want to conform to the Netscape specifications then you | ||
| 273 | should really also set: | ||
| 274 | |||
| 275 | nsCertType=objCA | ||
| 276 | |||
| 277 | in the *CA* certificate for just an object signing CA and | ||
| 278 | |||
| 279 | nsCertType=objCA,emailCA,sslCA | ||
| 280 | |||
| 281 | for everything. Current Netscape software doesn't enforce this so it can | ||
| 282 | be omitted. | ||
| 283 | |||
| 284 | Basic Constraints. | ||
| 285 | |||
| 286 | This is generally the only extension you need to worry about for simple | ||
| 287 | applications. If you want your certificate to be usable as a CA certificate | ||
| 288 | (in addition to an end user certificate) then you set this to: | ||
| 289 | |||
| 290 | basicConstraints=CA:TRUE | ||
| 291 | |||
| 292 | if you want to be certain the certificate cannot be used as a CA then do: | ||
| 293 | |||
| 294 | basicConstraints=CA:FALSE | ||
| 295 | |||
| 296 | The rest of this section describes more advanced usage. | ||
| 297 | |||
| 298 | Basic constraints is a multi-valued extension that supports a CA and an | ||
| 299 | optional pathlen option. The CA option takes the values true and false and | ||
| 300 | pathlen takes an integer. Note if the CA option is false the pathlen option | ||
| 301 | should be omitted. | ||
| 302 | |||
| 303 | The pathlen parameter indicates the maximum number of CAs that can appear | ||
| 304 | below this one in a chain. So if you have a CA with a pathlen of zero it can | ||
| 305 | only be used to sign end user certificates and not further CAs. This all | ||
| 306 | assumes that the software correctly interprets this extension of course. | ||
| 307 | |||
| 308 | Examples: | ||
| 309 | |||
| 310 | basicConstraints=CA:TRUE | ||
| 311 | basicConstraints=critical,CA:TRUE, pathlen:0 | ||
| 312 | |||
| 313 | NOTE: for a CA to be considered valid it must have the CA option set to | ||
| 314 | TRUE. An end user certificate MUST NOT have the CA value set to true. | ||
| 315 | According to PKIX recommendations it should exclude the extension entirely, | ||
| 316 | however some software may require CA set to FALSE for end entity certificates. | ||
| 317 | |||
| 318 | Subject Key Identifier. | ||
| 319 | |||
| 320 | This is really a string extension and can take two possible values. Either | ||
| 321 | a hex string giving details of the extension value to include or the word | ||
| 322 | 'hash' which then automatically follow PKIX guidelines in selecting and | ||
| 323 | appropriate key identifier. The use of the hex string is strongly discouraged. | ||
| 324 | |||
| 325 | Example: subjectKeyIdentifier=hash | ||
| 326 | |||
| 327 | Authority Key Identifier. | ||
| 328 | |||
| 329 | The authority key identifier extension permits two options. keyid and issuer: | ||
| 330 | both can take the optional value "always". | ||
| 331 | |||
| 332 | If the keyid option is present an attempt is made to copy the subject key | ||
| 333 | identifier from the parent certificate. If the value "always" is present | ||
| 334 | then an error is returned if the option fails. | ||
| 335 | |||
| 336 | The issuer option copies the issuer and serial number from the issuer | ||
| 337 | certificate. Normally this will only be done if the keyid option fails or | ||
| 338 | is not included: the "always" flag will always include the value. | ||
| 339 | |||
| 340 | Subject Alternative Name. | ||
| 341 | |||
| 342 | The subject alternative name extension allows various literal values to be | ||
| 343 | included in the configuration file. These include "email" (an email address) | ||
| 344 | "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a | ||
| 345 | registered ID: OBJECT IDENTIFIER) and IP (and IP address). | ||
| 346 | |||
| 347 | Also the email option include a special 'copy' value. This will automatically | ||
| 348 | include and email addresses contained in the certificate subject name in | ||
| 349 | the extension. | ||
| 350 | |||
| 351 | Examples: | ||
| 352 | |||
| 353 | subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/ | ||
| 354 | subjectAltName=email:my@other.address,RID:1.2.3.4 | ||
| 355 | |||
| 356 | Issuer Alternative Name. | ||
| 357 | |||
| 358 | The issuer alternative name option supports all the literal options of | ||
| 359 | subject alternative name. It does *not* support the email:copy option because | ||
| 360 | that would not make sense. It does support an additional issuer:copy option | ||
| 361 | that will copy all the subject alternative name values from the issuer | ||
| 362 | certificate (if possible). | ||
| 363 | |||
| 364 | CRL distribution points. | ||
| 365 | |||
| 366 | This is a multi-valued extension that supports all the literal options of | ||
| 367 | subject alternative name. Of the few software packages that currently interpret | ||
| 368 | this extension most only interpret the URI option. | ||
| 369 | |||
| 370 | Currently each option will set a new DistributionPoint with the fullName | ||
| 371 | field set to the given value. | ||
| 372 | |||
| 373 | Other fields like cRLissuer and reasons cannot currently be set or displayed: | ||
| 374 | at this time no examples were available that used these fields. | ||
| 375 | |||
| 376 | If you see this extension with <UNSUPPORTED> when you attempt to print it out | ||
| 377 | or it doesn't appear to display correctly then let me know, including the | ||
| 378 | certificate (mail me at steve@openssl.org) . | ||
| 379 | |||
| 380 | Examples: | ||
| 381 | |||
| 382 | crlDistributionPoints=URI:http://www.myhost.com/myca.crl | ||
| 383 | crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl | ||
| 384 | |||
| 385 | Certificate Policies. | ||
| 386 | |||
| 387 | This is a RAW extension. It attempts to display the contents of this extension: | ||
| 388 | unfortunately this extension is often improperly encoded. | ||
| 389 | |||
| 390 | The certificate policies extension will rarely be used in practice: few | ||
| 391 | software packages interpret it correctly or at all. IE5 does partially | ||
| 392 | support this extension: but it needs the 'ia5org' option because it will | ||
| 393 | only correctly support a broken encoding. Of the options below only the | ||
| 394 | policy OID, explicitText and CPS options are displayed with IE5. | ||
| 395 | |||
| 396 | All the fields of this extension can be set by using the appropriate syntax. | ||
| 397 | |||
| 398 | If you follow the PKIX recommendations of not including any qualifiers and just | ||
| 399 | using only one OID then you just include the value of that OID. Multiple OIDs | ||
| 400 | can be set separated by commas, for example: | ||
| 401 | |||
| 402 | certificatePolicies= 1.2.4.5, 1.1.3.4 | ||
| 403 | |||
| 404 | If you wish to include qualifiers then the policy OID and qualifiers need to | ||
| 405 | be specified in a separate section: this is done by using the @section syntax | ||
| 406 | instead of a literal OID value. | ||
| 407 | |||
| 408 | The section referred to must include the policy OID using the name | ||
| 409 | policyIdentifier, cPSuri qualifiers can be included using the syntax: | ||
| 410 | |||
| 411 | CPS.nnn=value | ||
| 412 | |||
| 413 | userNotice qualifiers can be set using the syntax: | ||
| 414 | |||
| 415 | userNotice.nnn=@notice | ||
| 416 | |||
| 417 | The value of the userNotice qualifier is specified in the relevant section. | ||
| 418 | This section can include explicitText, organization and noticeNumbers | ||
| 419 | options. explicitText and organization are text strings, noticeNumbers is a | ||
| 420 | comma separated list of numbers. The organization and noticeNumbers options | ||
| 421 | (if included) must BOTH be present. If you use the userNotice option with IE5 | ||
| 422 | then you need the 'ia5org' option at the top level to modify the encoding: | ||
| 423 | otherwise it will not be interpreted properly. | ||
| 424 | |||
| 425 | Example: | ||
| 426 | |||
| 427 | certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect | ||
| 428 | |||
| 429 | [polsect] | ||
| 430 | |||
| 431 | policyIdentifier = 1.3.5.8 | ||
| 432 | CPS.1="http://my.host.name/" | ||
| 433 | CPS.2="http://my.your.name/" | ||
| 434 | userNotice.1=@notice | ||
| 435 | |||
| 436 | [notice] | ||
| 437 | |||
| 438 | explicitText="Explicit Text Here" | ||
| 439 | organization="Organisation Name" | ||
| 440 | noticeNumbers=1,2,3,4 | ||
| 441 | |||
| 442 | TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field, | ||
| 443 | according to PKIX it should be of type DisplayText but Verisign uses an | ||
| 444 | IA5STRING and IE5 needs this too. | ||
| 445 | |||
| 446 | Display only extensions. | ||
| 447 | |||
| 448 | Some extensions are only partially supported and currently are only displayed | ||
| 449 | but cannot be set. These include private key usage period, CRL number, and | ||
| 450 | CRL reason. | ||
| 451 | |||
| 452 | ============================================================================== | ||
| 453 | X509V3 Extension code: programmers guide | ||
| 454 | ============================================================================== | ||
| 455 | |||
| 456 | The purpose of the extension code is twofold. It allows an extension to be | ||
| 457 | created from a string or structure describing its contents and it prints out an | ||
| 458 | extension in a human or machine readable form. | ||
| 459 | |||
| 460 | 1. Initialisation and cleanup. | ||
| 461 | |||
| 462 | X509V3_add_standard_extensions(); | ||
| 463 | |||
| 464 | This function should be called before any other extension code. It adds support | ||
| 465 | for some common PKIX and Netscape extensions. Additional custom extensions can | ||
| 466 | be added as well (see later). | ||
| 467 | |||
| 468 | void X509V3_EXT_cleanup(void); | ||
| 469 | |||
| 470 | This function should be called last to cleanup the extension code. After this | ||
| 471 | call no other extension calls should be made. | ||
| 472 | |||
| 473 | 2. Printing and parsing extensions. | ||
| 474 | |||
| 475 | The simplest way to print out extensions is via the standard X509 printing | ||
| 476 | routines: if you use the standard X509_print() function, the supported | ||
| 477 | extensions will be printed out automatically. | ||
| 478 | |||
| 479 | The following functions allow finer control over extension display: | ||
| 480 | |||
| 481 | int X509V3_EXT_print(BIO *out, X509_EXTENSION *ext, int flag, int indent); | ||
| 482 | int X509V3_EXT_print_fp(FILE *out, X509_EXTENSION *ext, int flag, int indent); | ||
| 483 | |||
| 484 | These two functions print out an individual extension to a BIO or FILE pointer. | ||
| 485 | Currently the flag argument is unused and should be set to 0. The 'indent' | ||
| 486 | argument is the number of spaces to indent each line. | ||
| 487 | |||
| 488 | void *X509V3_EXT_d2i(X509_EXTENSION *ext); | ||
| 489 | |||
| 490 | This function parses an extension and returns its internal structure. The | ||
| 491 | precise structure you get back depends on the extension being parsed. If the | ||
| 492 | extension if basicConstraints you will get back a pointer to a | ||
| 493 | BASIC_CONSTRAINTS structure. Check out the source in crypto/x509v3 for more | ||
| 494 | details about the structures returned. The returned structure should be freed | ||
| 495 | after use using the relevant free function, BASIC_CONSTRAINTS_free() for | ||
| 496 | example. | ||
| 497 | |||
| 498 | 3. Generating extensions. | ||
| 499 | |||
| 500 | An extension will typically be generated from a configuration file, or some | ||
| 501 | other kind of configuration database. | ||
| 502 | |||
| 503 | int X509V3_EXT_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, | ||
| 504 | X509 *cert); | ||
| 505 | int X509V3_EXT_CRL_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, | ||
| 506 | X509_CRL *crl); | ||
| 507 | |||
| 508 | These functions add all the extensions in the given section to the given | ||
| 509 | certificate or CRL. They will normally be called just before the certificate | ||
| 510 | or CRL is due to be signed. Both return 0 on error on non zero for success. | ||
| 511 | |||
| 512 | In each case 'conf' is the LHASH pointer of the configuration file to use | ||
| 513 | and 'section' is the section containing the extension details. | ||
| 514 | |||
| 515 | See the 'context functions' section for a description of the ctx paramater. | ||
| 516 | |||
| 517 | |||
| 518 | X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name, | ||
| 519 | char *value); | ||
| 520 | |||
| 521 | This function returns an extension based on a name and value pair, if the | ||
| 522 | pair will not need to access other sections in a config file (or there is no | ||
| 523 | config file) then the 'conf' parameter can be set to NULL. | ||
| 524 | |||
| 525 | X509_EXTENSION *X509V3_EXT_conf_nid(char *conf, X509V3_CTX *ctx, int nid, | ||
| 526 | char *value); | ||
| 527 | |||
| 528 | This function creates an extension in the same way as X509V3_EXT_conf() but | ||
| 529 | takes the NID of the extension rather than its name. | ||
| 530 | |||
| 531 | For example to produce basicConstraints with the CA flag and a path length of | ||
| 532 | 10: | ||
| 533 | |||
| 534 | x = X509V3_EXT_conf_nid(NULL, NULL, NID_basicConstraints, "CA:TRUE,pathlen:10"); | ||
| 535 | |||
| 536 | |||
| 537 | X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc); | ||
| 538 | |||
| 539 | This function sets up an extension from its internal structure. The ext_nid | ||
| 540 | parameter is the NID of the extension and 'crit' is the critical flag. | ||
| 541 | |||
| 542 | 4. Context functions. | ||
| 543 | |||
| 544 | The following functions set and manipulate an extension context structure. | ||
| 545 | The purpose of the extension context is to allow the extension code to | ||
| 546 | access various structures relating to the "environment" of the certificate: | ||
| 547 | for example the issuers certificate or the certificate request. | ||
| 548 | |||
| 549 | void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject, | ||
| 550 | X509_REQ *req, X509_CRL *crl, int flags); | ||
| 551 | |||
| 552 | This function sets up an X509V3_CTX structure with details of the certificate | ||
| 553 | environment: specifically the issuers certificate, the subject certificate, | ||
| 554 | the certificate request and the CRL: if these are not relevant or not | ||
| 555 | available then they can be set to NULL. The 'flags' parameter should be set | ||
| 556 | to zero. | ||
| 557 | |||
| 558 | X509V3_set_ctx_test(ctx) | ||
| 559 | |||
| 560 | This macro is used to set the 'ctx' structure to a 'test' value: this is to | ||
| 561 | allow the syntax of an extension (or configuration file) to be tested. | ||
| 562 | |||
| 563 | X509V3_set_ctx_nodb(ctx) | ||
| 564 | |||
| 565 | This macro is used when no configuration database is present. | ||
| 566 | |||
| 567 | void X509V3_set_conf_lhash(X509V3_CTX *ctx, LHASH *lhash); | ||
| 568 | |||
| 569 | This function is used to set the configuration database when it is an LHASH | ||
| 570 | structure: typically a configuration file. | ||
| 571 | |||
| 572 | The following functions are used to access a configuration database: they | ||
| 573 | should only be used in RAW extensions. | ||
| 574 | |||
| 575 | char * X509V3_get_string(X509V3_CTX *ctx, char *name, char *section); | ||
| 576 | |||
| 577 | This function returns the value of the parameter "name" in "section", or NULL | ||
| 578 | if there has been an error. | ||
| 579 | |||
| 580 | void X509V3_string_free(X509V3_CTX *ctx, char *str); | ||
| 581 | |||
| 582 | This function frees up the string returned by the above function. | ||
| 583 | |||
| 584 | STACK_OF(CONF_VALUE) * X509V3_get_section(X509V3_CTX *ctx, char *section); | ||
| 585 | |||
| 586 | This function returns a whole section as a STACK_OF(CONF_VALUE) . | ||
| 587 | |||
| 588 | void X509V3_section_free( X509V3_CTX *ctx, STACK_OF(CONF_VALUE) *section); | ||
| 589 | |||
| 590 | This function frees up the STACK returned by the above function. | ||
| 591 | |||
| 592 | Note: it is possible to use the extension code with a custom configuration | ||
| 593 | database. To do this the "db_meth" element of the X509V3_CTX structure should | ||
| 594 | be set to an X509V3_CTX_METHOD structure. This structure contains the following | ||
| 595 | function pointers: | ||
| 596 | |||
| 597 | char * (*get_string)(void *db, char *section, char *value); | ||
| 598 | STACK_OF(CONF_VALUE) * (*get_section)(void *db, char *section); | ||
| 599 | void (*free_string)(void *db, char * string); | ||
| 600 | void (*free_section)(void *db, STACK_OF(CONF_VALUE) *section); | ||
| 601 | |||
| 602 | these will be called and passed the 'db' element in the X509V3_CTX structure | ||
| 603 | to access the database. If a given function is not implemented or not required | ||
| 604 | it can be set to NULL. | ||
| 605 | |||
| 606 | 5. String helper functions. | ||
| 607 | |||
| 608 | There are several "i2s" and "s2i" functions that convert structures to and | ||
| 609 | from ASCII strings. In all the "i2s" cases the returned string should be | ||
| 610 | freed using Free() after use. Since some of these are part of other extension | ||
| 611 | code they may take a 'method' parameter. Unless otherwise stated it can be | ||
| 612 | safely set to NULL. | ||
| 613 | |||
| 614 | char *i2s_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, ASN1_OCTET_STRING *oct); | ||
| 615 | |||
| 616 | This returns a hex string from an ASN1_OCTET_STRING. | ||
| 617 | |||
| 618 | char * i2s_ASN1_INTEGER(X509V3_EXT_METHOD *meth, ASN1_INTEGER *aint); | ||
| 619 | char * i2s_ASN1_ENUMERATED(X509V3_EXT_METHOD *meth, ASN1_ENUMERATED *aint); | ||
| 620 | |||
| 621 | These return a string decimal representations of an ASN1_INTEGER and an | ||
| 622 | ASN1_ENUMERATED type, respectively. | ||
| 623 | |||
| 624 | ASN1_OCTET_STRING *s2i_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, | ||
| 625 | X509V3_CTX *ctx, char *str); | ||
| 626 | |||
| 627 | This converts an ASCII hex string to an ASN1_OCTET_STRING. | ||
| 628 | |||
| 629 | ASN1_INTEGER * s2i_ASN1_INTEGER(X509V3_EXT_METHOD *meth, char *value); | ||
| 630 | |||
| 631 | This converts a decimal ASCII string into an ASN1_INTEGER. | ||
| 632 | |||
| 633 | 6. Multi valued extension helper functions. | ||
| 634 | |||
| 635 | The following functions can be used to manipulate STACKs of CONF_VALUE | ||
| 636 | structures, as used by multi valued extensions. | ||
| 637 | |||
| 638 | int X509V3_get_value_bool(CONF_VALUE *value, int *asn1_bool); | ||
| 639 | |||
| 640 | This function expects a boolean value in 'value' and sets 'asn1_bool' to | ||
| 641 | it. That is it sets it to 0 for FALSE or 0xff for TRUE. The following | ||
| 642 | strings are acceptable: "TRUE", "true", "Y", "y", "YES", "yes", "FALSE" | ||
| 643 | "false", "N", "n", "NO" or "no". | ||
| 644 | |||
| 645 | int X509V3_get_value_int(CONF_VALUE *value, ASN1_INTEGER **aint); | ||
| 646 | |||
| 647 | This accepts a decimal integer of arbitrary length and sets an ASN1_INTEGER. | ||
| 648 | |||
| 649 | int X509V3_add_value(const char *name, const char *value, | ||
| 650 | STACK_OF(CONF_VALUE) **extlist); | ||
| 651 | |||
| 652 | This simply adds a string name and value pair. | ||
| 653 | |||
| 654 | int X509V3_add_value_uchar(const char *name, const unsigned char *value, | ||
| 655 | STACK_OF(CONF_VALUE) **extlist); | ||
| 656 | |||
| 657 | The same as above but for an unsigned character value. | ||
| 658 | |||
| 659 | int X509V3_add_value_bool(const char *name, int asn1_bool, | ||
| 660 | STACK_OF(CONF_VALUE) **extlist); | ||
| 661 | |||
| 662 | This adds either "TRUE" or "FALSE" depending on the value of 'ans1_bool' | ||
| 663 | |||
| 664 | int X509V3_add_value_bool_nf(char *name, int asn1_bool, | ||
| 665 | STACK_OF(CONF_VALUE) **extlist); | ||
| 666 | |||
| 667 | This is the same as above except it adds nothing if asn1_bool is FALSE. | ||
| 668 | |||
| 669 | int X509V3_add_value_int(const char *name, ASN1_INTEGER *aint, | ||
| 670 | STACK_OF(CONF_VALUE) **extlist); | ||
| 671 | |||
| 672 | This function adds the value of the ASN1_INTEGER in decimal form. | ||
| 673 | |||
| 674 | 7. Other helper functions. | ||
| 675 | |||
| 676 | <to be added> | ||
| 677 | |||
| 678 | ADDING CUSTOM EXTENSIONS. | ||
| 679 | |||
| 680 | Currently there are three types of supported extensions. | ||
| 681 | |||
| 682 | String extensions are simple strings where the value is placed directly in the | ||
| 683 | extensions, and the string returned is printed out. | ||
| 684 | |||
| 685 | Multi value extensions are passed a STACK_OF(CONF_VALUE) name and value pairs | ||
| 686 | or return a STACK_OF(CONF_VALUE). | ||
| 687 | |||
| 688 | Raw extensions are just passed a BIO or a value and it is the extensions | ||
| 689 | responsiblity to handle all the necessary printing. | ||
| 690 | |||
| 691 | There are two ways to add an extension. One is simply as an alias to an already | ||
| 692 | existing extension. An alias is an extension that is identical in ASN1 structure | ||
| 693 | to an existing extension but has a different OBJECT IDENTIFIER. This can be | ||
| 694 | done by calling: | ||
| 695 | |||
| 696 | int X509V3_EXT_add_alias(int nid_to, int nid_from); | ||
| 697 | |||
| 698 | 'nid_to' is the new extension NID and 'nid_from' is the already existing | ||
| 699 | extension NID. | ||
| 700 | |||
| 701 | Alternatively an extension can be written from scratch. This involves writing | ||
| 702 | the ASN1 code to encode and decode the extension and functions to print out and | ||
| 703 | generate the extension from strings. The relevant functions are then placed in | ||
| 704 | a X509V3_EXT_METHOD structure and int X509V3_EXT_add(X509V3_EXT_METHOD *ext); | ||
| 705 | called. | ||
| 706 | |||
| 707 | The X509V3_EXT_METHOD structure is described below. | ||
| 708 | |||
| 709 | strut { | ||
| 710 | int ext_nid; | ||
| 711 | int ext_flags; | ||
| 712 | X509V3_EXT_NEW ext_new; | ||
| 713 | X509V3_EXT_FREE ext_free; | ||
| 714 | X509V3_EXT_D2I d2i; | ||
| 715 | X509V3_EXT_I2D i2d; | ||
| 716 | X509V3_EXT_I2S i2s; | ||
| 717 | X509V3_EXT_S2I s2i; | ||
| 718 | X509V3_EXT_I2V i2v; | ||
| 719 | X509V3_EXT_V2I v2i; | ||
| 720 | X509V3_EXT_R2I r2i; | ||
| 721 | X509V3_EXT_I2R i2r; | ||
| 722 | |||
| 723 | void *usr_data; | ||
| 724 | }; | ||
| 725 | |||
| 726 | The elements have the following meanings. | ||
| 727 | |||
| 728 | ext_nid is the NID of the object identifier of the extension. | ||
| 729 | |||
| 730 | ext_flags is set of flags. Currently the only external flag is | ||
| 731 | X509V3_EXT_MULTILINE which means a multi valued extensions | ||
| 732 | should be printed on separate lines. | ||
| 733 | |||
| 734 | usr_data is an extension specific pointer to any relevant data. This | ||
| 735 | allows extensions to share identical code but have different | ||
| 736 | uses. An example of this is the bit string extension which uses | ||
| 737 | usr_data to contain a list of the bit names. | ||
| 738 | |||
| 739 | All the remaining elements are function pointers. | ||
| 740 | |||
| 741 | ext_new is a pointer to a function that allocates memory for the | ||
| 742 | extension ASN1 structure: for example ASN1_OBJECT_new(). | ||
| 743 | |||
| 744 | ext_free is a pointer to a function that free up memory of the extension | ||
| 745 | ASN1 structure: for example ASN1_OBJECT_free(). | ||
| 746 | |||
| 747 | d2i is the standard ASN1 function that converts a DER buffer into | ||
| 748 | the internal ASN1 structure: for example d2i_ASN1_IA5STRING(). | ||
| 749 | |||
| 750 | i2d is the standard ASN1 function that converts the internal | ||
| 751 | structure into the DER representation: for example | ||
| 752 | i2d_ASN1_IA5STRING(). | ||
| 753 | |||
| 754 | The remaining functions are depend on the type of extension. One i2X and | ||
| 755 | one X2i should be set and the rest set to NULL. The types set do not need | ||
| 756 | to match up, for example the extension could be set using the multi valued | ||
| 757 | v2i function and printed out using the raw i2r. | ||
| 758 | |||
| 759 | All functions have the X509V3_EXT_METHOD passed to them in the 'method' | ||
| 760 | parameter and an X509V3_CTX structure. Extension code can then access the | ||
| 761 | parent structure via the 'method' parameter to for example make use of the value | ||
| 762 | of usr_data. If the code needs to use detail relating to the request it can | ||
| 763 | use the 'ctx' parameter. | ||
| 764 | |||
| 765 | A note should be given here about the 'flags' member of the 'ctx' parameter. | ||
| 766 | If it has the value CTX_TEST then the configuration syntax is being checked | ||
| 767 | and no actual certificate or CRL exists. Therefore any attempt in the config | ||
| 768 | file to access such information should silently succeed. If the syntax is OK | ||
| 769 | then it should simply return a (possibly bogus) extension, otherwise it | ||
| 770 | should return NULL. | ||
| 771 | |||
| 772 | char *i2s(struct v3_ext_method *method, void *ext); | ||
| 773 | |||
| 774 | This function takes the internal structure in the ext parameter and returns | ||
| 775 | a Malloc'ed string representing its value. | ||
| 776 | |||
| 777 | void * s2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); | ||
| 778 | |||
| 779 | This function takes the string representation in the ext parameter and returns | ||
| 780 | an allocated internal structure: ext_free() will be used on this internal | ||
| 781 | structure after use. | ||
| 782 | |||
| 783 | i2v and v2i handle a STACK_OF(CONF_VALUE): | ||
| 784 | |||
| 785 | typedef struct | ||
| 786 | { | ||
| 787 | char *section; | ||
| 788 | char *name; | ||
| 789 | char *value; | ||
| 790 | } CONF_VALUE; | ||
| 791 | |||
| 792 | Only the name and value members are currently used. | ||
| 793 | |||
| 794 | STACK_OF(CONF_VALUE) * i2v(struct v3_ext_method *method, void *ext); | ||
| 795 | |||
| 796 | This function is passed the internal structure in the ext parameter and | ||
| 797 | returns a STACK of CONF_VALUE structures. The values of name, value, | ||
| 798 | section and the structure itself will be freed up with Free after use. | ||
| 799 | Several helper functions are available to add values to this STACK. | ||
| 800 | |||
| 801 | void * v2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, | ||
| 802 | STACK_OF(CONF_VALUE) *values); | ||
| 803 | |||
| 804 | This function takes a STACK_OF(CONF_VALUE) structures and should set the | ||
| 805 | values of the external structure. This typically uses the name element to | ||
| 806 | determine which structure element to set and the value element to determine | ||
| 807 | what to set it to. Several helper functions are available for this | ||
| 808 | purpose (see above). | ||
| 809 | |||
| 810 | int i2r(struct v3_ext_method *method, void *ext, BIO *out, int indent); | ||
| 811 | |||
| 812 | This function is passed the internal extension structure in the ext parameter | ||
| 813 | and sends out a human readable version of the extension to out. The 'indent' | ||
| 814 | paremeter should be noted to determine the necessary amount of indentation | ||
| 815 | needed on the output. | ||
| 816 | |||
| 817 | void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); | ||
| 818 | |||
| 819 | This is just passed the string representation of the extension. It is intended | ||
| 820 | to be used for more elaborate extensions where the standard single and multi | ||
| 821 | valued options are insufficient. They can use the 'ctx' parameter to parse the | ||
| 822 | configuration database themselves. See the context functions section for details | ||
| 823 | of how to do this. | ||
| 824 | |||
| 825 | Note: although this type takes the same parameters as the "r2s" function there | ||
| 826 | is a subtle difference. Whereas an "r2i" function can access a configuration | ||
| 827 | database an "s2i" function MUST NOT. This is so the internal code can safely | ||
| 828 | assume that an "s2i" function will work without a configuration database. | ||
| 829 | |||
| 830 | ============================================================================== | ||
| 831 | PKCS#12 Library | ||
| 832 | ============================================================================== | ||
| 833 | |||
| 834 | This section describes the internal PKCS#12 support. There are very few | ||
| 835 | differences between the old external library and the new internal code at | ||
| 836 | present. This may well change because the external library will not be updated | ||
| 837 | much in future. | ||
| 838 | |||
| 839 | This version now includes a couple of high level PKCS#12 functions which | ||
| 840 | generally "do the right thing" and should make it much easier to handle PKCS#12 | ||
| 841 | structures. | ||
| 842 | |||
| 843 | HIGH LEVEL FUNCTIONS. | ||
| 844 | |||
| 845 | For most applications you only need concern yourself with the high level | ||
| 846 | functions. They can parse and generate simple PKCS#12 files as produced by | ||
| 847 | Netscape and MSIE or indeed any compliant PKCS#12 file containing a single | ||
| 848 | private key and certificate pair. | ||
| 849 | |||
| 850 | 1. Initialisation and cleanup. | ||
| 851 | |||
| 852 | No special initialisation is needed for the internal PKCS#12 library: the | ||
| 853 | standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to | ||
| 854 | add all algorithms (you should at least add SHA1 though) then you can manually | ||
| 855 | initialise the PKCS#12 library with: | ||
| 856 | |||
| 857 | PKCS12_PBE_add(); | ||
| 858 | |||
| 859 | The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is | ||
| 860 | called or it can be directly freed with: | ||
| 861 | |||
| 862 | EVP_PBE_cleanup(); | ||
| 863 | |||
| 864 | after this call (or EVP_cleanup() ) no more PKCS#12 library functions should | ||
| 865 | be called. | ||
| 866 | |||
| 867 | 2. I/O functions. | ||
| 868 | |||
| 869 | i2d_PKCS12_bio(bp, p12) | ||
| 870 | |||
| 871 | This writes out a PKCS12 structure to a BIO. | ||
| 872 | |||
| 873 | i2d_PKCS12_fp(fp, p12) | ||
| 874 | |||
| 875 | This is the same but for a FILE pointer. | ||
| 876 | |||
| 877 | d2i_PKCS12_bio(bp, p12) | ||
| 878 | |||
| 879 | This reads in a PKCS12 structure from a BIO. | ||
| 880 | |||
| 881 | d2i_PKCS12_fp(fp, p12) | ||
| 882 | |||
| 883 | This is the same but for a FILE pointer. | ||
| 884 | |||
| 885 | 3. Parsing and creation functions. | ||
| 886 | |||
| 887 | 3.1 Parsing with PKCS12_parse(). | ||
| 888 | |||
| 889 | int PKCS12_parse(PKCS12 *p12, char *pass, EVP_PKEY **pkey, X509 **cert, | ||
| 890 | STACK **ca); | ||
| 891 | |||
| 892 | This function takes a PKCS12 structure and a password (ASCII, null terminated) | ||
| 893 | and returns the private key, the corresponding certificate and any CA | ||
| 894 | certificates. If any of these is not required it can be passed as a NULL. | ||
| 895 | The 'ca' parameter should be either NULL, a pointer to NULL or a valid STACK | ||
| 896 | structure. Typically to read in a PKCS#12 file you might do: | ||
| 897 | |||
| 898 | p12 = d2i_PKCS12_fp(fp, NULL); | ||
| 899 | PKCS12_parse(p12, password, &pkey, &cert, NULL); /* CAs not wanted */ | ||
| 900 | PKCS12_free(p12); | ||
| 901 | |||
| 902 | 3.2 PKCS#12 creation with PKCS12_create(). | ||
| 903 | |||
| 904 | PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, | ||
| 905 | STACK *ca, int nid_key, int nid_cert, int iter, | ||
| 906 | int mac_iter, int keytype); | ||
| 907 | |||
| 908 | This function will create a PKCS12 structure from a given password, name, | ||
| 909 | private key, certificate and optional STACK of CA certificates. The remaining | ||
| 910 | 5 parameters can be set to 0 and sensible defaults will be used. | ||
| 911 | |||
| 912 | The parameters nid_key and nid_cert are the key and certificate encryption | ||
| 913 | algorithms, iter is the encryption iteration count, mac_iter is the MAC | ||
| 914 | iteration count and keytype is the type of private key. If you really want | ||
| 915 | to know what these last 5 parameters do then read the low level section. | ||
| 916 | |||
| 917 | Typically to create a PKCS#12 file the following could be used: | ||
| 918 | |||
| 919 | p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0); | ||
| 920 | i2d_PKCS12_fp(fp, p12); | ||
| 921 | PKCS12_free(p12); | ||
| 922 | |||
| 923 | LOW LEVEL FUNCTIONS. | ||
| 924 | |||
| 925 | In some cases the high level functions do not provide the necessary | ||
| 926 | functionality. For example if you want to generate or parse more complex | ||
| 927 | PKCS#12 files. The sample pkcs12 application uses the low level functions | ||
| 928 | to display details about the internal structure of a PKCS#12 file. | ||
| 929 | |||
| 930 | Introduction. | ||
| 931 | |||
| 932 | This is a brief description of how a PKCS#12 file is represented internally: | ||
| 933 | some knowledge of PKCS#12 is assumed. | ||
| 934 | |||
| 935 | A PKCS#12 object contains several levels. | ||
| 936 | |||
| 937 | At the lowest level is a PKCS12_SAFEBAG. This can contain a certificate, a | ||
| 938 | CRL, a private key, encrypted or unencrypted, a set of safebags (so the | ||
| 939 | structure can be nested) or other secrets (not documented at present). | ||
| 940 | A safebag can optionally have attributes, currently these are: a unicode | ||
| 941 | friendlyName (a Unicode string) or a localKeyID (a string of bytes). | ||
| 942 | |||
| 943 | At the next level is an authSafe which is a set of safebags collected into | ||
| 944 | a PKCS#7 ContentInfo. This can be just plain data, or encrypted itself. | ||
| 945 | |||
| 946 | At the top level is the PKCS12 structure itself which contains a set of | ||
| 947 | authSafes in an embedded PKCS#7 Contentinfo of type data. In addition it | ||
| 948 | contains a MAC which is a kind of password protected digest to preserve | ||
| 949 | integrity (so any unencrypted stuff below can't be tampered with). | ||
| 950 | |||
| 951 | The reason for these levels is so various objects can be encrypted in various | ||
| 952 | ways. For example you might want to encrypt a set of private keys with | ||
| 953 | triple-DES and then include the related certificates either unencrypted or | ||
| 954 | with lower encryption. Yes it's the dreaded crypto laws at work again which | ||
| 955 | allow strong encryption on private keys and only weak encryption on other | ||
| 956 | stuff. | ||
| 957 | |||
| 958 | To build one of these things you turn all certificates and keys into safebags | ||
| 959 | (with optional attributes). You collect the safebags into (one or more) STACKS | ||
| 960 | and convert these into authsafes (encrypted or unencrypted). The authsafes | ||
| 961 | are collected into a STACK and added to a PKCS12 structure. Finally a MAC | ||
| 962 | inserted. | ||
| 963 | |||
| 964 | Pulling one apart is basically the reverse process. The MAC is verified against | ||
| 965 | the given password. The authsafes are extracted and each authsafe split into | ||
| 966 | a set of safebags (possibly involving decryption). Finally the safebags are | ||
| 967 | decomposed into the original keys and certificates and the attributes used to | ||
| 968 | match up private key and certificate pairs. | ||
| 969 | |||
| 970 | Anyway here are the functions that do the dirty work. | ||
| 971 | |||
| 972 | 1. Construction functions. | ||
| 973 | |||
| 974 | 1.1 Safebag functions. | ||
| 975 | |||
| 976 | M_PKCS12_x5092certbag(x509) | ||
| 977 | |||
| 978 | This macro takes an X509 structure and returns a certificate bag. The | ||
| 979 | X509 structure can be freed up after calling this function. | ||
| 980 | |||
| 981 | M_PKCS12_x509crl2certbag(crl) | ||
| 982 | |||
| 983 | As above but for a CRL. | ||
| 984 | |||
| 985 | PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey) | ||
| 986 | |||
| 987 | Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure. | ||
| 988 | Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo | ||
| 989 | structure contains a private key data in plain text form it should be free'd | ||
| 990 | up as soon as it has been encrypted for security reasons (freeing up the | ||
| 991 | structure zeros out the sensitive data). This can be done with | ||
| 992 | PKCS8_PRIV_KEY_INFO_free(). | ||
| 993 | |||
| 994 | PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage) | ||
| 995 | |||
| 996 | This sets the key type when a key is imported into MSIE or Outlook 98. Two | ||
| 997 | values are currently supported: KEY_EX and KEY_SIG. KEY_EX is an exchange type | ||
| 998 | key that can also be used for signing but its size is limited in the export | ||
| 999 | versions of MS software to 512 bits, it is also the default. KEY_SIG is a | ||
| 1000 | signing only key but the keysize is unlimited (well 16K is supposed to work). | ||
| 1001 | If you are using the domestic version of MSIE then you can ignore this because | ||
| 1002 | KEY_EX is not limited and can be used for both. | ||
| 1003 | |||
| 1004 | PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8) | ||
| 1005 | |||
| 1006 | Convert a PKCS8 private key structure into a keybag. This routine embeds the | ||
| 1007 | p8 structure in the keybag so p8 should not be freed up or used after it is | ||
| 1008 | called. The p8 structure will be freed up when the safebag is freed. | ||
| 1009 | |||
| 1010 | PKCS12_SAFEBAG *PKCS12_MAKE_SHKEYBAG(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8) | ||
| 1011 | |||
| 1012 | Convert a PKCS#8 structure into a shrouded key bag (encrypted). p8 is not | ||
| 1013 | embedded and can be freed up after use. | ||
| 1014 | |||
| 1015 | int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) | ||
| 1016 | int PKCS12_add_friendlyname(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) | ||
| 1017 | |||
| 1018 | Add a local key id or a friendlyname to a safebag. | ||
| 1019 | |||
| 1020 | 1.2 Authsafe functions. | ||
| 1021 | |||
| 1022 | PKCS7 *PKCS12_pack_p7data(STACK *sk) | ||
| 1023 | Take a stack of safebags and convert them into an unencrypted authsafe. The | ||
| 1024 | stack of safebags can be freed up after calling this function. | ||
| 1025 | |||
| 1026 | PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, STACK *bags); | ||
| 1027 | |||
| 1028 | As above but encrypted. | ||
| 1029 | |||
| 1030 | 1.3 PKCS12 functions. | ||
| 1031 | |||
| 1032 | PKCS12 *PKCS12_init(int mode) | ||
| 1033 | |||
| 1034 | Initialise a PKCS12 structure (currently mode should be NID_pkcs7_data). | ||
| 1035 | |||
| 1036 | M_PKCS12_pack_authsafes(p12, safes) | ||
| 1037 | |||
| 1038 | This macro takes a STACK of authsafes and adds them to a PKCS#12 structure. | ||
| 1039 | |||
| 1040 | int PKCS12_set_mac(PKCS12 *p12, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, EVP_MD *md_type); | ||
| 1041 | |||
| 1042 | Add a MAC to a PKCS12 structure. If EVP_MD is NULL use SHA-1, the spec suggests | ||
| 1043 | that SHA-1 should be used. | ||
| 1044 | |||
| 1045 | 2. Extraction Functions. | ||
| 1046 | |||
| 1047 | 2.1 Safebags. | ||
| 1048 | |||
| 1049 | M_PKCS12_bag_type(bag) | ||
| 1050 | |||
| 1051 | Return the type of "bag". Returns one of the following | ||
| 1052 | |||
| 1053 | NID_keyBag | ||
| 1054 | NID_pkcs8ShroudedKeyBag 7 | ||
| 1055 | NID_certBag 8 | ||
| 1056 | NID_crlBag 9 | ||
| 1057 | NID_secretBag 10 | ||
| 1058 | NID_safeContentsBag 11 | ||
| 1059 | |||
| 1060 | M_PKCS12_cert_bag_type(bag) | ||
| 1061 | |||
| 1062 | Returns type of certificate bag, following are understood. | ||
| 1063 | |||
| 1064 | NID_x509Certificate 14 | ||
| 1065 | NID_sdsiCertificate 15 | ||
| 1066 | |||
| 1067 | M_PKCS12_crl_bag_type(bag) | ||
| 1068 | |||
| 1069 | Returns crl bag type, currently only NID_crlBag is recognised. | ||
| 1070 | |||
| 1071 | M_PKCS12_certbag2x509(bag) | ||
| 1072 | |||
| 1073 | This macro extracts an X509 certificate from a certificate bag. | ||
| 1074 | |||
| 1075 | M_PKCS12_certbag2x509crl(bag) | ||
| 1076 | |||
| 1077 | As above but for a CRL. | ||
| 1078 | |||
| 1079 | EVP_PKEY * PKCS82PKEY(PKCS8_PRIV_KEY_INFO *p8) | ||
| 1080 | |||
| 1081 | Extract a private key from a PKCS8 private key info structure. | ||
| 1082 | |||
| 1083 | M_PKCS12_decrypt_skey(bag, pass, passlen) | ||
| 1084 | |||
| 1085 | Decrypt a shrouded key bag and return a PKCS8 private key info structure. | ||
| 1086 | Works with both RSA and DSA keys | ||
| 1087 | |||
| 1088 | char *PKCS12_get_friendlyname(bag) | ||
| 1089 | |||
| 1090 | Returns the friendlyName of a bag if present or NULL if none. The returned | ||
| 1091 | string is a null terminated ASCII string allocated with Malloc(). It should | ||
| 1092 | thus be freed up with Free() after use. | ||
| 1093 | |||
| 1094 | 2.2 AuthSafe functions. | ||
| 1095 | |||
| 1096 | M_PKCS12_unpack_p7data(p7) | ||
| 1097 | |||
| 1098 | Extract a STACK of safe bags from a PKCS#7 data ContentInfo. | ||
| 1099 | |||
| 1100 | #define M_PKCS12_unpack_p7encdata(p7, pass, passlen) | ||
| 1101 | |||
| 1102 | As above but for an encrypted content info. | ||
| 1103 | |||
| 1104 | 2.3 PKCS12 functions. | ||
| 1105 | |||
| 1106 | M_PKCS12_unpack_authsafes(p12) | ||
| 1107 | |||
| 1108 | Extract a STACK of authsafes from a PKCS12 structure. | ||
| 1109 | |||
| 1110 | M_PKCS12_mac_present(p12) | ||
| 1111 | |||
| 1112 | Check to see if a MAC is present. | ||
| 1113 | |||
| 1114 | int PKCS12_verify_mac(PKCS12 *p12, unsigned char *pass, int passlen) | ||
| 1115 | |||
| 1116 | Verify a MAC on a PKCS12 structure. Returns an error if MAC not present. | ||
| 1117 | |||
| 1118 | |||
| 1119 | Notes. | ||
| 1120 | |||
| 1121 | 1. All the function return 0 or NULL on error. | ||
| 1122 | 2. Encryption based functions take a common set of parameters. These are | ||
| 1123 | described below. | ||
| 1124 | |||
| 1125 | pass, passlen | ||
| 1126 | ASCII password and length. The password on the MAC is called the "integrity | ||
| 1127 | password" the encryption password is called the "privacy password" in the | ||
| 1128 | PKCS#12 documentation. The passwords do not have to be the same. If -1 is | ||
| 1129 | passed for the length it is worked out by the function itself (currently | ||
| 1130 | this is sometimes done whatever is passed as the length but that may change). | ||
| 1131 | |||
| 1132 | salt, saltlen | ||
| 1133 | A 'salt' if salt is NULL a random salt is used. If saltlen is also zero a | ||
| 1134 | default length is used. | ||
| 1135 | |||
| 1136 | iter | ||
| 1137 | Iteration count. This is a measure of how many times an internal function is | ||
| 1138 | called to encrypt the data. The larger this value is the longer it takes, it | ||
| 1139 | makes dictionary attacks on passwords harder. NOTE: Some implementations do | ||
| 1140 | not support an iteration count on the MAC. If the password for the MAC and | ||
| 1141 | encryption is the same then there is no point in having a high iteration | ||
| 1142 | count for encryption if the MAC has no count. The MAC could be attacked | ||
| 1143 | and the password used for the main decryption. | ||
| 1144 | |||
| 1145 | pbe_nid | ||
| 1146 | This is the NID of the password based encryption method used. The following are | ||
| 1147 | supported. | ||
| 1148 | NID_pbe_WithSHA1And128BitRC4 | ||
| 1149 | NID_pbe_WithSHA1And40BitRC4 | ||
| 1150 | NID_pbe_WithSHA1And3_Key_TripleDES_CBC | ||
| 1151 | NID_pbe_WithSHA1And2_Key_TripleDES_CBC | ||
| 1152 | NID_pbe_WithSHA1And128BitRC2_CBC | ||
| 1153 | NID_pbe_WithSHA1And40BitRC2_CBC | ||
| 1154 | |||
| 1155 | Which you use depends on the implementation you are exporting to. "Export | ||
| 1156 | grade" (i.e. cryptographically challenged) products cannot support all | ||
| 1157 | algorithms. Typically you may be able to use any encryption on shrouded key | ||
| 1158 | bags but they must then be placed in an unencrypted authsafe. Other authsafes | ||
| 1159 | may only support 40bit encryption. Of course if you are using SSLeay | ||
| 1160 | throughout you can strongly encrypt everything and have high iteration counts | ||
| 1161 | on everything. | ||
| 1162 | |||
| 1163 | 3. For decryption routines only the password and length are needed. | ||
| 1164 | |||
| 1165 | 4. Unlike the external version the nid's of objects are the values of the | ||
| 1166 | constants: that is NID_certBag is the real nid, therefore there is no | ||
| 1167 | PKCS12_obj_offset() function. Note the object constants are not the same as | ||
| 1168 | those of the external version. If you use these constants then you will need | ||
| 1169 | to recompile your code. | ||
| 1170 | |||
| 1171 | 5. With the exception of PKCS12_MAKE_KEYBAG(), after calling any function or | ||
| 1172 | macro of the form PKCS12_MAKE_SOMETHING(other) the "other" structure can be | ||
| 1173 | reused or freed up safely. | ||
| 1174 | |||
diff --git a/src/lib/libssl/src/doc/openssl_button.gif b/src/lib/libssl/src/doc/openssl_button.gif new file mode 100644 index 0000000000..3d3c90c9f8 --- /dev/null +++ b/src/lib/libssl/src/doc/openssl_button.gif | |||
| Binary files differ | |||
diff --git a/src/lib/libssl/src/doc/openssl_button.html b/src/lib/libssl/src/doc/openssl_button.html new file mode 100644 index 0000000000..44c91bd3d0 --- /dev/null +++ b/src/lib/libssl/src/doc/openssl_button.html | |||
| @@ -0,0 +1,7 @@ | |||
| 1 | |||
| 2 | <!-- the `Includes OpenSSL Cryptogaphy Software' button --> | ||
| 3 | <!-- freely usable by any application linked against OpenSSL --> | ||
| 4 | <a href="http://www.openssl.org/"> | ||
| 5 | <img src="openssl_button.gif" | ||
| 6 | width=102 height=47 border=0></a> | ||
| 7 | |||
diff --git a/src/lib/libssl/src/doc/rand.doc b/src/lib/libssl/src/doc/rand.doc deleted file mode 100644 index da02a07f64..0000000000 --- a/src/lib/libssl/src/doc/rand.doc +++ /dev/null | |||
| @@ -1,141 +0,0 @@ | |||
| 1 | My Random number library. | ||
| 2 | |||
| 3 | These routines can be used to generate pseudo random numbers and can be | ||
| 4 | used to 'seed' the pseudo random number generator (RNG). The RNG make no | ||
| 5 | effort to reproduce the same random number stream with each execution. | ||
| 6 | Various other routines in the SSLeay library 'seed' the RNG when suitable | ||
| 7 | 'random' input data is available. Read the section at the end for details | ||
| 8 | on the design of the RNG. | ||
| 9 | |||
| 10 | void RAND_bytes( | ||
| 11 | unsigned char *buf, | ||
| 12 | int num); | ||
| 13 | This routine puts 'num' random bytes into 'buf'. One should make | ||
| 14 | sure RAND_seed() has been called before using this routine. | ||
| 15 | |||
| 16 | void RAND_seed( | ||
| 17 | unsigned char *buf, | ||
| 18 | int num); | ||
| 19 | This routine adds more 'seed' data the RNG state. 'num' bytes | ||
| 20 | are added to the RNG state, they are taken from 'buf'. This | ||
| 21 | routine can be called with sensitive data such as user entered | ||
| 22 | passwords. This sensitive data is in no way recoverable from | ||
| 23 | the RAND library routines or state. Try to pass as much data | ||
| 24 | from 'random' sources as possible into the RNG via this function. | ||
| 25 | Also strongly consider using the RAND_load_file() and | ||
| 26 | RAND_write_file() routines. | ||
| 27 | |||
| 28 | void RAND_cleanup(); | ||
| 29 | When a program has finished with the RAND library, if it so | ||
| 30 | desires, it can 'zero' all RNG state. | ||
| 31 | |||
| 32 | The following 3 routines are convenience routines that can be used to | ||
| 33 | 'save' and 'restore' data from/to the RNG and it's state. | ||
| 34 | Since the more 'random' data that is feed as seed data the better, why not | ||
| 35 | keep it around between executions of the program? Of course the | ||
| 36 | application should pass more 'random' data in via RAND_seed() and | ||
| 37 | make sure no-one can read the 'random' data file. | ||
| 38 | |||
| 39 | char *RAND_file_name( | ||
| 40 | char *buf, | ||
| 41 | int size); | ||
| 42 | This routine returns a 'default' name for the location of a 'rand' | ||
| 43 | file. The 'rand' file should keep a sequence of random bytes used | ||
| 44 | to initialise the RNG. The filename is put in 'buf'. Buf is 'size' | ||
| 45 | bytes long. Buf is returned if things go well, if they do not, | ||
| 46 | NULL is returned. The 'rand' file name is generated in the | ||
| 47 | following way. First, if there is a 'RANDFILE' environment | ||
| 48 | variable, it is returned. Second, if there is a 'HOME' environment | ||
| 49 | variable, $HOME/.rand is returned. Third, NULL is returned. NULL | ||
| 50 | is also returned if a buf would overflow. | ||
| 51 | |||
| 52 | int RAND_load_file( | ||
| 53 | char *file, | ||
| 54 | long number); | ||
| 55 | This function 'adds' the 'file' into the RNG state. It does this by | ||
| 56 | doing a RAND_seed() on the value returned from a stat() system call | ||
| 57 | on the file and if 'number' is non-zero, upto 'number' bytes read | ||
| 58 | from the file. The number of bytes passed to RAND_seed() is returned. | ||
| 59 | |||
| 60 | int RAND_write_file( | ||
| 61 | char *file), | ||
| 62 | RAND_write_file() writes N random bytes to the file 'file', where | ||
| 63 | N is the size of the internal RND state (currently 1k). | ||
| 64 | This is a suitable method of saving RNG state for reloading via | ||
| 65 | RAND_load_file(). | ||
| 66 | |||
| 67 | What follows is a description of this RNG and a description of the rational | ||
| 68 | behind it's design. | ||
| 69 | |||
| 70 | It should be noted that this RNG is intended to be used to generate | ||
| 71 | 'random' keys for various ciphers including generation of DH and RSA keys. | ||
| 72 | |||
| 73 | It should also be noted that I have just created a system that I am happy with. | ||
| 74 | It may be overkill but that does not worry me. I have not spent that much | ||
| 75 | time on this algorithm so if there are glaring errors, please let me know. | ||
| 76 | Speed has not been a consideration in the design of these routines. | ||
| 77 | |||
| 78 | First up I will state the things I believe I need for a good RNG. | ||
| 79 | 1) A good hashing algorithm to mix things up and to convert the RNG 'state' | ||
| 80 | to random numbers. | ||
| 81 | 2) An initial source of random 'state'. | ||
| 82 | 3) The state should be very large. If the RNG is being used to generate | ||
| 83 | 4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum). | ||
| 84 | If your RNG state only has 128 bits, you are obviously limiting the | ||
| 85 | search space to 128 bits, not 2048. I'm probably getting a little | ||
| 86 | carried away on this last point but it does indicate that it may not be | ||
| 87 | a bad idea to keep quite a lot of RNG state. It should be easier to | ||
| 88 | break a cipher than guess the RNG seed data. | ||
| 89 | 4) Any RNG seed data should influence all subsequent random numbers | ||
| 90 | generated. This implies that any random seed data entered will have | ||
| 91 | an influence on all subsequent random numbers generated. | ||
| 92 | 5) When using data to seed the RNG state, the data used should not be | ||
| 93 | extractable from the RNG state. I believe this should be a | ||
| 94 | requirement because one possible source of 'secret' semi random | ||
| 95 | data would be a private key or a password. This data must | ||
| 96 | not be disclosed by either subsequent random numbers or a | ||
| 97 | 'core' dump left by a program crash. | ||
| 98 | 6) Given the same initial 'state', 2 systems should deviate in their RNG state | ||
| 99 | (and hence the random numbers generated) over time if at all possible. | ||
| 100 | 7) Given the random number output stream, it should not be possible to determine | ||
| 101 | the RNG state or the next random number. | ||
| 102 | |||
| 103 | |||
| 104 | The algorithm is as follows. | ||
| 105 | |||
| 106 | There is global state made up of a 1023 byte buffer (the 'state'), a | ||
| 107 | working message digest ('md') and a counter ('count'). | ||
| 108 | |||
| 109 | Whenever seed data is added, it is inserted into the 'state' as | ||
| 110 | follows. | ||
| 111 | The input is chopped up into units of 16 bytes (or less for | ||
| 112 | the last block). Each of these blocks is run through the MD5 | ||
| 113 | message digest. The data passed to the MD5 digest is the | ||
| 114 | current 'md', the same number of bytes from the 'state' | ||
| 115 | (the location determined by in incremented looping index) as | ||
| 116 | the current 'block' and the new key data 'block'. The result | ||
| 117 | of this is kept in 'md' and also xored into the 'state' at the | ||
| 118 | same locations that were used as input into the MD5. | ||
| 119 | I believe this system addresses points 1 (MD5), 3 (the 'state'), | ||
| 120 | 4 (via the 'md'), 5 (by the use of MD5 and xor). | ||
| 121 | |||
| 122 | When bytes are extracted from the RNG, the following process is used. | ||
| 123 | For each group of 8 bytes (or less), we do the following, | ||
| 124 | Input into MD5, the top 8 bytes from 'md', the byte that are | ||
| 125 | to be overwritten by the random bytes and bytes from the | ||
| 126 | 'state' (incrementing looping index). From this digest output | ||
| 127 | (which is kept in 'md'), the top (upto) 8 bytes are | ||
| 128 | returned to the caller and the bottom (upto) 8 bytes are xored | ||
| 129 | into the 'state'. | ||
| 130 | Finally, after we have finished 'generation' random bytes for the | ||
| 131 | called, 'count' (which is incremented) and 'md' are fed into MD5 and | ||
| 132 | the results are kept in 'md'. | ||
| 133 | I believe the above addressed points 1 (use of MD5), 6 (by | ||
| 134 | hashing into the 'state' the 'old' data from the caller that | ||
| 135 | is about to be overwritten) and 7 (by not using the 8 bytes | ||
| 136 | given to the caller to update the 'state', but they are used | ||
| 137 | to update 'md'). | ||
| 138 | |||
| 139 | So of the points raised, only 2 is not addressed, but sources of | ||
| 140 | random data will always be a problem. | ||
| 141 | |||
diff --git a/src/lib/libssl/src/doc/rc2.doc b/src/lib/libssl/src/doc/rc2.doc deleted file mode 100644 index efab015bd1..0000000000 --- a/src/lib/libssl/src/doc/rc2.doc +++ /dev/null | |||
| @@ -1,165 +0,0 @@ | |||
| 1 | The RC2 library. | ||
| 2 | |||
| 3 | RC2 is a block cipher that operates on 64bit (8 byte) quantities. It | ||
| 4 | uses variable size key, but 128bit (16 byte) key would normally be considered | ||
| 5 | good. It can be used in all the modes that DES can be used. This | ||
| 6 | library implements the ecb, cbc, cfb64, ofb64 modes. | ||
| 7 | |||
| 8 | I have implemented this library from an article posted to sci.crypt on | ||
| 9 | 11-Feb-1996. I personally don't know how far to trust the RC2 cipher. | ||
| 10 | While it is capable of having a key of any size, not much reseach has | ||
| 11 | publically been done on it at this point in time (Apr-1996) | ||
| 12 | since the cipher has only been public for a few months :-) | ||
| 13 | It is of a similar speed to DES and IDEA, so unless it is required for | ||
| 14 | meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable | ||
| 15 | to stick to IDEA, or for the paranoid, Tripple DES. | ||
| 16 | |||
| 17 | Mind you, having said all that, I should mention that I just read alot and | ||
| 18 | implement ciphers, I'm a 'babe in the woods' when it comes to evaluating | ||
| 19 | ciphers :-). | ||
| 20 | |||
| 21 | For all calls that have an 'input' and 'output' variables, they can be the | ||
| 22 | same. | ||
| 23 | |||
| 24 | This library requires the inclusion of 'rc2.h'. | ||
| 25 | |||
| 26 | All of the encryption functions take what is called an RC2_KEY as an | ||
| 27 | argument. An RC2_KEY is an expanded form of the RC2 key. | ||
| 28 | For all modes of the RC2 algorithm, the RC2_KEY used for | ||
| 29 | decryption is the same one that was used for encryption. | ||
| 30 | |||
| 31 | The define RC2_ENCRYPT is passed to specify encryption for the functions | ||
| 32 | that require an encryption/decryption flag. RC2_DECRYPT is passed to | ||
| 33 | specify decryption. | ||
| 34 | |||
| 35 | Please note that any of the encryption modes specified in my DES library | ||
| 36 | could be used with RC2. I have only implemented ecb, cbc, cfb64 and | ||
| 37 | ofb64 for the following reasons. | ||
| 38 | - ecb is the basic RC2 encryption. | ||
| 39 | - cbc is the normal 'chaining' form for block ciphers. | ||
| 40 | - cfb64 can be used to encrypt single characters, therefore input and output | ||
| 41 | do not need to be a multiple of 8. | ||
| 42 | - ofb64 is similar to cfb64 but is more like a stream cipher, not as | ||
| 43 | secure (not cipher feedback) but it does not have an encrypt/decrypt mode. | ||
| 44 | - If you want triple RC2, thats 384 bits of key and you must be totally | ||
| 45 | obsessed with security. Still, if you want it, it is simple enough to | ||
| 46 | copy the function from the DES library and change the des_encrypt to | ||
| 47 | RC2_encrypt; an exercise left for the paranoid reader :-). | ||
| 48 | |||
| 49 | The functions are as follows: | ||
| 50 | |||
| 51 | void RC2_set_key( | ||
| 52 | RC2_KEY *ks; | ||
| 53 | int len; | ||
| 54 | unsigned char *key; | ||
| 55 | int bits; | ||
| 56 | RC2_set_key converts an 'len' byte key into a RC2_KEY. | ||
| 57 | A 'ks' is an expanded form of the 'key' which is used to | ||
| 58 | perform actual encryption. It can be regenerated from the RC2 key | ||
| 59 | so it only needs to be kept when encryption or decryption is about | ||
| 60 | to occur. Don't save or pass around RC2_KEY's since they | ||
| 61 | are CPU architecture dependent, 'key's are not. RC2 is an | ||
| 62 | interesting cipher in that it can be used with a variable length | ||
| 63 | key. 'len' is the length of 'key' to be used as the key. | ||
| 64 | A 'len' of 16 is recomended. The 'bits' argument is an | ||
| 65 | interesting addition which I only found out about in Aug 96. | ||
| 66 | BSAFE uses this parameter to 'limit' the number of bits used | ||
| 67 | for the key. To use the 'key' unmodified, set bits to 1024. | ||
| 68 | This is what old versions of my RC2 library did (SSLeay 0.6.3). | ||
| 69 | RSAs BSAFE library sets this parameter to be 128 if 128 bit | ||
| 70 | keys are being used. So to be compatable with BSAFE, set it | ||
| 71 | to 128, if you don't want to reduce RC2's key length, leave it | ||
| 72 | at 1024. | ||
| 73 | |||
| 74 | void RC2_encrypt( | ||
| 75 | unsigned long *data, | ||
| 76 | RC2_KEY *key, | ||
| 77 | int encrypt); | ||
| 78 | This is the RC2 encryption function that gets called by just about | ||
| 79 | every other RC2 routine in the library. You should not use this | ||
| 80 | function except to implement 'modes' of RC2. I say this because the | ||
| 81 | functions that call this routine do the conversion from 'char *' to | ||
| 82 | long, and this needs to be done to make sure 'non-aligned' memory | ||
| 83 | access do not occur. | ||
| 84 | Data is a pointer to 2 unsigned long's and key is the | ||
| 85 | RC2_KEY to use. Encryption or decryption is indicated by 'encrypt'. | ||
| 86 | which can have the values RC2_ENCRYPT or RC2_DECRYPT. | ||
| 87 | |||
| 88 | void RC2_ecb_encrypt( | ||
| 89 | unsigned char *in, | ||
| 90 | unsigned char *out, | ||
| 91 | RC2_KEY *key, | ||
| 92 | int encrypt); | ||
| 93 | This is the basic Electronic Code Book form of RC2 (in DES this | ||
| 94 | mode is called Electronic Code Book so I'm going to use the term | ||
| 95 | for rc2 as well. | ||
| 96 | Input is encrypted into output using the key represented by | ||
| 97 | key. Depending on the encrypt, encryption or | ||
| 98 | decryption occurs. Input is 8 bytes long and output is 8 bytes. | ||
| 99 | |||
| 100 | void RC2_cbc_encrypt( | ||
| 101 | unsigned char *in, | ||
| 102 | unsigned char *out, | ||
| 103 | long length, | ||
| 104 | RC2_KEY *ks, | ||
| 105 | unsigned char *ivec, | ||
| 106 | int encrypt); | ||
| 107 | This routine implements RC2 in Cipher Block Chaining mode. | ||
| 108 | Input, which should be a multiple of 8 bytes is encrypted | ||
| 109 | (or decrypted) to output which will also be a multiple of 8 bytes. | ||
| 110 | The number of bytes is in length (and from what I've said above, | ||
| 111 | should be a multiple of 8). If length is not a multiple of 8, bad | ||
| 112 | things will probably happen. ivec is the initialisation vector. | ||
| 113 | This function updates iv after each call so that it can be passed to | ||
| 114 | the next call to RC2_cbc_encrypt(). | ||
| 115 | |||
| 116 | void RC2_cfb64_encrypt( | ||
| 117 | unsigned char *in, | ||
| 118 | unsigned char *out, | ||
| 119 | long length, | ||
| 120 | RC2_KEY *schedule, | ||
| 121 | unsigned char *ivec, | ||
| 122 | int *num, | ||
| 123 | int encrypt); | ||
| 124 | This is one of the more useful functions in this RC2 library, it | ||
| 125 | implements CFB mode of RC2 with 64bit feedback. | ||
| 126 | This allows you to encrypt an arbitrary number of bytes, | ||
| 127 | you do not require 8 byte padding. Each call to this | ||
| 128 | routine will encrypt the input bytes to output and then update ivec | ||
| 129 | and num. Num contains 'how far' we are though ivec. | ||
| 130 | 'Encrypt' is used to indicate encryption or decryption. | ||
| 131 | CFB64 mode operates by using the cipher to generate a stream | ||
| 132 | of bytes which is used to encrypt the plain text. | ||
| 133 | The cipher text is then encrypted to generate the next 64 bits to | ||
| 134 | be xored (incrementally) with the next 64 bits of plain | ||
| 135 | text. As can be seen from this, to encrypt or decrypt, | ||
| 136 | the same 'cipher stream' needs to be generated but the way the next | ||
| 137 | block of data is gathered for encryption is different for | ||
| 138 | encryption and decryption. | ||
| 139 | |||
| 140 | void RC2_ofb64_encrypt( | ||
| 141 | unsigned char *in, | ||
| 142 | unsigned char *out, | ||
| 143 | long length, | ||
| 144 | RC2_KEY *schedule, | ||
| 145 | unsigned char *ivec, | ||
| 146 | int *num); | ||
| 147 | This functions implements OFB mode of RC2 with 64bit feedback. | ||
| 148 | This allows you to encrypt an arbitrary number of bytes, | ||
| 149 | you do not require 8 byte padding. Each call to this | ||
| 150 | routine will encrypt the input bytes to output and then update ivec | ||
| 151 | and num. Num contains 'how far' we are though ivec. | ||
| 152 | This is in effect a stream cipher, there is no encryption or | ||
| 153 | decryption mode. | ||
| 154 | |||
| 155 | For reading passwords, I suggest using des_read_pw_string() from my DES library. | ||
| 156 | To generate a password from a text string, I suggest using MD5 (or MD2) to | ||
| 157 | produce a 16 byte message digest that can then be passed directly to | ||
| 158 | RC2_set_key(). | ||
| 159 | |||
| 160 | ===== | ||
| 161 | For more information about the specific RC2 modes in this library | ||
| 162 | (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the | ||
| 163 | documentation on my DES library. What is said about DES is directly | ||
| 164 | applicable for RC2. | ||
| 165 | |||
diff --git a/src/lib/libssl/src/doc/rc4.doc b/src/lib/libssl/src/doc/rc4.doc deleted file mode 100644 index 4b2897eb74..0000000000 --- a/src/lib/libssl/src/doc/rc4.doc +++ /dev/null | |||
| @@ -1,44 +0,0 @@ | |||
| 1 | The RC4 library. | ||
| 2 | RC4 is a stream cipher that operates on a byte stream. It can be used with | ||
| 3 | any length key but I would recommend normally using 16 bytes. | ||
| 4 | |||
| 5 | This library requires the inclusion of 'rc4.h'. | ||
| 6 | |||
| 7 | The RC4 encryption function takes what is called an RC4_KEY as an argument. | ||
| 8 | The RC4_KEY is generated by the RC4_set_key function from the key bytes. | ||
| 9 | |||
| 10 | RC4, being a stream cipher, does not have an encryption or decryption mode. | ||
| 11 | It produces a stream of bytes that the input stream is xor'ed against and | ||
| 12 | so decryption is just a case of 'encrypting' again with the same key. | ||
| 13 | |||
| 14 | I have only put in one 'mode' for RC4 which is the normal one. This means | ||
| 15 | there is no initialisation vector and there is no feedback of the cipher | ||
| 16 | text into the cipher. This implies that you should not ever use the | ||
| 17 | same key twice if you can help it. If you do, you leave yourself open to | ||
| 18 | known plain text attacks; if you know the plain text and | ||
| 19 | corresponding cipher text in one message, all messages that used the same | ||
| 20 | key can have the cipher text decoded for the corresponding positions in the | ||
| 21 | cipher stream. | ||
| 22 | |||
| 23 | The main positive feature of RC4 is that it is a very fast cipher; about 4 | ||
| 24 | times faster that DES. This makes it ideally suited to protocols where the | ||
| 25 | key is randomly chosen, like SSL. | ||
| 26 | |||
| 27 | The functions are as follows: | ||
| 28 | |||
| 29 | void RC4_set_key( | ||
| 30 | RC4_KEY *key; | ||
| 31 | int len; | ||
| 32 | unsigned char *data); | ||
| 33 | This function initialises the RC4_KEY structure with the key passed | ||
| 34 | in 'data', which is 'len' bytes long. The key data can be any | ||
| 35 | length but 16 bytes seems to be a good number. | ||
| 36 | |||
| 37 | void RC4( | ||
| 38 | RC4_KEY *key; | ||
| 39 | unsigned long len; | ||
| 40 | unsigned char *in; | ||
| 41 | unsigned char *out); | ||
| 42 | Do the actual RC4 encryption/decryption. Using the 'key', 'len' | ||
| 43 | bytes are transformed from 'in' to 'out'. As mentioned above, | ||
| 44 | decryption is the operation as encryption. | ||
diff --git a/src/lib/libssl/src/doc/readme b/src/lib/libssl/src/doc/readme deleted file mode 100644 index 824d4fd0e2..0000000000 --- a/src/lib/libssl/src/doc/readme +++ /dev/null | |||
| @@ -1,6 +0,0 @@ | |||
| 1 | This is the old 0.6.6 docuementation. Most of the cipher stuff is still | ||
| 2 | relevent but I'm working (very slowly) on new docuemtation. | ||
| 3 | The current version can be found online at | ||
| 4 | |||
| 5 | http://www.cryptsoft.com/ssleay/doc | ||
| 6 | |||
diff --git a/src/lib/libssl/src/doc/ref.doc b/src/lib/libssl/src/doc/ref.doc deleted file mode 100644 index 211559900d..0000000000 --- a/src/lib/libssl/src/doc/ref.doc +++ /dev/null | |||
| @@ -1,48 +0,0 @@ | |||
| 1 | I have lots more references etc, and will update this list in the future, | ||
| 2 | 30 Aug 1996 - eay | ||
| 3 | |||
| 4 | |||
| 5 | SSL The SSL Protocol - from Netscapes. | ||
| 6 | |||
| 7 | RC4 Newsgroups: sci.crypt | ||
| 8 | From: sterndark@netcom.com (David Sterndark) | ||
| 9 | Subject: RC4 Algorithm revealed. | ||
| 10 | Message-ID: <sternCvKL4B.Hyy@netcom.com> | ||
| 11 | |||
| 12 | RC2 Newsgroups: sci.crypt | ||
| 13 | From: pgut01@cs.auckland.ac.nz (Peter Gutmann) | ||
| 14 | Subject: Specification for Ron Rivests Cipher No.2 | ||
| 15 | Message-ID: <4fk39f$f70@net.auckland.ac.nz> | ||
| 16 | |||
| 17 | MD2 RFC1319 The MD2 Message-Digest Algorithm | ||
| 18 | MD5 RFC1321 The MD5 Message-Digest Algorithm | ||
| 19 | |||
| 20 | X509 Certificates | ||
| 21 | RFC1421 Privacy Enhancement for Internet Electronic Mail: Part I | ||
| 22 | RFC1422 Privacy Enhancement for Internet Electronic Mail: Part II | ||
| 23 | RFC1423 Privacy Enhancement for Internet Electronic Mail: Part III | ||
| 24 | RFC1424 Privacy Enhancement for Internet Electronic Mail: Part IV | ||
| 25 | |||
| 26 | RSA and various standard encoding | ||
| 27 | PKCS#1 RSA Encryption Standard | ||
| 28 | PKCS#5 Password-Based Encryption Standard | ||
| 29 | PKCS#7 Cryptographic Message Syntax Standard | ||
| 30 | A Layman's Guide to a Subset of ASN.1, BER, and DER | ||
| 31 | An Overview of the PKCS Standards | ||
| 32 | Some Examples of the PKCS Standards | ||
| 33 | |||
| 34 | IDEA Chapter 3 The Block Cipher IDEA | ||
| 35 | |||
| 36 | RSA, prime number generation and bignum algorithms | ||
| 37 | Introduction To Algorithms, | ||
| 38 | Thomas Cormen, Charles Leiserson, Ronald Rivest, | ||
| 39 | Section 29 Arithmetic Circuits | ||
| 40 | Section 33 Number-Theoretic Algorithms | ||
| 41 | |||
| 42 | Fast Private Key algorithm | ||
| 43 | Fast Decipherment Algorithm for RSA Public-Key Cryptosystem | ||
| 44 | J.-J. Quisquater and C. Couvreur, Electronics Letters, | ||
| 45 | 14th October 1982, Vol. 18 No. 21 | ||
| 46 | |||
| 47 | Prime number generation and bignum algorithms. | ||
| 48 | PGP-2.3a | ||
diff --git a/src/lib/libssl/src/doc/req.1 b/src/lib/libssl/src/doc/req.1 deleted file mode 100644 index 684fda580e..0000000000 --- a/src/lib/libssl/src/doc/req.1 +++ /dev/null | |||
| @@ -1,137 +0,0 @@ | |||
| 1 | The 'req' command is used to manipulate and deal with pkcs#10 | ||
| 2 | certificate requests. | ||
| 3 | |||
| 4 | It's default mode of operation is to load a certificate and then | ||
| 5 | write it out again. | ||
| 6 | |||
| 7 | By default the 'req' is read from stdin in 'PEM' format. | ||
| 8 | The -inform option can be used to specify 'pem' format or 'der' | ||
| 9 | format. PEM format is the base64 encoding of the DER format. | ||
| 10 | |||
| 11 | By default 'req' then writes the request back out. -outform can be used | ||
| 12 | to indicate the desired output format, be it 'pem' or 'der'. | ||
| 13 | |||
| 14 | To specify an input file, use the '-in' option and the '-out' option | ||
| 15 | can be used to specify the output file. | ||
| 16 | |||
| 17 | If you wish to perform a command and not output the certificate | ||
| 18 | request afterwards, use the '-noout' option. | ||
| 19 | |||
| 20 | When a certificate is loaded, it can be printed in a human readable | ||
| 21 | ascii format via the '-text' option. | ||
| 22 | |||
| 23 | To check that the signature on a certificate request is correct, use | ||
| 24 | the '-verify' option to make sure that the private key contained in the | ||
| 25 | certificate request corresponds to the signature. | ||
| 26 | |||
| 27 | Besides the default mode, there is also the 'generate a certificate | ||
| 28 | request' mode. There are several flags that trigger this mode. | ||
| 29 | |||
| 30 | -new will generate a new RSA key (if required) and then prompts | ||
| 31 | the user for details for the certificate request. | ||
| 32 | -newkey has an argument that is the number of bits to make the new | ||
| 33 | key. This function also triggers '-new'. | ||
| 34 | |||
| 35 | The '-new' option can have a key to use specified instead of having to | ||
| 36 | load one, '-key' is used to specify the file containg the key. | ||
| 37 | -keyform can be used to specify the format of the key. Only | ||
| 38 | 'pem' and 'der' formats are supported, later, 'netscape' format may be added. | ||
| 39 | |||
| 40 | Finally there is the '-x509' options which makes req output a self | ||
| 41 | signed x509 certificate instead of a certificate request. | ||
| 42 | |||
| 43 | Now as you may have noticed, there are lots of default options that | ||
| 44 | cannot be specified via the command line. They are held in a 'template' | ||
| 45 | or 'configuration file'. The -config option specifies which configuration | ||
| 46 | file to use. See conf.doc for details on the syntax of this file. | ||
| 47 | |||
| 48 | The req command uses the 'req' section of the config file. | ||
| 49 | |||
| 50 | --- | ||
| 51 | # The following variables are defined. For this example I will populate | ||
| 52 | # the various values | ||
| 53 | [ req ] | ||
| 54 | default_bits = 512 # default number of bits to use. | ||
| 55 | default_keyfile = testkey.pem # Where to write the generated keyfile | ||
| 56 | # if not specified. | ||
| 57 | distinguished_name= req_dn # The section that contains the | ||
| 58 | # information about which 'object' we | ||
| 59 | # want to put in the DN. | ||
| 60 | attributes = req_attr # The objects we want for the | ||
| 61 | # attributes field. | ||
| 62 | encrypt_rsa_key = no # Should we encrypt newly generated | ||
| 63 | # keys. I strongly recommend 'yes'. | ||
| 64 | |||
| 65 | # The distinguished name section. For the following entries, the | ||
| 66 | # object names must exist in the SSLeay header file objects.h. If they | ||
| 67 | # do not, they will be silently ignored. The entries have the following | ||
| 68 | # format. | ||
| 69 | # <object_name> => string to prompt with | ||
| 70 | # <object_name>_default => default value for people | ||
| 71 | # <object_name>_value => Automatically use this value for this field. | ||
| 72 | # <object_name>_min => minimum number of characters for data (def. 0) | ||
| 73 | # <object_name>_max => maximum number of characters for data (def. inf.) | ||
| 74 | # All of these entries are optional except for the first one. | ||
| 75 | [ req_dn ] | ||
| 76 | countryName = Country Name (2 letter code) | ||
| 77 | countryName_default = AU | ||
| 78 | |||
| 79 | stateOrProvinceName = State or Province Name (full name) | ||
| 80 | stateOrProvinceName_default = Queensland | ||
| 81 | |||
| 82 | localityName = Locality Name (eg, city) | ||
| 83 | |||
| 84 | organizationName = Organization Name (eg, company) | ||
| 85 | organizationName_default = Mincom Pty Ltd | ||
| 86 | |||
| 87 | organizationalUnitName = Organizational Unit Name (eg, section) | ||
| 88 | organizationalUnitName_default = MTR | ||
| 89 | |||
| 90 | commonName = Common Name (eg, YOUR name) | ||
| 91 | commonName_max = 64 | ||
| 92 | |||
| 93 | emailAddress = Email Address | ||
| 94 | emailAddress_max = 40 | ||
| 95 | |||
| 96 | # The next section is the attributes section. This is exactly the | ||
| 97 | # same as for the previous section except that the resulting objects are | ||
| 98 | # put in the attributes field. | ||
| 99 | [ req_attr ] | ||
| 100 | challengePassword = A challenge password | ||
| 101 | challengePassword_min = 4 | ||
| 102 | challengePassword_max = 20 | ||
| 103 | |||
| 104 | unstructuredName = An optional company name | ||
| 105 | |||
| 106 | ---- | ||
| 107 | Also note that the order that attributes appear in this file is the | ||
| 108 | order they will be put into the distinguished name. | ||
| 109 | |||
| 110 | Once this request has been generated, it can be sent to a CA for | ||
| 111 | certifying. | ||
| 112 | |||
| 113 | ---- | ||
| 114 | A few quick examples.... | ||
| 115 | |||
| 116 | To generate a new request and a new key | ||
| 117 | req -new | ||
| 118 | |||
| 119 | To generate a new request and a 1058 bit key | ||
| 120 | req -newkey 1058 | ||
| 121 | |||
| 122 | To generate a new request using a pre-existing key | ||
| 123 | req -new -key key.pem | ||
| 124 | |||
| 125 | To generate a self signed x509 certificate from a certificate | ||
| 126 | request using a supplied key, and we want to see the text form of the | ||
| 127 | output certificate (which we will put in the file selfSign.pem | ||
| 128 | req -x509 -in req.pem -key key.pem -text -out selfSign.pem | ||
| 129 | |||
| 130 | Verify that the signature is correct on a certificate request. | ||
| 131 | req -verify -in req.pem | ||
| 132 | |||
| 133 | Verify that the signature was made using a specified public key. | ||
| 134 | req -verify -in req.pem -key key.pem | ||
| 135 | |||
| 136 | Print the contents of a certificate request | ||
| 137 | req -text -in req.pem | ||
diff --git a/src/lib/libssl/src/doc/rsa.doc b/src/lib/libssl/src/doc/rsa.doc deleted file mode 100644 index f260452bc6..0000000000 --- a/src/lib/libssl/src/doc/rsa.doc +++ /dev/null | |||
| @@ -1,135 +0,0 @@ | |||
| 1 | The RSA encryption and utility routines. | ||
| 2 | |||
| 3 | The RSA routines are built on top of a big number library (the BN library). | ||
| 4 | There are support routines in the X509 library for loading and manipulating | ||
| 5 | the various objects in the RSA library. When errors are returned, read | ||
| 6 | about the ERR library for how to access the error codes. | ||
| 7 | |||
| 8 | All RSA encryption is done according to the PKCS-1 standard which is | ||
| 9 | compatible with PEM and RSAref. This means that any values being encrypted | ||
| 10 | must be less than the size of the modulus in bytes, minus 10, bytes long. | ||
| 11 | |||
| 12 | This library uses RAND_bytes()() for it's random data, make sure to feed | ||
| 13 | RAND_seed() with lots of interesting and varied data before using these | ||
| 14 | routines. | ||
| 15 | |||
| 16 | The RSA library has one specific data type, the RSA structure. | ||
| 17 | It is composed of 8 BIGNUM variables (see the BN library for details) and | ||
| 18 | can hold either a private RSA key or a public RSA key. | ||
| 19 | Some RSA libraries have different structures for public and private keys, I | ||
| 20 | don't. For my libraries, a public key is determined by the fact that the | ||
| 21 | RSA->d value is NULL. These routines will operate on any size RSA keys. | ||
| 22 | While I'm sure 4096 bit keys are very very secure, they take a lot longer | ||
| 23 | to process that 1024 bit keys :-). | ||
| 24 | |||
| 25 | The function in the RSA library are as follows. | ||
| 26 | |||
| 27 | RSA *RSA_new(); | ||
| 28 | This function creates a new RSA object. The sub-fields of the RSA | ||
| 29 | type are also malloced so you should always use this routine to | ||
| 30 | create RSA variables. | ||
| 31 | |||
| 32 | void RSA_free( | ||
| 33 | RSA *rsa); | ||
| 34 | This function 'frees' an RSA structure. This routine should always | ||
| 35 | be used to free the RSA structure since it will also 'free' any | ||
| 36 | sub-fields of the RSA type that need freeing. | ||
| 37 | |||
| 38 | int RSA_size( | ||
| 39 | RSA *rsa); | ||
| 40 | This function returns the size of the RSA modulus in bytes. Why do | ||
| 41 | I need this you may ask, well the reason is that when you encrypt | ||
| 42 | with RSA, the output string will be the size of the RSA modulus. | ||
| 43 | So the output for the RSA_encrypt and the input for the RSA_decrypt | ||
| 44 | routines need to be RSA_size() bytes long, because this is how many | ||
| 45 | bytes are expected. | ||
| 46 | |||
| 47 | For the following 4 RSA encryption routines, it should be noted that | ||
| 48 | RSA_private_decrypt() should be used on the output from | ||
| 49 | RSA_public_encrypt() and RSA_public_decrypt() should be used on | ||
| 50 | the output from RSA_private_encrypt(). | ||
| 51 | |||
| 52 | int RSA_public_encrypt( | ||
| 53 | int from_len; | ||
| 54 | unsigned char *from | ||
| 55 | unsigned char *to | ||
| 56 | RSA *rsa); | ||
| 57 | This function implements RSA public encryption, the rsa variable | ||
| 58 | should be a public key (but can be a private key). 'from_len' | ||
| 59 | bytes taken from 'from' and encrypted and put into 'to'. 'to' needs | ||
| 60 | to be at least RSA_size(rsa) bytes long. The number of bytes | ||
| 61 | written into 'to' is returned. -1 is returned on an error. The | ||
| 62 | operation performed is | ||
| 63 | to = from^rsa->e mod rsa->n. | ||
| 64 | |||
| 65 | int RSA_private_encrypt( | ||
| 66 | int from_len; | ||
| 67 | unsigned char *from | ||
| 68 | unsigned char *to | ||
| 69 | RSA *rsa); | ||
| 70 | This function implements RSA private encryption, the rsa variable | ||
| 71 | should be a private key. 'from_len' bytes taken from | ||
| 72 | 'from' and encrypted and put into 'to'. 'to' needs | ||
| 73 | to be at least RSA_size(rsa) bytes long. The number of bytes | ||
| 74 | written into 'to' is returned. -1 is returned on an error. The | ||
| 75 | operation performed is | ||
| 76 | to = from^rsa->d mod rsa->n. | ||
| 77 | |||
| 78 | int RSA_public_decrypt( | ||
| 79 | int from_len; | ||
| 80 | unsigned char *from | ||
| 81 | unsigned char *to | ||
| 82 | RSA *rsa); | ||
| 83 | This function implements RSA public decryption, the rsa variable | ||
| 84 | should be a public key (but can be a private key). 'from_len' | ||
| 85 | bytes are taken from 'from' and decrypted. The decrypted data is | ||
| 86 | put into 'to'. The number of bytes encrypted is returned. -1 is | ||
| 87 | returned to indicate an error. The operation performed is | ||
| 88 | to = from^rsa->e mod rsa->n. | ||
| 89 | |||
| 90 | int RSA_private_decrypt( | ||
| 91 | int from_len; | ||
| 92 | unsigned char *from | ||
| 93 | unsigned char *to | ||
| 94 | RSA *rsa); | ||
| 95 | This function implements RSA private decryption, the rsa variable | ||
| 96 | should be a private key. 'from_len' bytes are taken | ||
| 97 | from 'from' and decrypted. The decrypted data is | ||
| 98 | put into 'to'. The number of bytes encrypted is returned. -1 is | ||
| 99 | returned to indicate an error. The operation performed is | ||
| 100 | to = from^rsa->d mod rsa->n. | ||
| 101 | |||
| 102 | int RSA_mod_exp( | ||
| 103 | BIGNUM *n; | ||
| 104 | BIGNUM *p; | ||
| 105 | RSA *rsa); | ||
| 106 | Normally you will never use this routine. | ||
| 107 | This is really an internal function which is called by | ||
| 108 | RSA_private_encrypt() and RSA_private_decrypt(). It performs | ||
| 109 | n=n^p mod rsa->n except that it uses the 5 extra variables in the | ||
| 110 | RSA structure to make this more efficient. | ||
| 111 | |||
| 112 | RSA *RSA_generate_key( | ||
| 113 | int bits; | ||
| 114 | unsigned long e; | ||
| 115 | void (*callback)(); | ||
| 116 | char *cb_arg; | ||
| 117 | This routine is used to generate RSA private keys. It takes | ||
| 118 | quite a period of time to run and should only be used to | ||
| 119 | generate initial private keys that should then be stored | ||
| 120 | for later use. The passed callback function | ||
| 121 | will be called periodically so that feedback can be given | ||
| 122 | as to how this function is progressing. | ||
| 123 | 'bits' is the length desired for the modulus, so it would be 1024 | ||
| 124 | to generate a 1024 bit private key. | ||
| 125 | 'e' is the value to use for the public exponent 'e'. Traditionally | ||
| 126 | it is set to either 3 or 0x10001. | ||
| 127 | The callback function (if not NULL) is called in the following | ||
| 128 | situations. | ||
| 129 | when we have generated a suspected prime number to test, | ||
| 130 | callback(0,num1++,cb_arg). When it passes a prime number test, | ||
| 131 | callback(1,num2++,cb_arg). When it is rejected as one of | ||
| 132 | the 2 primes required due to gcd(prime,e value) != 0, | ||
| 133 | callback(2,num3++,cb_arg). When finally accepted as one | ||
| 134 | of the 2 primes, callback(3,num4++,cb_arg). | ||
| 135 | |||
diff --git a/src/lib/libssl/src/doc/rsaref.doc b/src/lib/libssl/src/doc/rsaref.doc deleted file mode 100644 index 0505b76f76..0000000000 --- a/src/lib/libssl/src/doc/rsaref.doc +++ /dev/null | |||
| @@ -1,35 +0,0 @@ | |||
| 1 | This package can be compiled to use the RSAref library. | ||
| 2 | This library is not allowed outside of the USA but inside the USA it is | ||
| 3 | claimed by RSA to be the only RSA public key library that can be used | ||
| 4 | besides BSAFE.. | ||
| 5 | |||
| 6 | There are 2 files, rsaref/rsaref.c and rsaref/rsaref.h that contain the glue | ||
| 7 | code to use RSAref. These files were written by looking at the PGP | ||
| 8 | source code and seeing which routines it used to access RSAref. | ||
| 9 | I have also been sent by some-one a copy of the RSAref header file that | ||
| 10 | contains the library error codes. | ||
| 11 | |||
| 12 | [ Jun 1996 update - I have recently gotten hold of RSAref 2.0 from | ||
| 13 | South Africa and have been doing some performace tests. ] | ||
| 14 | |||
| 15 | They have now been tested against the recently announced RSAEURO | ||
| 16 | library. | ||
| 17 | |||
| 18 | There are 2 ways to use SSLeay and RSAref. First, to build so that | ||
| 19 | the programs must be linked with RSAref, add '-DRSAref' to CFLAG in the top | ||
| 20 | level makefile and -lrsaref (or where ever you are keeping RSAref) to | ||
| 21 | EX_LIBS. | ||
| 22 | |||
| 23 | To build a makefile via util/mk1mf.pl to do this, use the 'rsaref' option. | ||
| 24 | |||
| 25 | The second method is to build as per normal and link applications with | ||
| 26 | the RSAglue library. The correct library order would be | ||
| 27 | cc -o cmd cmd.o -lssl -lRSAglue -lcrypto -lrsaref -ldes | ||
| 28 | The RSAglue library is built in the rsa directory and is NOT | ||
| 29 | automatically installed. | ||
| 30 | |||
| 31 | Be warned that the RSAEURO library, that is claimed to be compatible | ||
| 32 | with RSAref contains a different value for the maximum number of bits | ||
| 33 | supported. This changes structure sizes and so if you are using | ||
| 34 | RSAEURO, change the value of RSAref_MAX_BITS in rsa/rsaref.h | ||
| 35 | |||
diff --git a/src/lib/libssl/src/doc/s_mult.doc b/src/lib/libssl/src/doc/s_mult.doc deleted file mode 100644 index 726085bc57..0000000000 --- a/src/lib/libssl/src/doc/s_mult.doc +++ /dev/null | |||
| @@ -1,17 +0,0 @@ | |||
| 1 | s_mult is a test program I hacked up on a Sunday for testing non-blocking | ||
| 2 | IO. It has a select loop at it's centre that handles multiple readers | ||
| 3 | and writers. | ||
| 4 | |||
| 5 | Try the following command | ||
| 6 | ssleay s_mult -echo -nbio -ssl -v | ||
| 7 | echo - sends any sent text back to the sender | ||
| 8 | nbio - turns on non-blocking IO | ||
| 9 | ssl - accept SSL connections, default is normal text | ||
| 10 | v - print lots | ||
| 11 | type Q<cr> to quit | ||
| 12 | |||
| 13 | In another window, run the following | ||
| 14 | ssleay s_client -pause </etc/termcap | ||
| 15 | |||
| 16 | The pause option puts in a 1 second pause in each read(2)/write(2) call | ||
| 17 | so the other end will have read()s fail. | ||
diff --git a/src/lib/libssl/src/doc/session.doc b/src/lib/libssl/src/doc/session.doc deleted file mode 100644 index ffccb0306e..0000000000 --- a/src/lib/libssl/src/doc/session.doc +++ /dev/null | |||
| @@ -1,297 +0,0 @@ | |||
| 1 | I have just checked over and re-worked the session stuff. | ||
| 2 | The following brief example will ignore all setup information to do with | ||
| 3 | authentication. | ||
| 4 | |||
| 5 | Things operate as follows. | ||
| 6 | |||
| 7 | The SSL environment has a 'context', a SSL_CTX structure. This holds the | ||
| 8 | cached SSL_SESSIONS (which can be reused) and the certificate lookup | ||
| 9 | information. Each SSL structure needs to be associated with a SSL_CTX. | ||
| 10 | Normally only one SSL_CTX structure is needed per program. | ||
| 11 | |||
| 12 | SSL_CTX *SSL_CTX_new(void ); | ||
| 13 | void SSL_CTX_free(SSL_CTX *); | ||
| 14 | These 2 functions create and destroy SSL_CTX structures | ||
| 15 | |||
| 16 | The SSL_CTX has a session_cache_mode which is by default, | ||
| 17 | in SSL_SESS_CACHE_SERVER mode. What this means is that the library | ||
| 18 | will automatically add new session-id's to the cache apon sucsessful | ||
| 19 | SSL_accept() calls. | ||
| 20 | If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added | ||
| 21 | to the cache. | ||
| 22 | SSL_set_session_cache_mode(ctx,mode) will set the 'mode' and | ||
| 23 | SSL_get_session_cache_mode(ctx) will get the cache 'mode'. | ||
| 24 | The modes can be | ||
| 25 | SSL_SESS_CACHE_OFF - no caching | ||
| 26 | SSL_SESS_CACHE_CLIENT - only SSL_connect() | ||
| 27 | SSL_SESS_CACHE_SERVER - only SSL_accept() | ||
| 28 | SSL_SESS_NO_CACHE_BOTH - Either SSL_accept() or SSL_connect(). | ||
| 29 | If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are | ||
| 30 | not automatically removed each 255, SSL_connect()s or SSL_accept()s. | ||
| 31 | |||
| 32 | By default, apon every 255 successful SSL_connect() or SSL_accept()s, | ||
| 33 | the cache is flush. Please note that this could be expensive on | ||
| 34 | a heavily loaded SSL server, in which case, turn this off and | ||
| 35 | clear the cache of old entries 'manually' (with one of the functions | ||
| 36 | listed below) every few hours. Perhaps I should up this number, it is hard | ||
| 37 | to say. Remember, the '255' new calls is just a mechanims to get called | ||
| 38 | every now and then, in theory at most 255 new session-id's will have been | ||
| 39 | added but if 100 are added every minute, you would still have | ||
| 40 | 500 in the cache before any would start being flushed (assuming a 3 minute | ||
| 41 | timeout).. | ||
| 42 | |||
| 43 | int SSL_CTX_sess_hits(SSL_CTX *ctx); | ||
| 44 | int SSL_CTX_sess_misses(SSL_CTX *ctx); | ||
| 45 | int SSL_CTX_sess_timeouts(SSL_CTX *ctx); | ||
| 46 | These 3 functions return statistics about the SSL_CTX. These 3 are the | ||
| 47 | number of session id reuses. hits is the number of reuses, misses are the | ||
| 48 | number of lookups that failed, and timeouts is the number of cached | ||
| 49 | entries ignored because they had timeouted. | ||
| 50 | |||
| 51 | ctx->new_session_cb is a function pointer to a function of type | ||
| 52 | int new_session_callback(SSL *ssl,SSL_SESSION *new); | ||
| 53 | This function, if set in the SSL_CTX structure is called whenever a new | ||
| 54 | SSL_SESSION is added to the cache. If the callback returns non-zero, it | ||
| 55 | means that the application will have to do a SSL_SESSION_free() | ||
| 56 | on the structure (this is | ||
| 57 | to do with the cache keeping the reference counts correct, without the | ||
| 58 | application needing to know about it. | ||
| 59 | The 'active' parameter is the current SSL session for which this connection | ||
| 60 | was created. | ||
| 61 | |||
| 62 | void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,int (*cb)()); | ||
| 63 | to set the callback, | ||
| 64 | int (*cb)() SSL_CTX_sess_get_new_cb(SSL_CTX *ctx) | ||
| 65 | to get the callback. | ||
| 66 | |||
| 67 | If the 'get session' callback is set, when a session id is looked up and | ||
| 68 | it is not in the session-id cache, this callback is called. The callback is | ||
| 69 | of the form | ||
| 70 | SSL_SESSION *get_session_callback(unsigned char *sess_id,int sess_id_len, | ||
| 71 | int *copy); | ||
| 72 | |||
| 73 | The get_session_callback is intended to return null if no session id is found. | ||
| 74 | The reference count on the SSL_SESSION in incremented by the SSL library, | ||
| 75 | if copy is 1. Otherwise, the reference count is not modified. | ||
| 76 | |||
| 77 | void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and | ||
| 78 | int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback. | ||
| 79 | |||
| 80 | These callbacks are basically indended to be used by processes to | ||
| 81 | send their session-id's to other processes. I currently have not implemented | ||
| 82 | non-blocking semantics for these callbacks, it is upto the appication | ||
| 83 | to make the callbacks effiecent if they require blocking (perhaps | ||
| 84 | by 'saving' them and then 'posting them' when control returns from | ||
| 85 | the SSL_accept(). | ||
| 86 | |||
| 87 | LHASH *SSL_CTX_sessions(SSL_CTX *ctx) | ||
| 88 | This returns the session cache. The lhash strucutre can be accessed for | ||
| 89 | statistics about the cache. | ||
| 90 | |||
| 91 | void lh_stats(LHASH *lh, FILE *out); | ||
| 92 | void lh_node_stats(LHASH *lh, FILE *out); | ||
| 93 | void lh_node_usage_stats(LHASH *lh, FILE *out); | ||
| 94 | |||
| 95 | can be used to print details about it's activity and current state. | ||
| 96 | You can also delve directly into the lhash structure for 14 different | ||
| 97 | counters that are kept against the structure. When I wrote the lhash library, | ||
| 98 | I was interested in gathering statistics :-). | ||
| 99 | Have a read of doc/lhash.doc in the SSLeay distribution area for more details | ||
| 100 | on the lhash library. | ||
| 101 | |||
| 102 | Now as mentioned ealier, when a SSL is created, it needs a SSL_CTX. | ||
| 103 | SSL * SSL_new(SSL_CTX *); | ||
| 104 | |||
| 105 | This stores a session. A session is secret information shared between 2 | ||
| 106 | SSL contexts. It will only be created if both ends of the connection have | ||
| 107 | authenticated their peer to their satisfaction. It basically contains | ||
| 108 | the information required to use a particular secret key cipher. | ||
| 109 | |||
| 110 | To retrieve the SSL_CTX being used by a SSL, | ||
| 111 | SSL_CTX *SSL_get_SSL_CTX(SSL *s); | ||
| 112 | |||
| 113 | Now when a SSL session is established between to programs, the 'session' | ||
| 114 | information that is cached in the SSL_CTX can me manipulated by the | ||
| 115 | following functions. | ||
| 116 | int SSL_set_session(SSL *s, SSL_SESSION *session); | ||
| 117 | This will set the SSL_SESSION to use for the next SSL_connect(). If you use | ||
| 118 | this function on an already 'open' established SSL connection, 'bad things | ||
| 119 | will happen'. This function is meaning-less when used on a ssl strucutre | ||
| 120 | that is just about to be used in a SSL_accept() call since the | ||
| 121 | SSL_accept() will either create a new session or retrieve one from the | ||
| 122 | cache. | ||
| 123 | |||
| 124 | SSL_SESSION *SSL_get_session(SSL *s); | ||
| 125 | This will return the SSL_SESSION for the current SSL, NULL if there is | ||
| 126 | no session associated with the SSL structure. | ||
| 127 | |||
| 128 | The SSL sessions are kept in the SSL_CTX in a hash table, to remove a | ||
| 129 | session | ||
| 130 | void SSL_CTX_remove_session(SSL_CTX *,SSL_SESSION *c); | ||
| 131 | and to add one | ||
| 132 | int SSL_CTX_add_session(SSL_CTX *s, SSL_SESSION *c); | ||
| 133 | SSL_CTX_add_session() returns 1 if the session was already in the cache (so it | ||
| 134 | was not added). | ||
| 135 | Whenever a new session is created via SSL_connect()/SSL_accept(), | ||
| 136 | they are automatically added to the cache, depending on the session_cache_mode | ||
| 137 | settings. SSL_set_session() | ||
| 138 | does not add it to the cache. Just call SSL_CTX_add_session() if you do want the | ||
| 139 | session added. For a 'client' this would not normally be the case. | ||
| 140 | SSL_CTX_add_session() is not normally ever used, except for doing 'evil' things | ||
| 141 | which the next 2 funtions help you do. | ||
| 142 | |||
| 143 | int i2d_SSL_SESSION(SSL_SESSION *in,unsigned char **pp); | ||
| 144 | SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a,unsigned char **pp,long length); | ||
| 145 | These 2 functions are in the standard ASN1 library form and can be used to | ||
| 146 | load and save to a byte format, the SSL_SESSION structure. | ||
| 147 | With these functions, you can save and read these structures to a files or | ||
| 148 | arbitary byte string. | ||
| 149 | The PEM_write_SSL_SESSION(fp,x) and PEM_read_SSL_SESSION(fp,x,cb) will | ||
| 150 | write to a file pointer in base64 encoding. | ||
| 151 | |||
| 152 | What you can do with this, is pass session information between separate | ||
| 153 | processes. Please note, that you will probably also need to modify the | ||
| 154 | timeout information on the SSL_SESSIONs. | ||
| 155 | |||
| 156 | long SSL_get_time(SSL_SESSION *s) | ||
| 157 | will return the 'time' that the session | ||
| 158 | was loaded. The timeout is relative to this time. This information is | ||
| 159 | saved when the SSL_SESSION is converted to binarary but it is stored | ||
| 160 | in as a unix long, which is rather OS dependant, but easy to convert back. | ||
| 161 | |||
| 162 | long SSL_set_time(SSL_SESSION *s,long t) will set the above mentioned time. | ||
| 163 | The time value is just the value returned from time(3), and should really | ||
| 164 | be defined by be to be time_t. | ||
| 165 | |||
| 166 | long SSL_get_timeout(SSL_SESSION *s); | ||
| 167 | long SSL_set_timeout(SSL_SESSION *s,long t); | ||
| 168 | These 2 retrieve and set the timeout which is just a number of secconds | ||
| 169 | from the 'SSL_get_time()' value. When this time period has elapesed, | ||
| 170 | the session will no longer be in the cache (well it will actually be removed | ||
| 171 | the next time it is attempted to be retrieved, so you could 'bump' | ||
| 172 | the timeout so it remains valid). | ||
| 173 | The 'time' and 'timeout' are set on a session when it is created, not reset | ||
| 174 | each time it is reused. If you did wish to 'bump it', just after establishing | ||
| 175 | a connection, do a | ||
| 176 | SSL_set_time(ssl,time(NULL)); | ||
| 177 | |||
| 178 | You can also use | ||
| 179 | SSL_CTX_set_timeout(SSL_CTX *ctx,unsigned long t) and | ||
| 180 | SSL_CTX_get_timeout(SSL_CTX *ctx) to manipulate the default timeouts for | ||
| 181 | all SSL connections created against a SSL_CTX. If you set a timeout in | ||
| 182 | an SSL_CTX, all new SSL's created will inherit the timeout. It can be over | ||
| 183 | written by the SSL_set_timeout(SSL *s,unsigned long t) function call. | ||
| 184 | If you 'set' the timeout back to 0, the system default will be used. | ||
| 185 | |||
| 186 | SSL_SESSION *SSL_SESSION_new(); | ||
| 187 | void SSL_SESSION_free(SSL_SESSION *ses); | ||
| 188 | These 2 functions are used to create and dispose of SSL_SESSION functions. | ||
| 189 | You should not ever normally need to use them unless you are using | ||
| 190 | i2d_SSL_SESSION() and/or d2i_SSL_SESSION(). If you 'load' a SSL_SESSION | ||
| 191 | via d2i_SSL_SESSION(), you will need to SSL_SESSION_free() it. | ||
| 192 | Both SSL_set_session() and SSL_CTX_add_session() will 'take copies' of the | ||
| 193 | structure (via reference counts) when it is passed to them. | ||
| 194 | |||
| 195 | SSL_CTX_flush_sessions(ctx,time); | ||
| 196 | The first function will clear all sessions from the cache, which have expired | ||
| 197 | relative to 'time' (which could just be time(NULL)). | ||
| 198 | |||
| 199 | SSL_CTX_flush_sessions(ctx,0); | ||
| 200 | This is a special case that clears everything. | ||
| 201 | |||
| 202 | As a final comment, a 'session' is not enough to establish a new | ||
| 203 | connection. If a session has timed out, a certificate and private key | ||
| 204 | need to have been associated with the SSL structure. | ||
| 205 | SSL_copy_session_id(SSL *to,SSL *from); will copy not only the session | ||
| 206 | strucutre but also the private key and certificate associated with | ||
| 207 | 'from'. | ||
| 208 | |||
| 209 | EXAMPLES. | ||
| 210 | |||
| 211 | So lets play at being a wierd SSL server. | ||
| 212 | |||
| 213 | /* setup a context */ | ||
| 214 | ctx=SSL_CTX_new(); | ||
| 215 | |||
| 216 | /* Lets load some session from binary into the cache, why one would do | ||
| 217 | * this is not toally clear, but passing between programs does make sense | ||
| 218 | * Perhaps you are using 4096 bit keys and are happy to keep them | ||
| 219 | * valid for a week, to avoid the RSA overhead of 15 seconds, I'm not toally | ||
| 220 | * sure, perhaps this is a process called from an SSL inetd and this is being | ||
| 221 | * passed to the application. */ | ||
| 222 | session=d2i_SSL_SESSION(....) | ||
| 223 | SSL_CTX_add_session(ctx,session); | ||
| 224 | |||
| 225 | /* Lets even add a session from a file */ | ||
| 226 | session=PEM_read_SSL_SESSION(....) | ||
| 227 | SSL_CTX_add_session(ctx,session); | ||
| 228 | |||
| 229 | /* create a new SSL structure */ | ||
| 230 | ssl=SSL_new(ctx); | ||
| 231 | |||
| 232 | /* At this point we want to be able to 'create' new session if | ||
| 233 | * required, so we need a certificate and RSAkey. */ | ||
| 234 | SSL_use_RSAPrivateKey_file(ssl,...) | ||
| 235 | SSL_use_certificate_file(ssl,...) | ||
| 236 | |||
| 237 | /* Now since we are a server, it make little sence to load a session against | ||
| 238 | * the ssl strucutre since a SSL_accept() will either create a new session or | ||
| 239 | * grab an existing one from the cache. */ | ||
| 240 | |||
| 241 | /* grab a socket descriptor */ | ||
| 242 | fd=accept(...); | ||
| 243 | |||
| 244 | /* associated it with the ssl strucutre */ | ||
| 245 | SSL_set_fd(ssl,fd); | ||
| 246 | |||
| 247 | SSL_accept(ssl); /* 'do' SSL using out cert and RSA key */ | ||
| 248 | |||
| 249 | /* Lets print out the session details or lets save it to a file, | ||
| 250 | * perhaps with a secret key cipher, so that we can pass it to the FBI | ||
| 251 | * when they want to decode the session :-). While we have RSA | ||
| 252 | * this does not matter much but when I do SSLv3, this will allow a mechanism | ||
| 253 | * for the server/client to record the information needed to decode | ||
| 254 | * the traffic that went over the wire, even when using Diffie-Hellman */ | ||
| 255 | PEM_write_SSL_SESSION(SSL_get_session(ssl),stdout,....) | ||
| 256 | |||
| 257 | Lets 'connect' back to the caller using the same session id. | ||
| 258 | |||
| 259 | ssl2=SSL_new(ctx); | ||
| 260 | fd2=connect(them); | ||
| 261 | SSL_set_fd(ssl2,fd2); | ||
| 262 | SSL_set_session(ssl2,SSL_get_session(ssl)); | ||
| 263 | SSL_connect(ssl2); | ||
| 264 | |||
| 265 | /* what the hell, lets accept no more connections using this session */ | ||
| 266 | SSL_CTX_remove_session(SSL_get_SSL_CTX(ssl),SSL_get_session(ssl)); | ||
| 267 | |||
| 268 | /* we could have just as easily used ssl2 since they both are using the | ||
| 269 | * same session. | ||
| 270 | * You will note that both ssl and ssl2 are still using the session, and | ||
| 271 | * the SSL_SESSION structure will be free()ed when both ssl and ssl2 | ||
| 272 | * finish using the session. Also note that you could continue to initiate | ||
| 273 | * connections using this session by doing SSL_get_session(ssl) to get the | ||
| 274 | * existing session, but SSL_accept() will not be able to find it to | ||
| 275 | * use for incoming connections. | ||
| 276 | * Of corse, the session will timeout at the far end and it will no | ||
| 277 | * longer be accepted after a while. The time and timeout are ignored except | ||
| 278 | * by SSL_accept(). */ | ||
| 279 | |||
| 280 | /* Since we have had our server running for 10 weeks, and memory is getting | ||
| 281 | * short, perhaps we should clear the session cache to remove those | ||
| 282 | * 100000 session entries that have expired. Some may consider this | ||
| 283 | * a memory leak :-) */ | ||
| 284 | |||
| 285 | SSL_CTX_flush_sessions(ctx,time(NULL)); | ||
| 286 | |||
| 287 | /* Ok, after a bit more time we wish to flush all sessions from the cache | ||
| 288 | * so that all new connections will be authenticated and incure the | ||
| 289 | * public key operation overhead */ | ||
| 290 | |||
| 291 | SSL_CTX_flush_sessions(ctx,0); | ||
| 292 | |||
| 293 | /* As a final note, to copy everything to do with a SSL, use */ | ||
| 294 | SSL_copy_session_id(SSL *to,SSL *from); | ||
| 295 | /* as this also copies the certificate and RSA key so new session can | ||
| 296 | * be established using the same details */ | ||
| 297 | |||
diff --git a/src/lib/libssl/src/doc/sha.doc b/src/lib/libssl/src/doc/sha.doc deleted file mode 100644 index 895fa182ed..0000000000 --- a/src/lib/libssl/src/doc/sha.doc +++ /dev/null | |||
| @@ -1,52 +0,0 @@ | |||
| 1 | The SHA (Secure Hash Algorithm) library. | ||
| 2 | SHA is a message digest algorithm that can be used to condense an arbitrary | ||
| 3 | length message down to a 20 byte hash. The functions all need to be passed | ||
| 4 | a SHA_CTX which is used to hold the SHA context during multiple SHA_Update() | ||
| 5 | function calls. The normal method of use for this library is as follows | ||
| 6 | This library contains both SHA and SHA-1 digest algorithms. SHA-1 is | ||
| 7 | an update to SHA (which should really be called SHA-0 now) which | ||
| 8 | tweaks the algorithm slightly. The SHA-1 algorithm is used by simply | ||
| 9 | using SHA1_Init(), SHA1_Update(), SHA1_Final() and SHA1() instead of the | ||
| 10 | SHA*() calls | ||
| 11 | |||
| 12 | SHA_Init(...); | ||
| 13 | SHA_Update(...); | ||
| 14 | ... | ||
| 15 | SHA_Update(...); | ||
| 16 | SHA_Final(...); | ||
| 17 | |||
| 18 | This library requires the inclusion of 'sha.h'. | ||
| 19 | |||
| 20 | The functions are as follows: | ||
| 21 | |||
| 22 | void SHA_Init( | ||
| 23 | SHA_CTX *c); | ||
| 24 | This function needs to be called to initiate a SHA_CTX structure for | ||
| 25 | use. | ||
| 26 | |||
| 27 | void SHA_Update( | ||
| 28 | SHA_CTX *c; | ||
| 29 | unsigned char *data; | ||
| 30 | unsigned long len); | ||
| 31 | This updates the message digest context being generated with 'len' | ||
| 32 | bytes from the 'data' pointer. The number of bytes can be any | ||
| 33 | length. | ||
| 34 | |||
| 35 | void SHA_Final( | ||
| 36 | unsigned char *md; | ||
| 37 | SHA_CTX *c; | ||
| 38 | This function is called when a message digest of the data digested | ||
| 39 | with SHA_Update() is wanted. The message digest is put in the 'md' | ||
| 40 | array and is SHA_DIGEST_LENGTH (20) bytes long. | ||
| 41 | |||
| 42 | unsigned char *SHA( | ||
| 43 | unsigned char *d; | ||
| 44 | unsigned long n; | ||
| 45 | unsigned char *md; | ||
| 46 | This function performs a SHA_Init(), followed by a SHA_Update() | ||
| 47 | followed by a SHA_Final() (using a local SHA_CTX). | ||
| 48 | The resulting digest is put into 'md' if it is not NULL. | ||
| 49 | Regardless of the value of 'md', the message | ||
| 50 | digest is returned from the function. If 'md' was NULL, the message | ||
| 51 | digest returned is being stored in a static structure. | ||
| 52 | |||
diff --git a/src/lib/libssl/src/doc/speed.doc b/src/lib/libssl/src/doc/speed.doc deleted file mode 100644 index 11dfa85f08..0000000000 --- a/src/lib/libssl/src/doc/speed.doc +++ /dev/null | |||
| @@ -1,96 +0,0 @@ | |||
| 1 | To get an idea of the performance of this library, use | ||
| 2 | ssleay speed | ||
| 3 | |||
| 4 | perl util/sp-diff.pl file1 file2 | ||
| 5 | |||
| 6 | will print out the relative differences between the 2 files which are | ||
| 7 | expected to be the output from the speed program. | ||
| 8 | |||
| 9 | The performace of the library is very dependant on the Compiler | ||
| 10 | quality and various flags used to build. | ||
| 11 | |||
| 12 | --- | ||
| 13 | |||
| 14 | These are some numbers I did comparing RSAref and SSLeay on a Pentium 100. | ||
| 15 | [ These numbers are all out of date, as of SSL - 0.6.1 the RSA | ||
| 16 | operations are about 2 times faster, so check the version number ] | ||
| 17 | |||
| 18 | RSA performance. | ||
| 19 | |||
| 20 | SSLeay 0.6.0 | ||
| 21 | Pentium 100, 32meg, Windows NT Workstation 3.51 | ||
| 22 | linux - gcc v 2.7.0 -O3 -fomit-frame-pointer -m486 | ||
| 23 | and | ||
| 24 | Windows NT - Windows NT 3.51 - Visual C++ 4.1 - 586 code + 32bit assember | ||
| 25 | Windows 3.1 - Windows NT 3.51 - Visual C++ 1.52c - 286 code + 32bit assember | ||
| 26 | NT Dos Shell- Windows NT 3.51 - Visual C++ 1.52c - 286 code + 16bit assember | ||
| 27 | |||
| 28 | Times are how long it takes to do an RSA private key operation. | ||
| 29 | |||
| 30 | 512bits 1024bits | ||
| 31 | ------------------------------- | ||
| 32 | SSLeay NT dll 0.042s 0.202s see above | ||
| 33 | SSLeay linux 0.046s 0.218s Assember inner loops (normal build) | ||
| 34 | SSLeay linux 0.067s 0.380s Pure C code with BN_LLONG defined | ||
| 35 | SSLeay W3.1 dll 0.108s 0.478s see above | ||
| 36 | SSLeay linux 0.109s 0.713s C without BN_LLONG. | ||
| 37 | RSAref2.0 linux 0.149s 0.936s | ||
| 38 | SSLeay MS-DOS 0.197s 1.049s see above | ||
| 39 | |||
| 40 | 486DX66, 32meg, Windows NT Server 3.51 | ||
| 41 | 512bits 1024bits | ||
| 42 | ------------------------------- | ||
| 43 | SSLeay NT dll 0.084s 0.495s <- SSLeay 0.6.3 | ||
| 44 | SSLeay NT dll 0.154s 0.882s | ||
| 45 | SSLeay W3.1 dll 0.335s 1.538s | ||
| 46 | SSLeay MS-DOS 0.490s 2.790s | ||
| 47 | |||
| 48 | What I find cute is that I'm still faster than RSAref when using standard C, | ||
| 49 | without using the 'long long' data type :-), %35 faster for 512bit and we | ||
| 50 | scale up to 3.2 times faster for the 'default linux' build. I should mention | ||
| 51 | that people should 'try' to use either x86-lnx.s (elf), x86-lnxa.s or | ||
| 52 | x86-sol.s for any x86 based unix they are building on. The only problems | ||
| 53 | with be with syntax but the performance gain is quite large, especially for | ||
| 54 | servers. The code is very simple, you just need to modify the 'header'. | ||
| 55 | |||
| 56 | The message is, if you are stuck using RSAref, the RSA performance will be | ||
| 57 | bad. Considering the code was compiled for a pentium, the 486DX66 number | ||
| 58 | would indicate 'Use RSAref and turn you Pentium 100 into a 486DX66' :-). | ||
| 59 | [ As of verson 0.6.1, it would be correct to say 'turn you pentium 100 | ||
| 60 | into a 486DX33' :-) ] | ||
| 61 | |||
| 62 | I won't tell people if the DLL's are using RSAref or my stuff if no-one | ||
| 63 | asks :-). | ||
| 64 | |||
| 65 | eric | ||
| 66 | |||
| 67 | PS while I know I could speed things up further, I will probably not do | ||
| 68 | so due to the effort involved. I did do some timings on the | ||
| 69 | SSLeay bignum format -> RSAref number format conversion that occurs | ||
| 70 | each time RSAref is used by SSLeay, and the numbers are trivial. | ||
| 71 | 0.00012s a call for 512bit vs 0.149s for the time spent in the function. | ||
| 72 | 0.00018s for 1024bit vs 0.938s. Insignificant. | ||
| 73 | So the 'way to go', to support faster RSA libraries, if people are keen, | ||
| 74 | is to write 'glue' code in a similar way that I do for RSAref and send it | ||
| 75 | to me :-). | ||
| 76 | My base library still has the advantage of being able to operate on | ||
| 77 | any size numbers, and is not that far from the performance from the | ||
| 78 | leaders in the field. (-%30?) | ||
| 79 | [ Well as of 0.6.1 I am now the leader in the filed on x86 (we at | ||
| 80 | least very close :-) ] | ||
| 81 | |||
| 82 | I suppose I should also mention some other numbers RSAref numbers, again | ||
| 83 | on my Pentium. | ||
| 84 | DES CBC EDE-DES MD5 | ||
| 85 | RSAref linux 830k/s 302k/s 4390k/s | ||
| 86 | SSLeay linux 855k/s 319k/s 10025k/s | ||
| 87 | SSLeay NT 1158k/s 410k/s 10470k/s | ||
| 88 | SSLeay w31 378k/s 143k/s 2383k/s (fully 16bit) | ||
| 89 | |||
| 90 | Got to admit that Visual C++ 4.[01] is a damn fine compiler :-) | ||
| 91 | -- | ||
| 92 | Eric Young | BOOL is tri-state according to Bill Gates. | ||
| 93 | AARNet: eay@cryptsoft.com | RTFM Win32 GetMessage(). | ||
| 94 | |||
| 95 | |||
| 96 | |||
diff --git a/src/lib/libssl/src/doc/ssl-ciph.doc b/src/lib/libssl/src/doc/ssl-ciph.doc deleted file mode 100644 index 33a7e41f0e..0000000000 --- a/src/lib/libssl/src/doc/ssl-ciph.doc +++ /dev/null | |||
| @@ -1,84 +0,0 @@ | |||
| 1 | This is a quick high level summery of how things work now. | ||
| 2 | |||
| 3 | Each SSLv2 and SSLv3 cipher is composed of 4 major attributes plus a few extra | ||
| 4 | minor ones. | ||
| 5 | |||
| 6 | They are 'The key exchange algorithm', which is RSA for SSLv2 but can also | ||
| 7 | be Diffle-Hellman for SSLv3. | ||
| 8 | |||
| 9 | An 'Authenticion algorithm', which can be RSA, Diffle-Helman, DSS or | ||
| 10 | none. | ||
| 11 | |||
| 12 | The cipher | ||
| 13 | |||
| 14 | The MAC digest. | ||
| 15 | |||
| 16 | A cipher can also be an export cipher and is either an SSLv2 or a | ||
| 17 | SSLv3 ciphers. | ||
| 18 | |||
| 19 | To specify which ciphers to use, one can either specify all the ciphers, | ||
| 20 | one at a time, or use 'aliases' to specify the preference and order for | ||
| 21 | the ciphers. | ||
| 22 | |||
| 23 | There are a large number of aliases, but the most importaint are | ||
| 24 | kRSA, kDHr, kDHd and kEDH for key exchange types. | ||
| 25 | |||
| 26 | aRSA, aDSS, aNULL and aDH for authentication | ||
| 27 | DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers | ||
| 28 | MD5, SHA0 and SHA1 digests | ||
| 29 | |||
| 30 | Now where this becomes interesting is that these can be put together to | ||
| 31 | specify the order and ciphers you wish to use. | ||
| 32 | |||
| 33 | To speed this up there are also aliases for certian groups of ciphers. | ||
| 34 | The main ones are | ||
| 35 | SSLv2 - all SSLv2 ciphers | ||
| 36 | SSLv3 - all SSLv3 ciphers | ||
| 37 | EXP - all export ciphers | ||
| 38 | LOW - all low strngth ciphers (no export ciphers, normally single DES) | ||
| 39 | MEDIUM - 128 bit encryption | ||
| 40 | HIGH - Triple DES | ||
| 41 | |||
| 42 | These aliases can be joined in a : separated list which specifies to | ||
| 43 | add ciphers, move them to the current location and delete them. | ||
| 44 | |||
| 45 | A simpler way to look at all of this is to use the 'ssleay ciphers -v' command. | ||
| 46 | The default library cipher spec is | ||
| 47 | !ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP | ||
| 48 | which means, first, remove from consideration any ciphers that do not | ||
| 49 | authenticate. Next up, use ciphers using RC4 and RSA. Next include the HIGH, | ||
| 50 | MEDIUM and the LOW security ciphers. Finish up by adding all the export | ||
| 51 | ciphers on the end, then 'pull' all the SSLv2 and export ciphers to | ||
| 52 | the end of the list. | ||
| 53 | |||
| 54 | The results are | ||
| 55 | $ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP' | ||
| 56 | |||
| 57 | RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1 | ||
| 58 | RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 | ||
| 59 | EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 | ||
| 60 | EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 | ||
| 61 | DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1 | ||
| 62 | IDEA-CBC-MD5 SSLv3 Kx=RSA Au=RSA Enc=IDEA(128) Mac=SHA1 | ||
| 63 | EDH-RSA-DES-CBC-SHA SSLv3 Kx=DH Au=RSA Enc=DES(56) Mac=SHA1 | ||
| 64 | EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH Au=DSS Enc=DES(56) Mac=SHA1 | ||
| 65 | DES-CBC-SHA SSLv3 Kx=RSA Au=RSA Enc=DES(56) Mac=SHA1 | ||
| 66 | DES-CBC3-MD5 SSLv2 Kx=RSA Au=RSA Enc=3DES(168) Mac=MD5 | ||
| 67 | DES-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=DES(56) Mac=MD5 | ||
| 68 | IDEA-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=IDEA(128) Mac=MD5 | ||
| 69 | RC2-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC2(128) Mac=MD5 | ||
| 70 | RC4-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 | ||
| 71 | EXP-EDH-RSA-DES-CBC SSLv3 Kx=DH(512) Au=RSA Enc=DES(40) Mac=SHA1 export | ||
| 72 | EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512) Au=DSS Enc=DES(40) Mac=SHA1 export | ||
| 73 | EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 export | ||
| 74 | EXP-RC2-CBC-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export | ||
| 75 | EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export | ||
| 76 | EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export | ||
| 77 | EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export | ||
| 78 | |||
| 79 | I would recoment people use the 'ssleay ciphers -v "text"' | ||
| 80 | command to check what they are going to use. | ||
| 81 | |||
| 82 | Anyway, I'm falling asleep here so I'll do some more tomorrow. | ||
| 83 | |||
| 84 | eric | ||
diff --git a/src/lib/libssl/src/doc/ssl.doc b/src/lib/libssl/src/doc/ssl.doc deleted file mode 100644 index 1f89cd5db2..0000000000 --- a/src/lib/libssl/src/doc/ssl.doc +++ /dev/null | |||
| @@ -1,172 +0,0 @@ | |||
| 1 | SSL_CTX_sessions(SSL_CTX *ctx) - the session-id hash table. | ||
| 2 | |||
| 3 | /* Session-id cache stats */ | ||
| 4 | SSL_CTX_sess_number | ||
| 5 | SSL_CTX_sess_connect | ||
| 6 | SSL_CTX_sess_connect_good | ||
| 7 | SSL_CTX_sess_accept | ||
| 8 | SSL_CTX_sess_accept_good | ||
| 9 | SSL_CTX_sess_hits | ||
| 10 | SSL_CTX_sess_cb_hits | ||
| 11 | SSL_CTX_sess_misses | ||
| 12 | SSL_CTX_sess_timeouts | ||
| 13 | |||
| 14 | /* Session-id application notification callbacks */ | ||
| 15 | SSL_CTX_sess_set_new_cb | ||
| 16 | SSL_CTX_sess_get_new_cb | ||
| 17 | SSL_CTX_sess_set_get_cb | ||
| 18 | SSL_CTX_sess_get_get_cb | ||
| 19 | |||
| 20 | /* Session-id cache operation mode */ | ||
| 21 | SSL_CTX_set_session_cache_mode | ||
| 22 | SSL_CTX_get_session_cache_mode | ||
| 23 | |||
| 24 | /* Set default timeout values to use. */ | ||
| 25 | SSL_CTX_set_timeout | ||
| 26 | SSL_CTX_get_timeout | ||
| 27 | |||
| 28 | /* Global SSL initalisation informational callback */ | ||
| 29 | SSL_CTX_set_info_callback | ||
| 30 | SSL_CTX_get_info_callback | ||
| 31 | SSL_set_info_callback | ||
| 32 | SSL_get_info_callback | ||
| 33 | |||
| 34 | /* If the SSL_accept/SSL_connect returned with -1, these indicate when | ||
| 35 | * we should re-call *. | ||
| 36 | SSL_want | ||
| 37 | SSL_want_nothing | ||
| 38 | SSL_want_read | ||
| 39 | SSL_want_write | ||
| 40 | SSL_want_x509_lookup | ||
| 41 | |||
| 42 | /* Where we are in SSL initalisation, used in non-blocking, perhaps | ||
| 43 | * have a look at ssl/bio_ssl.c */ | ||
| 44 | SSL_state | ||
| 45 | SSL_is_init_finished | ||
| 46 | SSL_in_init | ||
| 47 | SSL_in_connect_init | ||
| 48 | SSL_in_accept_init | ||
| 49 | |||
| 50 | /* Used to set the 'inital' state so SSL_in_connect_init and SSL_in_accept_init | ||
| 51 | * can be used to work out which function to call. */ | ||
| 52 | SSL_set_connect_state | ||
| 53 | SSL_set_accept_state | ||
| 54 | |||
| 55 | /* Where to look for certificates for authentication */ | ||
| 56 | SSL_set_default_verify_paths /* calles SSL_load_verify_locations */ | ||
| 57 | SSL_load_verify_locations | ||
| 58 | |||
| 59 | /* get info from an established connection */ | ||
| 60 | SSL_get_session | ||
| 61 | SSL_get_certificate | ||
| 62 | SSL_get_SSL_CTX | ||
| 63 | |||
| 64 | SSL_CTX_new | ||
| 65 | SSL_CTX_free | ||
| 66 | SSL_new | ||
| 67 | SSL_clear | ||
| 68 | SSL_free | ||
| 69 | |||
| 70 | SSL_CTX_set_cipher_list | ||
| 71 | SSL_get_cipher | ||
| 72 | SSL_set_cipher_list | ||
| 73 | SSL_get_cipher_list | ||
| 74 | SSL_get_shared_ciphers | ||
| 75 | |||
| 76 | SSL_accept | ||
| 77 | SSL_connect | ||
| 78 | SSL_read | ||
| 79 | SSL_write | ||
| 80 | |||
| 81 | SSL_debug | ||
| 82 | |||
| 83 | SSL_get_read_ahead | ||
| 84 | SSL_set_read_ahead | ||
| 85 | SSL_set_verify | ||
| 86 | |||
| 87 | SSL_pending | ||
| 88 | |||
| 89 | SSL_set_fd | ||
| 90 | SSL_set_rfd | ||
| 91 | SSL_set_wfd | ||
| 92 | SSL_set_bio | ||
| 93 | SSL_get_fd | ||
| 94 | SSL_get_rbio | ||
| 95 | SSL_get_wbio | ||
| 96 | |||
| 97 | SSL_use_RSAPrivateKey | ||
| 98 | SSL_use_RSAPrivateKey_ASN1 | ||
| 99 | SSL_use_RSAPrivateKey_file | ||
| 100 | SSL_use_PrivateKey | ||
| 101 | SSL_use_PrivateKey_ASN1 | ||
| 102 | SSL_use_PrivateKey_file | ||
| 103 | SSL_use_certificate | ||
| 104 | SSL_use_certificate_ASN1 | ||
| 105 | SSL_use_certificate_file | ||
| 106 | |||
| 107 | ERR_load_SSL_strings | ||
| 108 | SSL_load_error_strings | ||
| 109 | |||
| 110 | /* human readable version of the 'state' of the SSL connection. */ | ||
| 111 | SSL_state_string | ||
| 112 | SSL_state_string_long | ||
| 113 | /* These 2 report what kind of IO operation the library was trying to | ||
| 114 | * perform last. Probably not very usefull. */ | ||
| 115 | SSL_rstate_string | ||
| 116 | SSL_rstate_string_long | ||
| 117 | |||
| 118 | SSL_get_peer_certificate | ||
| 119 | |||
| 120 | SSL_SESSION_new | ||
| 121 | SSL_SESSION_print_fp | ||
| 122 | SSL_SESSION_print | ||
| 123 | SSL_SESSION_free | ||
| 124 | i2d_SSL_SESSION | ||
| 125 | d2i_SSL_SESSION | ||
| 126 | |||
| 127 | SSL_get_time | ||
| 128 | SSL_set_time | ||
| 129 | SSL_get_timeout | ||
| 130 | SSL_set_timeout | ||
| 131 | SSL_copy_session_id | ||
| 132 | SSL_set_session | ||
| 133 | SSL_CTX_add_session | ||
| 134 | SSL_CTX_remove_session | ||
| 135 | SSL_CTX_flush_sessions | ||
| 136 | |||
| 137 | BIO_f_ssl | ||
| 138 | |||
| 139 | /* used to hold information as to why a certificate verification failed */ | ||
| 140 | SSL_set_verify_result | ||
| 141 | SSL_get_verify_result | ||
| 142 | |||
| 143 | /* can be used by the application to associate data with an SSL structure. | ||
| 144 | * It needs to be 'free()ed' by the application */ | ||
| 145 | SSL_set_app_data | ||
| 146 | SSL_get_app_data | ||
| 147 | |||
| 148 | /* The following all set values that are kept in the SSL_CTX but | ||
| 149 | * are used as the default values when an SSL session is created. | ||
| 150 | * They are over writen by the relevent SSL_xxxx functions */ | ||
| 151 | |||
| 152 | /* SSL_set_verify */ | ||
| 153 | void SSL_CTX_set_default_verify | ||
| 154 | |||
| 155 | /* This callback, if set, totaly overrides the normal SSLeay verification | ||
| 156 | * functions and should return 1 on sucesss and 0 on failure */ | ||
| 157 | void SSL_CTX_set_cert_verify_callback | ||
| 158 | |||
| 159 | /* The following are the same as the equivilent SSL_xxx functions. | ||
| 160 | * Only one copy of this information is kept and if a particular | ||
| 161 | * SSL structure has a local override, it is totally separate structure. | ||
| 162 | */ | ||
| 163 | int SSL_CTX_use_RSAPrivateKey | ||
| 164 | int SSL_CTX_use_RSAPrivateKey_ASN1 | ||
| 165 | int SSL_CTX_use_RSAPrivateKey_file | ||
| 166 | int SSL_CTX_use_PrivateKey | ||
| 167 | int SSL_CTX_use_PrivateKey_ASN1 | ||
| 168 | int SSL_CTX_use_PrivateKey_file | ||
| 169 | int SSL_CTX_use_certificate | ||
| 170 | int SSL_CTX_use_certificate_ASN1 | ||
| 171 | int SSL_CTX_use_certificate_file | ||
| 172 | |||
diff --git a/src/lib/libssl/src/doc/ssl.pod b/src/lib/libssl/src/doc/ssl.pod new file mode 100644 index 0000000000..46ee443f57 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl.pod | |||
| @@ -0,0 +1,633 @@ | |||
| 1 | |||
| 2 | =pod | ||
| 3 | |||
| 4 | =head1 NAME | ||
| 5 | |||
| 6 | SSL - OpenSSL SSL/TLS library | ||
| 7 | |||
| 8 | =head1 SYNOPSIS | ||
| 9 | |||
| 10 | =head1 DESCRIPTION | ||
| 11 | |||
| 12 | The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and | ||
| 13 | Transport Layer Security (TLS v1) protocols. It provides a rich API which is | ||
| 14 | documented here. | ||
| 15 | |||
| 16 | =head1 HEADER FILES | ||
| 17 | |||
| 18 | Currently the OpenSSL B<ssl> library provides the following C header files | ||
| 19 | containing the prototypes for the data structures and and functions: | ||
| 20 | |||
| 21 | =over 4 | ||
| 22 | |||
| 23 | =item B<ssl.h> | ||
| 24 | |||
| 25 | That's the common header file for the SSL/TLS API. Include it into your | ||
| 26 | program to make the API of the B<ssl> library available. It internally | ||
| 27 | includes both more private SSL headers and headers from the B<crypto> library. | ||
| 28 | Whenever you need hard-core details on the internals of the SSL API, look | ||
| 29 | inside this header file. | ||
| 30 | |||
| 31 | =item B<ssl2.h> | ||
| 32 | |||
| 33 | That's the sub header file dealing with the SSLv2 protocol only. | ||
| 34 | I<Usually you don't have to include it explicitly because | ||
| 35 | it's already included by ssl.h>. | ||
| 36 | |||
| 37 | =item B<ssl3.h> | ||
| 38 | |||
| 39 | That's the sub header file dealing with the SSLv3 protocol only. | ||
| 40 | I<Usually you don't have to include it explicitly because | ||
| 41 | it's already included by ssl.h>. | ||
| 42 | |||
| 43 | =item B<ssl23.h> | ||
| 44 | |||
| 45 | That's the sub header file dealing with the combined use of the SSLv2 and | ||
| 46 | SSLv3 protocols. | ||
| 47 | I<Usually you don't have to include it explicitly because | ||
| 48 | it's already included by ssl.h>. | ||
| 49 | |||
| 50 | =item B<tls1.h> | ||
| 51 | |||
| 52 | That's the sub header file dealing with the TLSv1 protocol only. | ||
| 53 | I<Usually you don't have to include it explicitly because | ||
| 54 | it's already included by ssl.h>. | ||
| 55 | |||
| 56 | =back | ||
| 57 | |||
| 58 | =head1 DATA STRUCTURES | ||
| 59 | |||
| 60 | Currently the OpenSSL B<ssl> library functions deals with the following data | ||
| 61 | structures: | ||
| 62 | |||
| 63 | =over 4 | ||
| 64 | |||
| 65 | =item B<SSL_METHOD> (SSL Method) | ||
| 66 | |||
| 67 | That's a dispatch structure describing the internal B<ssl> library | ||
| 68 | methods/functions which implement the various protocol versions (SSLv1, SSLv2 | ||
| 69 | and TLSv1). It's needed to create an B<SSL_CTX>. | ||
| 70 | |||
| 71 | =item B<SSL_CIPHER> (SSL Cipher) | ||
| 72 | |||
| 73 | This structure holds the algorithm information for a particular cipher which | ||
| 74 | are a core part of the SSL/TLS protocol. The available ciphers are configured | ||
| 75 | on a B<SSL_CTX> basis and the actually used ones are then part of the | ||
| 76 | B<SSL_SESSION>. | ||
| 77 | |||
| 78 | =item B<SSL_CTX> (SSL Context) | ||
| 79 | |||
| 80 | That's the global context structure which is created by a server or client | ||
| 81 | once per program life-time and which holds mainly default values for the | ||
| 82 | B<SSL> structures which are later created for the connections. | ||
| 83 | |||
| 84 | =item B<SSL_SESSION> (SSL Session) | ||
| 85 | |||
| 86 | This is a structure containing the current SSL session details for a | ||
| 87 | connection: B<SSL_CIPHER>s, client and server certificates, keys, etc. | ||
| 88 | |||
| 89 | =item B<SSL> (SSL Connection) | ||
| 90 | |||
| 91 | That's the main SSL/TLS structure which is created by a server or client per | ||
| 92 | established connection. This actually is the core structure in the SSL API. | ||
| 93 | Under run-time the application usually deals with this structure which has | ||
| 94 | links to mostly all other structures. | ||
| 95 | |||
| 96 | =back | ||
| 97 | |||
| 98 | =head1 API FUNCTIONS | ||
| 99 | |||
| 100 | Currently the OpenSSL B<ssl> library exports 214 API functions. | ||
| 101 | They are documented in the following: | ||
| 102 | |||
| 103 | =head2 DEALING WITH PROTOCOL METHODS | ||
| 104 | |||
| 105 | Here we document the various API functions which deal with the SSL/TLS | ||
| 106 | protocol methods defined in B<SSL_METHOD> structures. | ||
| 107 | |||
| 108 | =over 4 | ||
| 109 | |||
| 110 | =item SSL_METHOD *B<SSLv2_client_method>(void); | ||
| 111 | |||
| 112 | Constructor for the SSLv2 SSL_METHOD structure for a dedicated client. | ||
| 113 | |||
| 114 | =item SSL_METHOD *B<SSLv2_server_method>(void); | ||
| 115 | |||
| 116 | Constructor for the SSLv2 SSL_METHOD structure for a dedicated server. | ||
| 117 | |||
| 118 | =item SSL_METHOD *B<SSLv2_method>(void); | ||
| 119 | |||
| 120 | Constructor for the SSLv2 SSL_METHOD structure for combined client and server. | ||
| 121 | |||
| 122 | =item SSL_METHOD *B<SSLv3_client_method>(void); | ||
| 123 | |||
| 124 | Constructor for the SSLv3 SSL_METHOD structure for a dedicated client. | ||
| 125 | |||
| 126 | =item SSL_METHOD *B<SSLv3_server_method>(void); | ||
| 127 | |||
| 128 | Constructor for the SSLv3 SSL_METHOD structure for a dedicated server. | ||
| 129 | |||
| 130 | =item SSL_METHOD *B<SSLv3_method>(void); | ||
| 131 | |||
| 132 | Constructor for the SSLv3 SSL_METHOD structure for combined client and server. | ||
| 133 | |||
| 134 | =item SSL_METHOD *B<TLSv1_client_method>(void); | ||
| 135 | |||
| 136 | Constructor for the TLSv1 SSL_METHOD structure for a dedicated client. | ||
| 137 | |||
| 138 | =item SSL_METHOD *B<TLSv1_server_method>(void); | ||
| 139 | |||
| 140 | Constructor for the TLSv1 SSL_METHOD structure for a dedicated server. | ||
| 141 | |||
| 142 | =item SSL_METHOD *B<TLSv1_method>(void); | ||
| 143 | |||
| 144 | Constructor for the TLSv1 SSL_METHOD structure for combined client and server. | ||
| 145 | |||
| 146 | =back | ||
| 147 | |||
| 148 | =head2 DEALING WITH CIPHERS | ||
| 149 | |||
| 150 | Here we document the various API functions which deal with the SSL/TLS | ||
| 151 | ciphers defined in B<SSL_CIPHER> structures. | ||
| 152 | |||
| 153 | =over 4 | ||
| 154 | |||
| 155 | =item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len); | ||
| 156 | |||
| 157 | Write a string to I<buf> (with a maximum size of I<len>) containing a human | ||
| 158 | readable description of I<cipher>. Returns I<buf>. | ||
| 159 | |||
| 160 | =item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits); | ||
| 161 | |||
| 162 | Determine the number of bits in I<cipher>. Because of export crippled ciphers | ||
| 163 | there are two bits: The bits the algorithm supports in general (stored to | ||
| 164 | I<alg_bits>) and the bits which are actually used (the return value). | ||
| 165 | |||
| 166 | =item char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher); | ||
| 167 | |||
| 168 | Return the internal name of I<cipher> as a string. These are the various | ||
| 169 | strings defined by the I<SSL2_TXT_xxx>, I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx> | ||
| 170 | definitions in the header files. | ||
| 171 | |||
| 172 | =item char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher); | ||
| 173 | |||
| 174 | Returns a string like "C<TLSv1/SSLv3>" or "C<SSLv2>" which indicates the | ||
| 175 | SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined | ||
| 176 | in the specification the first time). | ||
| 177 | |||
| 178 | =back | ||
| 179 | |||
| 180 | =head2 DEALING WITH PROTOCOL CONTEXTS | ||
| 181 | |||
| 182 | Here we document the various API functions which deal with the SSL/TLS | ||
| 183 | protocol context defined in the B<SSL_CTX> structure. | ||
| 184 | |||
| 185 | =over 4 | ||
| 186 | |||
| 187 | =item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x); | ||
| 188 | |||
| 189 | =item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509); | ||
| 190 | |||
| 191 | =item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c); | ||
| 192 | |||
| 193 | =item int B<SSL_CTX_check_private_key>(SSL_CTX *ctx); | ||
| 194 | |||
| 195 | =item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg); | ||
| 196 | |||
| 197 | =item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t); | ||
| 198 | |||
| 199 | =item void B<SSL_CTX_free>(SSL_CTX *a); | ||
| 200 | |||
| 201 | =item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx); | ||
| 202 | |||
| 203 | =item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx); | ||
| 204 | |||
| 205 | =item STACK *B<SSL_CTX_get_client_CA_list>(SSL_CTX *ctx); | ||
| 206 | |||
| 207 | =item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); | ||
| 208 | |||
| 209 | =item char *B<SSL_CTX_get_ex_data>(SSL_CTX *s, int idx); | ||
| 210 | |||
| 211 | =item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) | ||
| 212 | |||
| 213 | =item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret); | ||
| 214 | |||
| 215 | =item int B<SSL_CTX_get_quiet_shutdown>(SSL_CTX *ctx); | ||
| 216 | |||
| 217 | =item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx); | ||
| 218 | |||
| 219 | =item long B<SSL_CTX_get_timeout>(SSL_CTX *ctx); | ||
| 220 | |||
| 221 | =item int (*B<SSL_CTX_get_verify_callback>(SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx); | ||
| 222 | |||
| 223 | =item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx); | ||
| 224 | |||
| 225 | =item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, char *CAfile, char *CApath); | ||
| 226 | |||
| 227 | =item long B<SSL_CTX_need_tmp_RSA>(SSL_CTX *ctx); | ||
| 228 | |||
| 229 | =item SSL_CTX *B<SSL_CTX_new>(SSL_METHOD *meth); | ||
| 230 | |||
| 231 | =item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c); | ||
| 232 | |||
| 233 | =item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx); | ||
| 234 | |||
| 235 | =item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx); | ||
| 236 | |||
| 237 | =item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx); | ||
| 238 | |||
| 239 | =item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx); | ||
| 240 | |||
| 241 | =item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx); | ||
| 242 | |||
| 243 | =item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx); | ||
| 244 | |||
| 245 | =item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx); | ||
| 246 | |||
| 247 | =item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx); | ||
| 248 | |||
| 249 | =item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx); | ||
| 250 | |||
| 251 | =item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy); | ||
| 252 | |||
| 253 | =item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess); | ||
| 254 | |||
| 255 | =item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess); | ||
| 256 | |||
| 257 | =item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx); | ||
| 258 | |||
| 259 | =item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx); | ||
| 260 | |||
| 261 | =item int B<SSL_CTX_sess_number>(SSL_CTX *ctx); | ||
| 262 | |||
| 263 | =item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx,t); | ||
| 264 | |||
| 265 | =item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)); | ||
| 266 | |||
| 267 | =item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess)); | ||
| 268 | |||
| 269 | =item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)); | ||
| 270 | |||
| 271 | =item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx); | ||
| 272 | |||
| 273 | =item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx); | ||
| 274 | |||
| 275 | =item void B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg); | ||
| 276 | |||
| 277 | =item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs); | ||
| 278 | |||
| 279 | =item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(SSL_CTX *), char *arg) | ||
| 280 | |||
| 281 | =item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str); | ||
| 282 | |||
| 283 | =item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list); | ||
| 284 | |||
| 285 | =item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); | ||
| 286 | |||
| 287 | =item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void)) | ||
| 288 | |||
| 289 | =item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m); | ||
| 290 | |||
| 291 | =item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx); | ||
| 292 | |||
| 293 | =item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg); | ||
| 294 | |||
| 295 | =item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret)); | ||
| 296 | |||
| 297 | =item void B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op); | ||
| 298 | |||
| 299 | =item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode); | ||
| 300 | |||
| 301 | =item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode); | ||
| 302 | |||
| 303 | =item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, SSL_METHOD *meth); | ||
| 304 | |||
| 305 | =item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t); | ||
| 306 | |||
| 307 | =item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh); | ||
| 308 | |||
| 309 | =item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void)); | ||
| 310 | |||
| 311 | =item long B<SSL_CTX_set_tmp_rsa>(SSL_CTX *ctx, RSA *rsa); | ||
| 312 | |||
| 313 | =item SSL_CTX_set_tmp_rsa_callback | ||
| 314 | |||
| 315 | C<long B<SSL_CTX_set_tmp_rsa_callback>(SSL_CTX *B<ctx>, RSA *(*B<cb>)(SSL *B<ssl>, int B<export>, int B<keylength>));> | ||
| 316 | |||
| 317 | Sets the callback which will be called when a temporary private key is | ||
| 318 | required. The B<C<export>> flag will be set if the reason for needing | ||
| 319 | a temp key is that an export ciphersuite is in use, in which case, | ||
| 320 | B<C<keylength>> will contain the required keylength in bits. Generate a key of | ||
| 321 | appropriate size (using ???) and return it. | ||
| 322 | |||
| 323 | =item SSL_set_tmp_rsa_callback | ||
| 324 | |||
| 325 | long B<SSL_set_tmp_rsa_callback>(SSL *ssl, RSA *(*cb)(SSL *ssl, int export, int keylength)); | ||
| 326 | |||
| 327 | The same as L<"SSL_CTX_set_tmp_rsa_callback">, except it operates on an SSL | ||
| 328 | session instead of a context. | ||
| 329 | |||
| 330 | =item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void)) | ||
| 331 | |||
| 332 | =item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey); | ||
| 333 | |||
| 334 | =item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len); | ||
| 335 | |||
| 336 | =item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, char *file, int type); | ||
| 337 | |||
| 338 | =item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa); | ||
| 339 | |||
| 340 | =item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len); | ||
| 341 | |||
| 342 | =item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, char *file, int type); | ||
| 343 | |||
| 344 | =item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x); | ||
| 345 | |||
| 346 | =item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d); | ||
| 347 | |||
| 348 | =item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, char *file, int type); | ||
| 349 | |||
| 350 | =back | ||
| 351 | |||
| 352 | =head2 DEALING WITH SESSIONS | ||
| 353 | |||
| 354 | Here we document the various API functions which deal with the SSL/TLS | ||
| 355 | sessions defined in the B<SSL_SESSION> structures. | ||
| 356 | |||
| 357 | =over 4 | ||
| 358 | |||
| 359 | =item int B<SSL_SESSION_cmp>(SSL_SESSION *a, SSL_SESSION *b); | ||
| 360 | |||
| 361 | =item void B<SSL_SESSION_free>(SSL_SESSION *ss); | ||
| 362 | |||
| 363 | =item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s); | ||
| 364 | |||
| 365 | =item char *B<SSL_SESSION_get_ex_data>(SSL_SESSION *s, int idx); | ||
| 366 | |||
| 367 | =item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) | ||
| 368 | |||
| 369 | =item long B<SSL_SESSION_get_time>(SSL_SESSION *s); | ||
| 370 | |||
| 371 | =item long B<SSL_SESSION_get_timeout>(SSL_SESSION *s); | ||
| 372 | |||
| 373 | =item unsigned long B<SSL_SESSION_hash>(SSL_SESSION *a); | ||
| 374 | |||
| 375 | =item SSL_SESSION *B<SSL_SESSION_new>(void); | ||
| 376 | |||
| 377 | =item int B<SSL_SESSION_print>(BIO *bp, SSL_SESSION *x); | ||
| 378 | |||
| 379 | =item int B<SSL_SESSION_print_fp>(FILE *fp, SSL_SESSION *x); | ||
| 380 | |||
| 381 | =item void B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a); | ||
| 382 | |||
| 383 | =item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg); | ||
| 384 | |||
| 385 | =item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t); | ||
| 386 | |||
| 387 | =item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t); | ||
| 388 | |||
| 389 | =back | ||
| 390 | |||
| 391 | =head2 DEALING WITH CONNECTIONS | ||
| 392 | |||
| 393 | Here we document the various API functions which deal with the SSL/TLS | ||
| 394 | connection defined in the B<SSL> structure. | ||
| 395 | |||
| 396 | =over 4 | ||
| 397 | |||
| 398 | =item int B<SSL_accept>(SSL *ssl); | ||
| 399 | |||
| 400 | =item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir); | ||
| 401 | |||
| 402 | =item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file); | ||
| 403 | |||
| 404 | =item int B<SSL_add_client_CA>(SSL *ssl, X509 *x); | ||
| 405 | |||
| 406 | =item char *B<SSL_alert_desc_string>(int value); | ||
| 407 | |||
| 408 | =item char *B<SSL_alert_desc_string_long>(int value); | ||
| 409 | |||
| 410 | =item char *B<SSL_alert_type_string>(int value); | ||
| 411 | |||
| 412 | =item char *B<SSL_alert_type_string_long>(int value); | ||
| 413 | |||
| 414 | =item int B<SSL_check_private_key>(SSL *ssl); | ||
| 415 | |||
| 416 | =item void B<SSL_clear>(SSL *ssl); | ||
| 417 | |||
| 418 | =item long B<SSL_clear_num_renegotiations>(SSL *ssl); | ||
| 419 | |||
| 420 | =item int B<SSL_connect>(SSL *ssl); | ||
| 421 | |||
| 422 | =item void B<SSL_copy_session_id>(SSL *t, SSL *f); | ||
| 423 | |||
| 424 | =item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg); | ||
| 425 | |||
| 426 | =item int B<SSL_do_handshake>(SSL *ssl); | ||
| 427 | |||
| 428 | =item SSL *B<SSL_dup>(SSL *ssl); | ||
| 429 | |||
| 430 | =item STACK *B<SSL_dup_CA_list>(STACK *sk); | ||
| 431 | |||
| 432 | =item void B<SSL_free>(SSL *ssl); | ||
| 433 | |||
| 434 | =item SSL_CTX *B<SSL_get_SSL_CTX>(SSL *ssl); | ||
| 435 | |||
| 436 | =item char *B<SSL_get_app_data>(SSL *ssl); | ||
| 437 | |||
| 438 | =item X509 *B<SSL_get_certificate>(SSL *ssl); | ||
| 439 | |||
| 440 | =item SSL_CIPHER *B<SSL_get_cipher>(SSL *ssl); | ||
| 441 | |||
| 442 | =item int B<SSL_get_cipher_bits>(SSL *ssl, int *alg_bits); | ||
| 443 | |||
| 444 | =item char *B<SSL_get_cipher_list>(SSL *ssl, int n); | ||
| 445 | |||
| 446 | =item char *B<SSL_get_cipher_name>(SSL *ssl); | ||
| 447 | |||
| 448 | =item char *B<SSL_get_cipher_version>(SSL *ssl); | ||
| 449 | |||
| 450 | =item STACK *B<SSL_get_ciphers>(SSL *ssl); | ||
| 451 | |||
| 452 | =item STACK *B<SSL_get_client_CA_list>(SSL *ssl); | ||
| 453 | |||
| 454 | =item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl); | ||
| 455 | |||
| 456 | =item long B<SSL_get_default_timeout>(SSL *ssl); | ||
| 457 | |||
| 458 | =item int B<SSL_get_error>(SSL *ssl, int i); | ||
| 459 | |||
| 460 | =item char *B<SSL_get_ex_data>(SSL *ssl, int idx); | ||
| 461 | |||
| 462 | =item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void); | ||
| 463 | |||
| 464 | =item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) | ||
| 465 | |||
| 466 | =item int B<SSL_get_fd>(SSL *ssl); | ||
| 467 | |||
| 468 | =item void (*B<SSL_get_info_callback>(SSL *ssl);)(void) | ||
| 469 | |||
| 470 | =item STACK *B<SSL_get_peer_cert_chain>(SSL *ssl); | ||
| 471 | |||
| 472 | =item X509 *B<SSL_get_peer_certificate>(SSL *ssl); | ||
| 473 | |||
| 474 | =item EVP_PKEY *B<SSL_get_privatekey>(SSL *ssl); | ||
| 475 | |||
| 476 | =item int B<SSL_get_quiet_shutdown>(SSL *ssl); | ||
| 477 | |||
| 478 | =item BIO *B<SSL_get_rbio>(SSL *ssl); | ||
| 479 | |||
| 480 | =item int B<SSL_get_read_ahead>(SSL *ssl); | ||
| 481 | |||
| 482 | =item SSL_SESSION *B<SSL_get_session>(SSL *ssl); | ||
| 483 | |||
| 484 | =item char *B<SSL_get_shared_ciphers>(SSL *ssl, char *buf, int len); | ||
| 485 | |||
| 486 | =item int B<SSL_get_shutdown>(SSL *ssl); | ||
| 487 | |||
| 488 | =item SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl); | ||
| 489 | |||
| 490 | =item int B<SSL_get_state>(SSL *ssl); | ||
| 491 | |||
| 492 | =item long B<SSL_get_time>(SSL *ssl); | ||
| 493 | |||
| 494 | =item long B<SSL_get_timeout>(SSL *ssl); | ||
| 495 | |||
| 496 | =item int (*B<SSL_get_verify_callback>(SSL *ssl);)(void) | ||
| 497 | |||
| 498 | =item int B<SSL_get_verify_mode>(SSL *ssl); | ||
| 499 | |||
| 500 | =item long B<SSL_get_verify_result>(SSL *ssl); | ||
| 501 | |||
| 502 | =item char *B<SSL_get_version>(SSL *ssl); | ||
| 503 | |||
| 504 | =item BIO *B<SSL_get_wbio>(SSL *ssl); | ||
| 505 | |||
| 506 | =item int B<SSL_in_accept_init>(SSL *ssl); | ||
| 507 | |||
| 508 | =item int B<SSL_in_before>(SSL *ssl); | ||
| 509 | |||
| 510 | =item int B<SSL_in_connect_init>(SSL *ssl); | ||
| 511 | |||
| 512 | =item int B<SSL_in_init>(SSL *ssl); | ||
| 513 | |||
| 514 | =item int B<SSL_is_init_finished>(SSL *ssl); | ||
| 515 | |||
| 516 | =item STACK *B<SSL_load_client_CA_file>(char *file); | ||
| 517 | |||
| 518 | =item void B<SSL_load_error_strings>(void); | ||
| 519 | |||
| 520 | =item SSL *B<SSL_new>(SSL_CTX *ctx); | ||
| 521 | |||
| 522 | =item long B<SSL_num_renegotiations>(SSL *ssl); | ||
| 523 | |||
| 524 | =item int B<SSL_peek>(SSL *ssl, char *buf, int num); | ||
| 525 | |||
| 526 | =item int B<SSL_pending>(SSL *ssl); | ||
| 527 | |||
| 528 | =item int B<SSL_read>(SSL *ssl, char *buf, int num); | ||
| 529 | |||
| 530 | =item int B<SSL_renegotiate>(SSL *ssl); | ||
| 531 | |||
| 532 | =item char *B<SSL_rstate_string>(SSL *ssl); | ||
| 533 | |||
| 534 | =item char *B<SSL_rstate_string_long>(SSL *ssl); | ||
| 535 | |||
| 536 | =item long B<SSL_session_reused>(SSL *ssl); | ||
| 537 | |||
| 538 | =item void B<SSL_set_accept_state>(SSL *ssl); | ||
| 539 | |||
| 540 | =item void B<SSL_set_app_data>(SSL *ssl, char *arg); | ||
| 541 | |||
| 542 | =item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio); | ||
| 543 | |||
| 544 | =item int B<SSL_set_cipher_list>(SSL *ssl, char *str); | ||
| 545 | |||
| 546 | =item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list); | ||
| 547 | |||
| 548 | =item void B<SSL_set_connect_state>(SSL *ssl); | ||
| 549 | |||
| 550 | =item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg); | ||
| 551 | |||
| 552 | =item int B<SSL_set_fd>(SSL *ssl, int fd); | ||
| 553 | |||
| 554 | =item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void)) | ||
| 555 | |||
| 556 | =item void B<SSL_set_options>(SSL *ssl, unsigned long op); | ||
| 557 | |||
| 558 | =item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode); | ||
| 559 | |||
| 560 | =item void B<SSL_set_read_ahead>(SSL *ssl, int yes); | ||
| 561 | |||
| 562 | =item int B<SSL_set_rfd>(SSL *ssl, int fd); | ||
| 563 | |||
| 564 | =item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session); | ||
| 565 | |||
| 566 | =item void B<SSL_set_shutdown>(SSL *ssl, int mode); | ||
| 567 | |||
| 568 | =item int B<SSL_set_ssl_method>(SSL *ssl, SSL_METHOD *meth); | ||
| 569 | |||
| 570 | =item void B<SSL_set_time>(SSL *ssl, long t); | ||
| 571 | |||
| 572 | =item void B<SSL_set_timeout>(SSL *ssl, long t); | ||
| 573 | |||
| 574 | =item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void)) | ||
| 575 | |||
| 576 | =item void B<SSL_set_verify_result>(SSL *ssl, long arg); | ||
| 577 | |||
| 578 | =item int B<SSL_set_wfd>(SSL *ssl, int fd); | ||
| 579 | |||
| 580 | =item int B<SSL_shutdown>(SSL *ssl); | ||
| 581 | |||
| 582 | =item int B<SSL_state>(SSL *ssl); | ||
| 583 | |||
| 584 | =item char *B<SSL_state_string>(SSL *ssl); | ||
| 585 | |||
| 586 | =item char *B<SSL_state_string_long>(SSL *ssl); | ||
| 587 | |||
| 588 | =item long B<SSL_total_renegotiations>(SSL *ssl); | ||
| 589 | |||
| 590 | =item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey); | ||
| 591 | |||
| 592 | =item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len); | ||
| 593 | |||
| 594 | =item int B<SSL_use_PrivateKey_file>(SSL *ssl, char *file, int type); | ||
| 595 | |||
| 596 | =item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa); | ||
| 597 | |||
| 598 | =item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len); | ||
| 599 | |||
| 600 | =item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, char *file, int type); | ||
| 601 | |||
| 602 | =item int B<SSL_use_certificate>(SSL *ssl, X509 *x); | ||
| 603 | |||
| 604 | =item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d); | ||
| 605 | |||
| 606 | =item int B<SSL_use_certificate_file>(SSL *ssl, char *file, int type); | ||
| 607 | |||
| 608 | =item int B<SSL_version>(SSL *ssl); | ||
| 609 | |||
| 610 | =item int B<SSL_want>(SSL *ssl); | ||
| 611 | |||
| 612 | =item int B<SSL_want_nothing>(SSL *ssl); | ||
| 613 | |||
| 614 | =item int B<SSL_want_read>(SSL *ssl); | ||
| 615 | |||
| 616 | =item int B<SSL_want_write>(SSL *ssl); | ||
| 617 | |||
| 618 | =item int B<SSL_want_x509_lookup>(s); | ||
| 619 | |||
| 620 | =item int B<SSL_write>(SSL *ssl, char *buf, int num); | ||
| 621 | |||
| 622 | =back | ||
| 623 | |||
| 624 | =head1 SEE ALSO | ||
| 625 | |||
| 626 | openssl(1), crypto(3) | ||
| 627 | |||
| 628 | =head1 HISTORY | ||
| 629 | |||
| 630 | The ssl(3) document appeared in OpenSSL 0.9.2 | ||
| 631 | |||
| 632 | =cut | ||
| 633 | |||
diff --git a/src/lib/libssl/src/doc/ssl_ctx.doc b/src/lib/libssl/src/doc/ssl_ctx.doc deleted file mode 100644 index 508394e75f..0000000000 --- a/src/lib/libssl/src/doc/ssl_ctx.doc +++ /dev/null | |||
| @@ -1,68 +0,0 @@ | |||
| 1 | This is now a bit dated, quite a few of the SSL_ functions could be | ||
| 2 | SSL_CTX_ functions. I will update this in the future. 30 Aug 1996 | ||
| 3 | |||
| 4 | From eay@orb.mincom.oz.au Mon Dec 11 21:37:08 1995 | ||
| 5 | Received: by orb.mincom.oz.au id AA00696 | ||
| 6 | (5.65c/IDA-1.4.4 for eay); Mon, 11 Dec 1995 11:37:08 +1000 | ||
| 7 | Date: Mon, 11 Dec 1995 11:37:08 +1000 (EST) | ||
| 8 | From: Eric Young <eay@mincom.oz.au> | ||
| 9 | X-Sender: eay@orb | ||
| 10 | To: sameer <sameer@c2.org> | ||
| 11 | Cc: Eric Young <eay@mincom.oz.au> | ||
| 12 | Subject: Re: PEM_readX509 oesn't seem to be working | ||
| 13 | In-Reply-To: <199512110102.RAA12521@infinity.c2.org> | ||
| 14 | Message-Id: <Pine.SOL.3.91.951211112115.28608D-100000@orb> | ||
| 15 | Mime-Version: 1.0 | ||
| 16 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 17 | Status: RO | ||
| 18 | X-Status: | ||
| 19 | |||
| 20 | On Sun, 10 Dec 1995, sameer wrote: | ||
| 21 | > OK, that's solved. I've found out that it is saying "no | ||
| 22 | > certificate set" in SSL_accept because s->conn == NULL | ||
| 23 | > so there is some place I need to initialize s->conn that I am | ||
| 24 | > not initializing it. | ||
| 25 | |||
| 26 | The full order of things for a server should be. | ||
| 27 | |||
| 28 | ctx=SSL_CTX_new(); | ||
| 29 | |||
| 30 | /* The next line should not really be using ctx->cert but I'll leave it | ||
| 31 | * this way right now... I don't want a X509_ routine to know about an SSL | ||
| 32 | * structure, there should be an SSL_load_verify_locations... hmm, I may | ||
| 33 | * add it tonight. | ||
| 34 | */ | ||
| 35 | X509_load_verify_locations(ctx->cert,CAfile,CApath); | ||
| 36 | |||
| 37 | /* Ok now for each new connection we do the following */ | ||
| 38 | con=SSL_new(ctx); | ||
| 39 | SSL_set_fd(con,s); | ||
| 40 | SSL_set_verify(con,verify,verify_callback); | ||
| 41 | |||
| 42 | /* set the certificate and private key to use. */ | ||
| 43 | SSL_use_certificate_ASN1(con,X509_certificate); | ||
| 44 | SSL_use_RSAPrivateKey_ASN1(con,RSA_private_key); | ||
| 45 | |||
| 46 | SSL_accept(con); | ||
| 47 | |||
| 48 | SSL_read(con)/SSL_write(con); | ||
| 49 | |||
| 50 | There is a bit more than that but that is basically the structure. | ||
| 51 | |||
| 52 | Create a context and specify where to lookup certificates. | ||
| 53 | |||
| 54 | foreach connection | ||
| 55 | { | ||
| 56 | create a SSL structure | ||
| 57 | set the certificate and private key | ||
| 58 | do a SSL_accept | ||
| 59 | |||
| 60 | we should now be ok | ||
| 61 | } | ||
| 62 | |||
| 63 | eric | ||
| 64 | -- | ||
| 65 | Eric Young | Signature removed since it was generating | ||
| 66 | AARNet: eay@mincom.oz.au | more followups than the message contents :-) | ||
| 67 | |||
| 68 | |||
diff --git a/src/lib/libssl/src/doc/ssleay.doc b/src/lib/libssl/src/doc/ssleay.doc deleted file mode 100644 index a0e86aef7c..0000000000 --- a/src/lib/libssl/src/doc/ssleay.doc +++ /dev/null | |||
| @@ -1,213 +0,0 @@ | |||
| 1 | SSLeay: a cryptographic kitchen sink. | ||
| 2 | |||
| 3 | 1st December 1995 | ||
| 4 | Way back at the start of April 1995, I was looking for a mindless | ||
| 5 | programming project. A friend of mine (Tim Hudson) said "why don't you do SSL, | ||
| 6 | it has DES encryption in it and I would not mind using it in a SSL telnet". | ||
| 7 | While it was true I had written a DES library in previous years, litle | ||
| 8 | did I know what an expansive task SSL would turn into. | ||
| 9 | |||
| 10 | First of all, the SSL protocol contains DES encryption. Well and good. My | ||
| 11 | DES library was fast and portable. It also contained the RSA's RC4 stream | ||
| 12 | cipher. Again, not a problem, some-one had just posted to sci.crypt | ||
| 13 | something that was claimed to be RC4. It also contained IDEA, I had the | ||
| 14 | specifications, not a problem to implement. MD5, an RFC, trivial, at most | ||
| 15 | I could spend a week or so trying to see if I could speed up the | ||
| 16 | implementation. All in all a nice set of ciphers. | ||
| 17 | Then the first 'expantion of the scope', RSA public key | ||
| 18 | encryption. Since I did not knowing a thing about public key encryption | ||
| 19 | or number theory, this appeared quite a daunting task. Just writing a | ||
| 20 | big number library would be problomatic in itself, let alone making it fast. | ||
| 21 | At this point the scope of 'implementing SSL' expands eponentialy. | ||
| 22 | First of all, the RSA private keys were being kept in ASN.1 format. | ||
| 23 | Thankfully the RSA PKCS series of documents explains this format. So I now | ||
| 24 | needed to be able to encode and decode arbitary ASN.1 objects. The Public | ||
| 25 | keys were embeded in X509 certificates. Hmm... these are not only | ||
| 26 | ASN.1 objects but they make up a heirachy of authentication. To | ||
| 27 | authenticate a X509 certificate one needs to retrieve it's issuers | ||
| 28 | certificate etc etc. Hmm..., so I also need to implement some kind | ||
| 29 | of certificate management software. I would also have to implement | ||
| 30 | software to authenticate certificates. At this point the support code made | ||
| 31 | the SSL part of my library look quite small. | ||
| 32 | Around this time, the first version of SSLeay was released. | ||
| 33 | |||
| 34 | Ah, but here was the problem, I was not happy with the code so far. As may | ||
| 35 | have become obvious, I had been treating all of this as a learning | ||
| 36 | exersize, so I have completely written the library myself. As such, due | ||
| 37 | to the way it had grown like a fungus, much of the library was not | ||
| 38 | 'elagent' or neat. There were global and static variables all over the | ||
| 39 | place, the SSL part did not even handle non-blocking IO. | ||
| 40 | The Great rewrite began. | ||
| 41 | |||
| 42 | As of this point in time, the 'Great rewrite' has almost finished. So what | ||
| 43 | follows is an approximate list of what is actually SSLeay 0.5.0 | ||
| 44 | |||
| 45 | /********* This needs to be updated for 0.6.0+ *************/ | ||
| 46 | |||
| 47 | --- | ||
| 48 | The library contains the following routines. Please note that most of these | ||
| 49 | functions are not specfic for SSL or any other particular cipher | ||
| 50 | implementation. I have tried to make all the routines as general purpose | ||
| 51 | as possible. So you should not think of this library as an SSL | ||
| 52 | implemtation, but rather as a library of cryptographic functions | ||
| 53 | that also contains SSL. I refer to each of these function groupings as | ||
| 54 | libraries since they are often capable of functioning as independant | ||
| 55 | libraries | ||
| 56 | |||
| 57 | First up, the general ciphers and message digests supported by the library. | ||
| 58 | |||
| 59 | MD2 rfc???, a standard 'by parts' interface to this algorithm. | ||
| 60 | MD5 rfc???, the same type of interface as for the MD2 library except a | ||
| 61 | different algorithm. | ||
| 62 | SHA THe Secure Hash Algorithm. Again the same type of interface as | ||
| 63 | MD2/MD5 except the digest is 20 bytes. | ||
| 64 | SHA1 The 'revised' version of SHA. Just about identical to SHA except | ||
| 65 | for one tweak of an inner loop. | ||
| 66 | DES This is my libdes library that has been floating around for the last | ||
| 67 | few years. It has been enhanced for no other reason than completeness. | ||
| 68 | It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and | ||
| 69 | triple DES modes of ecb, cbc, cfb64 and ofb64. cfb64 and ofb64 are | ||
| 70 | functional interfaces to the 64 bit modes of cfb and ofb used in | ||
| 71 | such a way thay they function as single character interfaces. | ||
| 72 | RC4 The RSA Inc. stream cipher. | ||
| 73 | RC2 The RSA Inc. block cipher. | ||
| 74 | IDEA An implmentation of the IDEA cipher, the library supports ecb, cbc, | ||
| 75 | cfb64 and ofb64 modes of operation. | ||
| 76 | |||
| 77 | Now all the above mentioned ciphers and digests libraries support high | ||
| 78 | speed, minimal 'crap in the way' type interfaces. For fastest and | ||
| 79 | lowest level access, these routines should be used directly. | ||
| 80 | |||
| 81 | Now there was also the matter of public key crypto systems. These are | ||
| 82 | based on large integer arithmatic. | ||
| 83 | |||
| 84 | BN This is my large integer library. It supports all the normal | ||
| 85 | arithmentic operations. It uses malloc extensivly and as such has | ||
| 86 | no limits of the size of the numbers being manipulated. If you | ||
| 87 | wish to use 4000 bit RSA moduli, these routines will handle it. | ||
| 88 | This library also contains routines to 'generate' prime numbers and | ||
| 89 | to test for primality. The RSA and DH libraries sit on top of this | ||
| 90 | library. As of this point in time, I don't support SHA, but | ||
| 91 | when I do add it, it will just sit on top of the routines contained | ||
| 92 | in this library. | ||
| 93 | RSA This implements the RSA public key algorithm. It also contains | ||
| 94 | routines that will generate a new private/public key pair. | ||
| 95 | All the RSA functions conform to the PKCS#1 standard. | ||
| 96 | DH This is an implementation of the | ||
| 97 | Diffie-Hellman protocol. There are all the require routines for | ||
| 98 | the protocol, plus extra routines that can be used to generate a | ||
| 99 | strong prime for use with a specified generator. While this last | ||
| 100 | routine is not generally required by applications implementing DH, | ||
| 101 | It is present for completeness and because I thing it is much | ||
| 102 | better to be able to 'generate' your own 'magic' numbers as oposed | ||
| 103 | to using numbers suplied by others. I conform to the PKCS#3 | ||
| 104 | standard where required. | ||
| 105 | |||
| 106 | You may have noticed the preceeding section mentions the 'generation' of | ||
| 107 | prime numbers. Now this requries the use of 'random numbers'. | ||
| 108 | |||
| 109 | RAND This psuedo-random number library is based on MD5 at it's core | ||
| 110 | and a large internal state (2k bytes). Once you have entered enough | ||
| 111 | seed data into this random number algorithm I don't feel | ||
| 112 | you will ever need to worry about it generating predictable output. | ||
| 113 | Due to the way I am writing a portable library, I have left the | ||
| 114 | issue of how to get good initial random seed data upto the | ||
| 115 | application but I do have support routines for saving and loading a | ||
| 116 | persistant random number state for use between program runs. | ||
| 117 | |||
| 118 | Now to make all these ciphers easier to use, a higher level | ||
| 119 | interface was required. In this form, the same function would be used to | ||
| 120 | encrypt 'by parts', via any one of the above mentioned ciphers. | ||
| 121 | |||
| 122 | EVP The Digital EnVeloPe library is quite large. At it's core are | ||
| 123 | function to perform encryption and decryption by parts while using | ||
| 124 | an initial parameter to specify which of the 17 different ciphers | ||
| 125 | or 4 different message digests to use. On top of these are implmented | ||
| 126 | the digital signature functions, sign, verify, seal and open. | ||
| 127 | Base64 encoding of binary data is also done in this library. | ||
| 128 | |||
| 129 | PEM rfc???? describe the format for Privacy Enhanced eMail. | ||
| 130 | As part of this standard, methods of encoding digital enveloped | ||
| 131 | data is an ascii format are defined. As such, I use a form of these | ||
| 132 | to encode enveloped data. While at this point in time full support | ||
| 133 | for PEM has not been built into the library, a minimal subset of | ||
| 134 | the secret key and Base64 encoding is present. These reoutines are | ||
| 135 | mostly used to Ascii encode binary data with a 'type' associated | ||
| 136 | with it and perhaps details of private key encryption used to | ||
| 137 | encrypt the data. | ||
| 138 | |||
| 139 | PKCS7 This is another Digital Envelope encoding standard which uses ASN.1 | ||
| 140 | to encode the data. At this point in time, while there are some | ||
| 141 | routines to encode and decode this binary format, full support is | ||
| 142 | not present. | ||
| 143 | |||
| 144 | As Mentioned, above, there are several different ways to encode | ||
| 145 | data structures. | ||
| 146 | |||
| 147 | ASN1 This library is more a set of primatives used to encode the packing | ||
| 148 | and unpacking of data structures. It is used by the X509 | ||
| 149 | certificate standard and by the PKCS standards which are used by | ||
| 150 | this library. It also contains routines for duplicating and signing | ||
| 151 | the structures asocisated with X509. | ||
| 152 | |||
| 153 | X509 The X509 library contains routines for packing and unpacking, | ||
| 154 | verifying and just about every thing else you would want to do with | ||
| 155 | X509 certificates. | ||
| 156 | |||
| 157 | PKCS7 PKCS-7 is a standard for encoding digital envelope data | ||
| 158 | structures. At this point in time the routines will load and save | ||
| 159 | DER forms of these structees. They need to be re-worked to support | ||
| 160 | the BER form which is the normal way PKCS-7 is encoded. If the | ||
| 161 | previous 2 sentances don't make much sense, don't worry, this | ||
| 162 | library is not used by this version of SSLeay anyway. | ||
| 163 | |||
| 164 | OBJ ASN.1 uses 'object identifiers' to identify objects. A set of | ||
| 165 | functions were requred to translate from ASN.1 to an intenger, to a | ||
| 166 | character string. This library provieds these translations | ||
| 167 | |||
| 168 | Now I mentioned an X509 library. X509 specified a hieachy of certificates | ||
| 169 | which needs to be traversed to authenticate particular certificates. | ||
| 170 | |||
| 171 | METH This library is used to push 'methods' of retrieving certificates | ||
| 172 | into the library. There are some supplied 'methods' with SSLeay | ||
| 173 | but applications can add new methods if they so desire. | ||
| 174 | This library has not been finished and is not being used in this | ||
| 175 | version. | ||
| 176 | |||
| 177 | Now all the above are required for use in the initial point of this project. | ||
| 178 | |||
| 179 | SSL The SSL protocol. This is a full implmentation of SSL v 2. It | ||
| 180 | support both server and client authentication. SSL v 3 support | ||
| 181 | will be added when the SSL v 3 specification is released in it's | ||
| 182 | final form. | ||
| 183 | |||
| 184 | Now quite a few of the above mentioned libraries rely on a few 'complex' | ||
| 185 | data structures. For each of these I have a library. | ||
| 186 | |||
| 187 | Lhash This is a hash table library which is used extensivly. | ||
| 188 | |||
| 189 | STACK An implemetation of a Stack data structure. | ||
| 190 | |||
| 191 | BUF A simple character array structure that also support a function to | ||
| 192 | check that the array is greater that a certain size, if it is not, | ||
| 193 | it is realloced so that is it. | ||
| 194 | |||
| 195 | TXT_DB A simple memory based text file data base. The application can specify | ||
| 196 | unique indexes that will be enforced at update time. | ||
| 197 | |||
| 198 | CONF Most of the programs written for this library require a configuration | ||
| 199 | file. Instead of letting programs constantly re-implment this | ||
| 200 | subsystem, the CONF library provides a consistant and flexable | ||
| 201 | interface to not only configuration files but also environment | ||
| 202 | variables. | ||
| 203 | |||
| 204 | But what about when something goes wrong? | ||
| 205 | The one advantage (and perhaps disadvantage) of all of these | ||
| 206 | functions being in one library was the ability to implement a | ||
| 207 | single error reporting system. | ||
| 208 | |||
| 209 | ERR This library is used to report errors. The error system records | ||
| 210 | library number, function number (in the library) and reason | ||
| 211 | number. Multiple errors can be reported so that an 'error' trace | ||
| 212 | is created. The errors can be printed in numeric or textual form. | ||
| 213 | |||
diff --git a/src/lib/libssl/src/doc/ssleay.txt b/src/lib/libssl/src/doc/ssleay.txt new file mode 100644 index 0000000000..094e28ce48 --- /dev/null +++ b/src/lib/libssl/src/doc/ssleay.txt | |||
| @@ -0,0 +1,7014 @@ | |||
| 1 | |||
| 2 | Bundle of old SSLeay documentation files [OBSOLETE!] | ||
| 3 | |||
| 4 | ==== readme ======================================================== | ||
| 5 | |||
| 6 | This is the old 0.6.6 docuementation. Most of the cipher stuff is still | ||
| 7 | relevent but I'm working (very slowly) on new docuemtation. | ||
| 8 | The current version can be found online at | ||
| 9 | |||
| 10 | http://www.cryptsoft.com/ssleay/doc | ||
| 11 | |||
| 12 | ==== API.doc ======================================================== | ||
| 13 | |||
| 14 | SSL - SSLv2/v3/v23 etc. | ||
| 15 | |||
| 16 | BIO - methods and how they plug together | ||
| 17 | |||
| 18 | MEM - memory allocation callback | ||
| 19 | |||
| 20 | CRYPTO - locking for threads | ||
| 21 | |||
| 22 | EVP - Ciphers/Digests/signatures | ||
| 23 | |||
| 24 | RSA - methods | ||
| 25 | |||
| 26 | X509 - certificate retrieval | ||
| 27 | |||
| 28 | X509 - validation | ||
| 29 | |||
| 30 | X509 - X509v3 extensions | ||
| 31 | |||
| 32 | Objects - adding object identifiers | ||
| 33 | |||
| 34 | ASN.1 - parsing | ||
| 35 | |||
| 36 | PEM - parsing | ||
| 37 | |||
| 38 | ==== ssl/readme ===================================================== | ||
| 39 | |||
| 40 | 22 Jun 1996 | ||
| 41 | This file belongs in ../apps, but I'll leave it here because it deals | ||
| 42 | with SSL :-) It is rather dated but it gives you an idea of how | ||
| 43 | things work. | ||
| 44 | === | ||
| 45 | |||
| 46 | 17 Jul 1995 | ||
| 47 | I have been changing things quite a bit and have not fully updated | ||
| 48 | this file, so take what you read with a grain of salt | ||
| 49 | eric | ||
| 50 | === | ||
| 51 | The s_client and s_server programs can be used to test SSL capable | ||
| 52 | IP/port addresses and the verification of the X509 certificates in use | ||
| 53 | by these services. I strongly advise having a look at the code to get | ||
| 54 | an idea of how to use the authentication under SSLeay. Any feedback | ||
| 55 | on changes and improvements would be greatly accepted. | ||
| 56 | |||
| 57 | This file will probably be gibberish unless you have read | ||
| 58 | rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM | ||
| 59 | authentication. | ||
| 60 | |||
| 61 | A Brief outline (and examples) how to use them to do so. | ||
| 62 | |||
| 63 | NOTE: | ||
| 64 | The environment variable SSL_CIPER is used to specify the prefered | ||
| 65 | cipher to use, play around with setting it's value to combinations of | ||
| 66 | RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL | ||
| 67 | in a : separated list. | ||
| 68 | |||
| 69 | This directory contains 3 X509 certificates which can be used by these programs. | ||
| 70 | client.pem: a file containing a certificate and private key to be used | ||
| 71 | by s_client. | ||
| 72 | server.pem :a file containing a certificate and private key to be used | ||
| 73 | by s_server. | ||
| 74 | eay1024.pem:the certificate used to sign client.pem and server.pem. | ||
| 75 | This would be your CA's certificate. There is also a link | ||
| 76 | from the file a8556381.0 to eay1024.PEM. The value a8556381 | ||
| 77 | is returned by 'x509 -hash -noout <eay1024.pem' and is the | ||
| 78 | value used by X509 verification routines to 'find' this | ||
| 79 | certificte when search a directory for it. | ||
| 80 | [the above is not true any more, the CA cert is | ||
| 81 | ../certs/testca.pem which is signed by ../certs/mincomca.pem] | ||
| 82 | |||
| 83 | When testing the s_server, you may get | ||
| 84 | bind: Address already in use | ||
| 85 | errors. These indicate the port is still being held by the unix | ||
| 86 | kernel and you are going to have to wait for it to let go of it. If | ||
| 87 | this is the case, remember to use the port commands on the s_server and | ||
| 88 | s_client to talk on an alternative port. | ||
| 89 | |||
| 90 | ===== | ||
| 91 | s_client. | ||
| 92 | This program can be used to connect to any IP/hostname:port that is | ||
| 93 | talking SSL. Once connected, it will attempt to authenticate the | ||
| 94 | certificate it was passed and if everything works as expected, a 2 | ||
| 95 | directional channel will be open. Any text typed will be sent to the | ||
| 96 | other end. type Q<cr> to exit. Flags are as follows. | ||
| 97 | -host arg : Arg is the host or IP address to connect to. | ||
| 98 | -port arg : Arg is the port to connect to (https is 443). | ||
| 99 | -verify arg : Turn on authentication of the server certificate. | ||
| 100 | : Arg specifies the 'depth', this will covered below. | ||
| 101 | -cert arg : The optional certificate to use. This certificate | ||
| 102 | : will be returned to the server if the server | ||
| 103 | : requests it for client authentication. | ||
| 104 | -key arg : The private key that matches the certificate | ||
| 105 | : specified by the -cert option. If this is not | ||
| 106 | : specified (but -cert is), the -cert file will be | ||
| 107 | : searched for the Private key. Both files are | ||
| 108 | : assumed to be in PEM format. | ||
| 109 | -CApath arg : When to look for certificates when 'verifying' the | ||
| 110 | : certificate from the server. | ||
| 111 | -CAfile arg : A file containing certificates to be used for | ||
| 112 | : 'verifying' the server certificate. | ||
| 113 | -reconnect : Once a connection has been made, drop it and | ||
| 114 | : reconnect with same session-id. This is for testing :-). | ||
| 115 | |||
| 116 | The '-verify n' parameter specifies not only to verify the servers | ||
| 117 | certificate but to also only take notice of 'n' levels. The best way | ||
| 118 | to explain is to show via examples. | ||
| 119 | Given | ||
| 120 | s_server -cert server.PEM is running. | ||
| 121 | |||
| 122 | s_client | ||
| 123 | CONNECTED | ||
| 124 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server | ||
| 125 | issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 126 | verify error:num=1:unable to get issuer certificate | ||
| 127 | verify return:1 | ||
| 128 | CIPHER is CBC-DES-MD5 | ||
| 129 | What has happened is that the 'SSLeay demo server' certificate's | ||
| 130 | issuer ('CA') could not be found but because verify is not on, we | ||
| 131 | don't care and the connection has been made anyway. It is now 'up' | ||
| 132 | using CBC-DES-MD5 mode. This is an unauthenticate secure channel. | ||
| 133 | You may not be talking to the right person but the data going to them | ||
| 134 | is encrypted. | ||
| 135 | |||
| 136 | s_client -verify 0 | ||
| 137 | CONNECTED | ||
| 138 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server | ||
| 139 | issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 140 | verify error:num=1:unable to get issuer certificate | ||
| 141 | verify return:1 | ||
| 142 | CIPHER is CBC-DES-MD5 | ||
| 143 | We are 'verifying' but only to depth 0, so since the 'SSLeay demo server' | ||
| 144 | certificate passed the date and checksum, we are happy to proceed. | ||
| 145 | |||
| 146 | s_client -verify 1 | ||
| 147 | CONNECTED | ||
| 148 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server | ||
| 149 | issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 150 | verify error:num=1:unable to get issuer certificate | ||
| 151 | verify return:0 | ||
| 152 | ERROR | ||
| 153 | verify error:unable to get issuer certificate | ||
| 154 | In this case we failed to make the connection because we could not | ||
| 155 | authenticate the certificate because we could not find the | ||
| 156 | 'CA' certificate. | ||
| 157 | |||
| 158 | s_client -verify 1 -CAfile eay1024.PEM | ||
| 159 | CONNECTED | ||
| 160 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server | ||
| 161 | verify return:1 | ||
| 162 | depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 163 | verify return:1 | ||
| 164 | CIPHER is CBC-DES-MD5 | ||
| 165 | We loaded the certificates from the file eay1024.PEM. Everything | ||
| 166 | checked out and so we made the connection. | ||
| 167 | |||
| 168 | s_client -verify 1 -CApath . | ||
| 169 | CONNECTED | ||
| 170 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server | ||
| 171 | verify return:1 | ||
| 172 | depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 173 | verify return:1 | ||
| 174 | CIPHER is CBC-DES-MD5 | ||
| 175 | We looked in out local directory for issuer certificates and 'found' | ||
| 176 | a8556381.0 and so everything is ok. | ||
| 177 | |||
| 178 | It is worth noting that 'CA' is a self certified certificate. If you | ||
| 179 | are passed one of these, it will fail to 'verify' at depth 0 because | ||
| 180 | we need to lookup the certifier of a certificate from some information | ||
| 181 | that we trust and keep locally. | ||
| 182 | |||
| 183 | SSL_CIPHER=CBC3-DES-MD5:RC4-MD5 | ||
| 184 | export SSL_CIPHER | ||
| 185 | s_client -verify 10 -CApath . -reconnect | ||
| 186 | CONNECTED | ||
| 187 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server | ||
| 188 | verify return:1 | ||
| 189 | depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 190 | verify return:1 | ||
| 191 | drop the connection and reconnect with the same session id | ||
| 192 | CIPHER is CBC3-DES-MD5 | ||
| 193 | This has done a full connection and then re-estabished it with the | ||
| 194 | same session id but a new socket. No RSA stuff occures on the second | ||
| 195 | connection. Note that we said we would prefer to use CBC3-DES-MD5 | ||
| 196 | encryption and so, since the server supports it, we are. | ||
| 197 | |||
| 198 | ===== | ||
| 199 | s_server | ||
| 200 | This program accepts SSL connections on a specified port | ||
| 201 | Once connected, it will estabish an SSL connection and optionaly | ||
| 202 | attempt to authenticate the client. A 2 directional channel will be | ||
| 203 | open. Any text typed will be sent to the other end. Type Q<cr> to exit. | ||
| 204 | Flags are as follows. | ||
| 205 | -port arg : Arg is the port to listen on. | ||
| 206 | -verify arg : Turn on authentication of the client if they have a | ||
| 207 | : certificate. Arg specifies the 'depth'. | ||
| 208 | -Verify arg : Turn on authentication of the client. If they don't | ||
| 209 | : have a valid certificate, drop the connection. | ||
| 210 | -cert arg : The certificate to use. This certificate | ||
| 211 | : will be passed to the client. If it is not | ||
| 212 | : specified, it will default to server.PEM | ||
| 213 | -key arg : The private key that matches the certificate | ||
| 214 | : specified by the -cert option. If this is not | ||
| 215 | : specified (but -cert is), the -cert file will be | ||
| 216 | : searched for the Private key. Both files are | ||
| 217 | : assumed to be in PEM format. Default is server.PEM | ||
| 218 | -CApath arg : When to look for certificates when 'verifying' the | ||
| 219 | : certificate from the client. | ||
| 220 | -CAfile arg : A file containing certificates to be used for | ||
| 221 | : 'verifying' the client certificate. | ||
| 222 | |||
| 223 | For the following 'demo' I will specify the s_server command and | ||
| 224 | the s_client command and then list the output from the s_server. | ||
| 225 | s_server | ||
| 226 | s_client | ||
| 227 | CONNECTED | ||
| 228 | CIPHER is CBC-DES-MD5 | ||
| 229 | Everything up and running | ||
| 230 | |||
| 231 | s_server -verify 0 | ||
| 232 | s_client | ||
| 233 | CONNECTED | ||
| 234 | CIPHER is CBC-DES-MD5 | ||
| 235 | Ok since no certificate was returned and we don't care. | ||
| 236 | |||
| 237 | s_server -verify 0 | ||
| 238 | ./s_client -cert client.PEM | ||
| 239 | CONNECTED | ||
| 240 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client | ||
| 241 | issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 242 | verify error:num=1:unable to get issuer certificate | ||
| 243 | verify return:1 | ||
| 244 | CIPHER is CBC-DES-MD5 | ||
| 245 | Ok since we were only verifying to level 0 | ||
| 246 | |||
| 247 | s_server -verify 4 | ||
| 248 | s_client -cert client.PEM | ||
| 249 | CONNECTED | ||
| 250 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client | ||
| 251 | issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 252 | verify error:num=1:unable to get issuer certificate | ||
| 253 | verify return:0 | ||
| 254 | ERROR | ||
| 255 | verify error:unable to get issuer certificate | ||
| 256 | Bad because we could not authenticate the returned certificate. | ||
| 257 | |||
| 258 | s_server -verify 4 -CApath . | ||
| 259 | s_client -cert client.PEM | ||
| 260 | CONNECTED | ||
| 261 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client | ||
| 262 | verify return:1 | ||
| 263 | depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 264 | verify return:1 | ||
| 265 | CIPHER is CBC-DES-MD5 | ||
| 266 | Ok because we could authenticate the returned certificate :-). | ||
| 267 | |||
| 268 | s_server -Verify 0 -CApath . | ||
| 269 | s_client | ||
| 270 | CONNECTED | ||
| 271 | ERROR | ||
| 272 | SSL error:function is:REQUEST_CERTIFICATE | ||
| 273 | :error is :client end did not return a certificate | ||
| 274 | Error because no certificate returned. | ||
| 275 | |||
| 276 | s_server -Verify 4 -CApath . | ||
| 277 | s_client -cert client.PEM | ||
| 278 | CONNECTED | ||
| 279 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client | ||
| 280 | verify return:1 | ||
| 281 | depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 282 | verify return:1 | ||
| 283 | CIPHER is CBC-DES-MD5 | ||
| 284 | Full authentication of the client. | ||
| 285 | |||
| 286 | So in summary to do full authentication of both ends | ||
| 287 | s_server -Verify 9 -CApath . | ||
| 288 | s_client -cert client.PEM -CApath . -verify 9 | ||
| 289 | From the server side | ||
| 290 | CONNECTED | ||
| 291 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client | ||
| 292 | verify return:1 | ||
| 293 | depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 294 | verify return:1 | ||
| 295 | CIPHER is CBC-DES-MD5 | ||
| 296 | From the client side | ||
| 297 | CONNECTED | ||
| 298 | depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server | ||
| 299 | verify return:1 | ||
| 300 | depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA | ||
| 301 | verify return:1 | ||
| 302 | CIPHER is CBC-DES-MD5 | ||
| 303 | |||
| 304 | For general probing of the 'internet https' servers for the | ||
| 305 | distribution area, run | ||
| 306 | s_client -host www.netscape.com -port 443 -verify 4 -CApath ../rsa/hash | ||
| 307 | Then enter | ||
| 308 | GET / | ||
| 309 | and you should be talking to the https server on that host. | ||
| 310 | |||
| 311 | www.rsa.com was refusing to respond to connections on 443 when I was | ||
| 312 | testing. | ||
| 313 | |||
| 314 | have fun :-). | ||
| 315 | |||
| 316 | eric | ||
| 317 | |||
| 318 | ==== a_verify.doc ======================================================== | ||
| 319 | |||
| 320 | From eay@mincom.com Fri Oct 4 18:29:06 1996 | ||
| 321 | Received: by orb.mincom.oz.au id AA29080 | ||
| 322 | (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000 | ||
| 323 | Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST) | ||
| 324 | From: Eric Young <eay@mincom.oz.au> | ||
| 325 | X-Sender: eay@orb | ||
| 326 | To: wplatzer <wplatzer@iaik.tu-graz.ac.at> | ||
| 327 | Cc: Eric Young <eay@mincom.oz.au>, SSL Mailing List <ssl-users@mincom.com> | ||
| 328 | Subject: Re: Netscape's Public Key | ||
| 329 | In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at> | ||
| 330 | Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb> | ||
| 331 | Mime-Version: 1.0 | ||
| 332 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 333 | Status: RO | ||
| 334 | X-Status: | ||
| 335 | |||
| 336 | On Thu, 3 Oct 1996, wplatzer wrote: | ||
| 337 | > I get Public Key from Netscape (Gold 3.0b4), but cannot do anything | ||
| 338 | > with it... It looks like (asn1parse): | ||
| 339 | > | ||
| 340 | > 0:d=0 hl=3 l=180 cons: SEQUENCE | ||
| 341 | > 3:d=1 hl=2 l= 96 cons: SEQUENCE | ||
| 342 | > 5:d=2 hl=2 l= 92 cons: SEQUENCE | ||
| 343 | > 7:d=3 hl=2 l= 13 cons: SEQUENCE | ||
| 344 | > 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption | ||
| 345 | > 20:d=4 hl=2 l= 0 prim: NULL | ||
| 346 | > 22:d=3 hl=2 l= 75 prim: BIT STRING | ||
| 347 | > 99:d=2 hl=2 l= 0 prim: IA5STRING : | ||
| 348 | > 101:d=1 hl=2 l= 13 cons: SEQUENCE | ||
| 349 | > 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption | ||
| 350 | > 114:d=2 hl=2 l= 0 prim: NULL | ||
| 351 | > 116:d=1 hl=2 l= 65 prim: BIT STRING | ||
| 352 | > | ||
| 353 | > The first BIT STRING is the public key and the second BIT STRING is | ||
| 354 | > the signature. | ||
| 355 | > But a public key consists of the public exponent and the modulus. Are | ||
| 356 | > both numbers in the first BIT STRING? | ||
| 357 | > Is there a document simply describing this coding stuff (checking | ||
| 358 | > signature, get the public key, etc.)? | ||
| 359 | |||
| 360 | Minimal in SSLeay. If you want to see what the modulus and exponent are, | ||
| 361 | try asn1parse -offset 25 -length 75 <key.pem | ||
| 362 | asn1parse will currently stuff up on the 'length 75' part (fixed in next | ||
| 363 | release) but it will print the stuff. If you are after more | ||
| 364 | documentation on ASN.1, have a look at www.rsa.com and get their PKCS | ||
| 365 | documents, most of my initial work on SSLeay was done using them. | ||
| 366 | |||
| 367 | As for SSLeay, | ||
| 368 | util/crypto.num and util/ssl.num are lists of all exported functions in | ||
| 369 | the library (but not macros :-(. | ||
| 370 | |||
| 371 | The ones for extracting public keys from certificates and certificate | ||
| 372 | requests are EVP_PKEY * X509_REQ_extract_key(X509_REQ *req); | ||
| 373 | EVP_PKEY * X509_extract_key(X509 *x509); | ||
| 374 | |||
| 375 | To verify a signature on a signed ASN.1 object | ||
| 376 | int X509_verify(X509 *a,EVP_PKEY *key); | ||
| 377 | int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key); | ||
| 378 | int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key); | ||
| 379 | int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key); | ||
| 380 | |||
| 381 | I should mention that EVP_PKEY can be used to hold a public or a private key, | ||
| 382 | since for things like RSA and DSS, a public key is just a subset of what | ||
| 383 | is stored for the private key. | ||
| 384 | |||
| 385 | To sign any of the above structures | ||
| 386 | |||
| 387 | int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md); | ||
| 388 | int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md); | ||
| 389 | int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md); | ||
| 390 | int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md); | ||
| 391 | |||
| 392 | where md is the message digest to sign with. | ||
| 393 | |||
| 394 | There are all defined in x509.h and all the _sign and _verify functions are | ||
| 395 | actually macros to the ASN1_sign() and ASN1_verify() functions. | ||
| 396 | These functions will put the correct algorithm identifiers in the correct | ||
| 397 | places in the structures. | ||
| 398 | |||
| 399 | eric | ||
| 400 | -- | ||
| 401 | Eric Young | BOOL is tri-state according to Bill Gates. | ||
| 402 | AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). | ||
| 403 | |||
| 404 | ==== x509 ======================================================= | ||
| 405 | |||
| 406 | X509_verify() | ||
| 407 | X509_sign() | ||
| 408 | |||
| 409 | X509_get_version() | ||
| 410 | X509_get_serialNumber() | ||
| 411 | X509_get_issuer() | ||
| 412 | X509_get_subject() | ||
| 413 | X509_get_notBefore() | ||
| 414 | X509_get_notAfter() | ||
| 415 | X509_get_pubkey() | ||
| 416 | |||
| 417 | X509_set_version() | ||
| 418 | X509_set_serialNumber() | ||
| 419 | X509_set_issuer() | ||
| 420 | X509_set_subject() | ||
| 421 | X509_set_notBefore() | ||
| 422 | X509_set_notAfter() | ||
| 423 | X509_set_pubkey() | ||
| 424 | |||
| 425 | X509_get_extensions() | ||
| 426 | X509_set_extensions() | ||
| 427 | |||
| 428 | X509_EXTENSIONS_clear() | ||
| 429 | X509_EXTENSIONS_retrieve() | ||
| 430 | X509_EXTENSIONS_add() | ||
| 431 | X509_EXTENSIONS_delete() | ||
| 432 | |||
| 433 | ==== x509 attribute ================================================ | ||
| 434 | |||
| 435 | PKCS7 | ||
| 436 | STACK of X509_ATTRIBUTES | ||
| 437 | ASN1_OBJECT | ||
| 438 | STACK of ASN1_TYPE | ||
| 439 | |||
| 440 | So it is | ||
| 441 | |||
| 442 | p7.xa[].obj | ||
| 443 | p7.xa[].data[] | ||
| 444 | |||
| 445 | get_obj_by_nid(STACK , nid) | ||
| 446 | get_num_by_nid(STACK , nid) | ||
| 447 | get_data_by_nid(STACK , nid, index) | ||
| 448 | |||
| 449 | X509_ATTRIBUTE *X509_ATTRIBUTE_new(void ); | ||
| 450 | void X509_ATTRIBUTE_free(X509_ATTRIBUTE *a); | ||
| 451 | |||
| 452 | X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **ex, | ||
| 453 | int nid, STACK *value); | ||
| 454 | |||
| 455 | X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **ex, | ||
| 456 | int nid, STACK *value); | ||
| 457 | |||
| 458 | int X509_ATTRIBUTE_set_object(X509_ATTRIBUTE *ex,ASN1_OBJECT *obj); | ||
| 459 | int X509_ATTRIBUTE_add_data(X509_ATTRIBUTE *ex, int index, | ||
| 460 | ASN1_TYPE *value); | ||
| 461 | |||
| 462 | ASN1_OBJECT * X509_ATTRIBUTE_get_object(X509_ATTRIBUTE *ex); | ||
| 463 | int X509_ATTRIBUTE_get_num(X509_ATTRIBUTE *ne); | ||
| 464 | ASN1_TYPE * X509_ATTRIBUTE_get_data(X509_ATTRIBUTE *ne,int index); | ||
| 465 | |||
| 466 | ASN1_TYPE * X509_ATTRIBUTE_get_data_by_NID(X509_ATTRIBUTE *ne, | ||
| 467 | ASN1_OBJECT *obj); | ||
| 468 | |||
| 469 | X509_ATTRIBUTE *PKCS7_get_s_att_by_NID(PKCS7 *p7,int nid); | ||
| 470 | X509_ATTRIBUTE *PKCS7_get_u_att_by_NID(PKCS7 *p7,int nid); | ||
| 471 | |||
| 472 | ==== x509 v3 ======================================================== | ||
| 473 | |||
| 474 | The 'new' system. | ||
| 475 | |||
| 476 | The X509_EXTENSION_METHOD includes extensions and attributes and/or names. | ||
| 477 | Basically everthing that can be added to an X509 with an OID identifying it. | ||
| 478 | |||
| 479 | It operates via 2 methods per object id. | ||
| 480 | int a2i_XXX(X509 *x,char *str,int len); | ||
| 481 | int i2a_XXX(BIO *bp,X509 *x); | ||
| 482 | |||
| 483 | The a2i_XXX function will add the object with a value converted from the | ||
| 484 | string into the X509. Len can be -1 in which case the length is calculated | ||
| 485 | via strlen(str). Applications can always use direct knowledge to load and | ||
| 486 | unload the relevent objects themselves. | ||
| 487 | |||
| 488 | i2a_XXX will print to the passed BIO, a text representation of the | ||
| 489 | relevet object. Use a memory BIO if you want it printed to a buffer :-). | ||
| 490 | |||
| 491 | X509_add_by_NID(X509 *x,int nid,char *str,int len); | ||
| 492 | X509_add_by_OBJ(X509 *x,ASN1_OBJECT *obj,char *str,int len); | ||
| 493 | |||
| 494 | X509_print_by_name(BIO *bp,X509 *x); | ||
| 495 | X509_print_by_NID(BIO *bp,X509 *x); | ||
| 496 | X509_print_by_OBJ(BIO *bp,X509 *x); | ||
| 497 | |||
| 498 | ==== verify ======================================================== | ||
| 499 | |||
| 500 | X509_verify_cert_chain( | ||
| 501 | CERT_STORE *cert_store, | ||
| 502 | STACK /* X509 */ *certs, | ||
| 503 | int *verify_result, | ||
| 504 | int (*verify_error_callback)() | ||
| 505 | char *argument_to_callback, /* SSL */ | ||
| 506 | |||
| 507 | app_verify_callback( | ||
| 508 | char *app_verify_arg, /* from SSL_CTX */ | ||
| 509 | STACK /* X509 */ *certs, | ||
| 510 | int *verify_result, | ||
| 511 | int (*verify_error_callback)() | ||
| 512 | SSL *s, | ||
| 513 | |||
| 514 | int X509_verify_cert( | ||
| 515 | CERT_STORE *cert_store, | ||
| 516 | X509 *x509, | ||
| 517 | int *verify_result, | ||
| 518 | int (*verify_error_callback)(), | ||
| 519 | char *arg, | ||
| 520 | |||
| 521 | ==== apps.doc ======================================================== | ||
| 522 | |||
| 523 | The applications | ||
| 524 | |||
| 525 | Ok, where to begin.... | ||
| 526 | In the begining, when SSLeay was small (April 1995), there | ||
| 527 | were but few applications, they did happily cohabit in | ||
| 528 | the one bin directory. Then over time, they did multiply and grow, | ||
| 529 | and they started to look like microsoft software; 500k to print 'hello world'. | ||
| 530 | A new approach was needed. They were coalessed into one 'Monolithic' | ||
| 531 | application, ssleay. This one program is composed of many programs that | ||
| 532 | can all be compiled independantly. | ||
| 533 | |||
| 534 | ssleay has 3 modes of operation. | ||
| 535 | 1) If the ssleay binaray has the name of one of its component programs, it | ||
| 536 | executes that program and then exits. This can be achieve by using hard or | ||
| 537 | symbolic links, or failing that, just renaming the binary. | ||
| 538 | 2) If the first argument to ssleay is the name of one of the component | ||
| 539 | programs, that program runs that program and then exits. | ||
| 540 | 3) If there are no arguments, ssleay enters a 'command' mode. Each line is | ||
| 541 | interpreted as a program name plus arguments. After each 'program' is run, | ||
| 542 | ssleay returns to the comand line. | ||
| 543 | |||
| 544 | dgst - message digests | ||
| 545 | enc - encryption and base64 encoding | ||
| 546 | |||
| 547 | ans1parse - 'pulls' appart ASN.1 encoded objects like certificates. | ||
| 548 | |||
| 549 | dh - Diffle-Hellman parameter manipulation. | ||
| 550 | rsa - RSA manipulations. | ||
| 551 | crl - Certificate revokion list manipulations | ||
| 552 | x509 - X509 cert fiddles, including signing. | ||
| 553 | pkcs7 - pkcs7 manipulation, only DER versions right now. | ||
| 554 | |||
| 555 | genrsa - generate an RSA private key. | ||
| 556 | gendh - Generate a set of Diffle-Hellman parameters. | ||
| 557 | req - Generate a PKCS#10 object, a certificate request. | ||
| 558 | |||
| 559 | s_client - SSL client program | ||
| 560 | s_server - SSL server program | ||
| 561 | s_time - A SSL protocol timing program | ||
| 562 | s_mult - Another SSL server, but it multiplexes | ||
| 563 | connections. | ||
| 564 | s_filter - under development | ||
| 565 | |||
| 566 | errstr - Convert SSLeay error numbers to strings. | ||
| 567 | ca - Sign certificate requests, and generate | ||
| 568 | certificate revokion lists | ||
| 569 | crl2pkcs7 - put a crl and certifcates into a pkcs7 object. | ||
| 570 | speed - Benchmark the ciphers. | ||
| 571 | verify - Check certificates | ||
| 572 | hashdir - under development | ||
| 573 | |||
| 574 | [ there a now a few more options, play with the program to see what they | ||
| 575 | are ] | ||
| 576 | |||
| 577 | ==== asn1.doc ======================================================== | ||
| 578 | |||
| 579 | The ASN.1 Routines. | ||
| 580 | |||
| 581 | ASN.1 is a specification for how to encode structured 'data' in binary form. | ||
| 582 | The approach I have take to the manipulation of structures and their encoding | ||
| 583 | into ASN.1 is as follows. | ||
| 584 | |||
| 585 | For each distinct structure there are 4 function of the following form | ||
| 586 | TYPE *TYPE_new(void); | ||
| 587 | void TYPE_free(TYPE *); | ||
| 588 | TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length); | ||
| 589 | long i2d_TYPE(TYPE *a,unsigned char **pp); /* CHECK RETURN VALUE */ | ||
| 590 | |||
| 591 | where TYPE is the type of the 'object'. The TYPE that have these functions | ||
| 592 | can be in one of 2 forms, either the internal C malloc()ed data structure | ||
| 593 | or in the DER (a variant of ASN.1 encoding) binary encoding which is just | ||
| 594 | an array of unsigned bytes. The 'i2d' functions converts from the internal | ||
| 595 | form to the DER form and the 'd2i' functions convert from the DER form to | ||
| 596 | the internal form. | ||
| 597 | |||
| 598 | The 'new' function returns a malloc()ed version of the structure with all | ||
| 599 | substructures either created or left as NULL pointers. For 'optional' | ||
| 600 | fields, they are normally left as NULL to indicate no value. For variable | ||
| 601 | size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the | ||
| 602 | STACK data type is used to hold the values. Have a read of stack.doc | ||
| 603 | and have a look at the relevant header files to see what I mean. If there | ||
| 604 | is an error while malloc()ing the structure, NULL is returned. | ||
| 605 | |||
| 606 | The 'free' function will free() all the sub components of a particular | ||
| 607 | structure. If any of those sub components have been 'removed', replace | ||
| 608 | them with NULL pointers, the 'free' functions are tolerant of NULL fields. | ||
| 609 | |||
| 610 | The 'd2i' function copies a binary representation into a C structure. It | ||
| 611 | operates as follows. 'a' is a pointer to a pointer to | ||
| 612 | the structure to populate, 'pp' is a pointer to a pointer to where the DER | ||
| 613 | byte string is located and 'length' is the length of the '*pp' data. | ||
| 614 | If there are no errors, a pointer to the populated structure is returned. | ||
| 615 | If there is an error, NULL is returned. Errors can occur because of | ||
| 616 | malloc() failures but normally they will be due to syntax errors in the DER | ||
| 617 | encoded data being parsed. It is also an error if there was an | ||
| 618 | attempt to read more that 'length' bytes from '*p'. If | ||
| 619 | everything works correctly, the value in '*p' is updated | ||
| 620 | to point at the location just beyond where the DER | ||
| 621 | structure was read from. In this way, chained calls to 'd2i' type | ||
| 622 | functions can be made, with the pointer into the 'data' array being | ||
| 623 | 'walked' along the input byte array. | ||
| 624 | Depending on the value passed for 'a', different things will be done. If | ||
| 625 | 'a' is NULL, a new structure will be malloc()ed and returned. If '*a' is | ||
| 626 | NULL, a new structure will be malloc()ed and put into '*a' and returned. | ||
| 627 | If '*a' is not NULL, the structure in '*a' will be populated, or in the | ||
| 628 | case of an error, free()ed and then returned. | ||
| 629 | Having these semantics means that a structure | ||
| 630 | can call a 'd2i' function to populate a field and if the field is currently | ||
| 631 | NULL, the structure will be created. | ||
| 632 | |||
| 633 | The 'i2d' function type is used to copy a C structure to a byte array. | ||
| 634 | The parameter 'a' is the structure to convert and '*p' is where to put it. | ||
| 635 | As for the 'd2i' type structure, 'p' is updated to point after the last | ||
| 636 | byte written. If p is NULL, no data is written. The function also returns | ||
| 637 | the number of bytes written. Where this becomes useful is that if the | ||
| 638 | function is called with a NULL 'p' value, the length is returned. This can | ||
| 639 | then be used to malloc() an array of bytes and then the same function can | ||
| 640 | be recalled passing the malloced array to be written to. e.g. | ||
| 641 | |||
| 642 | int len; | ||
| 643 | unsigned char *bytes,*p; | ||
| 644 | len=i2d_X509(x,NULL); /* get the size of the ASN1 encoding of 'x' */ | ||
| 645 | if ((bytes=(unsigned char *)malloc(len)) == NULL) | ||
| 646 | goto err; | ||
| 647 | p=bytes; | ||
| 648 | i2d_X509(x,&p); | ||
| 649 | |||
| 650 | Please note that a new variable, 'p' was passed to i2d_X509. After the | ||
| 651 | call to i2d_X509 p has been incremented by len bytes. | ||
| 652 | |||
| 653 | Now the reason for this functional organisation is that it allows nested | ||
| 654 | structures to be built up by calling these functions as required. There | ||
| 655 | are various macros used to help write the general 'i2d', 'd2i', 'new' and | ||
| 656 | 'free' functions. They are discussed in another file and would only be | ||
| 657 | used by some-one wanting to add new structures to the library. As you | ||
| 658 | might be able to guess, the process of writing ASN.1 files can be a bit CPU | ||
| 659 | expensive for complex structures. I'm willing to live with this since the | ||
| 660 | simpler library code make my life easier and hopefully most programs using | ||
| 661 | these routines will have their execution profiles dominated by cipher or | ||
| 662 | message digest routines. | ||
| 663 | What follows is a list of 'TYPE' values and the corresponding ASN.1 | ||
| 664 | structure and where it is used. | ||
| 665 | |||
| 666 | TYPE ASN.1 | ||
| 667 | ASN1_INTEGER INTEGER | ||
| 668 | ASN1_BIT_STRING BIT STRING | ||
| 669 | ASN1_OCTET_STRING OCTET STRING | ||
| 670 | ASN1_OBJECT OBJECT IDENTIFIER | ||
| 671 | ASN1_PRINTABLESTRING PrintableString | ||
| 672 | ASN1_T61STRING T61String | ||
| 673 | ASN1_IA5STRING IA5String | ||
| 674 | ASN1_UTCTIME UTCTime | ||
| 675 | ASN1_TYPE Any of the above mentioned types plus SEQUENCE and SET | ||
| 676 | |||
| 677 | Most of the above mentioned types are actualled stored in the | ||
| 678 | ASN1_BIT_STRING type and macros are used to differentiate between them. | ||
| 679 | The 3 types used are | ||
| 680 | |||
| 681 | typedef struct asn1_object_st | ||
| 682 | { | ||
| 683 | /* both null if a dynamic ASN1_OBJECT, one is | ||
| 684 | * defined if a 'static' ASN1_OBJECT */ | ||
| 685 | char *sn,*ln; | ||
| 686 | int nid; | ||
| 687 | int length; | ||
| 688 | unsigned char *data; | ||
| 689 | } ASN1_OBJECT; | ||
| 690 | This is used to store ASN1 OBJECTS. Read 'objects.doc' for details ono | ||
| 691 | routines to manipulate this structure. 'sn' and 'ln' are used to hold text | ||
| 692 | strings that represent the object (short name and long or lower case name). | ||
| 693 | These are used by the 'OBJ' library. 'nid' is a number used by the OBJ | ||
| 694 | library to uniquely identify objects. The ASN1 routines will populate the | ||
| 695 | 'length' and 'data' fields which will contain the bit string representing | ||
| 696 | the object. | ||
| 697 | |||
| 698 | typedef struct asn1_bit_string_st | ||
| 699 | { | ||
| 700 | int length; | ||
| 701 | int type; | ||
| 702 | unsigned char *data; | ||
| 703 | } ASN1_BIT_STRING; | ||
| 704 | This structure is used to hold all the other base ASN1 types except for | ||
| 705 | ASN1_UTCTIME (which is really just a 'char *'). Length is the number of | ||
| 706 | bytes held in data and type is the ASN1 type of the object (there is a list | ||
| 707 | in asn1.h). | ||
| 708 | |||
| 709 | typedef struct asn1_type_st | ||
| 710 | { | ||
| 711 | int type; | ||
| 712 | union { | ||
| 713 | char *ptr; | ||
| 714 | ASN1_INTEGER * integer; | ||
| 715 | ASN1_BIT_STRING * bit_string; | ||
| 716 | ASN1_OCTET_STRING * octet_string; | ||
| 717 | ASN1_OBJECT * object; | ||
| 718 | ASN1_PRINTABLESTRING * printablestring; | ||
| 719 | ASN1_T61STRING * t61string; | ||
| 720 | ASN1_IA5STRING * ia5string; | ||
| 721 | ASN1_UTCTIME * utctime; | ||
| 722 | ASN1_BIT_STRING * set; | ||
| 723 | ASN1_BIT_STRING * sequence; | ||
| 724 | } value; | ||
| 725 | } ASN1_TYPE; | ||
| 726 | This structure is used in a few places when 'any' type of object can be | ||
| 727 | expected. | ||
| 728 | |||
| 729 | X509 Certificate | ||
| 730 | X509_CINF CertificateInfo | ||
| 731 | X509_ALGOR AlgorithmIdentifier | ||
| 732 | X509_NAME Name | ||
| 733 | X509_NAME_ENTRY A single sub component of the name. | ||
| 734 | X509_VAL Validity | ||
| 735 | X509_PUBKEY SubjectPublicKeyInfo | ||
| 736 | The above mentioned types are declared in x509.h. They are all quite | ||
| 737 | straight forward except for the X509_NAME/X509_NAME_ENTRY pair. | ||
| 738 | A X509_NAME is a STACK (see stack.doc) of X509_NAME_ENTRY's. | ||
| 739 | typedef struct X509_name_entry_st | ||
| 740 | { | ||
| 741 | ASN1_OBJECT *object; | ||
| 742 | ASN1_BIT_STRING *value; | ||
| 743 | int set; | ||
| 744 | int size; /* temp variable */ | ||
| 745 | } X509_NAME_ENTRY; | ||
| 746 | The size is a temporary variable used by i2d_NAME and set is the set number | ||
| 747 | for the particular NAME_ENTRY. A X509_NAME is encoded as a sequence of | ||
| 748 | sequence of sets. Normally each set contains only a single item. | ||
| 749 | Sometimes it contains more. Normally throughout this library there will be | ||
| 750 | only one item per set. The set field contains the 'set' that this entry is | ||
| 751 | a member of. So if you have just created a X509_NAME structure and | ||
| 752 | populated it with X509_NAME_ENTRYs, you should then traverse the X509_NAME | ||
| 753 | (which is just a STACK) and set the 'set/' field to incrementing numbers. | ||
| 754 | For more details on why this is done, read the ASN.1 spec for Distinguished | ||
| 755 | Names. | ||
| 756 | |||
| 757 | X509_REQ CertificateRequest | ||
| 758 | X509_REQ_INFO CertificateRequestInfo | ||
| 759 | These are used to hold certificate requests. | ||
| 760 | |||
| 761 | X509_CRL CertificateRevocationList | ||
| 762 | These are used to hold a certificate revocation list | ||
| 763 | |||
| 764 | RSAPrivateKey PrivateKeyInfo | ||
| 765 | RSAPublicKey PublicKeyInfo | ||
| 766 | Both these 'function groups' operate on 'RSA' structures (see rsa.doc). | ||
| 767 | The difference is that the RSAPublicKey operations only manipulate the m | ||
| 768 | and e fields in the RSA structure. | ||
| 769 | |||
| 770 | DSAPrivateKey DSS private key | ||
| 771 | DSAPublicKey DSS public key | ||
| 772 | Both these 'function groups' operate on 'DSS' structures (see dsa.doc). | ||
| 773 | The difference is that the RSAPublicKey operations only manipulate the | ||
| 774 | XXX fields in the DSA structure. | ||
| 775 | |||
| 776 | DHparams DHParameter | ||
| 777 | This is used to hold the p and g value for The Diffie-Hellman operation. | ||
| 778 | The function deal with the 'DH' strucure (see dh.doc). | ||
| 779 | |||
| 780 | Now all of these function types can be used with several other functions to give | ||
| 781 | quite useful set of general manipulation routines. Normally one would | ||
| 782 | not uses these functions directly but use them via macros. | ||
| 783 | |||
| 784 | char *ASN1_dup(int (*i2d)(),char *(*d2i)(),char *x); | ||
| 785 | 'x' is the input structure case to a 'char *', 'i2d' is the 'i2d_TYPE' | ||
| 786 | function for the type that 'x' is and d2i is the 'd2i_TYPE' function for the | ||
| 787 | type that 'x' is. As is obvious from the parameters, this function | ||
| 788 | duplicates the strucutre by transforming it into the DER form and then | ||
| 789 | re-loading it into a new strucutre and returning the new strucutre. This | ||
| 790 | is obviously a bit cpu intensive but when faced with a complex dynamic | ||
| 791 | structure this is the simplest programming approach. There are macros for | ||
| 792 | duplicating the major data types but is simple to add extras. | ||
| 793 | |||
| 794 | char *ASN1_d2i_fp(char *(*new)(),char *(*d2i)(),FILE *fp,unsigned char **x); | ||
| 795 | 'x' is a pointer to a pointer of the 'desired type'. new and d2i are the | ||
| 796 | corresponding 'TYPE_new' and 'd2i_TYPE' functions for the type and 'fp' is | ||
| 797 | an open file pointer to read from. This function reads from 'fp' as much | ||
| 798 | data as it can and then uses 'd2i' to parse the bytes to load and return | ||
| 799 | the parsed strucutre in 'x' (if it was non-NULL) and to actually return the | ||
| 800 | strucutre. The behavior of 'x' is as per all the other d2i functions. | ||
| 801 | |||
| 802 | char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x); | ||
| 803 | The 'BIO' is the new IO type being used in SSLeay (see bio.doc). This | ||
| 804 | function is the same as ASN1_d2i_fp() except for the BIO argument. | ||
| 805 | ASN1_d2i_fp() actually calls this function. | ||
| 806 | |||
| 807 | int ASN1_i2d_fp(int (*i2d)(),FILE *out,unsigned char *x); | ||
| 808 | 'x' is converted to bytes by 'i2d' and then written to 'out'. ASN1_i2d_fp | ||
| 809 | and ASN1_d2i_fp are not really symetric since ASN1_i2d_fp will read all | ||
| 810 | available data from the file pointer before parsing a single item while | ||
| 811 | ASN1_i2d_fp can be used to write a sequence of data objects. To read a | ||
| 812 | series of objects from a file I would sugest loading the file into a buffer | ||
| 813 | and calling the relevent 'd2i' functions. | ||
| 814 | |||
| 815 | char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x); | ||
| 816 | This function is the same as ASN1_i2d_fp() except for the BIO argument. | ||
| 817 | ASN1_i2d_fp() actually calls this function. | ||
| 818 | |||
| 819 | char * PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)()); | ||
| 820 | This function will read the next PEM encoded (base64) object of the same | ||
| 821 | type as 'x' (loaded by the d2i function). 'name' is the name that is in | ||
| 822 | the '-----BEGIN name-----' that designates the start of that object type. | ||
| 823 | If the data is encrypted, 'cb' will be called to prompt for a password. If | ||
| 824 | it is NULL a default function will be used to prompt from the password. | ||
| 825 | 'x' is delt with as per the standard 'd2i' function interface. This | ||
| 826 | function can be used to read a series of objects from a file. While any | ||
| 827 | data type can be encrypted (see PEM_ASN1_write) only RSA private keys tend | ||
| 828 | to be encrypted. | ||
| 829 | |||
| 830 | char * PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *fp, | ||
| 831 | char **x,int (*cb)()); | ||
| 832 | Same as PEM_ASN1_read() except using a BIO. This is called by | ||
| 833 | PEM_ASN1_read(). | ||
| 834 | |||
| 835 | int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,EVP_CIPHER *enc, | ||
| 836 | unsigned char *kstr,int klen,int (*callback)()); | ||
| 837 | |||
| 838 | int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *fp, | ||
| 839 | char *x,EVP_CIPHER *enc,unsigned char *kstr,int klen, | ||
| 840 | int (*callback)()); | ||
| 841 | |||
| 842 | int ASN1_sign(int (*i2d)(), X509_ALGOR *algor1, X509_ALGOR *algor2, | ||
| 843 | ASN1_BIT_STRING *signature, char *data, RSA *rsa, EVP_MD *type); | ||
| 844 | int ASN1_verify(int (*i2d)(), X509_ALGOR *algor1, | ||
| 845 | ASN1_BIT_STRING *signature,char *data, RSA *rsa); | ||
| 846 | |||
| 847 | int ASN1_BIT_STRING_cmp(ASN1_BIT_STRING *a, ASN1_BIT_STRING *b); | ||
| 848 | ASN1_BIT_STRING *ASN1_BIT_STRING_type_new(int type ); | ||
| 849 | |||
| 850 | int ASN1_UTCTIME_check(ASN1_UTCTIME *a); | ||
| 851 | void ASN1_UTCTIME_print(BIO *fp,ASN1_UTCTIME *a); | ||
| 852 | ASN1_UTCTIME *ASN1_UTCTIME_dup(ASN1_UTCTIME *a); | ||
| 853 | |||
| 854 | ASN1_BIT_STRING *d2i_asn1_print_type(ASN1_BIT_STRING **a,unsigned char **pp, | ||
| 855 | long length,int type); | ||
| 856 | |||
| 857 | int i2d_ASN1_SET(STACK *a, unsigned char **pp, | ||
| 858 | int (*func)(), int ex_tag, int ex_class); | ||
| 859 | STACK * d2i_ASN1_SET(STACK **a, unsigned char **pp, long length, | ||
| 860 | char *(*func)(), int ex_tag, int ex_class); | ||
| 861 | |||
| 862 | int i2a_ASN1_OBJECT(BIO *bp,ASN1_OBJECT *object); | ||
| 863 | int i2a_ASN1_INTEGER(BIO *bp, ASN1_INTEGER *a); | ||
| 864 | int a2i_ASN1_INTEGER(BIO *bp,ASN1_INTEGER *bs,char *buf,int size); | ||
| 865 | |||
| 866 | int ASN1_INTEGER_set(ASN1_INTEGER *a, long v); | ||
| 867 | long ASN1_INTEGER_get(ASN1_INTEGER *a); | ||
| 868 | ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai); | ||
| 869 | BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn); | ||
| 870 | |||
| 871 | /* given a string, return the correct type. Max is the maximum number | ||
| 872 | * of bytes to parse. It stops parsing when 'max' bytes have been | ||
| 873 | * processed or a '\0' is hit */ | ||
| 874 | int ASN1_PRINTABLE_type(unsigned char *s,int max); | ||
| 875 | |||
| 876 | void ASN1_parse(BIO *fp,unsigned char *pp,long len); | ||
| 877 | |||
| 878 | int i2d_ASN1_bytes(ASN1_BIT_STRING *a, unsigned char **pp, int tag, int class); | ||
| 879 | ASN1_BIT_STRING *d2i_ASN1_bytes(ASN1_OCTET_STRING **a, unsigned char **pp, | ||
| 880 | long length, int Ptag, int Pclass); | ||
| 881 | |||
| 882 | /* PARSING */ | ||
| 883 | int asn1_Finish(ASN1_CTX *c); | ||
| 884 | |||
| 885 | /* SPECIALS */ | ||
| 886 | int ASN1_get_object(unsigned char **pp, long *plength, int *ptag, | ||
| 887 | int *pclass, long omax); | ||
| 888 | int ASN1_check_infinite_end(unsigned char **p,long len); | ||
| 889 | void ASN1_put_object(unsigned char **pp, int constructed, int length, | ||
| 890 | int tag, int class); | ||
| 891 | int ASN1_object_size(int constructed, int length, int tag); | ||
| 892 | |||
| 893 | X509 * X509_get_cert(CERTIFICATE_CTX *ctx,X509_NAME * name,X509 *tmp_x509); | ||
| 894 | int X509_add_cert(CERTIFICATE_CTX *ctx,X509 *); | ||
| 895 | |||
| 896 | char * X509_cert_verify_error_string(int n); | ||
| 897 | int X509_add_cert_file(CERTIFICATE_CTX *c,char *file, int type); | ||
| 898 | char * X509_gmtime (char *s, long adj); | ||
| 899 | int X509_add_cert_dir (CERTIFICATE_CTX *c,char *dir, int type); | ||
| 900 | int X509_load_verify_locations (CERTIFICATE_CTX *ctx, | ||
| 901 | char *file_env, char *dir_env); | ||
| 902 | int X509_set_default_verify_paths(CERTIFICATE_CTX *cts); | ||
| 903 | X509 * X509_new_D2i_X509(int len, unsigned char *p); | ||
| 904 | char * X509_get_default_cert_area(void ); | ||
| 905 | char * X509_get_default_cert_dir(void ); | ||
| 906 | char * X509_get_default_cert_file(void ); | ||
| 907 | char * X509_get_default_cert_dir_env(void ); | ||
| 908 | char * X509_get_default_cert_file_env(void ); | ||
| 909 | char * X509_get_default_private_dir(void ); | ||
| 910 | X509_REQ *X509_X509_TO_req(X509 *x, RSA *rsa); | ||
| 911 | int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)()); | ||
| 912 | |||
| 913 | CERTIFICATE_CTX *CERTIFICATE_CTX_new(); | ||
| 914 | void CERTIFICATE_CTX_free(CERTIFICATE_CTX *c); | ||
| 915 | |||
| 916 | void X509_NAME_print(BIO *fp, X509_NAME *name, int obase); | ||
| 917 | int X509_print_fp(FILE *fp,X509 *x); | ||
| 918 | int X509_print(BIO *fp,X509 *x); | ||
| 919 | |||
| 920 | X509_INFO * X509_INFO_new(void); | ||
| 921 | void X509_INFO_free(X509_INFO *a); | ||
| 922 | |||
| 923 | char * X509_NAME_oneline(X509_NAME *a); | ||
| 924 | |||
| 925 | #define X509_verify(x,rsa) | ||
| 926 | #define X509_REQ_verify(x,rsa) | ||
| 927 | #define X509_CRL_verify(x,rsa) | ||
| 928 | |||
| 929 | #define X509_sign(x,rsa,md) | ||
| 930 | #define X509_REQ_sign(x,rsa,md) | ||
| 931 | #define X509_CRL_sign(x,rsa,md) | ||
| 932 | |||
| 933 | #define X509_dup(x509) | ||
| 934 | #define d2i_X509_fp(fp,x509) | ||
| 935 | #define i2d_X509_fp(fp,x509) | ||
| 936 | #define d2i_X509_bio(bp,x509) | ||
| 937 | #define i2d_X509_bio(bp,x509) | ||
| 938 | |||
| 939 | #define X509_CRL_dup(crl) | ||
| 940 | #define d2i_X509_CRL_fp(fp,crl) | ||
| 941 | #define i2d_X509_CRL_fp(fp,crl) | ||
| 942 | #define d2i_X509_CRL_bio(bp,crl) | ||
| 943 | #define i2d_X509_CRL_bio(bp,crl) | ||
| 944 | |||
| 945 | #define X509_REQ_dup(req) | ||
| 946 | #define d2i_X509_REQ_fp(fp,req) | ||
| 947 | #define i2d_X509_REQ_fp(fp,req) | ||
| 948 | #define d2i_X509_REQ_bio(bp,req) | ||
| 949 | #define i2d_X509_REQ_bio(bp,req) | ||
| 950 | |||
| 951 | #define RSAPrivateKey_dup(rsa) | ||
| 952 | #define d2i_RSAPrivateKey_fp(fp,rsa) | ||
| 953 | #define i2d_RSAPrivateKey_fp(fp,rsa) | ||
| 954 | #define d2i_RSAPrivateKey_bio(bp,rsa) | ||
| 955 | #define i2d_RSAPrivateKey_bio(bp,rsa) | ||
| 956 | |||
| 957 | #define X509_NAME_dup(xn) | ||
| 958 | #define X509_NAME_ENTRY_dup(ne) | ||
| 959 | |||
| 960 | void X509_REQ_print_fp(FILE *fp,X509_REQ *req); | ||
| 961 | void X509_REQ_print(BIO *fp,X509_REQ *req); | ||
| 962 | |||
| 963 | RSA *X509_REQ_extract_key(X509_REQ *req); | ||
| 964 | RSA *X509_extract_key(X509 *x509); | ||
| 965 | |||
| 966 | int X509_issuer_and_serial_cmp(X509 *a, X509 *b); | ||
| 967 | unsigned long X509_issuer_and_serial_hash(X509 *a); | ||
| 968 | |||
| 969 | X509_NAME * X509_get_issuer_name(X509 *a); | ||
| 970 | int X509_issuer_name_cmp(X509 *a, X509 *b); | ||
| 971 | unsigned long X509_issuer_name_hash(X509 *a); | ||
| 972 | |||
| 973 | X509_NAME * X509_get_subject_name(X509 *a); | ||
| 974 | int X509_subject_name_cmp(X509 *a,X509 *b); | ||
| 975 | unsigned long X509_subject_name_hash(X509 *x); | ||
| 976 | |||
| 977 | int X509_NAME_cmp (X509_NAME *a, X509_NAME *b); | ||
| 978 | unsigned long X509_NAME_hash(X509_NAME *x); | ||
| 979 | |||
| 980 | |||
| 981 | ==== bio.doc ======================================================== | ||
| 982 | |||
| 983 | BIO Routines | ||
| 984 | |||
| 985 | This documentation is rather sparse, you are probably best | ||
| 986 | off looking at the code for specific details. | ||
| 987 | |||
| 988 | The BIO library is a IO abstraction that was originally | ||
| 989 | inspired by the need to have callbacks to perform IO to FILE | ||
| 990 | pointers when using Windows 3.1 DLLs. There are two types | ||
| 991 | of BIO; a source/sink type and a filter type. | ||
| 992 | The source/sink methods are as follows: | ||
| 993 | - BIO_s_mem() memory buffer - a read/write byte array that | ||
| 994 | grows until memory runs out :-). | ||
| 995 | - BIO_s_file() FILE pointer - A wrapper around the normal | ||
| 996 | 'FILE *' commands, good for use with stdin/stdout. | ||
| 997 | - BIO_s_fd() File descriptor - A wrapper around file | ||
| 998 | descriptors, often used with pipes. | ||
| 999 | - BIO_s_socket() Socket - Used around sockets. It is | ||
| 1000 | mostly in the Microsoft world that sockets are different | ||
| 1001 | from file descriptors and there are all those ugly winsock | ||
| 1002 | commands. | ||
| 1003 | - BIO_s_null() Null - read nothing and write nothing.; a | ||
| 1004 | useful endpoint for filter type BIO's specifically things | ||
| 1005 | like the message digest BIO. | ||
| 1006 | |||
| 1007 | The filter types are | ||
| 1008 | - BIO_f_buffer() IO buffering - does output buffering into | ||
| 1009 | larger chunks and performs input buffering to allow gets() | ||
| 1010 | type functions. | ||
| 1011 | - BIO_f_md() Message digest - a transparent filter that can | ||
| 1012 | be asked to return a message digest for the data that has | ||
| 1013 | passed through it. | ||
| 1014 | - BIO_f_cipher() Encrypt or decrypt all data passing | ||
| 1015 | through the filter. | ||
| 1016 | - BIO_f_base64() Base64 decode on read and encode on write. | ||
| 1017 | - BIO_f_ssl() A filter that performs SSL encryption on the | ||
| 1018 | data sent through it. | ||
| 1019 | |||
| 1020 | Base BIO functions. | ||
| 1021 | The BIO library has a set of base functions that are | ||
| 1022 | implemented for each particular type. Filter BIOs will | ||
| 1023 | normally call the equivalent function on the source/sink BIO | ||
| 1024 | that they are layered on top of after they have performed | ||
| 1025 | some modification to the data stream. Multiple filter BIOs | ||
| 1026 | can be 'push' into a stack of modifers, so to read from a | ||
| 1027 | file, unbase64 it, then decrypt it, a BIO_f_cipher, | ||
| 1028 | BIO_f_base64 and a BIO_s_file would probably be used. If a | ||
| 1029 | sha-1 and md5 message digest needed to be generated, a stack | ||
| 1030 | two BIO_f_md() BIOs and a BIO_s_null() BIO could be used. | ||
| 1031 | The base functions are | ||
| 1032 | - BIO *BIO_new(BIO_METHOD *type); Create a new BIO of type 'type'. | ||
| 1033 | - int BIO_free(BIO *a); Free a BIO structure. Depending on | ||
| 1034 | the configuration, this will free the underlying data | ||
| 1035 | object for a source/sink BIO. | ||
| 1036 | - int BIO_read(BIO *b, char *data, int len); Read upto 'len' | ||
| 1037 | bytes into 'data'. | ||
| 1038 | - int BIO_gets(BIO *bp,char *buf, int size); Depending on | ||
| 1039 | the BIO, this can either be a 'get special' or a get one | ||
| 1040 | line of data, as per fgets(); | ||
| 1041 | - int BIO_write(BIO *b, char *data, int len); Write 'len' | ||
| 1042 | bytes from 'data' to the 'b' BIO. | ||
| 1043 | - int BIO_puts(BIO *bp,char *buf); Either a 'put special' or | ||
| 1044 | a write null terminated string as per fputs(). | ||
| 1045 | - long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg); A | ||
| 1046 | control function which is used to manipulate the BIO | ||
| 1047 | structure and modify it's state and or report on it. This | ||
| 1048 | function is just about never used directly, rather it | ||
| 1049 | should be used in conjunction with BIO_METHOD specific | ||
| 1050 | macros. | ||
| 1051 | - BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the | ||
| 1052 | top of the 'old' BIO list. new_top should be a filter BIO. | ||
| 1053 | All writes will go through 'new_top' first and last on read. | ||
| 1054 | 'old' is returned. | ||
| 1055 | - BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if | ||
| 1056 | there are no more. | ||
| 1057 | |||
| 1058 | If a particular low level BIO method is not supported | ||
| 1059 | (normally BIO_gets()), -2 will be returned if that method is | ||
| 1060 | called. Otherwise the IO methods (read, write, gets, puts) | ||
| 1061 | will return the number of bytes read or written, and 0 or -1 | ||
| 1062 | for error (or end of input). For the -1 case, | ||
| 1063 | BIO_should_retry(bio) can be called to determine if it was a | ||
| 1064 | genuine error or a temporary problem. -2 will also be | ||
| 1065 | returned if the BIO has not been initalised yet, in all | ||
| 1066 | cases, the correct error codes are set (accessible via the | ||
| 1067 | ERR library). | ||
| 1068 | |||
| 1069 | |||
| 1070 | The following functions are convenience functions: | ||
| 1071 | - int BIO_printf(BIO *bio, char * format, ..); printf but | ||
| 1072 | to a BIO handle. | ||
| 1073 | - long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a | ||
| 1074 | convenience function to allow a different argument types | ||
| 1075 | to be passed to BIO_ctrl(). | ||
| 1076 | - int BIO_dump(BIO *b,char *bytes,int len); output 'len' | ||
| 1077 | bytes from 'bytes' in a hex dump debug format. | ||
| 1078 | - long BIO_debug_callback(BIO *bio, int cmd, char *argp, int | ||
| 1079 | argi, long argl, long ret) - a default debug BIO callback, | ||
| 1080 | this is mentioned below. To use this one normally has to | ||
| 1081 | use the BIO_set_callback_arg() function to assign an | ||
| 1082 | output BIO for the callback to use. | ||
| 1083 | - BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack' | ||
| 1084 | of BIOs, this function scan the list and returns the first | ||
| 1085 | that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX. | ||
| 1086 | - void BIO_free_all(BIO *bio); Free the bio and all other BIOs | ||
| 1087 | in the list. It walks the bio->next_bio list. | ||
| 1088 | |||
| 1089 | |||
| 1090 | |||
| 1091 | Extra commands are normally implemented as macros calling BIO_ctrl(). | ||
| 1092 | - BIO_number_read(BIO *bio) - the number of bytes processed | ||
| 1093 | by BIO_read(bio,.). | ||
| 1094 | - BIO_number_written(BIO *bio) - the number of bytes written | ||
| 1095 | by BIO_write(bio,.). | ||
| 1096 | - BIO_reset(BIO *bio) - 'reset' the BIO. | ||
| 1097 | - BIO_eof(BIO *bio) - non zero if we are at the current end | ||
| 1098 | of input. | ||
| 1099 | - BIO_set_close(BIO *bio, int close_flag) - set the close flag. | ||
| 1100 | - BIO_get_close(BIO *bio) - return the close flag. | ||
| 1101 | BIO_pending(BIO *bio) - return the number of bytes waiting | ||
| 1102 | to be read (normally buffered internally). | ||
| 1103 | - BIO_flush(BIO *bio) - output any data waiting to be output. | ||
| 1104 | - BIO_should_retry(BIO *io) - after a BIO_read/BIO_write | ||
| 1105 | operation returns 0 or -1, a call to this function will | ||
| 1106 | return non zero if you should retry the call later (this | ||
| 1107 | is for non-blocking IO). | ||
| 1108 | - BIO_should_read(BIO *io) - we should retry when data can | ||
| 1109 | be read. | ||
| 1110 | - BIO_should_write(BIO *io) - we should retry when data can | ||
| 1111 | be written. | ||
| 1112 | - BIO_method_name(BIO *io) - return a string for the method name. | ||
| 1113 | - BIO_method_type(BIO *io) - return the unique ID of the BIO method. | ||
| 1114 | - BIO_set_callback(BIO *io, long (*callback)(BIO *io, int | ||
| 1115 | cmd, char *argp, int argi, long argl, long ret); - sets | ||
| 1116 | the debug callback. | ||
| 1117 | - BIO_get_callback(BIO *io) - return the assigned function | ||
| 1118 | as mentioned above. | ||
| 1119 | - BIO_set_callback_arg(BIO *io, char *arg) - assign some | ||
| 1120 | data against the BIO. This is normally used by the debug | ||
| 1121 | callback but could in reality be used for anything. To | ||
| 1122 | get an idea of how all this works, have a look at the code | ||
| 1123 | in the default debug callback mentioned above. The | ||
| 1124 | callback can modify the return values. | ||
| 1125 | |||
| 1126 | Details of the BIO_METHOD structure. | ||
| 1127 | typedef struct bio_method_st | ||
| 1128 | { | ||
| 1129 | int type; | ||
| 1130 | char *name; | ||
| 1131 | int (*bwrite)(); | ||
| 1132 | int (*bread)(); | ||
| 1133 | int (*bputs)(); | ||
| 1134 | int (*bgets)(); | ||
| 1135 | long (*ctrl)(); | ||
| 1136 | int (*create)(); | ||
| 1137 | int (*destroy)(); | ||
| 1138 | } BIO_METHOD; | ||
| 1139 | |||
| 1140 | The 'type' is the numeric type of the BIO, these are listed in buffer.h; | ||
| 1141 | 'Name' is a textual representation of the BIO 'type'. | ||
| 1142 | The 7 function pointers point to the respective function | ||
| 1143 | methods, some of which can be NULL if not implemented. | ||
| 1144 | The BIO structure | ||
| 1145 | typedef struct bio_st | ||
| 1146 | { | ||
| 1147 | BIO_METHOD *method; | ||
| 1148 | long (*callback)(BIO * bio, int mode, char *argp, int | ||
| 1149 | argi, long argl, long ret); | ||
| 1150 | char *cb_arg; /* first argument for the callback */ | ||
| 1151 | int init; | ||
| 1152 | int shutdown; | ||
| 1153 | int flags; /* extra storage */ | ||
| 1154 | int num; | ||
| 1155 | char *ptr; | ||
| 1156 | struct bio_st *next_bio; /* used by filter BIOs */ | ||
| 1157 | int references; | ||
| 1158 | unsigned long num_read; | ||
| 1159 | unsigned long num_write; | ||
| 1160 | } BIO; | ||
| 1161 | |||
| 1162 | - 'Method' is the BIO method. | ||
| 1163 | - 'callback', when configured, is called before and after | ||
| 1164 | each BIO method is called for that particular BIO. This | ||
| 1165 | is intended primarily for debugging and of informational feedback. | ||
| 1166 | - 'init' is 0 when the BIO can be used for operation. | ||
| 1167 | Often, after a BIO is created, a number of operations may | ||
| 1168 | need to be performed before it is available for use. An | ||
| 1169 | example is for BIO_s_sock(). A socket needs to be | ||
| 1170 | assigned to the BIO before it can be used. | ||
| 1171 | - 'shutdown', this flag indicates if the underlying | ||
| 1172 | comunication primative being used should be closed/freed | ||
| 1173 | when the BIO is closed. | ||
| 1174 | - 'flags' is used to hold extra state. It is primarily used | ||
| 1175 | to hold information about why a non-blocking operation | ||
| 1176 | failed and to record startup protocol information for the | ||
| 1177 | SSL BIO. | ||
| 1178 | - 'num' and 'ptr' are used to hold instance specific state | ||
| 1179 | like file descriptors or local data structures. | ||
| 1180 | - 'next_bio' is used by filter BIOs to hold the pointer of the | ||
| 1181 | next BIO in the chain. written data is sent to this BIO and | ||
| 1182 | data read is taken from it. | ||
| 1183 | - 'references' is used to indicate the number of pointers to | ||
| 1184 | this structure. This needs to be '1' before a call to | ||
| 1185 | BIO_free() is made if the BIO_free() function is to | ||
| 1186 | actually free() the structure, otherwise the reference | ||
| 1187 | count is just decreased. The actual BIO subsystem does | ||
| 1188 | not really use this functionality but it is useful when | ||
| 1189 | used in more advanced applicaion. | ||
| 1190 | - num_read and num_write are the total number of bytes | ||
| 1191 | read/written via the 'read()' and 'write()' methods. | ||
| 1192 | |||
| 1193 | BIO_ctrl operations. | ||
| 1194 | The following is the list of standard commands passed as the | ||
| 1195 | second parameter to BIO_ctrl() and should be supported by | ||
| 1196 | all BIO as best as possible. Some are optional, some are | ||
| 1197 | manditory, in any case, where is makes sense, a filter BIO | ||
| 1198 | should pass such requests to underlying BIO's. | ||
| 1199 | - BIO_CTRL_RESET - Reset the BIO back to an initial state. | ||
| 1200 | - BIO_CTRL_EOF - return 0 if we are not at the end of input, | ||
| 1201 | non 0 if we are. | ||
| 1202 | - BIO_CTRL_INFO - BIO specific special command, normal | ||
| 1203 | information return. | ||
| 1204 | - BIO_CTRL_SET - set IO specific parameter. | ||
| 1205 | - BIO_CTRL_GET - get IO specific parameter. | ||
| 1206 | - BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one | ||
| 1207 | of BIO_CLOSE or BIO_NOCLOSE. | ||
| 1208 | - BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag. | ||
| 1209 | - BIO_CTRL_PENDING - Return the number of bytes available | ||
| 1210 | for instant reading | ||
| 1211 | - BIO_CTRL_FLUSH - Output pending data, return number of bytes output. | ||
| 1212 | - BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned) | ||
| 1213 | should we 'retry' when IO is possible on the underlying IO object. | ||
| 1214 | - BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on. | ||
| 1215 | |||
| 1216 | The following command is a special BIO_s_file() specific option. | ||
| 1217 | - BIO_CTRL_SET_FILENAME - specify a file to open for IO. | ||
| 1218 | |||
| 1219 | The BIO_CTRL_RETRY_TYPE needs a little more explanation. | ||
| 1220 | When performing non-blocking IO, or say reading on a memory | ||
| 1221 | BIO, when no data is present (or cannot be written), | ||
| 1222 | BIO_read() and/or BIO_write() will return -1. | ||
| 1223 | BIO_should_retry(bio) will return true if this is due to an | ||
| 1224 | IO condition rather than an actual error. In the case of | ||
| 1225 | BIO_s_mem(), a read when there is no data will return -1 and | ||
| 1226 | a should retry when there is more 'read' data. | ||
| 1227 | The retry type is deduced from 2 macros | ||
| 1228 | BIO_should_read(bio) and BIO_should_write(bio). | ||
| 1229 | Now while it may appear obvious that a BIO_read() failure | ||
| 1230 | should indicate that a retry should be performed when more | ||
| 1231 | read data is available, this is often not true when using | ||
| 1232 | things like an SSL BIO. During the SSL protocol startup | ||
| 1233 | multiple reads and writes are performed, triggered by any | ||
| 1234 | SSL_read or SSL_write. | ||
| 1235 | So to write code that will transparently handle either a | ||
| 1236 | socket or SSL BIO, | ||
| 1237 | i=BIO_read(bio,..) | ||
| 1238 | if (I == -1) | ||
| 1239 | { | ||
| 1240 | if (BIO_should_retry(bio)) | ||
| 1241 | { | ||
| 1242 | if (BIO_should_read(bio)) | ||
| 1243 | { | ||
| 1244 | /* call us again when BIO can be read */ | ||
| 1245 | } | ||
| 1246 | if (BIO_should_write(bio)) | ||
| 1247 | { | ||
| 1248 | /* call us again when BIO can be written */ | ||
| 1249 | } | ||
| 1250 | } | ||
| 1251 | } | ||
| 1252 | |||
| 1253 | At this point in time only read and write conditions can be | ||
| 1254 | used but in the future I can see the situation for other | ||
| 1255 | conditions, specifically with SSL there could be a condition | ||
| 1256 | of a X509 certificate lookup taking place and so the non- | ||
| 1257 | blocking BIO_read would require a retry when the certificate | ||
| 1258 | lookup subsystem has finished it's lookup. This is all | ||
| 1259 | makes more sense and is easy to use in a event loop type | ||
| 1260 | setup. | ||
| 1261 | When using the SSL BIO, either SSL_read() or SSL_write()s | ||
| 1262 | can be called during the protocol startup and things will | ||
| 1263 | still work correctly. | ||
| 1264 | The nice aspect of the use of the BIO_should_retry() macro | ||
| 1265 | is that all the errno codes that indicate a non-fatal error | ||
| 1266 | are encapsulated in one place. The Windows specific error | ||
| 1267 | codes and WSAGetLastError() calls are also hidden from the | ||
| 1268 | application. | ||
| 1269 | |||
| 1270 | Notes on each BIO method. | ||
| 1271 | Normally buffer.h is just required but depending on the | ||
| 1272 | BIO_METHOD, ssl.h or evp.h will also be required. | ||
| 1273 | |||
| 1274 | BIO_METHOD *BIO_s_mem(void); | ||
| 1275 | - BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) - | ||
| 1276 | set the underlying BUF_MEM structure for the BIO to use. | ||
| 1277 | - BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL, | ||
| 1278 | set it to point to the memory array and return the number | ||
| 1279 | of bytes available. | ||
| 1280 | A read/write BIO. Any data written is appended to the | ||
| 1281 | memory array and any read is read from the front. This BIO | ||
| 1282 | can be used for read/write at the same time. BIO_gets() is | ||
| 1283 | supported in the fgets() sense. | ||
| 1284 | BIO_CTRL_INFO can be used to retrieve pointers to the memory | ||
| 1285 | buffer and it's length. | ||
| 1286 | |||
| 1287 | BIO_METHOD *BIO_s_file(void); | ||
| 1288 | - BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use. | ||
| 1289 | - BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use. | ||
| 1290 | - BIO_read_filename(BIO *bio, char *name) - read from file. | ||
| 1291 | - BIO_write_filename(BIO *bio, char *name) - write to file. | ||
| 1292 | - BIO_append_filename(BIO *bio, char *name) - append to file. | ||
| 1293 | This BIO sits over the normal system fread()/fgets() type | ||
| 1294 | functions. Gets() is supported. This BIO in theory could be | ||
| 1295 | used for read and write but it is best to think of each BIO | ||
| 1296 | of this type as either a read or a write BIO, not both. | ||
| 1297 | |||
| 1298 | BIO_METHOD *BIO_s_socket(void); | ||
| 1299 | BIO_METHOD *BIO_s_fd(void); | ||
| 1300 | - BIO_sock_should_retry(int i) - the underlying function | ||
| 1301 | used to determine if a call should be retried; the | ||
| 1302 | argument is the '0' or '-1' returned by the previous BIO | ||
| 1303 | operation. | ||
| 1304 | - BIO_fd_should_retry(int i) - same as the | ||
| 1305 | - BIO_sock_should_retry() except that it is different internally. | ||
| 1306 | - BIO_set_fd(BIO *bio, int fd, int close_flag) - set the | ||
| 1307 | file descriptor to use | ||
| 1308 | - BIO_get_fd(BIO *bio, int *fd) - get the file descriptor. | ||
| 1309 | These two methods are very similar. Gets() is not | ||
| 1310 | supported, if you want this functionality, put a | ||
| 1311 | BIO_f_buffer() onto it. This BIO is bi-directional if the | ||
| 1312 | underlying file descriptor is. This is normally the case | ||
| 1313 | for sockets but not the case for stdio descriptors. | ||
| 1314 | |||
| 1315 | BIO_METHOD *BIO_s_null(void); | ||
| 1316 | Read and write as much data as you like, it all disappears | ||
| 1317 | into this BIO. | ||
| 1318 | |||
| 1319 | BIO_METHOD *BIO_f_buffer(void); | ||
| 1320 | - BIO_get_buffer_num_lines(BIO *bio) - return the number of | ||
| 1321 | complete lines in the buffer. | ||
| 1322 | - BIO_set_buffer_size(BIO *bio, long size) - set the size of | ||
| 1323 | the buffers. | ||
| 1324 | This type performs input and output buffering. It performs | ||
| 1325 | both at the same time. The size of the buffer can be set | ||
| 1326 | via the set buffer size option. Data buffered for output is | ||
| 1327 | only written when the buffer fills. | ||
| 1328 | |||
| 1329 | BIO_METHOD *BIO_f_ssl(void); | ||
| 1330 | - BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL | ||
| 1331 | structure to use. | ||
| 1332 | - BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure | ||
| 1333 | in use. | ||
| 1334 | The SSL bio is a little different from normal BIOs because | ||
| 1335 | the underlying SSL structure is a little different. A SSL | ||
| 1336 | structure performs IO via a read and write BIO. These can | ||
| 1337 | be different and are normally set via the | ||
| 1338 | SSL_set_rbio()/SSL_set_wbio() calls. The SSL_set_fd() calls | ||
| 1339 | are just wrappers that create socket BIOs and then call | ||
| 1340 | SSL_set_bio() where the read and write BIOs are the same. | ||
| 1341 | The BIO_push() operation makes the SSLs IO BIOs the same, so | ||
| 1342 | make sure the BIO pushed is capable of two directional | ||
| 1343 | traffic. If it is not, you will have to install the BIOs | ||
| 1344 | via the more conventional SSL_set_bio() call. BIO_pop() will retrieve | ||
| 1345 | the 'SSL read' BIO. | ||
| 1346 | |||
| 1347 | BIO_METHOD *BIO_f_md(void); | ||
| 1348 | - BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest | ||
| 1349 | to use. | ||
| 1350 | - BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest | ||
| 1351 | method in use in mdp, return 0 if not set yet. | ||
| 1352 | - BIO_reset() reinitializes the digest (EVP_DigestInit()) | ||
| 1353 | and passes the reset to the underlying BIOs. | ||
| 1354 | All data read or written via BIO_read() or BIO_write() to | ||
| 1355 | this BIO will be added to the calculated digest. This | ||
| 1356 | implies that this BIO is only one directional. If read and | ||
| 1357 | write operations are performed, two separate BIO_f_md() BIOs | ||
| 1358 | are reuqired to generate digests on both the input and the | ||
| 1359 | output. BIO_gets(BIO *bio, char *md, int size) will place the | ||
| 1360 | generated digest into 'md' and return the number of bytes. | ||
| 1361 | The EVP_MAX_MD_SIZE should probably be used to size the 'md' | ||
| 1362 | array. Reading the digest will also reset it. | ||
| 1363 | |||
| 1364 | BIO_METHOD *BIO_f_cipher(void); | ||
| 1365 | - BIO_reset() reinitializes the cipher. | ||
| 1366 | - BIO_flush() should be called when the last bytes have been | ||
| 1367 | output to flush the final block of block ciphers. | ||
| 1368 | - BIO_get_cipher_status(BIO *b), when called after the last | ||
| 1369 | read from a cipher BIO, returns non-zero if the data | ||
| 1370 | decrypted correctly, otherwise, 0. | ||
| 1371 | - BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key, | ||
| 1372 | unsigned char *iv, int encrypt) This function is used to | ||
| 1373 | setup a cipher BIO. The length of key and iv are | ||
| 1374 | specified by the choice of EVP_CIPHER. Encrypt is 1 to | ||
| 1375 | encrypt and 0 to decrypt. | ||
| 1376 | |||
| 1377 | BIO_METHOD *BIO_f_base64(void); | ||
| 1378 | - BIO_flush() should be called when the last bytes have been output. | ||
| 1379 | This BIO base64 encodes when writing and base64 decodes when | ||
| 1380 | reading. It will scan the input until a suitable begin line | ||
| 1381 | is found. After reading data, BIO_reset() will reset the | ||
| 1382 | BIO to start scanning again. Do not mix reading and writing | ||
| 1383 | on the same base64 BIO. It is meant as a single stream BIO. | ||
| 1384 | |||
| 1385 | Directions type | ||
| 1386 | both BIO_s_mem() | ||
| 1387 | one/both BIO_s_file() | ||
| 1388 | both BIO_s_fd() | ||
| 1389 | both BIO_s_socket() | ||
| 1390 | both BIO_s_null() | ||
| 1391 | both BIO_f_buffer() | ||
| 1392 | one BIO_f_md() | ||
| 1393 | one BIO_f_cipher() | ||
| 1394 | one BIO_f_base64() | ||
| 1395 | both BIO_f_ssl() | ||
| 1396 | |||
| 1397 | It is easy to mix one and two directional BIOs, all one has | ||
| 1398 | to do is to keep two separate BIO pointers for reading and | ||
| 1399 | writing and be careful about usage of underlying BIOs. The | ||
| 1400 | SSL bio by it's very nature has to be two directional but | ||
| 1401 | the BIO_push() command will push the one BIO into the SSL | ||
| 1402 | BIO for both reading and writing. | ||
| 1403 | |||
| 1404 | The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c. | ||
| 1405 | |||
| 1406 | |||
| 1407 | ==== blowfish.doc ======================================================== | ||
| 1408 | |||
| 1409 | The Blowfish library. | ||
| 1410 | |||
| 1411 | Blowfish is a block cipher that operates on 64bit (8 byte) quantities. It | ||
| 1412 | uses variable size key, but 128bit (16 byte) key would normally be considered | ||
| 1413 | good. It can be used in all the modes that DES can be used. This | ||
| 1414 | library implements the ecb, cbc, cfb64, ofb64 modes. | ||
| 1415 | |||
| 1416 | Blowfish is quite a bit faster that DES, and much faster than IDEA or | ||
| 1417 | RC2. It is one of the faster block ciphers. | ||
| 1418 | |||
| 1419 | For all calls that have an 'input' and 'output' variables, they can be the | ||
| 1420 | same. | ||
| 1421 | |||
| 1422 | This library requires the inclusion of 'blowfish.h'. | ||
| 1423 | |||
| 1424 | All of the encryption functions take what is called an BF_KEY as an | ||
| 1425 | argument. An BF_KEY is an expanded form of the Blowfish key. | ||
| 1426 | For all modes of the Blowfish algorithm, the BF_KEY used for | ||
| 1427 | decryption is the same one that was used for encryption. | ||
| 1428 | |||
| 1429 | The define BF_ENCRYPT is passed to specify encryption for the functions | ||
| 1430 | that require an encryption/decryption flag. BF_DECRYPT is passed to | ||
| 1431 | specify decryption. | ||
| 1432 | |||
| 1433 | Please note that any of the encryption modes specified in my DES library | ||
| 1434 | could be used with Blowfish. I have only implemented ecb, cbc, cfb64 and | ||
| 1435 | ofb64 for the following reasons. | ||
| 1436 | - ecb is the basic Blowfish encryption. | ||
| 1437 | - cbc is the normal 'chaining' form for block ciphers. | ||
| 1438 | - cfb64 can be used to encrypt single characters, therefore input and output | ||
| 1439 | do not need to be a multiple of 8. | ||
| 1440 | - ofb64 is similar to cfb64 but is more like a stream cipher, not as | ||
| 1441 | secure (not cipher feedback) but it does not have an encrypt/decrypt mode. | ||
| 1442 | - If you want triple Blowfish, thats 384 bits of key and you must be totally | ||
| 1443 | obsessed with security. Still, if you want it, it is simple enough to | ||
| 1444 | copy the function from the DES library and change the des_encrypt to | ||
| 1445 | BF_encrypt; an exercise left for the paranoid reader :-). | ||
| 1446 | |||
| 1447 | The functions are as follows: | ||
| 1448 | |||
| 1449 | void BF_set_key( | ||
| 1450 | BF_KEY *ks; | ||
| 1451 | int len; | ||
| 1452 | unsigned char *key; | ||
| 1453 | BF_set_key converts an 'len' byte key into a BF_KEY. | ||
| 1454 | A 'ks' is an expanded form of the 'key' which is used to | ||
| 1455 | perform actual encryption. It can be regenerated from the Blowfish key | ||
| 1456 | so it only needs to be kept when encryption or decryption is about | ||
| 1457 | to occur. Don't save or pass around BF_KEY's since they | ||
| 1458 | are CPU architecture dependent, 'key's are not. Blowfish is an | ||
| 1459 | interesting cipher in that it can be used with a variable length | ||
| 1460 | key. 'len' is the length of 'key' to be used as the key. | ||
| 1461 | A 'len' of 16 is recomended by me, but blowfish can use upto | ||
| 1462 | 72 bytes. As a warning, blowfish has a very very slow set_key | ||
| 1463 | function, it actually runs BF_encrypt 521 times. | ||
| 1464 | |||
| 1465 | void BF_encrypt(unsigned long *data, BF_KEY *key); | ||
| 1466 | void BF_decrypt(unsigned long *data, BF_KEY *key); | ||
| 1467 | These are the Blowfish encryption function that gets called by just | ||
| 1468 | about every other Blowfish routine in the library. You should not | ||
| 1469 | use this function except to implement 'modes' of Blowfish. | ||
| 1470 | I say this because the | ||
| 1471 | functions that call this routine do the conversion from 'char *' to | ||
| 1472 | long, and this needs to be done to make sure 'non-aligned' memory | ||
| 1473 | access do not occur. | ||
| 1474 | Data is a pointer to 2 unsigned long's and key is the | ||
| 1475 | BF_KEY to use. | ||
| 1476 | |||
| 1477 | void BF_ecb_encrypt( | ||
| 1478 | unsigned char *in, | ||
| 1479 | unsigned char *out, | ||
| 1480 | BF_KEY *key, | ||
| 1481 | int encrypt); | ||
| 1482 | This is the basic Electronic Code Book form of Blowfish (in DES this | ||
| 1483 | mode is called Electronic Code Book so I'm going to use the term | ||
| 1484 | for blowfish as well. | ||
| 1485 | Input is encrypted into output using the key represented by | ||
| 1486 | key. Depending on the encrypt, encryption or | ||
| 1487 | decryption occurs. Input is 8 bytes long and output is 8 bytes. | ||
| 1488 | |||
| 1489 | void BF_cbc_encrypt( | ||
| 1490 | unsigned char *in, | ||
| 1491 | unsigned char *out, | ||
| 1492 | long length, | ||
| 1493 | BF_KEY *ks, | ||
| 1494 | unsigned char *ivec, | ||
| 1495 | int encrypt); | ||
| 1496 | This routine implements Blowfish in Cipher Block Chaining mode. | ||
| 1497 | Input, which should be a multiple of 8 bytes is encrypted | ||
| 1498 | (or decrypted) to output which will also be a multiple of 8 bytes. | ||
| 1499 | The number of bytes is in length (and from what I've said above, | ||
| 1500 | should be a multiple of 8). If length is not a multiple of 8, bad | ||
| 1501 | things will probably happen. ivec is the initialisation vector. | ||
| 1502 | This function updates iv after each call so that it can be passed to | ||
| 1503 | the next call to BF_cbc_encrypt(). | ||
| 1504 | |||
| 1505 | void BF_cfb64_encrypt( | ||
| 1506 | unsigned char *in, | ||
| 1507 | unsigned char *out, | ||
| 1508 | long length, | ||
| 1509 | BF_KEY *schedule, | ||
| 1510 | unsigned char *ivec, | ||
| 1511 | int *num, | ||
| 1512 | int encrypt); | ||
| 1513 | This is one of the more useful functions in this Blowfish library, it | ||
| 1514 | implements CFB mode of Blowfish with 64bit feedback. | ||
| 1515 | This allows you to encrypt an arbitrary number of bytes, | ||
| 1516 | you do not require 8 byte padding. Each call to this | ||
| 1517 | routine will encrypt the input bytes to output and then update ivec | ||
| 1518 | and num. Num contains 'how far' we are though ivec. | ||
| 1519 | 'Encrypt' is used to indicate encryption or decryption. | ||
| 1520 | CFB64 mode operates by using the cipher to generate a stream | ||
| 1521 | of bytes which is used to encrypt the plain text. | ||
| 1522 | The cipher text is then encrypted to generate the next 64 bits to | ||
| 1523 | be xored (incrementally) with the next 64 bits of plain | ||
| 1524 | text. As can be seen from this, to encrypt or decrypt, | ||
| 1525 | the same 'cipher stream' needs to be generated but the way the next | ||
| 1526 | block of data is gathered for encryption is different for | ||
| 1527 | encryption and decryption. | ||
| 1528 | |||
| 1529 | void BF_ofb64_encrypt( | ||
| 1530 | unsigned char *in, | ||
| 1531 | unsigned char *out, | ||
| 1532 | long length, | ||
| 1533 | BF_KEY *schedule, | ||
| 1534 | unsigned char *ivec, | ||
| 1535 | int *num); | ||
| 1536 | This functions implements OFB mode of Blowfish with 64bit feedback. | ||
| 1537 | This allows you to encrypt an arbitrary number of bytes, | ||
| 1538 | you do not require 8 byte padding. Each call to this | ||
| 1539 | routine will encrypt the input bytes to output and then update ivec | ||
| 1540 | and num. Num contains 'how far' we are though ivec. | ||
| 1541 | This is in effect a stream cipher, there is no encryption or | ||
| 1542 | decryption mode. | ||
| 1543 | |||
| 1544 | For reading passwords, I suggest using des_read_pw_string() from my DES library. | ||
| 1545 | To generate a password from a text string, I suggest using MD5 (or MD2) to | ||
| 1546 | produce a 16 byte message digest that can then be passed directly to | ||
| 1547 | BF_set_key(). | ||
| 1548 | |||
| 1549 | ===== | ||
| 1550 | For more information about the specific Blowfish modes in this library | ||
| 1551 | (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the | ||
| 1552 | documentation on my DES library. What is said about DES is directly | ||
| 1553 | applicable for Blowfish. | ||
| 1554 | |||
| 1555 | |||
| 1556 | ==== bn.doc ======================================================== | ||
| 1557 | |||
| 1558 | The Big Number library. | ||
| 1559 | |||
| 1560 | #include "bn.h" when using this library. | ||
| 1561 | |||
| 1562 | This big number library was written for use in implementing the RSA and DH | ||
| 1563 | public key encryption algorithms. As such, features such as negative | ||
| 1564 | numbers have not been extensively tested but they should work as expected. | ||
| 1565 | This library uses dynamic memory allocation for storing its data structures | ||
| 1566 | and so there are no limit on the size of the numbers manipulated by these | ||
| 1567 | routines but there is always the requirement to check return codes from | ||
| 1568 | functions just in case a memory allocation error has occurred. | ||
| 1569 | |||
| 1570 | The basic object in this library is a BIGNUM. It is used to hold a single | ||
| 1571 | large integer. This type should be considered opaque and fields should not | ||
| 1572 | be modified or accessed directly. | ||
| 1573 | typedef struct bignum_st | ||
| 1574 | { | ||
| 1575 | int top; /* Index of last used d. */ | ||
| 1576 | BN_ULONG *d; /* Pointer to an array of 'BITS2' bit chunks. */ | ||
| 1577 | int max; /* Size of the d array. */ | ||
| 1578 | int neg; | ||
| 1579 | } BIGNUM; | ||
| 1580 | The big number is stored in a malloced array of BN_ULONG's. A BN_ULONG can | ||
| 1581 | be either 16, 32 or 64 bits in size, depending on the 'number of bits' | ||
| 1582 | specified in bn.h. | ||
| 1583 | The 'd' field is this array. 'max' is the size of the 'd' array that has | ||
| 1584 | been allocated. 'top' is the 'last' entry being used, so for a value of 4, | ||
| 1585 | bn.d[0]=4 and bn.top=1. 'neg' is 1 if the number is negative. | ||
| 1586 | When a BIGNUM is '0', the 'd' field can be NULL and top == 0. | ||
| 1587 | |||
| 1588 | Various routines in this library require the use of 'temporary' BIGNUM | ||
| 1589 | variables during their execution. Due to the use of dynamic memory | ||
| 1590 | allocation to create BIGNUMs being rather expensive when used in | ||
| 1591 | conjunction with repeated subroutine calls, the BN_CTX structure is | ||
| 1592 | used. This structure contains BN_CTX BIGNUMs. BN_CTX | ||
| 1593 | is the maximum number of temporary BIGNUMs any publicly exported | ||
| 1594 | function will use. | ||
| 1595 | |||
| 1596 | #define BN_CTX 12 | ||
| 1597 | typedef struct bignum_ctx | ||
| 1598 | { | ||
| 1599 | int tos; /* top of stack */ | ||
| 1600 | BIGNUM *bn[BN_CTX]; /* The variables */ | ||
| 1601 | } BN_CTX; | ||
| 1602 | |||
| 1603 | The functions that follow have been grouped according to function. Most | ||
| 1604 | arithmetic functions return a result in the first argument, sometimes this | ||
| 1605 | first argument can also be an input parameter, sometimes it cannot. These | ||
| 1606 | restrictions are documented. | ||
| 1607 | |||
| 1608 | extern BIGNUM *BN_value_one; | ||
| 1609 | There is one variable defined by this library, a BIGNUM which contains the | ||
| 1610 | number 1. This variable is useful for use in comparisons and assignment. | ||
| 1611 | |||
| 1612 | Get Size functions. | ||
| 1613 | |||
| 1614 | int BN_num_bits(BIGNUM *a); | ||
| 1615 | This function returns the size of 'a' in bits. | ||
| 1616 | |||
| 1617 | int BN_num_bytes(BIGNUM *a); | ||
| 1618 | This function (macro) returns the size of 'a' in bytes. | ||
| 1619 | For conversion of BIGNUMs to byte streams, this is the number of | ||
| 1620 | bytes the output string will occupy. If the output byte | ||
| 1621 | format specifies that the 'top' bit indicates if the number is | ||
| 1622 | signed, so an extra '0' byte is required if the top bit on a | ||
| 1623 | positive number is being written, it is upto the application to | ||
| 1624 | make this adjustment. Like I said at the start, I don't | ||
| 1625 | really support negative numbers :-). | ||
| 1626 | |||
| 1627 | Creation/Destruction routines. | ||
| 1628 | |||
| 1629 | BIGNUM *BN_new(); | ||
| 1630 | Return a new BIGNUM object. The number initially has a value of 0. If | ||
| 1631 | there is an error, NULL is returned. | ||
| 1632 | |||
| 1633 | void BN_free(BIGNUM *a); | ||
| 1634 | Free()s a BIGNUM. | ||
| 1635 | |||
| 1636 | void BN_clear(BIGNUM *a); | ||
| 1637 | Sets 'a' to a value of 0 and also zeros all unused allocated | ||
| 1638 | memory. This function is used to clear a variable of 'sensitive' | ||
| 1639 | data that was held in it. | ||
| 1640 | |||
| 1641 | void BN_clear_free(BIGNUM *a); | ||
| 1642 | This function zeros the memory used by 'a' and then free()'s it. | ||
| 1643 | This function should be used to BN_free() BIGNUMS that have held | ||
| 1644 | sensitive numeric values like RSA private key values. Both this | ||
| 1645 | function and BN_clear tend to only be used by RSA and DH routines. | ||
| 1646 | |||
| 1647 | BN_CTX *BN_CTX_new(void); | ||
| 1648 | Returns a new BN_CTX. NULL on error. | ||
| 1649 | |||
| 1650 | void BN_CTX_free(BN_CTX *c); | ||
| 1651 | Free a BN_CTX structure. The BIGNUMs in 'c' are BN_clear_free()ed. | ||
| 1652 | |||
| 1653 | BIGNUM *bn_expand(BIGNUM *b, int bits); | ||
| 1654 | This is an internal function that should not normally be used. It | ||
| 1655 | ensures that 'b' has enough room for a 'bits' bit number. It is | ||
| 1656 | mostly used by the various BIGNUM routines. If there is an error, | ||
| 1657 | NULL is returned. if not, 'b' is returned. | ||
| 1658 | |||
| 1659 | BIGNUM *BN_copy(BIGNUM *to, BIGNUM *from); | ||
| 1660 | The 'from' is copied into 'to'. NULL is returned if there is an | ||
| 1661 | error, otherwise 'to' is returned. | ||
| 1662 | |||
| 1663 | BIGNUM *BN_dup(BIGNUM *a); | ||
| 1664 | A new BIGNUM is created and returned containing the value of 'a'. | ||
| 1665 | NULL is returned on error. | ||
| 1666 | |||
| 1667 | Comparison and Test Functions. | ||
| 1668 | |||
| 1669 | int BN_is_zero(BIGNUM *a) | ||
| 1670 | Return 1 if 'a' is zero, else 0. | ||
| 1671 | |||
| 1672 | int BN_is_one(a) | ||
| 1673 | Return 1 is 'a' is one, else 0. | ||
| 1674 | |||
| 1675 | int BN_is_word(a,w) | ||
| 1676 | Return 1 if 'a' == w, else 0. 'w' is a BN_ULONG. | ||
| 1677 | |||
| 1678 | int BN_cmp(BIGNUM *a, BIGNUM *b); | ||
| 1679 | Return -1 if 'a' is less than 'b', 0 if 'a' and 'b' are the same | ||
| 1680 | and 1 is 'a' is greater than 'b'. This is a signed comparison. | ||
| 1681 | |||
| 1682 | int BN_ucmp(BIGNUM *a, BIGNUM *b); | ||
| 1683 | This function is the same as BN_cmp except that the comparison | ||
| 1684 | ignores the sign of the numbers. | ||
| 1685 | |||
| 1686 | Arithmetic Functions | ||
| 1687 | For all of these functions, 0 is returned if there is an error and 1 is | ||
| 1688 | returned for success. The return value should always be checked. eg. | ||
| 1689 | if (!BN_add(r,a,b)) goto err; | ||
| 1690 | Unless explicitly mentioned, the 'return' value can be one of the | ||
| 1691 | 'parameters' to the function. | ||
| 1692 | |||
| 1693 | int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b); | ||
| 1694 | Add 'a' and 'b' and return the result in 'r'. This is r=a+b. | ||
| 1695 | |||
| 1696 | int BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b); | ||
| 1697 | Subtract 'a' from 'b' and put the result in 'r'. This is r=a-b. | ||
| 1698 | |||
| 1699 | int BN_lshift(BIGNUM *r, BIGNUM *a, int n); | ||
| 1700 | Shift 'a' left by 'n' bits. This is r=a*(2^n). | ||
| 1701 | |||
| 1702 | int BN_lshift1(BIGNUM *r, BIGNUM *a); | ||
| 1703 | Shift 'a' left by 1 bit. This form is more efficient than | ||
| 1704 | BN_lshift(r,a,1). This is r=a*2. | ||
| 1705 | |||
| 1706 | int BN_rshift(BIGNUM *r, BIGNUM *a, int n); | ||
| 1707 | Shift 'a' right by 'n' bits. This is r=int(a/(2^n)). | ||
| 1708 | |||
| 1709 | int BN_rshift1(BIGNUM *r, BIGNUM *a); | ||
| 1710 | Shift 'a' right by 1 bit. This form is more efficient than | ||
| 1711 | BN_rshift(r,a,1). This is r=int(a/2). | ||
| 1712 | |||
| 1713 | int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b); | ||
| 1714 | Multiply a by b and return the result in 'r'. 'r' must not be | ||
| 1715 | either 'a' or 'b'. It has to be a different BIGNUM. | ||
| 1716 | This is r=a*b. | ||
| 1717 | |||
| 1718 | int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); | ||
| 1719 | Multiply a by a and return the result in 'r'. 'r' must not be | ||
| 1720 | 'a'. This function is alot faster than BN_mul(r,a,a). This is r=a*a. | ||
| 1721 | |||
| 1722 | int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); | ||
| 1723 | Divide 'm' by 'd' and return the result in 'dv' and the remainder | ||
| 1724 | in 'rem'. Either of 'dv' or 'rem' can be NULL in which case that | ||
| 1725 | value is not returned. 'ctx' needs to be passed as a source of | ||
| 1726 | temporary BIGNUM variables. | ||
| 1727 | This is dv=int(m/d), rem=m%d. | ||
| 1728 | |||
| 1729 | int BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); | ||
| 1730 | Find the remainder of 'm' divided by 'd' and return it in 'rem'. | ||
| 1731 | 'ctx' holds the temporary BIGNUMs required by this function. | ||
| 1732 | This function is more efficient than BN_div(NULL,rem,m,d,ctx); | ||
| 1733 | This is rem=m%d. | ||
| 1734 | |||
| 1735 | int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BIGNUM *m,BN_CTX *ctx); | ||
| 1736 | Multiply 'a' by 'b' and return the remainder when divided by 'm'. | ||
| 1737 | 'ctx' holds the temporary BIGNUMs required by this function. | ||
| 1738 | This is r=(a*b)%m. | ||
| 1739 | |||
| 1740 | int BN_mod_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx); | ||
| 1741 | Raise 'a' to the 'p' power and return the remainder when divided by | ||
| 1742 | 'm'. 'ctx' holds the temporary BIGNUMs required by this function. | ||
| 1743 | This is r=(a^p)%m. | ||
| 1744 | |||
| 1745 | int BN_reciprocal(BIGNUM *r, BIGNUM *m, BN_CTX *ctx); | ||
| 1746 | Return the reciprocal of 'm'. 'ctx' holds the temporary variables | ||
| 1747 | required. This function returns -1 on error, otherwise it returns | ||
| 1748 | the number of bits 'r' is shifted left to make 'r' into an integer. | ||
| 1749 | This number of bits shifted is required in BN_mod_mul_reciprocal(). | ||
| 1750 | This is r=(1/m)<<(BN_num_bits(m)+1). | ||
| 1751 | |||
| 1752 | int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y, BIGNUM *m, | ||
| 1753 | BIGNUM *i, int nb, BN_CTX *ctx); | ||
| 1754 | This function is used to perform an efficient BN_mod_mul() | ||
| 1755 | operation. If one is going to repeatedly perform BN_mod_mul() with | ||
| 1756 | the same modulus is worth calculating the reciprocal of the modulus | ||
| 1757 | and then using this function. This operation uses the fact that | ||
| 1758 | a/b == a*r where r is the reciprocal of b. On modern computers | ||
| 1759 | multiplication is very fast and big number division is very slow. | ||
| 1760 | 'x' is multiplied by 'y' and then divided by 'm' and the remainder | ||
| 1761 | is returned. 'i' is the reciprocal of 'm' and 'nb' is the number | ||
| 1762 | of bits as returned from BN_reciprocal(). Normal usage is as follows. | ||
| 1763 | bn=BN_reciprocal(i,m); | ||
| 1764 | for (...) | ||
| 1765 | { BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); } | ||
| 1766 | This is r=(x*y)%m. Internally it is approximately | ||
| 1767 | r=(x*y)-m*(x*y/m) or r=(x*y)-m*((x*y*i) >> bn) | ||
| 1768 | This function is used in BN_mod_exp() and BN_is_prime(). | ||
| 1769 | |||
| 1770 | Assignment Operations | ||
| 1771 | |||
| 1772 | int BN_one(BIGNUM *a) | ||
| 1773 | Set 'a' to hold the value one. | ||
| 1774 | This is a=1. | ||
| 1775 | |||
| 1776 | int BN_zero(BIGNUM *a) | ||
| 1777 | Set 'a' to hold the value zero. | ||
| 1778 | This is a=0. | ||
| 1779 | |||
| 1780 | int BN_set_word(BIGNUM *a, unsigned long w); | ||
| 1781 | Set 'a' to hold the value of 'w'. 'w' is an unsigned long. | ||
| 1782 | This is a=w. | ||
| 1783 | |||
| 1784 | unsigned long BN_get_word(BIGNUM *a); | ||
| 1785 | Returns 'a' in an unsigned long. Not remarkably, often 'a' will | ||
| 1786 | be biger than a word, in which case 0xffffffffL is returned. | ||
| 1787 | |||
| 1788 | Word Operations | ||
| 1789 | These functions are much more efficient that the normal bignum arithmetic | ||
| 1790 | operations. | ||
| 1791 | |||
| 1792 | BN_ULONG BN_mod_word(BIGNUM *a, unsigned long w); | ||
| 1793 | Return the remainder of 'a' divided by 'w'. | ||
| 1794 | This is return(a%w). | ||
| 1795 | |||
| 1796 | int BN_add_word(BIGNUM *a, unsigned long w); | ||
| 1797 | Add 'w' to 'a'. This function does not take the sign of 'a' into | ||
| 1798 | account. This is a+=w; | ||
| 1799 | |||
| 1800 | Bit operations. | ||
| 1801 | |||
| 1802 | int BN_is_bit_set(BIGNUM *a, int n); | ||
| 1803 | This function return 1 if bit 'n' is set in 'a' else 0. | ||
| 1804 | |||
| 1805 | int BN_set_bit(BIGNUM *a, int n); | ||
| 1806 | This function sets bit 'n' to 1 in 'a'. | ||
| 1807 | This is a&= ~(1<<n); | ||
| 1808 | |||
| 1809 | int BN_clear_bit(BIGNUM *a, int n); | ||
| 1810 | This function sets bit 'n' to zero in 'a'. Return 0 if less | ||
| 1811 | than 'n' bits in 'a' else 1. This is a&= ~(1<<n); | ||
| 1812 | |||
| 1813 | int BN_mask_bits(BIGNUM *a, int n); | ||
| 1814 | Truncate 'a' to n bits long. This is a&= ~((~0)<<n) | ||
| 1815 | |||
| 1816 | Format conversion routines. | ||
| 1817 | |||
| 1818 | BIGNUM *BN_bin2bn(unsigned char *s, int len,BIGNUM *ret); | ||
| 1819 | This function converts 'len' bytes in 's' into a BIGNUM which | ||
| 1820 | is put in 'ret'. If ret is NULL, a new BIGNUM is created. | ||
| 1821 | Either this new BIGNUM or ret is returned. The number is | ||
| 1822 | assumed to be in bigendian form in 's'. By this I mean that | ||
| 1823 | to 'ret' is created as follows for 'len' == 5. | ||
| 1824 | ret = s[0]*2^32 + s[1]*2^24 + s[2]*2^16 + s[3]*2^8 + s[4]; | ||
| 1825 | This function cannot be used to convert negative numbers. It | ||
| 1826 | is always assumed the number is positive. The application | ||
| 1827 | needs to diddle the 'neg' field of th BIGNUM its self. | ||
| 1828 | The better solution would be to save the numbers in ASN.1 format | ||
| 1829 | since this is a defined standard for storing big numbers. | ||
| 1830 | Look at the functions | ||
| 1831 | |||
| 1832 | ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai); | ||
| 1833 | BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn); | ||
| 1834 | int i2d_ASN1_INTEGER(ASN1_INTEGER *a,unsigned char **pp); | ||
| 1835 | ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **a,unsigned char **pp, | ||
| 1836 | long length; | ||
| 1837 | |||
| 1838 | int BN_bn2bin(BIGNUM *a, unsigned char *to); | ||
| 1839 | This function converts 'a' to a byte string which is put into | ||
| 1840 | 'to'. The representation is big-endian in that the most | ||
| 1841 | significant byte of 'a' is put into to[0]. This function | ||
| 1842 | returns the number of bytes used to hold 'a'. BN_num_bytes(a) | ||
| 1843 | would return the same value and can be used to determine how | ||
| 1844 | large 'to' needs to be. If the number is negative, this | ||
| 1845 | information is lost. Since this library was written to | ||
| 1846 | manipulate large positive integers, the inability to save and | ||
| 1847 | restore them is not considered to be a problem by me :-). | ||
| 1848 | As for BN_bin2bn(), look at the ASN.1 integer encoding funtions | ||
| 1849 | for SSLeay. They use BN_bin2bn() and BN_bn2bin() internally. | ||
| 1850 | |||
| 1851 | char *BN_bn2ascii(BIGNUM *a); | ||
| 1852 | This function returns a malloc()ed string that contains the | ||
| 1853 | ascii hexadecimal encoding of 'a'. The number is in bigendian | ||
| 1854 | format with a '-' in front if the number is negative. | ||
| 1855 | |||
| 1856 | int BN_ascii2bn(BIGNUM **bn, char *a); | ||
| 1857 | The inverse of BN_bn2ascii. The function returns the number of | ||
| 1858 | characters from 'a' were processed in generating a the bignum. | ||
| 1859 | error is inticated by 0 being returned. The number is a | ||
| 1860 | hex digit string, optionally with a leading '-'. If *bn | ||
| 1861 | is null, a BIGNUM is created and returned via that variable. | ||
| 1862 | |||
| 1863 | int BN_print_fp(FILE *fp, BIGNUM *a); | ||
| 1864 | 'a' is printed to file pointer 'fp'. It is in the same format | ||
| 1865 | that is output from BN_bn2ascii(). 0 is returned on error, | ||
| 1866 | 1 if things are ok. | ||
| 1867 | |||
| 1868 | int BN_print(BIO *bp, BIGNUM *a); | ||
| 1869 | Same as BN_print except that the output is done to the SSLeay libraries | ||
| 1870 | BIO routines. BN_print_fp() actually calls this function. | ||
| 1871 | |||
| 1872 | Miscellaneous Routines. | ||
| 1873 | |||
| 1874 | int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); | ||
| 1875 | This function returns in 'rnd' a random BIGNUM that is bits | ||
| 1876 | long. If bottom is 1, the number returned is odd. If top is set, | ||
| 1877 | the top 2 bits of the number are set. This is useful because if | ||
| 1878 | this is set, 2 'n; bit numbers multiplied together will return a 2n | ||
| 1879 | bit number. If top was not set, they could produce a 2n-1 bit | ||
| 1880 | number. | ||
| 1881 | |||
| 1882 | BIGNUM *BN_mod_inverse(BIGNUM *a, BIGNUM *n,BN_CTX *ctx); | ||
| 1883 | This function create a new BIGNUM and returns it. This number | ||
| 1884 | is the inverse mod 'n' of 'a'. By this it is meant that the | ||
| 1885 | returned value 'r' satisfies (a*r)%n == 1. This function is | ||
| 1886 | used in the generation of RSA keys. 'ctx', as per usual, | ||
| 1887 | is used to hold temporary variables that are required by the | ||
| 1888 | function. NULL is returned on error. | ||
| 1889 | |||
| 1890 | int BN_gcd(BIGNUM *r,BIGNUM *a,BIGNUM *b,BN_CTX *ctx); | ||
| 1891 | 'r' has the greatest common divisor of 'a' and 'b'. 'ctx' is | ||
| 1892 | used for temporary variables and 0 is returned on error. | ||
| 1893 | |||
| 1894 | int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(),BN_CTX *ctx, | ||
| 1895 | char *cb_arg); | ||
| 1896 | This function is used to check if a BIGNUM ('p') is prime. | ||
| 1897 | It performs this test by using the Miller-Rabin randomised | ||
| 1898 | primality test. This is a probalistic test that requires a | ||
| 1899 | number of rounds to ensure the number is prime to a high | ||
| 1900 | degree of probability. Since this can take quite some time, a | ||
| 1901 | callback function can be passed and it will be called each | ||
| 1902 | time 'p' passes a round of the prime testing. 'callback' will | ||
| 1903 | be called as follows, callback(1,n,cb_arg) where n is the number of | ||
| 1904 | the round, just passed. As per usual 'ctx' contains temporary | ||
| 1905 | variables used. If ctx is NULL, it does not matter, a local version | ||
| 1906 | will be malloced. This parameter is present to save some mallocing | ||
| 1907 | inside the function but probably could be removed. | ||
| 1908 | 0 is returned on error. | ||
| 1909 | 'ncheck' is the number of Miller-Rabin tests to run. It is | ||
| 1910 | suggested to use the value 'BN_prime_checks' by default. | ||
| 1911 | |||
| 1912 | BIGNUM *BN_generate_prime( | ||
| 1913 | int bits, | ||
| 1914 | int strong, | ||
| 1915 | BIGNUM *a, | ||
| 1916 | BIGNUM *rems, | ||
| 1917 | void (*callback)()); | ||
| 1918 | char *cb_arg | ||
| 1919 | This function is used to generate prime numbers. It returns a | ||
| 1920 | new BIGNUM that has a high probability of being a prime. | ||
| 1921 | 'bits' is the number of bits that | ||
| 1922 | are to be in the prime. If 'strong' is true, the returned prime | ||
| 1923 | will also be a strong prime ((p-1)/2 is also prime). | ||
| 1924 | While searching for the prime ('p'), we | ||
| 1925 | can add the requirement that the prime fill the following | ||
| 1926 | condition p%a == rem. This can be used to help search for | ||
| 1927 | primes with specific features, which is required when looking | ||
| 1928 | for primes suitable for use with certain 'g' values in the | ||
| 1929 | Diffie-Hellman key exchange algorithm. If 'a' is NULL, | ||
| 1930 | this condition is not checked. If rem is NULL, rem is assumed | ||
| 1931 | to be 1. Since this search for a prime | ||
| 1932 | can take quite some time, if callback is not NULL, it is called | ||
| 1933 | in the following situations. | ||
| 1934 | We have a suspected prime (from a quick sieve), | ||
| 1935 | callback(0,sus_prime++,cb_arg). Each item to be passed to BN_is_prime(). | ||
| 1936 | callback(1,round++,cb_arg). Each successful 'round' in BN_is_prime(). | ||
| 1937 | callback(2,round,cb_arg). For each successful BN_is_prime() test. | ||
| 1938 | |||
| 1939 | Hints | ||
| 1940 | ----- | ||
| 1941 | |||
| 1942 | DSA wants 64*32 to use word mont mul, but RSA wants to use full. | ||
| 1943 | |||
| 1944 | ==== callback.doc ======================================================== | ||
| 1945 | |||
| 1946 | Callback functions used in SSLeay. | ||
| 1947 | |||
| 1948 | -------------------------- | ||
| 1949 | The BIO library. | ||
| 1950 | |||
| 1951 | Each BIO structure can have a callback defined against it. This callback is | ||
| 1952 | called 2 times for each BIO 'function'. It is passed 6 parameters. | ||
| 1953 | BIO_debug_callback() is an example callback which is defined in | ||
| 1954 | crypto/buffer/bio_cb.c and is used in apps/dgst.c This is intended mostly | ||
| 1955 | for debuging or to notify the application of IO. | ||
| 1956 | |||
| 1957 | long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl, | ||
| 1958 | long ret); | ||
| 1959 | bio is the BIO being called, cmd is the type of BIO function being called. | ||
| 1960 | Look at the BIO_CB_* defines in buffer.h. Argp and argi are the arguments | ||
| 1961 | passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts(). In the case of | ||
| 1962 | BIO_ctrl(), argl is also defined. The first time the callback is called, | ||
| 1963 | before the underlying function has been executed, 0 is passed as 'ret', and | ||
| 1964 | if the return code from the callback is not > 0, the call is aborted | ||
| 1965 | and the returned <= 0 value is returned. | ||
| 1966 | The second time the callback is called, the 'cmd' value also has | ||
| 1967 | BIO_CB_RETURN logically 'or'ed with it. The 'ret' value is the value returned | ||
| 1968 | from the actuall function call and whatever the callback returns is returned | ||
| 1969 | from the BIO function. | ||
| 1970 | |||
| 1971 | BIO_set_callback(b,cb) can be used to set the callback function | ||
| 1972 | (b is a BIO), and BIO_set_callback_arg(b,arg) can be used to | ||
| 1973 | set the cb_arg argument in the BIO strucutre. This field is only intended | ||
| 1974 | to be used by application, primarily in the callback function since it is | ||
| 1975 | accessable since the BIO is passed. | ||
| 1976 | |||
| 1977 | -------------------------- | ||
| 1978 | The PEM library. | ||
| 1979 | |||
| 1980 | The pem library only really uses one type of callback, | ||
| 1981 | static int def_callback(char *buf, int num, int verify); | ||
| 1982 | which is used to return a password string if required. | ||
| 1983 | 'buf' is the buffer to put the string in. 'num' is the size of 'buf' | ||
| 1984 | and 'verify' is used to indicate that the password should be checked. | ||
| 1985 | This last flag is mostly used when reading a password for encryption. | ||
| 1986 | |||
| 1987 | For all of these functions, a NULL callback will call the above mentioned | ||
| 1988 | default callback. This default function does not work under Windows 3.1. | ||
| 1989 | For other machines, it will use an application defined prompt string | ||
| 1990 | (EVP_set_pw_prompt(), which defines a library wide prompt string) | ||
| 1991 | if defined, otherwise it will use it's own PEM password prompt. | ||
| 1992 | It will then call EVP_read_pw_string() to get a password from the console. | ||
| 1993 | If your application wishes to use nice fancy windows to retrieve passwords, | ||
| 1994 | replace this function. The callback should return the number of bytes read | ||
| 1995 | into 'buf'. If the number of bytes <= 0, it is considered an error. | ||
| 1996 | |||
| 1997 | Functions that take this callback are listed below. For the 'read' type | ||
| 1998 | functions, the callback will only be required if the PEM data is encrypted. | ||
| 1999 | |||
| 2000 | For the Write functions, normally a password can be passed in 'kstr', of | ||
| 2001 | 'klen' bytes which will be used if the 'enc' cipher is not NULL. If | ||
| 2002 | 'kstr' is NULL, the callback will be used to retrieve a password. | ||
| 2003 | |||
| 2004 | int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len, | ||
| 2005 | int (*callback)()); | ||
| 2006 | char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)()); | ||
| 2007 | char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)()); | ||
| 2008 | int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x, | ||
| 2009 | EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)()); | ||
| 2010 | int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x, | ||
| 2011 | EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)()); | ||
| 2012 | STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)()); | ||
| 2013 | STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)()); | ||
| 2014 | |||
| 2015 | #define PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb) | ||
| 2016 | #define PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb) | ||
| 2017 | #define PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb) | ||
| 2018 | #define PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb) | ||
| 2019 | #define PEM_read_SSL_SESSION(fp,x,cb) | ||
| 2020 | #define PEM_read_X509(fp,x,cb) | ||
| 2021 | #define PEM_read_X509_REQ(fp,x,cb) | ||
| 2022 | #define PEM_read_X509_CRL(fp,x,cb) | ||
| 2023 | #define PEM_read_RSAPrivateKey(fp,x,cb) | ||
| 2024 | #define PEM_read_DSAPrivateKey(fp,x,cb) | ||
| 2025 | #define PEM_read_PrivateKey(fp,x,cb) | ||
| 2026 | #define PEM_read_PKCS7(fp,x,cb) | ||
| 2027 | #define PEM_read_DHparams(fp,x,cb) | ||
| 2028 | #define PEM_read_bio_SSL_SESSION(bp,x,cb) | ||
| 2029 | #define PEM_read_bio_X509(bp,x,cb) | ||
| 2030 | #define PEM_read_bio_X509_REQ(bp,x,cb) | ||
| 2031 | #define PEM_read_bio_X509_CRL(bp,x,cb) | ||
| 2032 | #define PEM_read_bio_RSAPrivateKey(bp,x,cb) | ||
| 2033 | #define PEM_read_bio_DSAPrivateKey(bp,x,cb) | ||
| 2034 | #define PEM_read_bio_PrivateKey(bp,x,cb) | ||
| 2035 | #define PEM_read_bio_PKCS7(bp,x,cb) | ||
| 2036 | #define PEM_read_bio_DHparams(bp,x,cb) | ||
| 2037 | int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); | ||
| 2038 | RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)()); | ||
| 2039 | |||
| 2040 | Now you will notice that macros like | ||
| 2041 | #define PEM_write_X509(fp,x) \ | ||
| 2042 | PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \ | ||
| 2043 | (char *)x, NULL,NULL,0,NULL) | ||
| 2044 | Don't do encryption normally. If you want to PEM encrypt your X509 structure, | ||
| 2045 | either just call PEM_ASN1_write directly or just define you own | ||
| 2046 | macro variant. As you can see, this macro just sets all encryption related | ||
| 2047 | parameters to NULL. | ||
| 2048 | |||
| 2049 | |||
| 2050 | -------------------------- | ||
| 2051 | The SSL library. | ||
| 2052 | |||
| 2053 | #define SSL_set_info_callback(ssl,cb) | ||
| 2054 | #define SSL_CTX_set_info_callback(ctx,cb) | ||
| 2055 | void callback(SSL *ssl,int location,int ret) | ||
| 2056 | This callback is called each time around the SSL_connect()/SSL_accept() | ||
| 2057 | state machine. So it will be called each time the SSL protocol progresses. | ||
| 2058 | It is mostly present for use when debugging. When SSL_connect() or | ||
| 2059 | SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or | ||
| 2060 | SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned. | ||
| 2061 | Have a look at the SSL_CB_* defines in ssl.h. If an info callback is defined | ||
| 2062 | against the SSL_CTX, it is called unless there is one set against the SSL. | ||
| 2063 | Have a look at | ||
| 2064 | void client_info_callback() in apps/s_client() for an example. | ||
| 2065 | |||
| 2066 | Certificate verification. | ||
| 2067 | void SSL_set_verify(SSL *s, int mode, int (*callback) ()); | ||
| 2068 | void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)()); | ||
| 2069 | This callback is used to help verify client and server X509 certificates. | ||
| 2070 | It is actually passed to X509_cert_verify(), along with the SSL structure | ||
| 2071 | so you have to read about X509_cert_verify() :-). The SSL_CTX version is used | ||
| 2072 | if the SSL version is not defined. X509_cert_verify() is the function used | ||
| 2073 | by the SSL part of the library to verify certificates. This function is | ||
| 2074 | nearly always defined by the application. | ||
| 2075 | |||
| 2076 | void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg); | ||
| 2077 | int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain); | ||
| 2078 | This call is used to replace the SSLeay certificate verification code. | ||
| 2079 | The 'arg' is kept in the SSL_CTX and is passed to the callback. | ||
| 2080 | If the callback returns 0, the certificate is rejected, otherwise it | ||
| 2081 | is accepted. The callback is replacing the X509_cert_verify() call. | ||
| 2082 | This feature is not often used, but if you wished to implement | ||
| 2083 | some totally different certificate authentication system, this 'hook' is | ||
| 2084 | vital. | ||
| 2085 | |||
| 2086 | SSLeay keeps a cache of session-ids against each SSL_CTX. These callbacks can | ||
| 2087 | be used to notify the application when a SSL_SESSION is added to the cache | ||
| 2088 | or to retrieve a SSL_SESSION that is not in the cache from the application. | ||
| 2089 | #define SSL_CTX_sess_set_get_cb(ctx,cb) | ||
| 2090 | SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy); | ||
| 2091 | If defined, this callback is called to return the SESSION_ID for the | ||
| 2092 | session-id in 'session_id', of 'session_id_len' bytes. 'copy' is set to 1 | ||
| 2093 | if the server is to 'take a copy' of the SSL_SESSION structure. It is 0 | ||
| 2094 | if the SSL_SESSION is being 'passed in' so the SSLeay library is now | ||
| 2095 | responsible for 'free()ing' the structure. Basically it is used to indicate | ||
| 2096 | if the reference count on the SSL_SESSION structure needs to be incremented. | ||
| 2097 | |||
| 2098 | #define SSL_CTX_sess_set_new_cb(ctx,cb) | ||
| 2099 | int callback(SSL *s, SSL_SESSION *sess); | ||
| 2100 | When a new connection is established, if the SSL_SESSION is going to be added | ||
| 2101 | to the cache, this callback is called. Return 1 if a 'copy' is required, | ||
| 2102 | otherwise, return 0. This return value just causes the reference count | ||
| 2103 | to be incremented (on return of a 1), this means the application does | ||
| 2104 | not need to worry about incrementing the refernece count (and the | ||
| 2105 | locking that implies in a multi-threaded application). | ||
| 2106 | |||
| 2107 | void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)()); | ||
| 2108 | This sets the SSL password reading function. | ||
| 2109 | It is mostly used for windowing applications | ||
| 2110 | and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey() | ||
| 2111 | calls inside the SSL library. The only reason this is present is because the | ||
| 2112 | calls to PEM_* functions is hidden in the SSLeay library so you have to | ||
| 2113 | pass in the callback some how. | ||
| 2114 | |||
| 2115 | #define SSL_CTX_set_client_cert_cb(ctx,cb) | ||
| 2116 | int callback(SSL *s,X509 **x509, EVP_PKEY **pkey); | ||
| 2117 | Called when a client certificate is requested but there is not one set | ||
| 2118 | against the SSL_CTX or the SSL. If the callback returns 1, x509 and | ||
| 2119 | pkey need to point to valid data. The library will free these when | ||
| 2120 | required so if the application wants to keep these around, increment | ||
| 2121 | their reference counts. If 0 is returned, no client cert is | ||
| 2122 | available. If -1 is returned, it is assumed that the callback needs | ||
| 2123 | to be called again at a later point in time. SSL_connect will return | ||
| 2124 | -1 and SSL_want_x509_lookup(ssl) returns true. Remember that | ||
| 2125 | application data can be attached to an SSL structure via the | ||
| 2126 | SSL_set_app_data(SSL *ssl,char *data) call. | ||
| 2127 | |||
| 2128 | -------------------------- | ||
| 2129 | The X509 library. | ||
| 2130 | |||
| 2131 | int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(), | ||
| 2132 | int *error,char *arg,STACK *cert_chain); | ||
| 2133 | int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg, | ||
| 2134 | STACK *cert_chain); | ||
| 2135 | |||
| 2136 | X509_cert_verify() is used to authenticate X509 certificates. The 'ctx' holds | ||
| 2137 | the details of the various caches and files used to locate certificates. | ||
| 2138 | 'xs' is the certificate to verify and 'cb' is the application callback (more | ||
| 2139 | detail later). 'error' will be set to the error code and 'arg' is passed | ||
| 2140 | to the 'cb' callback. Look at the VERIFY_* defines in crypto/x509/x509.h | ||
| 2141 | |||
| 2142 | When ever X509_cert_verify() makes a 'negative' decision about a | ||
| 2143 | certitificate, the callback is called. If everything checks out, the | ||
| 2144 | callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self | ||
| 2145 | signed cert that is not the passed certificate). | ||
| 2146 | |||
| 2147 | The callback is passed the X509_cert_verify opinion of the certificate | ||
| 2148 | in 'ok', the certificate in 'xs', the issuer certificate in 'xi', | ||
| 2149 | the 'depth' of the certificate in the verification 'chain', the | ||
| 2150 | VERIFY_* code in 'error' and the argument passed to X509_cert_verify() | ||
| 2151 | in 'arg'. cert_chain is a list of extra certs to use if they are not | ||
| 2152 | in the cache. | ||
| 2153 | |||
| 2154 | The callback can be used to look at the error reason, and then return 0 | ||
| 2155 | for an 'error' or '1' for ok. This will override the X509_cert_verify() | ||
| 2156 | opinion of the certificates validity. Processing will continue depending on | ||
| 2157 | the return value. If one just wishes to use the callback for informational | ||
| 2158 | reason, just return the 'ok' parameter. | ||
| 2159 | |||
| 2160 | -------------------------- | ||
| 2161 | The BN and DH library. | ||
| 2162 | |||
| 2163 | BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add, | ||
| 2164 | BIGNUM *rem,void (*callback)(int,int)); | ||
| 2165 | int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int), | ||
| 2166 | |||
| 2167 | Read doc/bn.doc for the description of these 2. | ||
| 2168 | |||
| 2169 | DH *DH_generate_parameters(int prime_len,int generator, | ||
| 2170 | void (*callback)(int,int)); | ||
| 2171 | Read doc/bn.doc for the description of the callback, since it is just passed | ||
| 2172 | to BN_generate_prime(), except that it is also called as | ||
| 2173 | callback(3,0) by this function. | ||
| 2174 | |||
| 2175 | -------------------------- | ||
| 2176 | The CRYPTO library. | ||
| 2177 | |||
| 2178 | void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file, | ||
| 2179 | int line)); | ||
| 2180 | void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount, | ||
| 2181 | int type,char *file, int line)); | ||
| 2182 | void CRYPTO_set_id_callback(unsigned long (*func)(void)); | ||
| 2183 | |||
| 2184 | Read threads.doc for info on these ones. | ||
| 2185 | |||
| 2186 | |||
| 2187 | ==== cipher.doc ======================================================== | ||
| 2188 | |||
| 2189 | The Cipher subroutines. | ||
| 2190 | |||
| 2191 | These routines require "evp.h" to be included. | ||
| 2192 | |||
| 2193 | These functions are a higher level interface to the various cipher | ||
| 2194 | routines found in this library. As such, they allow the same code to be | ||
| 2195 | used to encrypt and decrypt via different ciphers with only a change | ||
| 2196 | in an initial parameter. These routines also provide buffering for block | ||
| 2197 | ciphers. | ||
| 2198 | |||
| 2199 | These routines all take a pointer to the following structure to specify | ||
| 2200 | which cipher to use. If you wish to use a new cipher with these routines, | ||
| 2201 | you would probably be best off looking an how an existing cipher is | ||
| 2202 | implemented and copying it. At this point in time, I'm not going to go | ||
| 2203 | into many details. This structure should be considered opaque | ||
| 2204 | |||
| 2205 | typedef struct pem_cipher_st | ||
| 2206 | { | ||
| 2207 | int type; | ||
| 2208 | int block_size; | ||
| 2209 | int key_len; | ||
| 2210 | int iv_len; | ||
| 2211 | void (*enc_init)(); /* init for encryption */ | ||
| 2212 | void (*dec_init)(); /* init for decryption */ | ||
| 2213 | void (*do_cipher)(); /* encrypt data */ | ||
| 2214 | } EVP_CIPHER; | ||
| 2215 | |||
| 2216 | The type field is the object NID of the cipher type | ||
| 2217 | (read the section on Objects for an explanation of what a NID is). | ||
| 2218 | The cipher block_size is how many bytes need to be passed | ||
| 2219 | to the cipher at a time. Key_len is the | ||
| 2220 | length of the key the cipher requires and iv_len is the length of the | ||
| 2221 | initialisation vector required. enc_init is the function | ||
| 2222 | called to initialise the ciphers context for encryption and dec_init is the | ||
| 2223 | function to initialise for decryption (they need to be different, especially | ||
| 2224 | for the IDEA cipher). | ||
| 2225 | |||
| 2226 | One reason for specifying the Cipher via a pointer to a structure | ||
| 2227 | is that if you only use des-cbc, only the des-cbc routines will | ||
| 2228 | be included when you link the program. If you passed an integer | ||
| 2229 | that specified which cipher to use, the routine that mapped that | ||
| 2230 | integer to a set of cipher functions would cause all the ciphers | ||
| 2231 | to be link into the code. This setup also allows new ciphers | ||
| 2232 | to be added by the application (with some restrictions). | ||
| 2233 | |||
| 2234 | The thirteen ciphers currently defined in this library are | ||
| 2235 | |||
| 2236 | EVP_CIPHER *EVP_des_ecb(); /* DES in ecb mode, iv=0, block=8, key= 8 */ | ||
| 2237 | EVP_CIPHER *EVP_des_ede(); /* DES in ecb ede mode, iv=0, block=8, key=16 */ | ||
| 2238 | EVP_CIPHER *EVP_des_ede3(); /* DES in ecb ede mode, iv=0, block=8, key=24 */ | ||
| 2239 | EVP_CIPHER *EVP_des_cfb(); /* DES in cfb mode, iv=8, block=1, key= 8 */ | ||
| 2240 | EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */ | ||
| 2241 | EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */ | ||
| 2242 | EVP_CIPHER *EVP_des_ofb(); /* DES in ofb mode, iv=8, block=1, key= 8 */ | ||
| 2243 | EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */ | ||
| 2244 | EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */ | ||
| 2245 | EVP_CIPHER *EVP_des_cbc(); /* DES in cbc mode, iv=8, block=8, key= 8 */ | ||
| 2246 | EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */ | ||
| 2247 | EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */ | ||
| 2248 | EVP_CIPHER *EVP_desx_cbc(); /* DES in desx cbc mode,iv=8, block=8, key=24 */ | ||
| 2249 | EVP_CIPHER *EVP_rc4(); /* RC4, iv=0, block=1, key=16 */ | ||
| 2250 | EVP_CIPHER *EVP_idea_ecb(); /* IDEA in ecb mode, iv=0, block=8, key=16 */ | ||
| 2251 | EVP_CIPHER *EVP_idea_cfb(); /* IDEA in cfb mode, iv=8, block=1, key=16 */ | ||
| 2252 | EVP_CIPHER *EVP_idea_ofb(); /* IDEA in ofb mode, iv=8, block=1, key=16 */ | ||
| 2253 | EVP_CIPHER *EVP_idea_cbc(); /* IDEA in cbc mode, iv=8, block=8, key=16 */ | ||
| 2254 | EVP_CIPHER *EVP_rc2_ecb(); /* RC2 in ecb mode, iv=0, block=8, key=16 */ | ||
| 2255 | EVP_CIPHER *EVP_rc2_cfb(); /* RC2 in cfb mode, iv=8, block=1, key=16 */ | ||
| 2256 | EVP_CIPHER *EVP_rc2_ofb(); /* RC2 in ofb mode, iv=8, block=1, key=16 */ | ||
| 2257 | EVP_CIPHER *EVP_rc2_cbc(); /* RC2 in cbc mode, iv=8, block=8, key=16 */ | ||
| 2258 | EVP_CIPHER *EVP_bf_ecb(); /* Blowfish in ecb mode,iv=0, block=8, key=16 */ | ||
| 2259 | EVP_CIPHER *EVP_bf_cfb(); /* Blowfish in cfb mode,iv=8, block=1, key=16 */ | ||
| 2260 | EVP_CIPHER *EVP_bf_ofb(); /* Blowfish in ofb mode,iv=8, block=1, key=16 */ | ||
| 2261 | EVP_CIPHER *EVP_bf_cbc(); /* Blowfish in cbc mode,iv=8, block=8, key=16 */ | ||
| 2262 | |||
| 2263 | The meaning of the compound names is as follows. | ||
| 2264 | des The base cipher is DES. | ||
| 2265 | idea The base cipher is IDEA | ||
| 2266 | rc4 The base cipher is RC4-128 | ||
| 2267 | rc2 The base cipher is RC2-128 | ||
| 2268 | ecb Electronic Code Book form of the cipher. | ||
| 2269 | cbc Cipher Block Chaining form of the cipher. | ||
| 2270 | cfb 64 bit Cipher Feedback form of the cipher. | ||
| 2271 | ofb 64 bit Output Feedback form of the cipher. | ||
| 2272 | ede The cipher is used in Encrypt, Decrypt, Encrypt mode. The first | ||
| 2273 | and last keys are the same. | ||
| 2274 | ede3 The cipher is used in Encrypt, Decrypt, Encrypt mode. | ||
| 2275 | |||
| 2276 | All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument. | ||
| 2277 | The state of the cipher is kept in this structure. | ||
| 2278 | |||
| 2279 | typedef struct EVP_CIPHER_Ctx_st | ||
| 2280 | { | ||
| 2281 | EVP_CIPHER *cipher; | ||
| 2282 | int encrypt; /* encrypt or decrypt */ | ||
| 2283 | int buf_len; /* number we have left */ | ||
| 2284 | unsigned char buf[8]; | ||
| 2285 | union { | ||
| 2286 | .... /* cipher specific stuff */ | ||
| 2287 | } c; | ||
| 2288 | } EVP_CIPHER_CTX; | ||
| 2289 | |||
| 2290 | Cipher is a pointer the the EVP_CIPHER for the current context. The encrypt | ||
| 2291 | flag indicates encryption or decryption. buf_len is the number of bytes | ||
| 2292 | currently being held in buf. | ||
| 2293 | The 'c' union holds the cipher specify context. | ||
| 2294 | |||
| 2295 | The following functions are to be used. | ||
| 2296 | |||
| 2297 | int EVP_read_pw_string( | ||
| 2298 | char *buf, | ||
| 2299 | int len, | ||
| 2300 | char *prompt, | ||
| 2301 | int verify, | ||
| 2302 | This function is the same as des_read_pw_string() (des.doc). | ||
| 2303 | |||
| 2304 | void EVP_set_pw_prompt(char *prompt); | ||
| 2305 | This function sets the 'default' prompt to use to use in | ||
| 2306 | EVP_read_pw_string when the prompt parameter is NULL. If the | ||
| 2307 | prompt parameter is NULL, this 'default prompt' feature is turned | ||
| 2308 | off. Be warned, this is a global variable so weird things | ||
| 2309 | will happen if it is used under Win16 and care must be taken | ||
| 2310 | with a multi-threaded version of the library. | ||
| 2311 | |||
| 2312 | char *EVP_get_pw_prompt(); | ||
| 2313 | This returns a pointer to the default prompt string. NULL | ||
| 2314 | if it is not set. | ||
| 2315 | |||
| 2316 | int EVP_BytesToKey( | ||
| 2317 | EVP_CIPHER *type, | ||
| 2318 | EVP_MD *md, | ||
| 2319 | unsigned char *salt, | ||
| 2320 | unsigned char *data, | ||
| 2321 | int datal, | ||
| 2322 | int count, | ||
| 2323 | unsigned char *key, | ||
| 2324 | unsigned char *iv); | ||
| 2325 | This function is used to generate a key and an initialisation vector | ||
| 2326 | for a specified cipher from a key string and a salt. Type | ||
| 2327 | specifies the cipher the 'key' is being generated for. Md is the | ||
| 2328 | message digest algorithm to use to generate the key and iv. The salt | ||
| 2329 | is an optional 8 byte object that is used to help seed the key | ||
| 2330 | generator. | ||
| 2331 | If the salt value is NULL, it is just not used. Datal is the | ||
| 2332 | number of bytes to use from 'data' in the key generation. | ||
| 2333 | This function returns the key size for the specified cipher, if | ||
| 2334 | data is NULL, this value is returns and no other | ||
| 2335 | computation is performed. Count is | ||
| 2336 | the number of times to loop around the key generator. I would | ||
| 2337 | suggest leaving it's value as 1. Key and iv are the structures to | ||
| 2338 | place the returning iv and key in. If they are NULL, no value is | ||
| 2339 | generated for that particular value. | ||
| 2340 | The algorithm used is as follows | ||
| 2341 | |||
| 2342 | /* M[] is an array of message digests | ||
| 2343 | * MD() is the message digest function */ | ||
| 2344 | M[0]=MD(data . salt); | ||
| 2345 | for (i=1; i<count; i++) M[0]=MD(M[0]); | ||
| 2346 | |||
| 2347 | i=1 | ||
| 2348 | while (data still needed for key and iv) | ||
| 2349 | { | ||
| 2350 | M[i]=MD(M[i-1] . data . salt); | ||
| 2351 | for (i=1; i<count; i++) M[i]=MD(M[i]); | ||
| 2352 | i++; | ||
| 2353 | } | ||
| 2354 | |||
| 2355 | If the salt is NULL, it is not used. | ||
| 2356 | The digests are concatenated together. | ||
| 2357 | M = M[0] . M[1] . M[2] ....... | ||
| 2358 | |||
| 2359 | For key= 8, iv=8 => key=M[0.. 8], iv=M[ 9 .. 16]. | ||
| 2360 | For key=16, iv=0 => key=M[0..16]. | ||
| 2361 | For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24]. | ||
| 2362 | For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32]. | ||
| 2363 | |||
| 2364 | This routine will produce DES-CBC keys and iv that are compatible | ||
| 2365 | with the PKCS-5 standard when md2 or md5 are used. If md5 is | ||
| 2366 | used, the salt is NULL and count is 1, this routine will produce | ||
| 2367 | the password to key mapping normally used with RC4. | ||
| 2368 | I have attempted to logically extend the PKCS-5 standard to | ||
| 2369 | generate keys and iv for ciphers that require more than 16 bytes, | ||
| 2370 | if anyone knows what the correct standard is, please inform me. | ||
| 2371 | When using sha or sha1, things are a bit different under this scheme, | ||
| 2372 | since sha produces a 20 byte digest. So for ciphers requiring | ||
| 2373 | 24 bits of data, 20 will come from the first MD and 4 will | ||
| 2374 | come from the second. | ||
| 2375 | |||
| 2376 | I have considered having a separate function so this 'routine' | ||
| 2377 | can be used without the requirement of passing a EVP_CIPHER *, | ||
| 2378 | but I have decided to not bother. If you wish to use the | ||
| 2379 | function without official EVP_CIPHER structures, just declare | ||
| 2380 | a local one and set the key_len and iv_len fields to the | ||
| 2381 | length you desire. | ||
| 2382 | |||
| 2383 | The following routines perform encryption and decryption 'by parts'. By | ||
| 2384 | this I mean that there are groups of 3 routines. An Init function that is | ||
| 2385 | used to specify a cipher and initialise data structures. An Update routine | ||
| 2386 | that does encryption/decryption, one 'chunk' at a time. And finally a | ||
| 2387 | 'Final' function that finishes the encryption/decryption process. | ||
| 2388 | All these functions take a EVP_CIPHER pointer to specify which cipher to | ||
| 2389 | encrypt/decrypt with. They also take a EVP_CIPHER_CTX object as an | ||
| 2390 | argument. This structure is used to hold the state information associated | ||
| 2391 | with the operation in progress. | ||
| 2392 | |||
| 2393 | void EVP_EncryptInit( | ||
| 2394 | EVP_CIPHER_CTX *ctx, | ||
| 2395 | EVP_CIPHER *type, | ||
| 2396 | unsigned char *key, | ||
| 2397 | unsigned char *iv); | ||
| 2398 | This function initialise a EVP_CIPHER_CTX for encryption using the | ||
| 2399 | cipher passed in the 'type' field. The cipher is initialised to use | ||
| 2400 | 'key' as the key and 'iv' for the initialisation vector (if one is | ||
| 2401 | required). If the type, key or iv is NULL, the value currently in the | ||
| 2402 | EVP_CIPHER_CTX is reused. So to perform several decrypt | ||
| 2403 | using the same cipher, key and iv, initialise with the cipher, | ||
| 2404 | key and iv the first time and then for subsequent calls, | ||
| 2405 | reuse 'ctx' but pass NULL for type, key and iv. You must make sure | ||
| 2406 | to pass a key that is large enough for a particular cipher. I | ||
| 2407 | would suggest using the EVP_BytesToKey() function. | ||
| 2408 | |||
| 2409 | void EVP_EncryptUpdate( | ||
| 2410 | EVP_CIPHER_CTX *ctx, | ||
| 2411 | unsigned char *out, | ||
| 2412 | int *outl, | ||
| 2413 | unsigned char *in, | ||
| 2414 | int inl); | ||
| 2415 | This function takes 'inl' bytes from 'in' and outputs bytes | ||
| 2416 | encrypted by the cipher 'ctx' was initialised with into 'out'. The | ||
| 2417 | number of bytes written to 'out' is put into outl. If a particular | ||
| 2418 | cipher encrypts in blocks, less or more bytes than input may be | ||
| 2419 | output. Currently the largest block size used by supported ciphers | ||
| 2420 | is 8 bytes, so 'out' should have room for 'inl+7' bytes. Normally | ||
| 2421 | EVP_EncryptInit() is called once, followed by lots and lots of | ||
| 2422 | calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal | ||
| 2423 | call. | ||
| 2424 | |||
| 2425 | void EVP_EncryptFinal( | ||
| 2426 | EVP_CIPHER_CTX *ctx, | ||
| 2427 | unsigned char *out, | ||
| 2428 | int *outl); | ||
| 2429 | Because quite a large number of ciphers are block ciphers, there is | ||
| 2430 | often an incomplete block to write out at the end of the | ||
| 2431 | encryption. EVP_EncryptFinal() performs processing on this last | ||
| 2432 | block. The last block in encoded in such a way that it is possible | ||
| 2433 | to determine how many bytes in the last block are valid. For 8 byte | ||
| 2434 | block size ciphers, if only 5 bytes in the last block are valid, the | ||
| 2435 | last three bytes will be filled with the value 3. If only 2 were | ||
| 2436 | valid, the other 6 would be filled with sixes. If all 8 bytes are | ||
| 2437 | valid, a extra 8 bytes are appended to the cipher stream containing | ||
| 2438 | nothing but 8 eights. These last bytes are output into 'out' and | ||
| 2439 | the number of bytes written is put into 'outl' These last bytes | ||
| 2440 | are output into 'out' and the number of bytes written is put into | ||
| 2441 | 'outl'. This form of block cipher finalisation is compatible with | ||
| 2442 | PKCS-5. Please remember that even if you are using ciphers like | ||
| 2443 | RC4 that has no blocking and so the function will not write | ||
| 2444 | anything into 'out', it would still be a good idea to pass a | ||
| 2445 | variable for 'out' that can hold 8 bytes just in case the cipher is | ||
| 2446 | changed some time in the future. It should also be remembered | ||
| 2447 | that the EVP_CIPHER_CTX contains the password and so when one has | ||
| 2448 | finished encryption with a particular EVP_CIPHER_CTX, it is good | ||
| 2449 | practice to zero the structure | ||
| 2450 | (ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)). | ||
| 2451 | |||
| 2452 | void EVP_DecryptInit( | ||
| 2453 | EVP_CIPHER_CTX *ctx, | ||
| 2454 | EVP_CIPHER *type, | ||
| 2455 | unsigned char *key, | ||
| 2456 | unsigned char *iv); | ||
| 2457 | This function is basically the same as EVP_EncryptInit() accept that | ||
| 2458 | is prepares the EVP_CIPHER_CTX for decryption. | ||
| 2459 | |||
| 2460 | void EVP_DecryptUpdate( | ||
| 2461 | EVP_CIPHER_CTX *ctx, | ||
| 2462 | unsigned char *out, | ||
| 2463 | int *outl, | ||
| 2464 | unsigned char *in, | ||
| 2465 | int inl); | ||
| 2466 | This function is basically the same as EVP_EncryptUpdate() | ||
| 2467 | except that it performs decryption. There is one | ||
| 2468 | fundamental difference though. 'out' can not be the same as | ||
| 2469 | 'in' for any ciphers with a block size greater than 1 if more | ||
| 2470 | than one call to EVP_DecryptUpdate() will be made. This | ||
| 2471 | is because this routine can hold a 'partial' block between | ||
| 2472 | calls. When a partial block is decrypted (due to more bytes | ||
| 2473 | being passed via this function, they will be written to 'out' | ||
| 2474 | overwriting the input bytes in 'in' that have not been read | ||
| 2475 | yet. From this it should also be noted that 'out' should | ||
| 2476 | be at least one 'block size' larger than 'inl'. This problem | ||
| 2477 | only occurs on the second and subsequent call to | ||
| 2478 | EVP_DecryptUpdate() when using a block cipher. | ||
| 2479 | |||
| 2480 | int EVP_DecryptFinal( | ||
| 2481 | EVP_CIPHER_CTX *ctx, | ||
| 2482 | unsigned char *out, | ||
| 2483 | int *outl); | ||
| 2484 | This function is different to EVP_EncryptFinal in that it 'removes' | ||
| 2485 | any padding bytes appended when the data was encrypted. Due to the | ||
| 2486 | way in which 1 to 8 bytes may have been appended when encryption | ||
| 2487 | using a block cipher, 'out' can end up with 0 to 7 bytes being put | ||
| 2488 | into it. When decoding the padding bytes, it is possible to detect | ||
| 2489 | an incorrect decryption. If the decryption appears to be wrong, 0 | ||
| 2490 | is returned. If everything seems ok, 1 is returned. For ciphers | ||
| 2491 | with a block size of 1 (RC4), this function would normally not | ||
| 2492 | return any bytes and would always return 1. Just because this | ||
| 2493 | function returns 1 does not mean the decryption was correct. It | ||
| 2494 | would normally be wrong due to either the wrong key/iv or | ||
| 2495 | corruption of the cipher data fed to EVP_DecryptUpdate(). | ||
| 2496 | As for EVP_EncryptFinal, it is a good idea to zero the | ||
| 2497 | EVP_CIPHER_CTX after use since the structure contains the key used | ||
| 2498 | to decrypt the data. | ||
| 2499 | |||
| 2500 | The following Cipher routines are convenience routines that call either | ||
| 2501 | EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX | ||
| 2502 | was setup to encrypt or decrypt. | ||
| 2503 | |||
| 2504 | void EVP_CipherInit( | ||
| 2505 | EVP_CIPHER_CTX *ctx, | ||
| 2506 | EVP_CIPHER *type, | ||
| 2507 | unsigned char *key, | ||
| 2508 | unsigned char *iv, | ||
| 2509 | int enc); | ||
| 2510 | This function take arguments that are the same as EVP_EncryptInit() | ||
| 2511 | and EVP_DecryptInit() except for the extra 'enc' flag. If 1, the | ||
| 2512 | EVP_CIPHER_CTX is setup for encryption, if 0, decryption. | ||
| 2513 | |||
| 2514 | void EVP_CipherUpdate( | ||
| 2515 | EVP_CIPHER_CTX *ctx, | ||
| 2516 | unsigned char *out, | ||
| 2517 | int *outl, | ||
| 2518 | unsigned char *in, | ||
| 2519 | int inl); | ||
| 2520 | Again this function calls either EVP_EncryptUpdate() or | ||
| 2521 | EVP_DecryptUpdate() depending on state in the 'ctx' structure. | ||
| 2522 | As noted for EVP_DecryptUpdate(), when this routine is used | ||
| 2523 | for decryption with block ciphers, 'out' should not be the | ||
| 2524 | same as 'in'. | ||
| 2525 | |||
| 2526 | int EVP_CipherFinal( | ||
| 2527 | EVP_CIPHER_CTX *ctx, | ||
| 2528 | unsigned char *outm, | ||
| 2529 | int *outl); | ||
| 2530 | This routine call EVP_EncryptFinal() or EVP_DecryptFinal() | ||
| 2531 | depending on the state information in 'ctx'. 1 is always returned | ||
| 2532 | if the mode is encryption, otherwise the return value is the return | ||
| 2533 | value of EVP_DecryptFinal(). | ||
| 2534 | |||
| 2535 | ==== cipher.m ======================================================== | ||
| 2536 | |||
| 2537 | Date: Tue, 15 Oct 1996 08:16:14 +1000 (EST) | ||
| 2538 | From: Eric Young <eay@mincom.com> | ||
| 2539 | X-Sender: eay@orb | ||
| 2540 | To: Roland Haring <rharing@tandem.cl> | ||
| 2541 | Cc: ssl-users@mincom.com | ||
| 2542 | Subject: Re: Symmetric encryption with ssleay | ||
| 2543 | In-Reply-To: <m0vBpyq-00001aC@tandemnet.tandem.cl> | ||
| 2544 | Message-Id: <Pine.SOL.3.91.961015075623.11394A-100000@orb> | ||
| 2545 | Mime-Version: 1.0 | ||
| 2546 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 2547 | Sender: ssl-lists-owner@mincom.com | ||
| 2548 | Precedence: bulk | ||
| 2549 | Status: RO | ||
| 2550 | X-Status: | ||
| 2551 | |||
| 2552 | On Fri, 11 Oct 1996, Roland Haring wrote: | ||
| 2553 | > THE_POINT: | ||
| 2554 | > Would somebody be so kind to give me the minimum basic | ||
| 2555 | > calls I need to do to libcrypto.a to get some text encrypted | ||
| 2556 | > and decrypted again? ...hopefully with code included to do | ||
| 2557 | > base64 encryption and decryption ... e.g. that sign-it.c code | ||
| 2558 | > posted some while ago was a big help :-) (please, do not point | ||
| 2559 | > me to apps/enc.c where I suspect my Heissenbug to be hidden :-) | ||
| 2560 | |||
| 2561 | Ok, the base64 encoding stuff in 'enc.c' does the wrong thing sometimes | ||
| 2562 | when the data is less than a line long (this is for decoding). I'll dig | ||
| 2563 | up the exact fix today and post it. I am taking longer on 0.6.5 than I | ||
| 2564 | intended so I'll just post this patch. | ||
| 2565 | |||
| 2566 | The documentation to read is in | ||
| 2567 | doc/cipher.doc, | ||
| 2568 | doc/encode.doc (very sparse :-). | ||
| 2569 | and perhaps | ||
| 2570 | doc/digest.doc, | ||
| 2571 | |||
| 2572 | The basic calls to encrypt with say triple DES are | ||
| 2573 | |||
| 2574 | Given | ||
| 2575 | char key[EVP_MAX_KEY_LENGTH]; | ||
| 2576 | char iv[EVP_MAX_IV_LENGTH]; | ||
| 2577 | EVP_CIPHER_CTX ctx; | ||
| 2578 | unsigned char out[512+8]; | ||
| 2579 | int outl; | ||
| 2580 | |||
| 2581 | /* optional generation of key/iv data from text password using md5 | ||
| 2582 | * via an upward compatable verson of PKCS#5. */ | ||
| 2583 | EVP_BytesToKey(EVP_des_ede3_cbc,EVP_md5,NULL,passwd,strlen(passwd), | ||
| 2584 | key,iv); | ||
| 2585 | |||
| 2586 | /* Initalise the EVP_CIPHER_CTX */ | ||
| 2587 | EVP_EncryptInit(ctx,EVP_des_ede3_cbc,key,iv); | ||
| 2588 | |||
| 2589 | while (....) | ||
| 2590 | { | ||
| 2591 | /* This is processing 512 bytes at a time, the bytes are being | ||
| 2592 | * copied into 'out', outl bytes are output. 'out' should not be the | ||
| 2593 | * same as 'in' for reasons mentioned in the documentation. */ | ||
| 2594 | EVP_EncryptUpdate(ctx,out,&outl,in,512); | ||
| 2595 | } | ||
| 2596 | |||
| 2597 | /* Output the last 'block'. If the cipher is a block cipher, the last | ||
| 2598 | * block is encoded in such a way so that a wrong decryption will normally be | ||
| 2599 | * detected - again, one of the PKCS standards. */ | ||
| 2600 | |||
| 2601 | EVP_EncryptFinal(ctx,out,&outl); | ||
| 2602 | |||
| 2603 | To decrypt, use the EVP_DecryptXXXXX functions except that EVP_DecryptFinal() | ||
| 2604 | will return 0 if the decryption fails (only detectable on block ciphers). | ||
| 2605 | |||
| 2606 | You can also use | ||
| 2607 | EVP_CipherInit() | ||
| 2608 | EVP_CipherUpdate() | ||
| 2609 | EVP_CipherFinal() | ||
| 2610 | which does either encryption or decryption depending on an extra | ||
| 2611 | parameter to EVP_CipherInit(). | ||
| 2612 | |||
| 2613 | |||
| 2614 | To do the base64 encoding, | ||
| 2615 | EVP_EncodeInit() | ||
| 2616 | EVP_EncodeUpdate() | ||
| 2617 | EVP_EncodeFinal() | ||
| 2618 | |||
| 2619 | EVP_DecodeInit() | ||
| 2620 | EVP_DecodeUpdate() | ||
| 2621 | EVP_DecodeFinal() | ||
| 2622 | |||
| 2623 | where the encoding is quite simple, but the decoding can be a bit more | ||
| 2624 | fun (due to dud input). | ||
| 2625 | |||
| 2626 | EVP_DecodeUpdate() returns -1 for an error on an input line, 0 if the | ||
| 2627 | 'last line' was just processed, and 1 if more lines should be submitted. | ||
| 2628 | |||
| 2629 | EVP_DecodeFinal() returns -1 for an error or 1 if things are ok. | ||
| 2630 | |||
| 2631 | So the loop becomes | ||
| 2632 | EVP_DecodeInit(....) | ||
| 2633 | for (;;) | ||
| 2634 | { | ||
| 2635 | i=EVP_DecodeUpdate(....); | ||
| 2636 | if (i < 0) goto err; | ||
| 2637 | |||
| 2638 | /* process the data */ | ||
| 2639 | |||
| 2640 | if (i == 0) break; | ||
| 2641 | } | ||
| 2642 | EVP_DecodeFinal(....); | ||
| 2643 | /* process the data */ | ||
| 2644 | |||
| 2645 | The problem in 'enc.c' is that I was stuff the processing up after the | ||
| 2646 | EVP_DecodeFinal(...) when the for(..) loop was not being run (one line of | ||
| 2647 | base64 data) and this was because 'enc.c' tries to scan over a file until | ||
| 2648 | it hits the first valid base64 encoded line. | ||
| 2649 | |||
| 2650 | hope this helps a bit. | ||
| 2651 | eric | ||
| 2652 | -- | ||
| 2653 | Eric Young | BOOL is tri-state according to Bill Gates. | ||
| 2654 | AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). | ||
| 2655 | |||
| 2656 | ==== conf.doc ======================================================== | ||
| 2657 | |||
| 2658 | The CONF library. | ||
| 2659 | |||
| 2660 | The CONF library is a simple set of routines that can be used to configure | ||
| 2661 | programs. It is a superset of the genenv() function with some extra | ||
| 2662 | structure. | ||
| 2663 | |||
| 2664 | The library consists of 5 functions. | ||
| 2665 | |||
| 2666 | LHASH *CONF_load(LHASH *config,char *file); | ||
| 2667 | This function is called to load in a configuration file. Multiple | ||
| 2668 | configuration files can be loaded, with each subsequent 'load' overwriting | ||
| 2669 | any already defined 'variables'. If there is an error, NULL is returned. | ||
| 2670 | If config is NULL, a new LHASH structure is created and returned, otherwise | ||
| 2671 | the new data in the 'file' is loaded into the 'config' structure. | ||
| 2672 | |||
| 2673 | void CONF_free(LHASH *config); | ||
| 2674 | This function free()s the data in config. | ||
| 2675 | |||
| 2676 | char *CONF_get_string(LHASH *config,char *section,char *name); | ||
| 2677 | This function returns the string found in 'config' that corresponds to the | ||
| 2678 | 'section' and 'name' specified. Classes and the naming system used will be | ||
| 2679 | discussed later in this document. If the variable is not defined, an NULL | ||
| 2680 | is returned. | ||
| 2681 | |||
| 2682 | long CONF_get_long(LHASH *config,char *section, char *name); | ||
| 2683 | This function is the same as CONF_get_string() except that it converts the | ||
| 2684 | string to an long and returns it. If variable is not a number or the | ||
| 2685 | variable does not exist, 0 is returned. This is a little problematic but I | ||
| 2686 | don't know of a simple way around it. | ||
| 2687 | |||
| 2688 | STACK *CONF_get_section(LHASH *config, char *section); | ||
| 2689 | This function returns a 'stack' of CONF_VALUE items that are all the | ||
| 2690 | items defined in a particular section. DO NOT free() any of the | ||
| 2691 | variable returned. They will disappear when CONF_free() is called. | ||
| 2692 | |||
| 2693 | The 'lookup' model. | ||
| 2694 | The configuration file is divided into 'sections'. Each section is started by | ||
| 2695 | a line of the form '[ section ]'. All subsequent variable definitions are | ||
| 2696 | of this section. A variable definition is a simple alpha-numeric name | ||
| 2697 | followed by an '=' and then the data. A section or variable name can be | ||
| 2698 | described by a regular expression of the following form '[A-Za-z0-9_]+'. | ||
| 2699 | The value of the variable is the text after the '=' until the end of the | ||
| 2700 | line, stripped of leading and trailing white space. | ||
| 2701 | At this point I should mention that a '#' is a comment character, \ is the | ||
| 2702 | escape character, and all three types of quote can be used to stop any | ||
| 2703 | special interpretation of the data. | ||
| 2704 | Now when the data is being loaded, variable expansion can occur. This is | ||
| 2705 | done by expanding any $NAME sequences into the value represented by the | ||
| 2706 | variable NAME. If the variable is not in the current section, the different | ||
| 2707 | section can be specified by using the $SECTION::NAME form. The ${NAME} form | ||
| 2708 | also works and is very useful for expanding variables inside strings. | ||
| 2709 | |||
| 2710 | When a variable is looked up, there are 2 special section. 'default', which | ||
| 2711 | is the initial section, and 'ENV' which is the processes environment | ||
| 2712 | variables (accessed via getenv()). When a variable is looked up, it is | ||
| 2713 | first 'matched' with it's section (if one was specified), if this fails, the | ||
| 2714 | 'default' section is matched. | ||
| 2715 | If the 'lhash' variable passed was NULL, the environment is searched. | ||
| 2716 | |||
| 2717 | Now why do we bother with sections? So we can have multiple programs using | ||
| 2718 | the same configuration file, or multiple instances of the same program | ||
| 2719 | using different variables. It also provides a nice mechanism to override | ||
| 2720 | the processes environment variables (eg ENV::HOME=/tmp). If there is a | ||
| 2721 | program specific variable missing, we can have default values. | ||
| 2722 | Multiple configuration files can be loaded, with each new value clearing | ||
| 2723 | any predefined values. A system config file can provide 'default' values, | ||
| 2724 | and application/usr specific files can provide overriding values. | ||
| 2725 | |||
| 2726 | Examples | ||
| 2727 | |||
| 2728 | # This is a simple example | ||
| 2729 | SSLEAY_HOME = /usr/local/ssl | ||
| 2730 | ENV::PATH = $SSLEAY_HOME/bin:$PATH # override my path | ||
| 2731 | |||
| 2732 | [X509] | ||
| 2733 | cert_dir = $SSLEAY_HOME/certs # /usr/local/ssl/certs | ||
| 2734 | |||
| 2735 | [SSL] | ||
| 2736 | CIPHER = DES-EDE-MD5:RC4-MD5 | ||
| 2737 | USER_CERT = $HOME/${USER}di'r 5' # /home/eay/eaydir 5 | ||
| 2738 | USER_CERT = $HOME/\${USER}di\'r # /home/eay/${USER}di'r | ||
| 2739 | USER_CERT = "$HOME/${US"ER}di\'r # $HOME/${USER}di'r | ||
| 2740 | |||
| 2741 | TEST = 1234\ | ||
| 2742 | 5678\ | ||
| 2743 | 9ab # TEST=123456789ab | ||
| 2744 | TTT = 1234\n\n # TTT=1234<nl><nl> | ||
| 2745 | |||
| 2746 | |||
| 2747 | |||
| 2748 | ==== des.doc ======================================================== | ||
| 2749 | |||
| 2750 | The DES library. | ||
| 2751 | |||
| 2752 | Please note that this library was originally written to operate with | ||
| 2753 | eBones, a version of Kerberos that had had encryption removed when it left | ||
| 2754 | the USA and then put back in. As such there are some routines that I will | ||
| 2755 | advise not using but they are still in the library for historical reasons. | ||
| 2756 | For all calls that have an 'input' and 'output' variables, they can be the | ||
| 2757 | same. | ||
| 2758 | |||
| 2759 | This library requires the inclusion of 'des.h'. | ||
| 2760 | |||
| 2761 | All of the encryption functions take what is called a des_key_schedule as an | ||
| 2762 | argument. A des_key_schedule is an expanded form of the des key. | ||
| 2763 | A des_key is 8 bytes of odd parity, the type used to hold the key is a | ||
| 2764 | des_cblock. A des_cblock is an array of 8 bytes, often in this library | ||
| 2765 | description I will refer to input bytes when the function specifies | ||
| 2766 | des_cblock's as input or output, this just means that the variable should | ||
| 2767 | be a multiple of 8 bytes. | ||
| 2768 | |||
| 2769 | The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to | ||
| 2770 | specify decryption. The functions and global variable are as follows: | ||
| 2771 | |||
| 2772 | int des_check_key; | ||
| 2773 | DES keys are supposed to be odd parity. If this variable is set to | ||
| 2774 | a non-zero value, des_set_key() will check that the key has odd | ||
| 2775 | parity and is not one of the known weak DES keys. By default this | ||
| 2776 | variable is turned off; | ||
| 2777 | |||
| 2778 | void des_set_odd_parity( | ||
| 2779 | des_cblock *key ); | ||
| 2780 | This function takes a DES key (8 bytes) and sets the parity to odd. | ||
| 2781 | |||
| 2782 | int des_is_weak_key( | ||
| 2783 | des_cblock *key ); | ||
| 2784 | This function returns a non-zero value if the DES key passed is a | ||
| 2785 | weak, DES key. If it is a weak key, don't use it, try a different | ||
| 2786 | one. If you are using 'random' keys, the chances of hitting a weak | ||
| 2787 | key are 1/2^52 so it is probably not worth checking for them. | ||
| 2788 | |||
| 2789 | int des_set_key( | ||
| 2790 | des_cblock *key, | ||
| 2791 | des_key_schedule schedule); | ||
| 2792 | Des_set_key converts an 8 byte DES key into a des_key_schedule. | ||
| 2793 | A des_key_schedule is an expanded form of the key which is used to | ||
| 2794 | perform actual encryption. It can be regenerated from the DES key | ||
| 2795 | so it only needs to be kept when encryption or decryption is about | ||
| 2796 | to occur. Don't save or pass around des_key_schedule's since they | ||
| 2797 | are CPU architecture dependent, DES keys are not. If des_check_key | ||
| 2798 | is non zero, zero is returned if the key has the wrong parity or | ||
| 2799 | the key is a weak key, else 1 is returned. | ||
| 2800 | |||
| 2801 | int des_key_sched( | ||
| 2802 | des_cblock *key, | ||
| 2803 | des_key_schedule schedule); | ||
| 2804 | An alternative name for des_set_key(). | ||
| 2805 | |||
| 2806 | int des_rw_mode; /* defaults to DES_PCBC_MODE */ | ||
| 2807 | This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default). | ||
| 2808 | This specifies the function to use in the enc_read() and enc_write() | ||
| 2809 | functions. | ||
| 2810 | |||
| 2811 | void des_encrypt( | ||
| 2812 | unsigned long *data, | ||
| 2813 | des_key_schedule ks, | ||
| 2814 | int enc); | ||
| 2815 | This is the DES encryption function that gets called by just about | ||
| 2816 | every other DES routine in the library. You should not use this | ||
| 2817 | function except to implement 'modes' of DES. I say this because the | ||
| 2818 | functions that call this routine do the conversion from 'char *' to | ||
| 2819 | long, and this needs to be done to make sure 'non-aligned' memory | ||
| 2820 | access do not occur. The characters are loaded 'little endian', | ||
| 2821 | have a look at my source code for more details on how I use this | ||
| 2822 | function. | ||
| 2823 | Data is a pointer to 2 unsigned long's and ks is the | ||
| 2824 | des_key_schedule to use. enc, is non zero specifies encryption, | ||
| 2825 | zero if decryption. | ||
| 2826 | |||
| 2827 | void des_encrypt2( | ||
| 2828 | unsigned long *data, | ||
| 2829 | des_key_schedule ks, | ||
| 2830 | int enc); | ||
| 2831 | This functions is the same as des_encrypt() except that the DES | ||
| 2832 | initial permutation (IP) and final permutation (FP) have been left | ||
| 2833 | out. As for des_encrypt(), you should not use this function. | ||
| 2834 | It is used by the routines in my library that implement triple DES. | ||
| 2835 | IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same | ||
| 2836 | as des_encrypt() des_encrypt() des_encrypt() except faster :-). | ||
| 2837 | |||
| 2838 | void des_ecb_encrypt( | ||
| 2839 | des_cblock *input, | ||
| 2840 | des_cblock *output, | ||
| 2841 | des_key_schedule ks, | ||
| 2842 | int enc); | ||
| 2843 | This is the basic Electronic Code Book form of DES, the most basic | ||
| 2844 | form. Input is encrypted into output using the key represented by | ||
| 2845 | ks. If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise | ||
| 2846 | decryption occurs. Input is 8 bytes long and output is 8 bytes. | ||
| 2847 | (the des_cblock structure is 8 chars). | ||
| 2848 | |||
| 2849 | void des_ecb3_encrypt( | ||
| 2850 | des_cblock *input, | ||
| 2851 | des_cblock *output, | ||
| 2852 | des_key_schedule ks1, | ||
| 2853 | des_key_schedule ks2, | ||
| 2854 | des_key_schedule ks3, | ||
| 2855 | int enc); | ||
| 2856 | This is the 3 key EDE mode of ECB DES. What this means is that | ||
| 2857 | the 8 bytes of input is encrypted with ks1, decrypted with ks2 and | ||
| 2858 | then encrypted again with ks3, before being put into output; | ||
| 2859 | C=E(ks3,D(ks2,E(ks1,M))). There is a macro, des_ecb2_encrypt() | ||
| 2860 | that only takes 2 des_key_schedules that implements, | ||
| 2861 | C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1. | ||
| 2862 | |||
| 2863 | void des_cbc_encrypt( | ||
| 2864 | des_cblock *input, | ||
| 2865 | des_cblock *output, | ||
| 2866 | long length, | ||
| 2867 | des_key_schedule ks, | ||
| 2868 | des_cblock *ivec, | ||
| 2869 | int enc); | ||
| 2870 | This routine implements DES in Cipher Block Chaining mode. | ||
| 2871 | Input, which should be a multiple of 8 bytes is encrypted | ||
| 2872 | (or decrypted) to output which will also be a multiple of 8 bytes. | ||
| 2873 | The number of bytes is in length (and from what I've said above, | ||
| 2874 | should be a multiple of 8). If length is not a multiple of 8, I'm | ||
| 2875 | not being held responsible :-). ivec is the initialisation vector. | ||
| 2876 | This function does not modify this variable. To correctly implement | ||
| 2877 | cbc mode, you need to do one of 2 things; copy the last 8 bytes of | ||
| 2878 | cipher text for use as the next ivec in your application, | ||
| 2879 | or use des_ncbc_encrypt(). | ||
| 2880 | Only this routine has this problem with updating the ivec, all | ||
| 2881 | other routines that are implementing cbc mode update ivec. | ||
| 2882 | |||
| 2883 | void des_ncbc_encrypt( | ||
| 2884 | des_cblock *input, | ||
| 2885 | des_cblock *output, | ||
| 2886 | long length, | ||
| 2887 | des_key_schedule sk, | ||
| 2888 | des_cblock *ivec, | ||
| 2889 | int enc); | ||
| 2890 | For historical reasons, des_cbc_encrypt() did not update the | ||
| 2891 | ivec with the value requires so that subsequent calls to | ||
| 2892 | des_cbc_encrypt() would 'chain'. This was needed so that the same | ||
| 2893 | 'length' values would not need to be used when decrypting. | ||
| 2894 | des_ncbc_encrypt() does the right thing. It is the same as | ||
| 2895 | des_cbc_encrypt accept that ivec is updates with the correct value | ||
| 2896 | to pass in subsequent calls to des_ncbc_encrypt(). I advise using | ||
| 2897 | des_ncbc_encrypt() instead of des_cbc_encrypt(); | ||
| 2898 | |||
| 2899 | void des_xcbc_encrypt( | ||
| 2900 | des_cblock *input, | ||
| 2901 | des_cblock *output, | ||
| 2902 | long length, | ||
| 2903 | des_key_schedule sk, | ||
| 2904 | des_cblock *ivec, | ||
| 2905 | des_cblock *inw, | ||
| 2906 | des_cblock *outw, | ||
| 2907 | int enc); | ||
| 2908 | This is RSA's DESX mode of DES. It uses inw and outw to | ||
| 2909 | 'whiten' the encryption. inw and outw are secret (unlike the iv) | ||
| 2910 | and are as such, part of the key. So the key is sort of 24 bytes. | ||
| 2911 | This is much better than cbc des. | ||
| 2912 | |||
| 2913 | void des_3cbc_encrypt( | ||
| 2914 | des_cblock *input, | ||
| 2915 | des_cblock *output, | ||
| 2916 | long length, | ||
| 2917 | des_key_schedule sk1, | ||
| 2918 | des_key_schedule sk2, | ||
| 2919 | des_cblock *ivec1, | ||
| 2920 | des_cblock *ivec2, | ||
| 2921 | int enc); | ||
| 2922 | This function is flawed, do not use it. I have left it in the | ||
| 2923 | library because it is used in my des(1) program and will function | ||
| 2924 | correctly when used by des(1). If I removed the function, people | ||
| 2925 | could end up unable to decrypt files. | ||
| 2926 | This routine implements outer triple cbc encryption using 2 ks and | ||
| 2927 | 2 ivec's. Use des_ede2_cbc_encrypt() instead. | ||
| 2928 | |||
| 2929 | void des_ede3_cbc_encrypt( | ||
| 2930 | des_cblock *input, | ||
| 2931 | des_cblock *output, | ||
| 2932 | long length, | ||
| 2933 | des_key_schedule ks1, | ||
| 2934 | des_key_schedule ks2, | ||
| 2935 | des_key_schedule ks3, | ||
| 2936 | des_cblock *ivec, | ||
| 2937 | int enc); | ||
| 2938 | This function implements outer triple CBC DES encryption with 3 | ||
| 2939 | keys. What this means is that each 'DES' operation | ||
| 2940 | inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))). | ||
| 2941 | Again, this is cbc mode so an ivec is requires. | ||
| 2942 | This mode is used by SSL. | ||
| 2943 | There is also a des_ede2_cbc_encrypt() that only uses 2 | ||
| 2944 | des_key_schedule's, the first being reused for the final | ||
| 2945 | encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of triple DES | ||
| 2946 | is used by the RSAref library. | ||
| 2947 | |||
| 2948 | void des_pcbc_encrypt( | ||
| 2949 | des_cblock *input, | ||
| 2950 | des_cblock *output, | ||
| 2951 | long length, | ||
| 2952 | des_key_schedule ks, | ||
| 2953 | des_cblock *ivec, | ||
| 2954 | int enc); | ||
| 2955 | This is Propagating Cipher Block Chaining mode of DES. It is used | ||
| 2956 | by Kerberos v4. It's parameters are the same as des_ncbc_encrypt(). | ||
| 2957 | |||
| 2958 | void des_cfb_encrypt( | ||
| 2959 | unsigned char *in, | ||
| 2960 | unsigned char *out, | ||
| 2961 | int numbits, | ||
| 2962 | long length, | ||
| 2963 | des_key_schedule ks, | ||
| 2964 | des_cblock *ivec, | ||
| 2965 | int enc); | ||
| 2966 | Cipher Feedback Back mode of DES. This implementation 'feeds back' | ||
| 2967 | in numbit blocks. The input (and output) is in multiples of numbits | ||
| 2968 | bits. numbits should to be a multiple of 8 bits. Length is the | ||
| 2969 | number of bytes input. If numbits is not a multiple of 8 bits, | ||
| 2970 | the extra bits in the bytes will be considered padding. So if | ||
| 2971 | numbits is 12, for each 2 input bytes, the 4 high bits of the | ||
| 2972 | second byte will be ignored. So to encode 72 bits when using | ||
| 2973 | a numbits of 12 take 12 bytes. To encode 72 bits when using | ||
| 2974 | numbits of 9 will take 16 bytes. To encode 80 bits when using | ||
| 2975 | numbits of 16 will take 10 bytes. etc, etc. This padding will | ||
| 2976 | apply to both input and output. | ||
| 2977 | |||
| 2978 | |||
| 2979 | void des_cfb64_encrypt( | ||
| 2980 | unsigned char *in, | ||
| 2981 | unsigned char *out, | ||
| 2982 | long length, | ||
| 2983 | des_key_schedule ks, | ||
| 2984 | des_cblock *ivec, | ||
| 2985 | int *num, | ||
| 2986 | int enc); | ||
| 2987 | This is one of the more useful functions in this DES library, it | ||
| 2988 | implements CFB mode of DES with 64bit feedback. Why is this | ||
| 2989 | useful you ask? Because this routine will allow you to encrypt an | ||
| 2990 | arbitrary number of bytes, no 8 byte padding. Each call to this | ||
| 2991 | routine will encrypt the input bytes to output and then update ivec | ||
| 2992 | and num. num contains 'how far' we are though ivec. If this does | ||
| 2993 | not make much sense, read more about cfb mode of DES :-). | ||
| 2994 | |||
| 2995 | void des_ede3_cfb64_encrypt( | ||
| 2996 | unsigned char *in, | ||
| 2997 | unsigned char *out, | ||
| 2998 | long length, | ||
| 2999 | des_key_schedule ks1, | ||
| 3000 | des_key_schedule ks2, | ||
| 3001 | des_key_schedule ks3, | ||
| 3002 | des_cblock *ivec, | ||
| 3003 | int *num, | ||
| 3004 | int enc); | ||
| 3005 | Same as des_cfb64_encrypt() accept that the DES operation is | ||
| 3006 | triple DES. As usual, there is a macro for | ||
| 3007 | des_ede2_cfb64_encrypt() which reuses ks1. | ||
| 3008 | |||
| 3009 | void des_ofb_encrypt( | ||
| 3010 | unsigned char *in, | ||
| 3011 | unsigned char *out, | ||
| 3012 | int numbits, | ||
| 3013 | long length, | ||
| 3014 | des_key_schedule ks, | ||
| 3015 | des_cblock *ivec); | ||
| 3016 | This is a implementation of Output Feed Back mode of DES. It is | ||
| 3017 | the same as des_cfb_encrypt() in that numbits is the size of the | ||
| 3018 | units dealt with during input and output (in bits). | ||
| 3019 | |||
| 3020 | void des_ofb64_encrypt( | ||
| 3021 | unsigned char *in, | ||
| 3022 | unsigned char *out, | ||
| 3023 | long length, | ||
| 3024 | des_key_schedule ks, | ||
| 3025 | des_cblock *ivec, | ||
| 3026 | int *num); | ||
| 3027 | The same as des_cfb64_encrypt() except that it is Output Feed Back | ||
| 3028 | mode. | ||
| 3029 | |||
| 3030 | void des_ede3_ofb64_encrypt( | ||
| 3031 | unsigned char *in, | ||
| 3032 | unsigned char *out, | ||
| 3033 | long length, | ||
| 3034 | des_key_schedule ks1, | ||
| 3035 | des_key_schedule ks2, | ||
| 3036 | des_key_schedule ks3, | ||
| 3037 | des_cblock *ivec, | ||
| 3038 | int *num); | ||
| 3039 | Same as des_ofb64_encrypt() accept that the DES operation is | ||
| 3040 | triple DES. As usual, there is a macro for | ||
| 3041 | des_ede2_ofb64_encrypt() which reuses ks1. | ||
| 3042 | |||
| 3043 | int des_read_pw_string( | ||
| 3044 | char *buf, | ||
| 3045 | int length, | ||
| 3046 | char *prompt, | ||
| 3047 | int verify); | ||
| 3048 | This routine is used to get a password from the terminal with echo | ||
| 3049 | turned off. Buf is where the string will end up and length is the | ||
| 3050 | size of buf. Prompt is a string presented to the 'user' and if | ||
| 3051 | verify is set, the key is asked for twice and unless the 2 copies | ||
| 3052 | match, an error is returned. A return code of -1 indicates a | ||
| 3053 | system error, 1 failure due to use interaction, and 0 is success. | ||
| 3054 | |||
| 3055 | unsigned long des_cbc_cksum( | ||
| 3056 | des_cblock *input, | ||
| 3057 | des_cblock *output, | ||
| 3058 | long length, | ||
| 3059 | des_key_schedule ks, | ||
| 3060 | des_cblock *ivec); | ||
| 3061 | This function produces an 8 byte checksum from input that it puts in | ||
| 3062 | output and returns the last 4 bytes as a long. The checksum is | ||
| 3063 | generated via cbc mode of DES in which only the last 8 byes are | ||
| 3064 | kept. I would recommend not using this function but instead using | ||
| 3065 | the EVP_Digest routines, or at least using MD5 or SHA. This | ||
| 3066 | function is used by Kerberos v4 so that is why it stays in the | ||
| 3067 | library. | ||
| 3068 | |||
| 3069 | char *des_fcrypt( | ||
| 3070 | const char *buf, | ||
| 3071 | const char *salt | ||
| 3072 | char *ret); | ||
| 3073 | This is my fast version of the unix crypt(3) function. This version | ||
| 3074 | takes only a small amount of space relative to other fast | ||
| 3075 | crypt() implementations. This is different to the normal crypt | ||
| 3076 | in that the third parameter is the buffer that the return value | ||
| 3077 | is written into. It needs to be at least 14 bytes long. This | ||
| 3078 | function is thread safe, unlike the normal crypt. | ||
| 3079 | |||
| 3080 | char *crypt( | ||
| 3081 | const char *buf, | ||
| 3082 | const char *salt); | ||
| 3083 | This function calls des_fcrypt() with a static array passed as the | ||
| 3084 | third parameter. This emulates the normal non-thread safe semantics | ||
| 3085 | of crypt(3). | ||
| 3086 | |||
| 3087 | void des_string_to_key( | ||
| 3088 | char *str, | ||
| 3089 | des_cblock *key); | ||
| 3090 | This function takes str and converts it into a DES key. I would | ||
| 3091 | recommend using MD5 instead and use the first 8 bytes of output. | ||
| 3092 | When I wrote the first version of these routines back in 1990, MD5 | ||
| 3093 | did not exist but I feel these routines are still sound. This | ||
| 3094 | routines is compatible with the one in MIT's libdes. | ||
| 3095 | |||
| 3096 | void des_string_to_2keys( | ||
| 3097 | char *str, | ||
| 3098 | des_cblock *key1, | ||
| 3099 | des_cblock *key2); | ||
| 3100 | This function takes str and converts it into 2 DES keys. | ||
| 3101 | I would recommend using MD5 and using the 16 bytes as the 2 keys. | ||
| 3102 | I have nothing against these 2 'string_to_key' routines, it's just | ||
| 3103 | that if you say that your encryption key is generated by using the | ||
| 3104 | 16 bytes of an MD5 hash, every-one knows how you generated your | ||
| 3105 | keys. | ||
| 3106 | |||
| 3107 | int des_read_password( | ||
| 3108 | des_cblock *key, | ||
| 3109 | char *prompt, | ||
| 3110 | int verify); | ||
| 3111 | This routine combines des_read_pw_string() with des_string_to_key(). | ||
| 3112 | |||
| 3113 | int des_read_2passwords( | ||
| 3114 | des_cblock *key1, | ||
| 3115 | des_cblock *key2, | ||
| 3116 | char *prompt, | ||
| 3117 | int verify); | ||
| 3118 | This routine combines des_read_pw_string() with des_string_to_2key(). | ||
| 3119 | |||
| 3120 | void des_random_seed( | ||
| 3121 | des_cblock key); | ||
| 3122 | This routine sets a starting point for des_random_key(). | ||
| 3123 | |||
| 3124 | void des_random_key( | ||
| 3125 | des_cblock ret); | ||
| 3126 | This function return a random key. Make sure to 'seed' the random | ||
| 3127 | number generator (with des_random_seed()) before using this function. | ||
| 3128 | I personally now use a MD5 based random number system. | ||
| 3129 | |||
| 3130 | int des_enc_read( | ||
| 3131 | int fd, | ||
| 3132 | char *buf, | ||
| 3133 | int len, | ||
| 3134 | des_key_schedule ks, | ||
| 3135 | des_cblock *iv); | ||
| 3136 | This function will write to a file descriptor the encrypted data | ||
| 3137 | from buf. This data will be preceded by a 4 byte 'byte count' and | ||
| 3138 | will be padded out to 8 bytes. The encryption is either CBC of | ||
| 3139 | PCBC depending on the value of des_rw_mode. If it is DES_PCBC_MODE, | ||
| 3140 | pcbc is used, if DES_CBC_MODE, cbc is used. The default is to use | ||
| 3141 | DES_PCBC_MODE. | ||
| 3142 | |||
| 3143 | int des_enc_write( | ||
| 3144 | int fd, | ||
| 3145 | char *buf, | ||
| 3146 | int len, | ||
| 3147 | des_key_schedule ks, | ||
| 3148 | des_cblock *iv); | ||
| 3149 | This routines read stuff written by des_enc_read() and decrypts it. | ||
| 3150 | I have used these routines quite a lot but I don't believe they are | ||
| 3151 | suitable for non-blocking io. If you are after a full | ||
| 3152 | authentication/encryption over networks, have a look at SSL instead. | ||
| 3153 | |||
| 3154 | unsigned long des_quad_cksum( | ||
| 3155 | des_cblock *input, | ||
| 3156 | des_cblock *output, | ||
| 3157 | long length, | ||
| 3158 | int out_count, | ||
| 3159 | des_cblock *seed); | ||
| 3160 | This is a function from Kerberos v4 that is not anything to do with | ||
| 3161 | DES but was needed. It is a cksum that is quicker to generate than | ||
| 3162 | des_cbc_cksum(); I personally would use MD5 routines now. | ||
| 3163 | ===== | ||
| 3164 | Modes of DES | ||
| 3165 | Quite a bit of the following information has been taken from | ||
| 3166 | AS 2805.5.2 | ||
| 3167 | Australian Standard | ||
| 3168 | Electronic funds transfer - Requirements for interfaces, | ||
| 3169 | Part 5.2: Modes of operation for an n-bit block cipher algorithm | ||
| 3170 | Appendix A | ||
| 3171 | |||
| 3172 | There are several different modes in which DES can be used, they are | ||
| 3173 | as follows. | ||
| 3174 | |||
| 3175 | Electronic Codebook Mode (ECB) (des_ecb_encrypt()) | ||
| 3176 | - 64 bits are enciphered at a time. | ||
| 3177 | - The order of the blocks can be rearranged without detection. | ||
| 3178 | - The same plaintext block always produces the same ciphertext block | ||
| 3179 | (for the same key) making it vulnerable to a 'dictionary attack'. | ||
| 3180 | - An error will only affect one ciphertext block. | ||
| 3181 | |||
| 3182 | Cipher Block Chaining Mode (CBC) (des_cbc_encrypt()) | ||
| 3183 | - a multiple of 64 bits are enciphered at a time. | ||
| 3184 | - The CBC mode produces the same ciphertext whenever the same | ||
| 3185 | plaintext is encrypted using the same key and starting variable. | ||
| 3186 | - The chaining operation makes the ciphertext blocks dependent on the | ||
| 3187 | current and all preceding plaintext blocks and therefore blocks can not | ||
| 3188 | be rearranged. | ||
| 3189 | - The use of different starting variables prevents the same plaintext | ||
| 3190 | enciphering to the same ciphertext. | ||
| 3191 | - An error will affect the current and the following ciphertext blocks. | ||
| 3192 | |||
| 3193 | Cipher Feedback Mode (CFB) (des_cfb_encrypt()) | ||
| 3194 | - a number of bits (j) <= 64 are enciphered at a time. | ||
| 3195 | - The CFB mode produces the same ciphertext whenever the same | ||
| 3196 | plaintext is encrypted using the same key and starting variable. | ||
| 3197 | - The chaining operation makes the ciphertext variables dependent on the | ||
| 3198 | current and all preceding variables and therefore j-bit variables are | ||
| 3199 | chained together and can not be rearranged. | ||
| 3200 | - The use of different starting variables prevents the same plaintext | ||
| 3201 | enciphering to the same ciphertext. | ||
| 3202 | - The strength of the CFB mode depends on the size of k (maximal if | ||
| 3203 | j == k). In my implementation this is always the case. | ||
| 3204 | - Selection of a small value for j will require more cycles through | ||
| 3205 | the encipherment algorithm per unit of plaintext and thus cause | ||
| 3206 | greater processing overheads. | ||
| 3207 | - Only multiples of j bits can be enciphered. | ||
| 3208 | - An error will affect the current and the following ciphertext variables. | ||
| 3209 | |||
| 3210 | Output Feedback Mode (OFB) (des_ofb_encrypt()) | ||
| 3211 | - a number of bits (j) <= 64 are enciphered at a time. | ||
| 3212 | - The OFB mode produces the same ciphertext whenever the same | ||
| 3213 | plaintext enciphered using the same key and starting variable. More | ||
| 3214 | over, in the OFB mode the same key stream is produced when the same | ||
| 3215 | key and start variable are used. Consequently, for security reasons | ||
| 3216 | a specific start variable should be used only once for a given key. | ||
| 3217 | - The absence of chaining makes the OFB more vulnerable to specific attacks. | ||
| 3218 | - The use of different start variables values prevents the same | ||
| 3219 | plaintext enciphering to the same ciphertext, by producing different | ||
| 3220 | key streams. | ||
| 3221 | - Selection of a small value for j will require more cycles through | ||
| 3222 | the encipherment algorithm per unit of plaintext and thus cause | ||
| 3223 | greater processing overheads. | ||
| 3224 | - Only multiples of j bits can be enciphered. | ||
| 3225 | - OFB mode of operation does not extend ciphertext errors in the | ||
| 3226 | resultant plaintext output. Every bit error in the ciphertext causes | ||
| 3227 | only one bit to be in error in the deciphered plaintext. | ||
| 3228 | - OFB mode is not self-synchronising. If the two operation of | ||
| 3229 | encipherment and decipherment get out of synchronism, the system needs | ||
| 3230 | to be re-initialised. | ||
| 3231 | - Each re-initialisation should use a value of the start variable | ||
| 3232 | different from the start variable values used before with the same | ||
| 3233 | key. The reason for this is that an identical bit stream would be | ||
| 3234 | produced each time from the same parameters. This would be | ||
| 3235 | susceptible to a ' known plaintext' attack. | ||
| 3236 | |||
| 3237 | Triple ECB Mode (des_ecb3_encrypt()) | ||
| 3238 | - Encrypt with key1, decrypt with key2 and encrypt with key3 again. | ||
| 3239 | - As for ECB encryption but increases the key length to 168 bits. | ||
| 3240 | There are theoretic attacks that can be used that make the effective | ||
| 3241 | key length 112 bits, but this attack also requires 2^56 blocks of | ||
| 3242 | memory, not very likely, even for the NSA. | ||
| 3243 | - If both keys are the same it is equivalent to encrypting once with | ||
| 3244 | just one key. | ||
| 3245 | - If the first and last key are the same, the key length is 112 bits. | ||
| 3246 | There are attacks that could reduce the key space to 55 bit's but it | ||
| 3247 | requires 2^56 blocks of memory. | ||
| 3248 | - If all 3 keys are the same, this is effectively the same as normal | ||
| 3249 | ecb mode. | ||
| 3250 | |||
| 3251 | Triple CBC Mode (des_ede3_cbc_encrypt()) | ||
| 3252 | - Encrypt with key1, decrypt with key2 and then encrypt with key3. | ||
| 3253 | - As for CBC encryption but increases the key length to 168 bits with | ||
| 3254 | the same restrictions as for triple ecb mode. | ||
| 3255 | |||
| 3256 | ==== digest.doc ======================================================== | ||
| 3257 | |||
| 3258 | |||
| 3259 | The Message Digest subroutines. | ||
| 3260 | |||
| 3261 | These routines require "evp.h" to be included. | ||
| 3262 | |||
| 3263 | These functions are a higher level interface to the various message digest | ||
| 3264 | routines found in this library. As such, they allow the same code to be | ||
| 3265 | used to digest via different algorithms with only a change in an initial | ||
| 3266 | parameter. They are basically just a front-end to the MD2, MD5, SHA | ||
| 3267 | and SHA1 | ||
| 3268 | routines. | ||
| 3269 | |||
| 3270 | These routines all take a pointer to the following structure to specify | ||
| 3271 | which message digest algorithm to use. | ||
| 3272 | typedef struct evp_md_st | ||
| 3273 | { | ||
| 3274 | int type; | ||
| 3275 | int pkey_type; | ||
| 3276 | int md_size; | ||
| 3277 | void (*init)(); | ||
| 3278 | void (*update)(); | ||
| 3279 | void (*final)(); | ||
| 3280 | |||
| 3281 | int required_pkey_type; /*EVP_PKEY_xxx */ | ||
| 3282 | int (*sign)(); | ||
| 3283 | int (*verify)(); | ||
| 3284 | } EVP_MD; | ||
| 3285 | |||
| 3286 | If additional message digest algorithms are to be supported, a structure of | ||
| 3287 | this type needs to be declared and populated and then the Digest routines | ||
| 3288 | can be used with that algorithm. The type field is the object NID of the | ||
| 3289 | digest type (read the section on Objects for an explanation). The pkey_type | ||
| 3290 | is the Object type to use when the a message digest is generated by there | ||
| 3291 | routines and then is to be signed with the pkey algorithm. Md_size is | ||
| 3292 | the size of the message digest returned. Init, update | ||
| 3293 | and final are the relevant functions to perform the message digest function | ||
| 3294 | by parts. One reason for specifying the message digest to use via this | ||
| 3295 | mechanism is that if you only use md5, only the md5 routines will | ||
| 3296 | be included in you linked program. If you passed an integer | ||
| 3297 | that specified which message digest to use, the routine that mapped that | ||
| 3298 | integer to a set of message digest functions would cause all the message | ||
| 3299 | digests functions to be link into the code. This setup also allows new | ||
| 3300 | message digest functions to be added by the application. | ||
| 3301 | |||
| 3302 | The six message digests defined in this library are | ||
| 3303 | |||
| 3304 | EVP_MD *EVP_md2(void); /* RSA sign/verify */ | ||
| 3305 | EVP_MD *EVP_md5(void); /* RSA sign/verify */ | ||
| 3306 | EVP_MD *EVP_sha(void); /* RSA sign/verify */ | ||
| 3307 | EVP_MD *EVP_sha1(void); /* RSA sign/verify */ | ||
| 3308 | EVP_MD *EVP_dss(void); /* DSA sign/verify */ | ||
| 3309 | EVP_MD *EVP_dss1(void); /* DSA sign/verify */ | ||
| 3310 | |||
| 3311 | All the message digest routines take a EVP_MD_CTX pointer as an argument. | ||
| 3312 | The state of the message digest is kept in this structure. | ||
| 3313 | |||
| 3314 | typedef struct pem_md_ctx_st | ||
| 3315 | { | ||
| 3316 | EVP_MD *digest; | ||
| 3317 | union { | ||
| 3318 | unsigned char base[4]; /* this is used in my library as a | ||
| 3319 | * 'pointer' to all union elements | ||
| 3320 | * structures. */ | ||
| 3321 | MD2_CTX md2; | ||
| 3322 | MD5_CTX md5; | ||
| 3323 | SHA_CTX sha; | ||
| 3324 | } md; | ||
| 3325 | } EVP_MD_CTX; | ||
| 3326 | |||
| 3327 | The Digest functions are as follows. | ||
| 3328 | |||
| 3329 | void EVP_DigestInit( | ||
| 3330 | EVP_MD_CTX *ctx, | ||
| 3331 | EVP_MD *type); | ||
| 3332 | This function is used to initialise the EVP_MD_CTX. The message | ||
| 3333 | digest that will associated with 'ctx' is specified by 'type'. | ||
| 3334 | |||
| 3335 | void EVP_DigestUpdate( | ||
| 3336 | EVP_MD_CTX *ctx, | ||
| 3337 | unsigned char *data, | ||
| 3338 | unsigned int cnt); | ||
| 3339 | This function is used to pass more data to the message digest | ||
| 3340 | function. 'cnt' bytes are digested from 'data'. | ||
| 3341 | |||
| 3342 | void EVP_DigestFinal( | ||
| 3343 | EVP_MD_CTX *ctx, | ||
| 3344 | unsigned char *md, | ||
| 3345 | unsigned int *len); | ||
| 3346 | This function finishes the digestion and puts the message digest | ||
| 3347 | into 'md'. The length of the message digest is put into len; | ||
| 3348 | EVP_MAX_MD_SIZE is the size of the largest message digest that | ||
| 3349 | can be returned from this function. Len can be NULL if the | ||
| 3350 | size of the digest is not required. | ||
| 3351 | |||
| 3352 | |||
| 3353 | ==== encode.doc ======================================================== | ||
| 3354 | |||
| 3355 | |||
| 3356 | void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); | ||
| 3357 | void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out, | ||
| 3358 | int *outl,unsigned char *in,int inl); | ||
| 3359 | void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl); | ||
| 3360 | int EVP_EncodeBlock(unsigned char *t, unsigned char *f, int n); | ||
| 3361 | |||
| 3362 | void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); | ||
| 3363 | int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl, | ||
| 3364 | unsigned char *in, int inl); | ||
| 3365 | int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned | ||
| 3366 | char *out, int *outl); | ||
| 3367 | int EVP_DecodeBlock(unsigned char *t, unsigned | ||
| 3368 | char *f, int n); | ||
| 3369 | |||
| 3370 | |||
| 3371 | ==== envelope.doc ======================================================== | ||
| 3372 | |||
| 3373 | The following routines are use to create 'digital' envelopes. | ||
| 3374 | By this I mean that they perform various 'higher' level cryptographic | ||
| 3375 | functions. Have a read of 'cipher.doc' and 'digest.doc' since those | ||
| 3376 | routines are used by these functions. | ||
| 3377 | cipher.doc contains documentation about the cipher part of the | ||
| 3378 | envelope library and digest.doc contatins the description of the | ||
| 3379 | message digests supported. | ||
| 3380 | |||
| 3381 | To 'sign' a document involves generating a message digest and then encrypting | ||
| 3382 | the digest with an private key. | ||
| 3383 | |||
| 3384 | #define EVP_SignInit(a,b) EVP_DigestInit(a,b) | ||
| 3385 | #define EVP_SignUpdate(a,b,c) EVP_DigestUpdate(a,b,c) | ||
| 3386 | Due to the fact this operation is basically just an extended message | ||
| 3387 | digest, the first 2 functions are macro calls to Digest generating | ||
| 3388 | functions. | ||
| 3389 | |||
| 3390 | int EVP_SignFinal( | ||
| 3391 | EVP_MD_CTX *ctx, | ||
| 3392 | unsigned char *md, | ||
| 3393 | unsigned int *s, | ||
| 3394 | EVP_PKEY *pkey); | ||
| 3395 | This finalisation function finishes the generation of the message | ||
| 3396 | digest and then encrypts the digest (with the correct message digest | ||
| 3397 | object identifier) with the EVP_PKEY private key. 'ctx' is the message digest | ||
| 3398 | context. 'md' will end up containing the encrypted message digest. This | ||
| 3399 | array needs to be EVP_PKEY_size(pkey) bytes long. 's' will actually | ||
| 3400 | contain the exact length. 'pkey' of course is the private key. It is | ||
| 3401 | one of EVP_PKEY_RSA or EVP_PKEY_DSA type. | ||
| 3402 | If there is an error, 0 is returned, otherwise 1. | ||
| 3403 | |||
| 3404 | Verify is used to check an signed message digest. | ||
| 3405 | |||
| 3406 | #define EVP_VerifyInit(a,b) EVP_DigestInit(a,b) | ||
| 3407 | #define EVP_VerifyUpdate(a,b,c) EVP_DigestUpdate(a,b,c) | ||
| 3408 | Since the first step is to generate a message digest, the first 2 functions | ||
| 3409 | are macros. | ||
| 3410 | |||
| 3411 | int EVP_VerifyFinal( | ||
| 3412 | EVP_MD_CTX *ctx, | ||
| 3413 | unsigned char *md, | ||
| 3414 | unsigned int s, | ||
| 3415 | EVP_PKEY *pkey); | ||
| 3416 | This function finishes the generation of the message digest and then | ||
| 3417 | compares it with the supplied encrypted message digest. 'md' contains the | ||
| 3418 | 's' bytes of encrypted message digest. 'pkey' is used to public key decrypt | ||
| 3419 | the digest. It is then compared with the message digest just generated. | ||
| 3420 | If they match, 1 is returned else 0. | ||
| 3421 | |||
| 3422 | int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek, | ||
| 3423 | int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk); | ||
| 3424 | Must have at least one public key, error is 0. I should also mention that | ||
| 3425 | the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size. | ||
| 3426 | |||
| 3427 | #define EVP_SealUpdate(a,b,c,d,e) EVP_EncryptUpdate(a,b,c,d,e) | ||
| 3428 | void EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl); | ||
| 3429 | |||
| 3430 | |||
| 3431 | int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek, | ||
| 3432 | int ekl,unsigned char *iv,EVP_PKEY *priv); | ||
| 3433 | 0 on failure | ||
| 3434 | |||
| 3435 | #define EVP_OpenUpdate(a,b,c,d,e) EVP_DecryptUpdate(a,b,c,d,e) | ||
| 3436 | |||
| 3437 | int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); | ||
| 3438 | Decrypt final return code | ||
| 3439 | |||
| 3440 | |||
| 3441 | ==== error.doc ======================================================== | ||
| 3442 | |||
| 3443 | The error routines. | ||
| 3444 | |||
| 3445 | The 'error' system I've implemented is intended to server 2 purpose, to | ||
| 3446 | record the reason why a command failed and to record where in the libraries | ||
| 3447 | the failure occurred. It is more or less setup to record a 'trace' of which | ||
| 3448 | library components were being traversed when the error occurred. | ||
| 3449 | |||
| 3450 | When an error is recorded, it is done so a as single unsigned long which is | ||
| 3451 | composed of three parts. The top byte is the 'library' number, the middle | ||
| 3452 | 12 bytes is the function code, and the bottom 12 bits is the 'reason' code. | ||
| 3453 | |||
| 3454 | Each 'library', or should a say, 'section' of the SSLeay library has a | ||
| 3455 | different unique 'library' error number. Each function in the library has | ||
| 3456 | a number that is unique for that library. Each 'library' also has a number | ||
| 3457 | for each 'error reason' that is only unique for that 'library'. | ||
| 3458 | |||
| 3459 | Due to the way these error routines record a 'error trace', there is an | ||
| 3460 | array per thread that is used to store the error codes. | ||
| 3461 | The various functions in this library are used to access | ||
| 3462 | and manipulate this array. | ||
| 3463 | |||
| 3464 | void ERR_put_error(int lib, int func,int reason); | ||
| 3465 | This routine records an error in library 'lib', function 'func' | ||
| 3466 | and reason 'reason'. As errors get 'put' into the buffer, they wrap | ||
| 3467 | around and overwrite old errors if too many are written. It is assumed | ||
| 3468 | that the last errors are the most important. | ||
| 3469 | |||
| 3470 | unsigned long ERR_get_error(void ); | ||
| 3471 | This function returns the last error added to the error buffer. | ||
| 3472 | In effect it is popping the value off the buffer so repeated calls will | ||
| 3473 | continue to return values until there are no more errors to return in which | ||
| 3474 | case 0 is returned. | ||
| 3475 | |||
| 3476 | unsigned long ERR_peek_error(void ); | ||
| 3477 | This function returns the value of the last error added to the | ||
| 3478 | error buffer but does not 'pop' it from the buffer. | ||
| 3479 | |||
| 3480 | void ERR_clear_error(void ); | ||
| 3481 | This function clears the error buffer, discarding all unread | ||
| 3482 | errors. | ||
| 3483 | |||
| 3484 | While the above described error system obviously produces lots of different | ||
| 3485 | error number, a method for 'reporting' these errors in a human readable | ||
| 3486 | form is required. To achieve this, each library has the option of | ||
| 3487 | 'registering' error strings. | ||
| 3488 | |||
| 3489 | typedef struct ERR_string_data_st | ||
| 3490 | { | ||
| 3491 | unsigned long error; | ||
| 3492 | char *string; | ||
| 3493 | } ERR_STRING_DATA; | ||
| 3494 | |||
| 3495 | The 'ERR_STRING_DATA' contains an error code and the corresponding text | ||
| 3496 | string. To add new function error strings for a library, the | ||
| 3497 | ERR_STRING_DATA needs to be 'registered' with the library. | ||
| 3498 | |||
| 3499 | void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err); | ||
| 3500 | This function 'registers' the array of ERR_STRING_DATA pointed to by | ||
| 3501 | 'err' as error text strings for the error library 'lib'. | ||
| 3502 | |||
| 3503 | void ERR_free_strings(void); | ||
| 3504 | This function free()s all the loaded error strings. | ||
| 3505 | |||
| 3506 | char *ERR_error_string(unsigned long error,char *buf); | ||
| 3507 | This function returns a text string that is a human readable | ||
| 3508 | version of the error represented by 'error'. Buff should be at least 120 | ||
| 3509 | bytes long and if it is NULL, the return value is a pointer to a static | ||
| 3510 | variable that will contain the error string, otherwise 'buf' is returned. | ||
| 3511 | If there is not a text string registered for a particular error, a text | ||
| 3512 | string containing the error number is returned instead. | ||
| 3513 | |||
| 3514 | void ERR_print_errors(BIO *bp); | ||
| 3515 | void ERR_print_errors_fp(FILE *fp); | ||
| 3516 | This function is a convenience routine that prints the error string | ||
| 3517 | for each error until all errors have been accounted for. | ||
| 3518 | |||
| 3519 | char *ERR_lib_error_string(unsigned long e); | ||
| 3520 | char *ERR_func_error_string(unsigned long e); | ||
| 3521 | char *ERR_reason_error_string(unsigned long e); | ||
| 3522 | The above three functions return the 3 different components strings for the | ||
| 3523 | error 'e'. ERR_error_string() uses these functions. | ||
| 3524 | |||
| 3525 | void ERR_load_ERR_strings(void ); | ||
| 3526 | This function 'registers' the error strings for the 'ERR' module. | ||
| 3527 | |||
| 3528 | void ERR_load_crypto_strings(void ); | ||
| 3529 | This function 'register' the error strings for just about every | ||
| 3530 | library in the SSLeay package except for the SSL routines. There is no | ||
| 3531 | need to ever register any error text strings and you will probably save in | ||
| 3532 | program size. If on the other hand you do 'register' all errors, it is | ||
| 3533 | quite easy to determine why a particular routine failed. | ||
| 3534 | |||
| 3535 | As a final footnote as to why the error system is designed as it is. | ||
| 3536 | 1) I did not want a single 'global' error code. | ||
| 3537 | 2) I wanted to know which subroutine a failure occurred in. | ||
| 3538 | 3) For Windows NT etc, it should be simple to replace the 'key' routines | ||
| 3539 | with code to pass error codes back to the application. | ||
| 3540 | 4) I wanted the option of meaningful error text strings. | ||
| 3541 | |||
| 3542 | Late breaking news - the changes to support threads. | ||
| 3543 | |||
| 3544 | Each 'thread' has an 'ERR_STATE' state associated with it. | ||
| 3545 | ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling | ||
| 3546 | thread/process. | ||
| 3547 | |||
| 3548 | ERR_remove_state(unsigned long pid); will 'free()' this state. If pid == 0 | ||
| 3549 | the current 'thread/process' will have it's error state removed. | ||
| 3550 | If you do not remove the error state of a thread, this could be considered a | ||
| 3551 | form of memory leak, so just after 'reaping' a thread that has died, | ||
| 3552 | call ERR_remove_state(pid). | ||
| 3553 | |||
| 3554 | Have a read of thread.doc for more details for what is required for | ||
| 3555 | multi-threading support. All the other error routines will | ||
| 3556 | work correctly when using threads. | ||
| 3557 | |||
| 3558 | |||
| 3559 | ==== idea.doc ======================================================== | ||
| 3560 | |||
| 3561 | The IDEA library. | ||
| 3562 | IDEA is a block cipher that operates on 64bit (8 byte) quantities. It | ||
| 3563 | uses a 128bit (16 byte) key. It can be used in all the modes that DES can | ||
| 3564 | be used. This library implements the ecb, cbc, cfb64 and ofb64 modes. | ||
| 3565 | |||
| 3566 | For all calls that have an 'input' and 'output' variables, they can be the | ||
| 3567 | same. | ||
| 3568 | |||
| 3569 | This library requires the inclusion of 'idea.h'. | ||
| 3570 | |||
| 3571 | All of the encryption functions take what is called an IDEA_KEY_SCHEDULE as an | ||
| 3572 | argument. An IDEA_KEY_SCHEDULE is an expanded form of the idea key. | ||
| 3573 | For all modes of the IDEA algorithm, the IDEA_KEY_SCHEDULE used for | ||
| 3574 | decryption is different to the one used for encryption. | ||
| 3575 | |||
| 3576 | The define IDEA_ENCRYPT is passed to specify encryption for the functions | ||
| 3577 | that require an encryption/decryption flag. IDEA_DECRYPT is passed to | ||
| 3578 | specify decryption. For some mode there is no encryption/decryption | ||
| 3579 | flag since this is determined by the IDEA_KEY_SCHEDULE. | ||
| 3580 | |||
| 3581 | So to encrypt you would do the following | ||
| 3582 | idea_set_encrypt_key(key,encrypt_ks); | ||
| 3583 | idea_ecb_encrypt(...,encrypt_ks); | ||
| 3584 | idea_cbc_encrypt(....,encrypt_ks,...,IDEA_ENCRYPT); | ||
| 3585 | |||
| 3586 | To Decrypt | ||
| 3587 | idea_set_encrypt_key(key,encrypt_ks); | ||
| 3588 | idea_set_decrypt_key(encrypt_ks,decrypt_ks); | ||
| 3589 | idea_ecb_encrypt(...,decrypt_ks); | ||
| 3590 | idea_cbc_encrypt(....,decrypt_ks,...,IDEA_DECRYPT); | ||
| 3591 | |||
| 3592 | Please note that any of the encryption modes specified in my DES library | ||
| 3593 | could be used with IDEA. I have only implemented ecb, cbc, cfb64 and | ||
| 3594 | ofb64 for the following reasons. | ||
| 3595 | - ecb is the basic IDEA encryption. | ||
| 3596 | - cbc is the normal 'chaining' form for block ciphers. | ||
| 3597 | - cfb64 can be used to encrypt single characters, therefore input and output | ||
| 3598 | do not need to be a multiple of 8. | ||
| 3599 | - ofb64 is similar to cfb64 but is more like a stream cipher, not as | ||
| 3600 | secure (not cipher feedback) but it does not have an encrypt/decrypt mode. | ||
| 3601 | - If you want triple IDEA, thats 384 bits of key and you must be totally | ||
| 3602 | obsessed with security. Still, if you want it, it is simple enough to | ||
| 3603 | copy the function from the DES library and change the des_encrypt to | ||
| 3604 | idea_encrypt; an exercise left for the paranoid reader :-). | ||
| 3605 | |||
| 3606 | The functions are as follows: | ||
| 3607 | |||
| 3608 | void idea_set_encrypt_key( | ||
| 3609 | unsigned char *key; | ||
| 3610 | IDEA_KEY_SCHEDULE *ks); | ||
| 3611 | idea_set_encrypt_key converts a 16 byte IDEA key into an | ||
| 3612 | IDEA_KEY_SCHEDULE. The IDEA_KEY_SCHEDULE is an expanded form of | ||
| 3613 | the key which can be used to perform IDEA encryption. | ||
| 3614 | An IDEA_KEY_SCHEDULE is an expanded form of the key which is used to | ||
| 3615 | perform actual encryption. It can be regenerated from the IDEA key | ||
| 3616 | so it only needs to be kept when encryption is about | ||
| 3617 | to occur. Don't save or pass around IDEA_KEY_SCHEDULE's since they | ||
| 3618 | are CPU architecture dependent, IDEA keys are not. | ||
| 3619 | |||
| 3620 | void idea_set_decrypt_key( | ||
| 3621 | IDEA_KEY_SCHEDULE *encrypt_ks, | ||
| 3622 | IDEA_KEY_SCHEDULE *decrypt_ks); | ||
| 3623 | This functions converts an encryption IDEA_KEY_SCHEDULE into a | ||
| 3624 | decryption IDEA_KEY_SCHEDULE. For all decryption, this conversion | ||
| 3625 | of the key must be done. In some modes of IDEA, an | ||
| 3626 | encryption/decryption flag is also required, this is because these | ||
| 3627 | functions involve block chaining and the way this is done changes | ||
| 3628 | depending on which of encryption of decryption is being done. | ||
| 3629 | Please note that there is no quick way to generate the decryption | ||
| 3630 | key schedule other than generating the encryption key schedule and | ||
| 3631 | then converting it. | ||
| 3632 | |||
| 3633 | void idea_encrypt( | ||
| 3634 | unsigned long *data, | ||
| 3635 | IDEA_KEY_SCHEDULE *ks); | ||
| 3636 | This is the IDEA encryption function that gets called by just about | ||
| 3637 | every other IDEA routine in the library. You should not use this | ||
| 3638 | function except to implement 'modes' of IDEA. I say this because the | ||
| 3639 | functions that call this routine do the conversion from 'char *' to | ||
| 3640 | long, and this needs to be done to make sure 'non-aligned' memory | ||
| 3641 | access do not occur. | ||
| 3642 | Data is a pointer to 2 unsigned long's and ks is the | ||
| 3643 | IDEA_KEY_SCHEDULE to use. Encryption or decryption depends on the | ||
| 3644 | IDEA_KEY_SCHEDULE. | ||
| 3645 | |||
| 3646 | void idea_ecb_encrypt( | ||
| 3647 | unsigned char *input, | ||
| 3648 | unsigned char *output, | ||
| 3649 | IDEA_KEY_SCHEDULE *ks); | ||
| 3650 | This is the basic Electronic Code Book form of IDEA (in DES this | ||
| 3651 | mode is called Electronic Code Book so I'm going to use the term | ||
| 3652 | for idea as well :-). | ||
| 3653 | Input is encrypted into output using the key represented by | ||
| 3654 | ks. Depending on the IDEA_KEY_SCHEDULE, encryption or | ||
| 3655 | decryption occurs. Input is 8 bytes long and output is 8 bytes. | ||
| 3656 | |||
| 3657 | void idea_cbc_encrypt( | ||
| 3658 | unsigned char *input, | ||
| 3659 | unsigned char *output, | ||
| 3660 | long length, | ||
| 3661 | IDEA_KEY_SCHEDULE *ks, | ||
| 3662 | unsigned char *ivec, | ||
| 3663 | int enc); | ||
| 3664 | This routine implements IDEA in Cipher Block Chaining mode. | ||
| 3665 | Input, which should be a multiple of 8 bytes is encrypted | ||
| 3666 | (or decrypted) to output which will also be a multiple of 8 bytes. | ||
| 3667 | The number of bytes is in length (and from what I've said above, | ||
| 3668 | should be a multiple of 8). If length is not a multiple of 8, bad | ||
| 3669 | things will probably happen. ivec is the initialisation vector. | ||
| 3670 | This function updates iv after each call so that it can be passed to | ||
| 3671 | the next call to idea_cbc_encrypt(). | ||
| 3672 | |||
| 3673 | void idea_cfb64_encrypt( | ||
| 3674 | unsigned char *in, | ||
| 3675 | unsigned char *out, | ||
| 3676 | long length, | ||
| 3677 | des_key_schedule ks, | ||
| 3678 | des_cblock *ivec, | ||
| 3679 | int *num, | ||
| 3680 | int enc); | ||
| 3681 | This is one of the more useful functions in this IDEA library, it | ||
| 3682 | implements CFB mode of IDEA with 64bit feedback. | ||
| 3683 | This allows you to encrypt an arbitrary number of bytes, | ||
| 3684 | you do not require 8 byte padding. Each call to this | ||
| 3685 | routine will encrypt the input bytes to output and then update ivec | ||
| 3686 | and num. Num contains 'how far' we are though ivec. | ||
| 3687 | Enc is used to indicate encryption or decryption. | ||
| 3688 | One very important thing to remember is that when decrypting, use | ||
| 3689 | the encryption form of the key. | ||
| 3690 | CFB64 mode operates by using the cipher to | ||
| 3691 | generate a stream of bytes which is used to encrypt the plain text. | ||
| 3692 | The cipher text is then encrypted to generate the next 64 bits to | ||
| 3693 | be xored (incrementally) with the next 64 bits of plain | ||
| 3694 | text. As can be seen from this, to encrypt or decrypt, | ||
| 3695 | the same 'cipher stream' needs to be generated but the way the next | ||
| 3696 | block of data is gathered for encryption is different for | ||
| 3697 | encryption and decryption. What this means is that to encrypt | ||
| 3698 | idea_set_encrypt_key(key,ks); | ||
| 3699 | idea_cfb64_encrypt(...,ks,..,IDEA_ENCRYPT) | ||
| 3700 | do decrypt | ||
| 3701 | idea_set_encrypt_key(key,ks) | ||
| 3702 | idea_cfb64_encrypt(...,ks,...,IDEA_DECRYPT) | ||
| 3703 | Note: The same IDEA_KEY_SCHEDULE but different encryption flags. | ||
| 3704 | For idea_cbc or idea_ecb, idea_set_decrypt_key() would need to be | ||
| 3705 | used to generate the IDEA_KEY_SCHEDULE for decryption. | ||
| 3706 | The reason I'm stressing this point is that I just wasted 3 hours | ||
| 3707 | today trying to decrypt using this mode and the decryption form of | ||
| 3708 | the key :-(. | ||
| 3709 | |||
| 3710 | void idea_ofb64_encrypt( | ||
| 3711 | unsigned char *in, | ||
| 3712 | unsigned char *out, | ||
| 3713 | long length, | ||
| 3714 | des_key_schedule ks, | ||
| 3715 | des_cblock *ivec, | ||
| 3716 | int *num); | ||
| 3717 | This functions implements OFB mode of IDEA with 64bit feedback. | ||
| 3718 | This allows you to encrypt an arbitrary number of bytes, | ||
| 3719 | you do not require 8 byte padding. Each call to this | ||
| 3720 | routine will encrypt the input bytes to output and then update ivec | ||
| 3721 | and num. Num contains 'how far' we are though ivec. | ||
| 3722 | This is in effect a stream cipher, there is no encryption or | ||
| 3723 | decryption mode. The same key and iv should be used to | ||
| 3724 | encrypt and decrypt. | ||
| 3725 | |||
| 3726 | For reading passwords, I suggest using des_read_pw_string() from my DES library. | ||
| 3727 | To generate a password from a text string, I suggest using MD5 (or MD2) to | ||
| 3728 | produce a 16 byte message digest that can then be passed directly to | ||
| 3729 | idea_set_encrypt_key(). | ||
| 3730 | |||
| 3731 | ===== | ||
| 3732 | For more information about the specific IDEA modes in this library | ||
| 3733 | (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the | ||
| 3734 | documentation on my DES library. What is said about DES is directly | ||
| 3735 | applicable for IDEA. | ||
| 3736 | |||
| 3737 | |||
| 3738 | ==== legal.doc ======================================================== | ||
| 3739 | |||
| 3740 | From eay@mincom.com Thu Jun 27 00:25:45 1996 | ||
| 3741 | Received: by orb.mincom.oz.au id AA15821 | ||
| 3742 | (5.65c/IDA-1.4.4 for eay); Wed, 26 Jun 1996 14:25:45 +1000 | ||
| 3743 | Date: Wed, 26 Jun 1996 14:25:45 +1000 (EST) | ||
| 3744 | From: Eric Young <eay@mincom.oz.au> | ||
| 3745 | X-Sender: eay@orb | ||
| 3746 | To: Ken Toll <ktoll@ren.digitalage.com> | ||
| 3747 | Cc: Eric Young <eay@mincom.oz.au>, ssl-talk@netscape.com | ||
| 3748 | Subject: Re: Unidentified subject! | ||
| 3749 | In-Reply-To: <9606261950.ZM28943@ren.digitalage.com> | ||
| 3750 | Message-Id: <Pine.SOL.3.91.960626131156.28573K-100000@orb> | ||
| 3751 | Mime-Version: 1.0 | ||
| 3752 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 3753 | Status: O | ||
| 3754 | X-Status: | ||
| 3755 | |||
| 3756 | |||
| 3757 | This is a little off topic but since SSLeay is a free implementation of | ||
| 3758 | the SSLv2 protocol, I feel it is worth responding on the topic of if it | ||
| 3759 | is actually legal for Americans to use free cryptographic software. | ||
| 3760 | |||
| 3761 | On Wed, 26 Jun 1996, Ken Toll wrote: | ||
| 3762 | > Is the U.S the only country that SSLeay cannot be used commercially | ||
| 3763 | > (because of RSAref) or is that going to be an issue with every country | ||
| 3764 | > that a client/server application (non-web browser/server) is deployed | ||
| 3765 | > and sold? | ||
| 3766 | |||
| 3767 | >From what I understand, the software patents that apply to algorithms | ||
| 3768 | like RSA and DH only apply in the USA. The IDEA algorithm I believe is | ||
| 3769 | patened in europe (USA?), but considing how little it is used by other SSL | ||
| 3770 | implementations, it quite easily be left out of the SSLeay build | ||
| 3771 | (this can be done with a compile flag). | ||
| 3772 | |||
| 3773 | Actually if the RSA patent did apply outside the USA, it could be rather | ||
| 3774 | interesting since RSA is not alowed to let RSA toolkits outside of the USA | ||
| 3775 | [1], and since these are the only forms that they will alow the algorithm | ||
| 3776 | to be used in, it would mean that non-one outside of the USA could produce | ||
| 3777 | public key software which would be a very strong statment for | ||
| 3778 | international patent law to make :-). This logic is a little flawed but | ||
| 3779 | it still points out some of the more interesting permutations of USA | ||
| 3780 | patent law and ITAR restrictions. | ||
| 3781 | |||
| 3782 | Inside the USA there is also the unresolved issue of RC4/RC2 which were | ||
| 3783 | made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2). I have | ||
| 3784 | copies of the origional postings if people are interested. RSA I believe | ||
| 3785 | claim that they were 'trade-secrets' and that some-one broke an NDA in | ||
| 3786 | revealing them. Other claim they reverse engineered the algorithms from | ||
| 3787 | compiled binaries. If the algorithms were reverse engineered, I belive | ||
| 3788 | RSA had no legal leg to stand on. If an NDA was broken, I don't know. | ||
| 3789 | Regardless, RSA, I belive, is willing to go to court over the issue so | ||
| 3790 | licencing is probably the best idea, or at least talk to them. | ||
| 3791 | If there are people who actually know more about this, pease let me know, I | ||
| 3792 | don't want to vilify or spread miss-information if I can help it. | ||
| 3793 | |||
| 3794 | If you are not producing a web browser, it is easy to build SSLeay with | ||
| 3795 | RC2/RC4 removed. Since RC4 is the defacto standard cipher in | ||
| 3796 | all web software (and it is damn fast) it is more or less required for | ||
| 3797 | www use. For non www use of SSL, especially for an application where | ||
| 3798 | interoperability with other vendors is not critical just leave it out. | ||
| 3799 | |||
| 3800 | Removing IDEA, RC2 and RC4 would only leave DES and Triple DES but | ||
| 3801 | they should be ok. Considing that Triple DES can encrypt at rates of | ||
| 3802 | 410k/sec on a pentium 100, and 940k/sec on a P6/200, this is quite | ||
| 3803 | reasonable performance. Single DES clocks in at 1160k/s and 2467k/s | ||
| 3804 | respectivly is actually quite fast for those not so paranoid (56 bit key).[1] | ||
| 3805 | |||
| 3806 | > Is it possible to get a certificate for commercial use outside of the U.S.? | ||
| 3807 | yes. | ||
| 3808 | |||
| 3809 | Thawte Consulting issues certificates (they are the people who sell the | ||
| 3810 | Sioux httpd server and are based in South Africa) | ||
| 3811 | Verisign will issue certificates for Sioux (sold from South Africa), so this | ||
| 3812 | proves that they will issue certificate for OS use if they are | ||
| 3813 | happy with the quality of the software. | ||
| 3814 | |||
| 3815 | (The above mentioned companies just the ones that I know for sure are issuing | ||
| 3816 | certificates outside the USA). | ||
| 3817 | |||
| 3818 | There is always the point that if you are using SSL for an intra net, | ||
| 3819 | SSLeay provides programs that can be used so you can issue your own | ||
| 3820 | certificates. They need polishing but at least it is a good starting point. | ||
| 3821 | |||
| 3822 | I am not doing anything outside Australian law by implementing these | ||
| 3823 | algorithms (to the best of my knowedge). It is another example of how | ||
| 3824 | the world legal system does not cope with the internet very well. | ||
| 3825 | |||
| 3826 | I may start making shared libraries available (I have now got DLL's for | ||
| 3827 | Windows). This will mean that distributions into the usa could be | ||
| 3828 | shipped with a version with a reduced cipher set and the versions outside | ||
| 3829 | could use the DLL/shared library with all the ciphers (and without RSAref). | ||
| 3830 | |||
| 3831 | This could be completly hidden from the application, so this would not | ||
| 3832 | even require a re-linking. | ||
| 3833 | |||
| 3834 | This is the reverse of what people were talking about doing to get around | ||
| 3835 | USA export regulations :-) | ||
| 3836 | |||
| 3837 | eric | ||
| 3838 | |||
| 3839 | [1]: The RSAref2.0 tookit is available on at least 3 ftp sites in Europe | ||
| 3840 | and one in South Africa. | ||
| 3841 | |||
| 3842 | [2]: Since I always get questions when I post benchmark numbers :-), | ||
| 3843 | DES performace figures are in 1000's of bytes per second in cbc | ||
| 3844 | mode using an 8192 byte buffer. The pentium 100 was running Windows NT | ||
| 3845 | 3.51 DLLs and the 686/200 was running NextStep. | ||
| 3846 | I quote pentium 100 benchmarks because it is basically the | ||
| 3847 | 'entry level' computer that most people buy for personal use. | ||
| 3848 | Windows 95 is the OS shipping on those boxes, so I'll give | ||
| 3849 | NT numbers (the same Win32 runtime environment). The 686 | ||
| 3850 | numbers are present as an indication of where we will be in a | ||
| 3851 | few years. | ||
| 3852 | -- | ||
| 3853 | Eric Young | BOOL is tri-state according to Bill Gates. | ||
| 3854 | AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). | ||
| 3855 | |||
| 3856 | |||
| 3857 | |||
| 3858 | ==== lhash.doc ======================================================== | ||
| 3859 | |||
| 3860 | The LHASH library. | ||
| 3861 | |||
| 3862 | I wrote this library in 1991 and have since forgotten why I called it lhash. | ||
| 3863 | It implements a hash table from an article I read at the | ||
| 3864 | time from 'Communications of the ACM'. What makes this hash | ||
| 3865 | table different is that as the table fills, the hash table is | ||
| 3866 | increased (or decreased) in size via realloc(). | ||
| 3867 | When a 'resize' is done, instead of all hashes being redistributed over | ||
| 3868 | twice as many 'buckets', one bucket is split. So when an 'expand' is done, | ||
| 3869 | there is only a minimal cost to redistribute some values. Subsequent | ||
| 3870 | inserts will cause more single 'bucket' redistributions but there will | ||
| 3871 | never be a sudden large cost due to redistributing all the 'buckets'. | ||
| 3872 | |||
| 3873 | The state for a particular hash table is kept in the LHASH structure. | ||
| 3874 | The LHASH structure also records statistics about most aspects of accessing | ||
| 3875 | the hash table. This is mostly a legacy of my writing this library for | ||
| 3876 | the reasons of implementing what looked like a nice algorithm rather than | ||
| 3877 | for a particular software product. | ||
| 3878 | |||
| 3879 | Internal stuff you probably don't want to know about. | ||
| 3880 | The decision to increase or decrease the hash table size is made depending | ||
| 3881 | on the 'load' of the hash table. The load is the number of items in the | ||
| 3882 | hash table divided by the size of the hash table. The default values are | ||
| 3883 | as follows. If (hash->up_load < load) => expand. | ||
| 3884 | if (hash->down_load > load) => contract. The 'up_load' has a default value of | ||
| 3885 | 1 and 'down_load' has a default value of 2. These numbers can be modified | ||
| 3886 | by the application by just playing with the 'up_load' and 'down_load' | ||
| 3887 | variables. The 'load' is kept in a form which is multiplied by 256. So | ||
| 3888 | hash->up_load=8*256; will cause a load of 8 to be set. | ||
| 3889 | |||
| 3890 | If you are interested in performance the field to watch is | ||
| 3891 | num_comp_calls. The hash library keeps track of the 'hash' value for | ||
| 3892 | each item so when a lookup is done, the 'hashes' are compared, if | ||
| 3893 | there is a match, then a full compare is done, and | ||
| 3894 | hash->num_comp_calls is incremented. If num_comp_calls is not equal | ||
| 3895 | to num_delete plus num_retrieve it means that your hash function is | ||
| 3896 | generating hashes that are the same for different values. It is | ||
| 3897 | probably worth changing your hash function if this is the case because | ||
| 3898 | even if your hash table has 10 items in a 'bucked', it can be searched | ||
| 3899 | with 10 'unsigned long' compares and 10 linked list traverses. This | ||
| 3900 | will be much less expensive that 10 calls to you compare function. | ||
| 3901 | |||
| 3902 | LHASH *lh_new( | ||
| 3903 | unsigned long (*hash)(), | ||
| 3904 | int (*cmp)()); | ||
| 3905 | This function is used to create a new LHASH structure. It is passed | ||
| 3906 | function pointers that are used to store and retrieve values passed | ||
| 3907 | into the hash table. The 'hash' | ||
| 3908 | function is a hashing function that will return a hashed value of | ||
| 3909 | it's passed structure. 'cmp' is passed 2 parameters, it returns 0 | ||
| 3910 | is they are equal, otherwise, non zero. | ||
| 3911 | If there are any problems (usually malloc failures), NULL is | ||
| 3912 | returned, otherwise a new LHASH structure is returned. The | ||
| 3913 | hash value is normally truncated to a power of 2, so make sure | ||
| 3914 | that your hash function returns well mixed low order bits. | ||
| 3915 | |||
| 3916 | void lh_free( | ||
| 3917 | LHASH *lh); | ||
| 3918 | This function free()s a LHASH structure. If there is malloced | ||
| 3919 | data in the hash table, it will not be freed. Consider using the | ||
| 3920 | lh_doall function to deallocate any remaining entries in the hash | ||
| 3921 | table. | ||
| 3922 | |||
| 3923 | char *lh_insert( | ||
| 3924 | LHASH *lh, | ||
| 3925 | char *data); | ||
| 3926 | This function inserts the data pointed to by data into the lh hash | ||
| 3927 | table. If there is already and entry in the hash table entry, the | ||
| 3928 | value being replaced is returned. A NULL is returned if the new | ||
| 3929 | entry does not clash with an entry already in the table (the normal | ||
| 3930 | case) or on a malloc() failure (perhaps I should change this....). | ||
| 3931 | The 'char *data' is exactly what is passed to the hash and | ||
| 3932 | comparison functions specified in lh_new(). | ||
| 3933 | |||
| 3934 | char *lh_delete( | ||
| 3935 | LHASH *lh, | ||
| 3936 | char *data); | ||
| 3937 | This routine deletes an entry from the hash table. The value being | ||
| 3938 | deleted is returned. NULL is returned if there is no such value in | ||
| 3939 | the hash table. | ||
| 3940 | |||
| 3941 | char *lh_retrieve( | ||
| 3942 | LHASH *lh, | ||
| 3943 | char *data); | ||
| 3944 | If 'data' is in the hash table it is returned, else NULL is | ||
| 3945 | returned. The way these routines would normally be uses is that a | ||
| 3946 | dummy structure would have key fields populated and then | ||
| 3947 | ret=lh_retrieve(hash,&dummy);. Ret would now be a pointer to a fully | ||
| 3948 | populated structure. | ||
| 3949 | |||
| 3950 | void lh_doall( | ||
| 3951 | LHASH *lh, | ||
| 3952 | void (*func)(char *a)); | ||
| 3953 | This function will, for every entry in the hash table, call function | ||
| 3954 | 'func' with the data item as parameters. | ||
| 3955 | This function can be quite useful when used as follows. | ||
| 3956 | void cleanup(STUFF *a) | ||
| 3957 | { STUFF_free(a); } | ||
| 3958 | lh_doall(hash,cleanup); | ||
| 3959 | lh_free(hash); | ||
| 3960 | This can be used to free all the entries, lh_free() then | ||
| 3961 | cleans up the 'buckets' that point to nothing. Be careful | ||
| 3962 | when doing this. If you delete entries from the hash table, | ||
| 3963 | in the call back function, the table may decrease in size, | ||
| 3964 | moving item that you are | ||
| 3965 | currently on down lower in the hash table. This could cause | ||
| 3966 | some entries to be skipped. The best solution to this problem | ||
| 3967 | is to set lh->down_load=0 before you start. This will stop | ||
| 3968 | the hash table ever being decreased in size. | ||
| 3969 | |||
| 3970 | void lh_doall_arg( | ||
| 3971 | LHASH *lh; | ||
| 3972 | void(*func)(char *a,char *arg)); | ||
| 3973 | char *arg; | ||
| 3974 | This function is the same as lh_doall except that the function | ||
| 3975 | called will be passed 'arg' as the second argument. | ||
| 3976 | |||
| 3977 | unsigned long lh_strhash( | ||
| 3978 | char *c); | ||
| 3979 | This function is a demo string hashing function. Since the LHASH | ||
| 3980 | routines would normally be passed structures, this routine would | ||
| 3981 | not normally be passed to lh_new(), rather it would be used in the | ||
| 3982 | function passed to lh_new(). | ||
| 3983 | |||
| 3984 | The next three routines print out various statistics about the state of the | ||
| 3985 | passed hash table. These numbers are all kept in the lhash structure. | ||
| 3986 | |||
| 3987 | void lh_stats( | ||
| 3988 | LHASH *lh, | ||
| 3989 | FILE *out); | ||
| 3990 | This function prints out statistics on the size of the hash table, | ||
| 3991 | how many entries are in it, and the number and result of calls to | ||
| 3992 | the routines in this library. | ||
| 3993 | |||
| 3994 | void lh_node_stats( | ||
| 3995 | LHASH *lh, | ||
| 3996 | FILE *out); | ||
| 3997 | For each 'bucket' in the hash table, the number of entries is | ||
| 3998 | printed. | ||
| 3999 | |||
| 4000 | void lh_node_usage_stats( | ||
| 4001 | LHASH *lh, | ||
| 4002 | FILE *out); | ||
| 4003 | This function prints out a short summary of the state of the hash | ||
| 4004 | table. It prints what I call the 'load' and the 'actual load'. | ||
| 4005 | The load is the average number of data items per 'bucket' in the | ||
| 4006 | hash table. The 'actual load' is the average number of items per | ||
| 4007 | 'bucket', but only for buckets which contain entries. So the | ||
| 4008 | 'actual load' is the average number of searches that will need to | ||
| 4009 | find an item in the hash table, while the 'load' is the average number | ||
| 4010 | that will be done to record a miss. | ||
| 4011 | |||
| 4012 | ==== md2.doc ======================================================== | ||
| 4013 | |||
| 4014 | The MD2 library. | ||
| 4015 | MD2 is a message digest algorithm that can be used to condense an arbitrary | ||
| 4016 | length message down to a 16 byte hash. The functions all need to be passed | ||
| 4017 | a MD2_CTX which is used to hold the MD2 context during multiple MD2_Update() | ||
| 4018 | function calls. The normal method of use for this library is as follows | ||
| 4019 | |||
| 4020 | MD2_Init(...); | ||
| 4021 | MD2_Update(...); | ||
| 4022 | ... | ||
| 4023 | MD2_Update(...); | ||
| 4024 | MD2_Final(...); | ||
| 4025 | |||
| 4026 | This library requires the inclusion of 'md2.h'. | ||
| 4027 | |||
| 4028 | The main negative about MD2 is that it is slow, especially when compared | ||
| 4029 | to MD5. | ||
| 4030 | |||
| 4031 | The functions are as follows: | ||
| 4032 | |||
| 4033 | void MD2_Init( | ||
| 4034 | MD2_CTX *c); | ||
| 4035 | This function needs to be called to initiate a MD2_CTX structure for | ||
| 4036 | use. | ||
| 4037 | |||
| 4038 | void MD2_Update( | ||
| 4039 | MD2_CTX *c; | ||
| 4040 | unsigned char *data; | ||
| 4041 | unsigned long len); | ||
| 4042 | This updates the message digest context being generated with 'len' | ||
| 4043 | bytes from the 'data' pointer. The number of bytes can be any | ||
| 4044 | length. | ||
| 4045 | |||
| 4046 | void MD2_Final( | ||
| 4047 | unsigned char *md; | ||
| 4048 | MD2_CTX *c; | ||
| 4049 | This function is called when a message digest of the data digested | ||
| 4050 | with MD2_Update() is wanted. The message digest is put in the 'md' | ||
| 4051 | array and is MD2_DIGEST_LENGTH (16) bytes long. | ||
| 4052 | |||
| 4053 | unsigned char *MD2( | ||
| 4054 | unsigned long n; | ||
| 4055 | unsigned char *d; | ||
| 4056 | unsigned char *md; | ||
| 4057 | This function performs a MD2_Init(), followed by a MD2_Update() | ||
| 4058 | followed by a MD2_Final() (using a local MD2_CTX). | ||
| 4059 | The resulting digest is put into 'md' if it is not NULL. | ||
| 4060 | Regardless of the value of 'md', the message | ||
| 4061 | digest is returned from the function. If 'md' was NULL, the message | ||
| 4062 | digest returned is being stored in a static structure. | ||
| 4063 | |||
| 4064 | ==== md5.doc ======================================================== | ||
| 4065 | |||
| 4066 | The MD5 library. | ||
| 4067 | MD5 is a message digest algorithm that can be used to condense an arbitrary | ||
| 4068 | length message down to a 16 byte hash. The functions all need to be passed | ||
| 4069 | a MD5_CTX which is used to hold the MD5 context during multiple MD5_Update() | ||
| 4070 | function calls. This library also contains random number routines that are | ||
| 4071 | based on MD5 | ||
| 4072 | |||
| 4073 | The normal method of use for this library is as follows | ||
| 4074 | |||
| 4075 | MD5_Init(...); | ||
| 4076 | MD5_Update(...); | ||
| 4077 | ... | ||
| 4078 | MD5_Update(...); | ||
| 4079 | MD5_Final(...); | ||
| 4080 | |||
| 4081 | This library requires the inclusion of 'md5.h'. | ||
| 4082 | |||
| 4083 | The functions are as follows: | ||
| 4084 | |||
| 4085 | void MD5_Init( | ||
| 4086 | MD5_CTX *c); | ||
| 4087 | This function needs to be called to initiate a MD5_CTX structure for | ||
| 4088 | use. | ||
| 4089 | |||
| 4090 | void MD5_Update( | ||
| 4091 | MD5_CTX *c; | ||
| 4092 | unsigned char *data; | ||
| 4093 | unsigned long len); | ||
| 4094 | This updates the message digest context being generated with 'len' | ||
| 4095 | bytes from the 'data' pointer. The number of bytes can be any | ||
| 4096 | length. | ||
| 4097 | |||
| 4098 | void MD5_Final( | ||
| 4099 | unsigned char *md; | ||
| 4100 | MD5_CTX *c; | ||
| 4101 | This function is called when a message digest of the data digested | ||
| 4102 | with MD5_Update() is wanted. The message digest is put in the 'md' | ||
| 4103 | array and is MD5_DIGEST_LENGTH (16) bytes long. | ||
| 4104 | |||
| 4105 | unsigned char *MD5( | ||
| 4106 | unsigned char *d; | ||
| 4107 | unsigned long n; | ||
| 4108 | unsigned char *md; | ||
| 4109 | This function performs a MD5_Init(), followed by a MD5_Update() | ||
| 4110 | followed by a MD5_Final() (using a local MD5_CTX). | ||
| 4111 | The resulting digest is put into 'md' if it is not NULL. | ||
| 4112 | Regardless of the value of 'md', the message | ||
| 4113 | digest is returned from the function. If 'md' was NULL, the message | ||
| 4114 | digest returned is being stored in a static structure. | ||
| 4115 | |||
| 4116 | |||
| 4117 | ==== memory.doc ======================================================== | ||
| 4118 | |||
| 4119 | In the interests of debugging SSLeay, there is an option to compile | ||
| 4120 | using some simple memory leak checking. | ||
| 4121 | |||
| 4122 | All malloc(), free() and realloc() calls in SSLeay now go via | ||
| 4123 | Malloc(), Free() and Realloc() (except those in crypto/lhash). | ||
| 4124 | |||
| 4125 | If CRYPTO_MDEBUG is defined, these calls are #defined to | ||
| 4126 | CRYPTO_malloc(), CRYPTO_free() and CRYPTO_realloc(). | ||
| 4127 | If it is not defined, they are #defined to malloc(), free() and realloc(). | ||
| 4128 | |||
| 4129 | the CRYPTO_malloc() routines by default just call the underlying library | ||
| 4130 | functons. | ||
| 4131 | |||
| 4132 | If CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON) is called, memory leak detection is | ||
| 4133 | turned on. CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_OFF) turns it off. | ||
| 4134 | |||
| 4135 | When turned on, each Malloc() or Realloc() call is recored along with the file | ||
| 4136 | and line number from where the call was made. (This is done using the | ||
| 4137 | lhash library which always uses normal system malloc(3) routines). | ||
| 4138 | |||
| 4139 | void CRYPTO_mem_leaks(BIO *b); | ||
| 4140 | void CRYPTO_mem_leaks_fp(FILE *fp); | ||
| 4141 | These both print out the list of memory that has not been free()ed. | ||
| 4142 | This will probably be rather hard to read, but if you look for the 'top level' | ||
| 4143 | structure allocation, this will often give an idea as to what is not being | ||
| 4144 | free()ed. I don't expect people to use this stuff normally. | ||
| 4145 | |||
| 4146 | ==== ca.1 ======================================================== | ||
| 4147 | |||
| 4148 | From eay@orb.mincom.oz.au Thu Dec 28 23:56:45 1995 | ||
| 4149 | Received: by orb.mincom.oz.au id AA07374 | ||
| 4150 | (5.65c/IDA-1.4.4 for eay); Thu, 28 Dec 1995 13:56:45 +1000 | ||
| 4151 | Date: Thu, 28 Dec 1995 13:56:45 +1000 (EST) | ||
| 4152 | From: Eric Young <eay@mincom.oz.au> | ||
| 4153 | X-Sender: eay@orb | ||
| 4154 | To: sameer <sameer@c2.org> | ||
| 4155 | Cc: ssleay@mincom.oz.au | ||
| 4156 | Subject: Re: 'ca' | ||
| 4157 | In-Reply-To: <199512230440.UAA23410@infinity.c2.org> | ||
| 4158 | Message-Id: <Pine.SOL.3.91.951228133525.7269A-100000@orb> | ||
| 4159 | Mime-Version: 1.0 | ||
| 4160 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 4161 | Status: RO | ||
| 4162 | X-Status: | ||
| 4163 | |||
| 4164 | On Fri, 22 Dec 1995, sameer wrote: | ||
| 4165 | > I could use documentation on 'ca'. Thanks. | ||
| 4166 | |||
| 4167 | Very quickly. | ||
| 4168 | The ca program uses the ssleay.conf file for most of its configuration | ||
| 4169 | |||
| 4170 | ./ca -help | ||
| 4171 | |||
| 4172 | -verbose - Talk alot while doing things | ||
| 4173 | -config file - A config file. If you don't want to use the | ||
| 4174 | default config file | ||
| 4175 | -name arg - The particular CA definition to use | ||
| 4176 | In the config file, the section to use for parameters. This lets | ||
| 4177 | multiple setups to be contained in the one file. By default, the | ||
| 4178 | default_ca variable is looked up in the [ ca ] section. So in the | ||
| 4179 | shipped ssleay.conf, the CA definition used is CA_default. It could be | ||
| 4180 | any other name. | ||
| 4181 | -gencrl days - Generate a new CRL, days is when the next CRL is due | ||
| 4182 | This will generate a new certificate revocion list. | ||
| 4183 | -days arg - number of days to certify the certificate for | ||
| 4184 | When certifiying certificates, this is the number of days to use. | ||
| 4185 | -md arg - md to use, one of md2, md5, sha or sha1 | ||
| 4186 | -policy arg - The CA 'policy' to support | ||
| 4187 | I'll describe this later, but there are 2 policies definied in the | ||
| 4188 | shipped ssleay.conf | ||
| 4189 | -keyfile arg - PEM RSA private key file | ||
| 4190 | -key arg - key to decode the RSA private key if it is encrypted | ||
| 4191 | since we need to keep the CA's RSA key encrypted | ||
| 4192 | -cert - The CA certificate | ||
| 4193 | -in file - The input PEM encoded certificate request(s) | ||
| 4194 | -out file - Where to put the output file(s) | ||
| 4195 | -outdir dir - Where to put output certificates | ||
| 4196 | The -out options concatinates all the output certificied | ||
| 4197 | certificates to one file, -outdir puts them in a directory, | ||
| 4198 | named by serial number. | ||
| 4199 | -infiles .... - The last argument, requests to process | ||
| 4200 | The certificate requests to process, -in is the same. | ||
| 4201 | |||
| 4202 | Just about all the above have default values defined in ssleay.conf. | ||
| 4203 | |||
| 4204 | The key variables in ssleay.conf are (for the pariticular '-name' being | ||
| 4205 | used, in the default, it is CA_default). | ||
| 4206 | |||
| 4207 | dir is where all the CA database stuff is kept. | ||
| 4208 | certs is where all the previously issued certificates are kept. | ||
| 4209 | The database is a simple text database containing the following tab separated | ||
| 4210 | fields. | ||
| 4211 | status: a value of 'R' - revoked, 'E' -expired or 'V' valid. | ||
| 4212 | issued date: When the certificate was certified. | ||
| 4213 | revoked date: When it was revoked, blank if not revoked. | ||
| 4214 | serial number: The certificate serial number. | ||
| 4215 | certificate: Where the certificate is located. | ||
| 4216 | CN: The name of the certificate. | ||
| 4217 | |||
| 4218 | The demo file has quite a few made up values it it. The last 2 were | ||
| 4219 | added by the ca program and are acurate. | ||
| 4220 | The CA program does not update the 'certificate' file correctly right now. | ||
| 4221 | The serial field should be unique as should the CN/status combination. | ||
| 4222 | The ca program checks these at startup. What still needs to be | ||
| 4223 | wrtten is a program to 'regenerate' the data base file from the issued | ||
| 4224 | certificate list (and a CRL list). | ||
| 4225 | |||
| 4226 | Back to the CA_default variables. | ||
| 4227 | |||
| 4228 | Most of the variables are commented. | ||
| 4229 | |||
| 4230 | policy is the default policy. | ||
| 4231 | |||
| 4232 | Ok for policies, they define the order and which fields must be present | ||
| 4233 | in the certificate request and what gets filled in. | ||
| 4234 | |||
| 4235 | So a value of | ||
| 4236 | countryName = match | ||
| 4237 | means that the country name must match the CA certificate. | ||
| 4238 | organizationalUnitName = optional | ||
| 4239 | The org.Unit,Name does not have to be present and | ||
| 4240 | commonName = supplied | ||
| 4241 | commonName must be supplied in the certificate request. | ||
| 4242 | |||
| 4243 | For the 'policy_match' polocy, the order of the attributes in the | ||
| 4244 | generated certiticate would be | ||
| 4245 | countryName | ||
| 4246 | stateOrProvinceName | ||
| 4247 | organizationName | ||
| 4248 | organizationalUnitName | ||
| 4249 | commonName | ||
| 4250 | emailAddress | ||
| 4251 | |||
| 4252 | Have a play, it sort of makes sense. If you think about how the persona | ||
| 4253 | requests operate, it is similar to the 'policy_match' policy and the | ||
| 4254 | 'policy_anything' is similar to what versign is doing. | ||
| 4255 | |||
| 4256 | I hope this helps a bit. Some backend scripts are definitly needed to | ||
| 4257 | update the database and to make certificate revocion easy. All | ||
| 4258 | certificates issued should also be kept forever (or until they expire?) | ||
| 4259 | |||
| 4260 | hope this helps | ||
| 4261 | eric (who has to run off an buy some cheap knee pads for the caving in 4 | ||
| 4262 | days time :-) | ||
| 4263 | |||
| 4264 | -- | ||
| 4265 | Eric Young | Signature removed since it was generating | ||
| 4266 | AARNet: eay@mincom.oz.au | more followups than the message contents :-) | ||
| 4267 | |||
| 4268 | |||
| 4269 | ==== ms3-ca.doc ======================================================== | ||
| 4270 | |||
| 4271 | Date: Mon, 9 Jun 97 08:00:33 +0200 | ||
| 4272 | From: Holger.Reif@PrakInf.TU-Ilmenau.DE (Holger Reif) | ||
| 4273 | Subject: ms3-ca.doc | ||
| 4274 | Organization: TU Ilmenau, Fak. IA, FG Telematik | ||
| 4275 | Content-Length: 14575 | ||
| 4276 | Status: RO | ||
| 4277 | X-Status: | ||
| 4278 | |||
| 4279 | Loading client certs into MSIE 3.01 | ||
| 4280 | =================================== | ||
| 4281 | |||
| 4282 | This document conatains all the information necessary to succesfully set up | ||
| 4283 | some scripts to issue client certs to Microsoft Internet Explorer. It | ||
| 4284 | includes the required knowledge about the model MSIE uses for client | ||
| 4285 | certification and includes complete sample scripts ready to play with. The | ||
| 4286 | scripts were tested against a modified ca program of SSLeay 0.6.6 and should | ||
| 4287 | work with the regular ca program that comes with version 0.8.0. I haven't | ||
| 4288 | tested against MSIE 4.0 | ||
| 4289 | |||
| 4290 | You can use the information contained in this document in either way you | ||
| 4291 | want. However if you feel it saved you a lot of time I ask you to be as fair | ||
| 4292 | as to mention my name: Holger Reif <reif@prakinf.tu-ilmenau.de>. | ||
| 4293 | |||
| 4294 | 1.) The model used by MSIE | ||
| 4295 | -------------------------- | ||
| 4296 | |||
| 4297 | The Internet Explorer doesn't come with a embedded engine for installing | ||
| 4298 | client certs like Netscape's Navigator. It rather uses the CryptoAPI (CAPI) | ||
| 4299 | defined by Microsoft. CAPI comes with WindowsNT 4.0 or is installed together | ||
| 4300 | with Internet Explorer since 3.01. The advantage of this approach is a higher | ||
| 4301 | flexibility because the certificates in the (per user) system open | ||
| 4302 | certificate store may be used by other applications as well. The drawback | ||
| 4303 | however is that you need to do a bit more work to get a client cert issued. | ||
| 4304 | |||
| 4305 | CAPI defines functions which will handle basic cryptographic work, eg. | ||
| 4306 | generating keys, encrypting some data, signing text or building a certificate | ||
| 4307 | request. The procedure is as follows: A CAPI function generates you a key | ||
| 4308 | pair and saves it into the certificate store. After that one builds a | ||
| 4309 | Distinguished Name. Together with that key pair another CAPI function forms a | ||
| 4310 | PKCS#10 request which you somehow need to submit to a CA. Finally the issued | ||
| 4311 | cert is given to a yet another CAPI function which saves it into the | ||
| 4312 | certificate store. | ||
| 4313 | |||
| 4314 | The certificate store with the user's keys and certs is in the registry. You | ||
| 4315 | will find it under HKEY_CURRENT_USER/Software/Microsoft/Cryptography/ (I | ||
| 4316 | leave it to you as a little exercise to figure out what all the entries mean | ||
| 4317 | ;-). Note that the keys are protected only with the user's usual Windows | ||
| 4318 | login password. | ||
| 4319 | |||
| 4320 | 2.) The practical usage | ||
| 4321 | ----------------------- | ||
| 4322 | |||
| 4323 | Unfortunatly since CAPI is a system API you can't access its functions from | ||
| 4324 | HTML code directly. For this purpose Microsoft provides a wrapper called | ||
| 4325 | certenr3.dll. This DLL accesses the CAPI functions and provides an interface | ||
| 4326 | usable from Visual Basic Script. One needs to install that library on the | ||
| 4327 | computer which wants to have client cert. The easiest way is to load it as an | ||
| 4328 | ActiveX control (certenr3.dll is properly authenticode signed by MS ;-). If | ||
| 4329 | you have ever enrolled e cert request at a CA you will have installed it. | ||
| 4330 | |||
| 4331 | At time of writing certenr3.dll is contained in | ||
| 4332 | http://www.microsoft.com/workshop/prog/security/csa/certenr3.exe. It comes | ||
| 4333 | with an README file which explains the available functions. It is labeled | ||
| 4334 | beta but every CA seems to use it anyway. The license.txt allows you the | ||
| 4335 | usage for your own purposes (as far as I understood) and a somehow limited | ||
| 4336 | distribution. | ||
| 4337 | |||
| 4338 | The two functions of main interest are GenerateKeyPair and AcceptCredentials. | ||
| 4339 | For complete explanation of all possible parameters see the README file. Here | ||
| 4340 | are only minimal required parameters and their values. | ||
| 4341 | |||
| 4342 | GenerateKeyPair(sessionID, FASLE, szName, 0, "ClientAuth", TRUE, FALSE, 1) | ||
| 4343 | - sessionID is a (locally to that computer) unique string to correlate the | ||
| 4344 | generated key pair with a cert installed later. | ||
| 4345 | - szName is the DN of the form "C=DE; S=Thueringen; L=Ilmenau; CN=Holger | ||
| 4346 | Reif; 1.2.840.113549.1.9.1=reif@prakinf.tu-ilmenau.de". Note that S is the | ||
| 4347 | abreviation for StateOrProvince. The recognized abreviation include CN, O, C, | ||
| 4348 | OU, G, I, L, S, T. If the abreviation is unknown (eg. for PKCS#9 email addr) | ||
| 4349 | you need to use the full object identifier. The starting point for searching | ||
| 4350 | them could be crypto/objects.h since all OIDs know to SSLeay are listed | ||
| 4351 | there. | ||
| 4352 | - note: the possible ninth parameter which should give a default name to the | ||
| 4353 | certificate storage location doesn't seem to work. Changes to the constant | ||
| 4354 | values in the call above doesn't seem to make sense. You can't generate | ||
| 4355 | PKCS#10 extensions with that function. | ||
| 4356 | |||
| 4357 | The result of GenerateKeyPair is the base64 encoded PKCS#10 request. However | ||
| 4358 | it has a little strange format that SSLeay doesn't accept. (BTW I feel the | ||
| 4359 | decision of rejecting that format as standard conforming.) It looks like | ||
| 4360 | follows: | ||
| 4361 | 1st line with 76 chars | ||
| 4362 | 2nd line with 76 chars | ||
| 4363 | ... | ||
| 4364 | (n-2)th line with 76 chars | ||
| 4365 | (n-1)th line contains a multiple of 4 chars less then 76 (possible | ||
| 4366 | empty) | ||
| 4367 | (n)th line has zero or 4 chars (then with 1 or 2 equal signs - the | ||
| 4368 | original text's lenght wasn'T a multiple of 3) | ||
| 4369 | The line separator has two chars: 0x0d 0x0a | ||
| 4370 | |||
| 4371 | AcceptCredentials(sessionID, credentials, 0, FALSE) | ||
| 4372 | - sessionID needs to be the same as while generating the key pair | ||
| 4373 | - credentials is the base64 encoded PKCS#7 object containing the cert. | ||
| 4374 | |||
| 4375 | CRL's and CA certs are not required simply just the client cert. (It seems to | ||
| 4376 | me that both are not even checked somehow.) The only format of the base64 | ||
| 4377 | encoded object I succesfully used was all characters in a very long string | ||
| 4378 | without line feeds or carriage returns. (Hey, it doesn't matter, only a | ||
| 4379 | computer reads it!) | ||
| 4380 | |||
| 4381 | The result should be S_OK. For error handling see the example that comes with | ||
| 4382 | certenr3.dll. | ||
| 4383 | |||
| 4384 | A note about ASN.1 character encodings. certenr3.dll seems to know only about | ||
| 4385 | 2 of them: UniversalString and PrintableString. First it is definitely wrong | ||
| 4386 | for an email address which is IA5STRING (checked by ssleay's ca). Second | ||
| 4387 | unfortunately MSIE (at least until version 3.02) can't handle UniversalString | ||
| 4388 | correctly - they just blow up you cert store! Therefore ssleay's ca (starting | ||
| 4389 | from version 0.8.0) tries to convert the encodings automatically to IA5STRING | ||
| 4390 | or TeletexString. The beef is it will work only for the latin-1 (western) | ||
| 4391 | charset. Microsoft still has to do abit of homework... | ||
| 4392 | |||
| 4393 | 3.) An example | ||
| 4394 | -------------- | ||
| 4395 | |||
| 4396 | At least you need two steps: generating the key & request and then installing | ||
| 4397 | the certificate. A real world CA would have some more steps involved, eg. | ||
| 4398 | accepting some license. Note that both scripts shown below are just | ||
| 4399 | experimental state without any warrenty! | ||
| 4400 | |||
| 4401 | First how to generate a request. Note that we can't use a static page because | ||
| 4402 | of the sessionID. I generate it from system time plus pid and hope it is | ||
| 4403 | unique enough. Your are free to feed it through md5 to get more impressive | ||
| 4404 | ID's ;-) Then the intended text is read in with sed which inserts the | ||
| 4405 | sessionID. | ||
| 4406 | |||
| 4407 | -----BEGIN ms-enroll.cgi----- | ||
| 4408 | #!/bin/sh | ||
| 4409 | SESSION_ID=`date '+%y%m%d%H%M%S'`$$ | ||
| 4410 | echo Content-type: text/html | ||
| 4411 | echo | ||
| 4412 | sed s/template_for_sessId/$SESSION_ID/ <<EOF | ||
| 4413 | <HTML><HEAD> | ||
| 4414 | <TITLE>Certificate Enrollment Test Page</TITLE> | ||
| 4415 | </HEAD><BODY> | ||
| 4416 | |||
| 4417 | <OBJECT | ||
| 4418 | classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43" | ||
| 4419 | codebase=certenr3.dll | ||
| 4420 | id=certHelper | ||
| 4421 | > | ||
| 4422 | </OBJECT> | ||
| 4423 | |||
| 4424 | <CENTER> | ||
| 4425 | <H2>enrollment for a personal cert</H2> | ||
| 4426 | <BR><HR WIDTH=50%><BR><P> | ||
| 4427 | <FORM NAME="MSIE_Enrollment" ACTION="ms-gencert.cgi" ENCTYPE=x-www-form- | ||
| 4428 | encoded METHOD=POST> | ||
| 4429 | <TABLE> | ||
| 4430 | <TR><TD>Country</TD><TD><INPUT NAME="Country" VALUE=""></TD></TR> | ||
| 4431 | <TR><TD>State</TD><TD><INPUT NAME="StateOrProvince" VALUE=""></TD></TR> | ||
| 4432 | <TR><TD>Location</TD><TD><INPUT NAME="Location" VALUE=""></TD></TR> | ||
| 4433 | <TR><TD>Organization</TD><TD><INPUT NAME="Organization" | ||
| 4434 | VALUE=""></TD></TR> | ||
| 4435 | <TR><TD>Organizational Unit</TD> | ||
| 4436 | <TD><INPUT NAME="OrganizationalUnit" VALUE=""></TD></TR> | ||
| 4437 | <TR><TD>Name</TD><TD><INPUT NAME="CommonName" VALUE=""></TD></TR> | ||
| 4438 | <TR><TD>eMail Address</TD> | ||
| 4439 | <TD><INPUT NAME="EmailAddress" VALUE=""></TD></TR> | ||
| 4440 | <TR><TD></TD> | ||
| 4441 | <TD><INPUT TYPE="BUTTON" NAME="submit" VALUE="Beantragen"></TD></TR> | ||
| 4442 | </TABLE> | ||
| 4443 | <INPUT TYPE="hidden" NAME="SessionId" VALUE="template_for_sessId"> | ||
| 4444 | <INPUT TYPE="hidden" NAME="Request" VALUE=""> | ||
| 4445 | </FORM> | ||
| 4446 | <BR><HR WIDTH=50%><BR><P> | ||
| 4447 | </CENTER> | ||
| 4448 | |||
| 4449 | <SCRIPT LANGUAGE=VBS> | ||
| 4450 | Dim DN | ||
| 4451 | |||
| 4452 | Sub Submit_OnClick | ||
| 4453 | Dim TheForm | ||
| 4454 | Set TheForm = Document.MSIE_Enrollment | ||
| 4455 | sessionId = TheForm.SessionId.value | ||
| 4456 | reqHardware = FALSE | ||
| 4457 | C = TheForm.Country.value | ||
| 4458 | SP = TheForm.StateOrProvince.value | ||
| 4459 | L = TheForm.Location.value | ||
| 4460 | O = TheForm.Organization.value | ||
| 4461 | OU = TheForm.OrganizationalUnit.value | ||
| 4462 | CN = TheForm.CommonName.value | ||
| 4463 | Email = TheForm.EmailAddress.value | ||
| 4464 | szPurpose = "ClientAuth" | ||
| 4465 | doAcceptanceUINow = FALSE | ||
| 4466 | doOnline = TRUE | ||
| 4467 | |||
| 4468 | DN = "" | ||
| 4469 | |||
| 4470 | Call Add_RDN("C", C) | ||
| 4471 | Call Add_RDN("S", SP) | ||
| 4472 | Call Add_RDN("L", L) | ||
| 4473 | Call Add_RDN("O", O) | ||
| 4474 | Call Add_RDN("OU", OU) | ||
| 4475 | Call Add_RDN("CN", CN) | ||
| 4476 | Call Add_RDN("1.2.840.113549.1.9.1", Email) | ||
| 4477 | ' rsadsi | ||
| 4478 | ' pkcs | ||
| 4479 | ' pkcs9 | ||
| 4480 | ' eMailAddress | ||
| 4481 | On Error Resume Next | ||
| 4482 | sz10 = certHelper.GenerateKeyPair(sessionId, _ | ||
| 4483 | FALSE, DN, 0, ClientAuth, FASLE, TRUE, 1)_ | ||
| 4484 | theError = Err.Number | ||
| 4485 | On Error Goto 0 | ||
| 4486 | if (sz10 = Empty OR theError <> 0) Then | ||
| 4487 | sz = "The error '" & Hex(theError) & "' occurred." & chr(13) & _ | ||
| 4488 | chr(10) & "Your credentials could not be generated." | ||
| 4489 | result = MsgBox(sz, 0, "Credentials Enrollment") | ||
| 4490 | Exit Sub | ||
| 4491 | else | ||
| 4492 | TheForm.Request.value = sz10 | ||
| 4493 | TheForm.Submit | ||
| 4494 | end if | ||
| 4495 | End Sub | ||
| 4496 | |||
| 4497 | Sub Add_RDN(sn, value) | ||
| 4498 | if (value <> "") then | ||
| 4499 | if (DN <> "") then | ||
| 4500 | DN = DN & "; " | ||
| 4501 | end if | ||
| 4502 | DN = DN & sn & "=" & value | ||
| 4503 | end if | ||
| 4504 | End Sub | ||
| 4505 | </SCRIPT> | ||
| 4506 | </BODY> | ||
| 4507 | </HTML> | ||
| 4508 | EOF | ||
| 4509 | -----END ms-enroll.cgi----- | ||
| 4510 | |||
| 4511 | Second, how to extract the request and feed the certificate back? We need to | ||
| 4512 | "normalize" the base64 encoding of the PKCS#10 format which means | ||
| 4513 | regenerating the lines and wrapping with BEGIN and END line. This is done by | ||
| 4514 | gawk. The request is taken by ca the normal way. Then the cert needs to be | ||
| 4515 | packed into a PKCS#7 structure (note: the use of a CRL is necessary for | ||
| 4516 | crl2pkcs7 as of version 0.6.6. Starting with 0.8.0 it it might probably be | ||
| 4517 | ommited). Finally we need to format the PKCS#7 object and generate the HTML | ||
| 4518 | text. I use two templates to have a clearer script. | ||
| 4519 | |||
| 4520 | 1st note: postit2 is slightly modified from a program I found at ncsa's ftp | ||
| 4521 | site. Grab it from http://www.easterngraphics.com/certs/IX9704/postit2.c. You | ||
| 4522 | need utils.c from there too. | ||
| 4523 | |||
| 4524 | 2nd note: I'm note quite sure wether the gawk script really handles all | ||
| 4525 | possible inputs for the request right! Today I don't use this construction | ||
| 4526 | anymore myself. | ||
| 4527 | |||
| 4528 | 3d note: the cert must be of version 3! This could be done with the nsComment | ||
| 4529 | line in ssleay.cnf... | ||
| 4530 | |||
| 4531 | ------BEGIN ms-gencert.cgi----- | ||
| 4532 | #!/bin/sh | ||
| 4533 | FILE="/tmp/"`date '+%y%m%d%H%M%S'-`$$ | ||
| 4534 | rm -f "$FILE".* | ||
| 4535 | |||
| 4536 | HOME=`pwd`; export HOME # as ssleay.cnf insists on having such an env var | ||
| 4537 | cd /usr/local/ssl #where demoCA (as named in ssleay.conf) is located | ||
| 4538 | |||
| 4539 | postit2 -s " " -i 0x0d > "$FILE".inp # process the FORM vars | ||
| 4540 | |||
| 4541 | SESSION_ID=`gawk '$1 == "SessionId" { print $2; exit }' "$FILE".inp` | ||
| 4542 | |||
| 4543 | gawk \ | ||
| 4544 | 'BEGIN { \ | ||
| 4545 | OFS = ""; \ | ||
| 4546 | print "-----BEGIN CERTIFICATE REQUEST-----"; \ | ||
| 4547 | req_seen=0 \ | ||
| 4548 | } \ | ||
| 4549 | $1 == "Request" { \ | ||
| 4550 | req_seen=1; \ | ||
| 4551 | if (length($2) == 72) print($2); \ | ||
| 4552 | lastline=$2; \ | ||
| 4553 | next; \ | ||
| 4554 | } \ | ||
| 4555 | { \ | ||
| 4556 | if (req_seen == 1) { \ | ||
| 4557 | if (length($1) >= 72) print($1); \ | ||
| 4558 | else if (length(lastline) < 72) { \ | ||
| 4559 | req_seen=0; \ | ||
| 4560 | print (lastline,$1); \ | ||
| 4561 | } \ | ||
| 4562 | lastline=$1; \ | ||
| 4563 | } \ | ||
| 4564 | } \ | ||
| 4565 | END { \ | ||
| 4566 | print "-----END CERTIFICATE REQUEST-----"; \ | ||
| 4567 | }' > "$FILE".pem < "$FILE".inp | ||
| 4568 | |||
| 4569 | ssleay ca -batch -in "$FILE".pem -key passwd -out "$FILE".out | ||
| 4570 | ssleay crl2pkcs7 -certfile "$FILE".out -out "$FILE".pkcs7 -in demoCA/crl.pem | ||
| 4571 | |||
| 4572 | sed s/template_for_sessId/$SESSION_ID/ <ms-enroll2a.html >"$FILE".cert | ||
| 4573 | /usr/local/bin/gawk \ | ||
| 4574 | 'BEGIN { \ | ||
| 4575 | OFS = ""; \ | ||
| 4576 | dq = sprintf("%c",34); \ | ||
| 4577 | } \ | ||
| 4578 | $0 ~ "PKCS7" { next; } \ | ||
| 4579 | { \ | ||
| 4580 | print dq$0dq" & _"; \ | ||
| 4581 | }' <"$FILE".pkcs7 >> "$FILE".cert | ||
| 4582 | cat ms-enroll2b.html >>"$FILE".cert | ||
| 4583 | |||
| 4584 | echo Content-type: text/html | ||
| 4585 | echo Content-length: `wc -c "$FILE".cert` | ||
| 4586 | echo | ||
| 4587 | cat "$FILE".cert | ||
| 4588 | rm -f "$FILE".* | ||
| 4589 | -----END ms-gencert.cgi----- | ||
| 4590 | |||
| 4591 | ----BEGIN ms-enroll2a.html---- | ||
| 4592 | <HTML><HEAD><TITLE>Certificate Acceptance Test Page</TITLE></HEAD><BODY> | ||
| 4593 | |||
| 4594 | <OBJECT | ||
| 4595 | classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43" | ||
| 4596 | codebase=certenr3.dll | ||
| 4597 | id=certHelper | ||
| 4598 | > | ||
| 4599 | </OBJECT> | ||
| 4600 | |||
| 4601 | <CENTER> | ||
| 4602 | <H2>Your personal certificate</H2> | ||
| 4603 | <BR><HR WIDTH=50%><BR><P> | ||
| 4604 | Press the button! | ||
| 4605 | <P><INPUT TYPE=BUTTON VALUE="Nimm mich!" NAME="InstallCert"> | ||
| 4606 | </CENTER> | ||
| 4607 | <BR><HR WIDTH=50%><BR> | ||
| 4608 | |||
| 4609 | <SCRIPT LANGUAGE=VBS> | ||
| 4610 | Sub InstallCert_OnClick | ||
| 4611 | |||
| 4612 | sessionId = "template_for_sessId" | ||
| 4613 | credentials = "" & _ | ||
| 4614 | ----END ms-enroll2a.html---- | ||
| 4615 | |||
| 4616 | ----BEGIN ms-enroll2b.html---- | ||
| 4617 | "" | ||
| 4618 | On Error Resume Next | ||
| 4619 | result = certHelper.AcceptCredentials(sessionId, credentials, 0, | ||
| 4620 | FALSE) | ||
| 4621 | if (IsEmpty(result)) Then | ||
| 4622 | sz = "The error '" & Err.Number & "' occurred." & chr(13) & | ||
| 4623 | chr(10) & "This Digital ID could not be registered." | ||
| 4624 | msgOut = MsgBox(sz, 0, "Credentials Registration Error") | ||
| 4625 | navigate "error.html" | ||
| 4626 | else | ||
| 4627 | sz = "Digital ID successfully registered." | ||
| 4628 | msgOut = MsgBox(sz, 0, "Credentials Registration") | ||
| 4629 | navigate "success.html" | ||
| 4630 | end if | ||
| 4631 | Exit Sub | ||
| 4632 | End Sub | ||
| 4633 | </SCRIPT> | ||
| 4634 | </BODY> | ||
| 4635 | </HTML> | ||
| 4636 | ----END ms-enroll2b.html---- | ||
| 4637 | |||
| 4638 | 4.) What do do with the cert? | ||
| 4639 | ----------------------------- | ||
| 4640 | |||
| 4641 | The cert is visible (without restarting MSIE) under the following menu: | ||
| 4642 | View->Options->Security->Personal certs. You can examine it's contents at | ||
| 4643 | least partially. | ||
| 4644 | |||
| 4645 | To use it for client authentication you need to use SSL3.0 (fortunately | ||
| 4646 | SSLeay supports it with 0.8.0). Furthermore MSIE is told to only supports a | ||
| 4647 | kind of automatic selection of certs (I personally wasn't able to test it | ||
| 4648 | myself). But there is a requirement that the issuer of the server cert and | ||
| 4649 | the issuer of the client cert needs to be the same (according to a developer | ||
| 4650 | from MS). Which means: you need may more then one cert to talk to all | ||
| 4651 | servers... | ||
| 4652 | |||
| 4653 | I'm sure we will get a bit more experience after ApacheSSL is available for | ||
| 4654 | SSLeay 0.8.8. | ||
| 4655 | |||
| 4656 | |||
| 4657 | I hope you enjoyed reading and that in future questions on this topic will | ||
| 4658 | rarely appear on ssl-users@moncom.com ;-) | ||
| 4659 | |||
| 4660 | Ilmenau, 9th of June 1997 | ||
| 4661 | Holger Reif <reif@prakinf.tu-ilmenau.de> | ||
| 4662 | -- | ||
| 4663 | read you later - Holger Reif | ||
| 4664 | ---------------------------------------- Signaturprojekt Deutsche Einheit | ||
| 4665 | TU Ilmenau - Informatik - Telematik (Verdamp lang her) | ||
| 4666 | Holger.Reif@PrakInf.TU-Ilmenau.DE Alt wie ein Baum werden, um ueber | ||
| 4667 | http://Remus.PrakInf.TU-Ilmenau.DE/Reif/ alle 7 Bruecken gehen zu koennen | ||
| 4668 | |||
| 4669 | |||
| 4670 | ==== ns-ca.doc ======================================================== | ||
| 4671 | |||
| 4672 | The following documentation was supplied by Jeff Barber, who provided the | ||
| 4673 | patch to the CA program to add this functionality. | ||
| 4674 | |||
| 4675 | eric | ||
| 4676 | -- | ||
| 4677 | Jeff Barber Email: jeffb@issl.atl.hp.com | ||
| 4678 | |||
| 4679 | Hewlett Packard Phone: (404) 648-9503 | ||
| 4680 | Internet and System Security Lab Fax: (404) 648-9516 | ||
| 4681 | |||
| 4682 | oo | ||
| 4683 | ---------------------cut /\ here for ns-ca.doc ------------------------------ | ||
| 4684 | |||
| 4685 | This document briefly describes how to use SSLeay to implement a | ||
| 4686 | certificate authority capable of dynamically serving up client | ||
| 4687 | certificates for version 3.0 beta 5 (and presumably later) versions of | ||
| 4688 | the Netscape Navigator. Before describing how this is done, it's | ||
| 4689 | important to understand a little about how the browser implements its | ||
| 4690 | client certificate support. This is documented in some detail in the | ||
| 4691 | URLs based at <URL:http://home.netscape.com/eng/security/certs.html>. | ||
| 4692 | Here's a brief overview: | ||
| 4693 | |||
| 4694 | - The Navigator supports a new HTML tag "KEYGEN" which will cause | ||
| 4695 | the browser to generate an RSA key pair when you submit a form | ||
| 4696 | containing the tag. The public key, along with an optional | ||
| 4697 | challenge (supposedly provided for use in certificate revocation | ||
| 4698 | but I don't use it) is signed, DER-encoded, base-64 encoded | ||
| 4699 | and sent to the web server as the value of the variable | ||
| 4700 | whose NAME is provided in the KEYGEN tag. The private key is | ||
| 4701 | stored by the browser in a local key database. | ||
| 4702 | |||
| 4703 | This "Signed Public Key And Challenge" (SPKAC) arrives formatted | ||
| 4704 | into 64 character lines (which are of course URL-encoded when | ||
| 4705 | sent via HTTP -- i.e. spaces, newlines and most punctuatation are | ||
| 4706 | encoded as "%HH" where HH is the hex equivalent of the ASCII code). | ||
| 4707 | Note that the SPKAC does not contain the other usual attributes | ||
| 4708 | of a certificate request, especially the subject name fields. | ||
| 4709 | These must be otherwise encoded in the form for submission along | ||
| 4710 | with the SPKAC. | ||
| 4711 | |||
| 4712 | - Either immediately (in response to this form submission), or at | ||
| 4713 | some later date (a real CA will probably verify your identity in | ||
| 4714 | some way before issuing the certificate), a web server can send a | ||
| 4715 | certificate based on the public key and other attributes back to | ||
| 4716 | the browser by encoding it in DER (the binary form) and sending it | ||
| 4717 | to the browser as MIME type: | ||
| 4718 | "Content-type: application/x-x509-user-cert" | ||
| 4719 | |||
| 4720 | The browser uses the public key encoded in the certificate to | ||
| 4721 | associate the certificate with the appropriate private key in | ||
| 4722 | its local key database. Now, the certificate is "installed". | ||
| 4723 | |||
| 4724 | - When a server wants to require authentication based on client | ||
| 4725 | certificates, it uses the right signals via the SSL protocol to | ||
| 4726 | trigger the Navigator to ask you which certificate you want to | ||
| 4727 | send. Whether the certificate is accepted is dependent on CA | ||
| 4728 | certificates and so forth installed in the server and is beyond | ||
| 4729 | the scope of this document. | ||
| 4730 | |||
| 4731 | |||
| 4732 | Now, here's how the SSLeay package can be used to provide client | ||
| 4733 | certficates: | ||
| 4734 | |||
| 4735 | - You prepare a file for input to the SSLeay ca application. | ||
| 4736 | The file contains a number of "name = value" pairs that identify | ||
| 4737 | the subject. The names here are the same subject name component | ||
| 4738 | identifiers used in the CA section of the lib/ssleay.conf file, | ||
| 4739 | such as "emailAddress", "commonName" "organizationName" and so | ||
| 4740 | forth. Both the long version and the short version (e.g. "Email", | ||
| 4741 | "CN", "O") can be used. | ||
| 4742 | |||
| 4743 | One more name is supported: this one is "SPKAC". Its value | ||
| 4744 | is simply the value of the base-64 encoded SPKAC sent by the | ||
| 4745 | browser (with all the newlines and other space charaters | ||
| 4746 | removed -- and newline escapes are NOT supported). | ||
| 4747 | |||
| 4748 | [ As of SSLeay 0.6.4, multiple lines are supported. | ||
| 4749 | Put a \ at the end of each line and it will be joined with the | ||
| 4750 | previous line with the '\n' removed - eay ] | ||
| 4751 | |||
| 4752 | Here's a sample input file: | ||
| 4753 | |||
| 4754 | C = US | ||
| 4755 | SP = Georgia | ||
| 4756 | O = Some Organization, Inc. | ||
| 4757 | OU = Netscape Compatibility Group | ||
| 4758 | CN = John X. Doe | ||
| 4759 | Email = jxdoe@someorg.com | ||
| 4760 | SPKAC = MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwmk6FMJ4uAVIYbcvIOx5+bDGTfvL8X5gE+R67ccMk6rCSGbVQz2cetyQtnI+VIs0NwdD6wjuSuVtVFbLoHonowIDAQABFgAwDQYJKoZIhvcNAQEEBQADQQBFZDUWFl6BJdomtN1Bi53mwijy1rRgJ4YirF15yBEDM3DjAQkKXHYOIX+qpz4KXKnl6EYxTnGSFL5wWt8X2iyx | ||
| 4761 | |||
| 4762 | - You execute the ca command (either from a CGI program run out of | ||
| 4763 | the web server, or as a later manual task) giving it the above | ||
| 4764 | file as input. For example, if the file were named /tmp/cert.req, | ||
| 4765 | you'd run: | ||
| 4766 | $SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert | ||
| 4767 | |||
| 4768 | The output is in DER format (binary) if a -out argument is | ||
| 4769 | provided, as above; otherwise, it's in the PEM format (base-64 | ||
| 4770 | encoded DER). Also, the "-batch" switch is implied by the | ||
| 4771 | "-spkac" so you don't get asked whether to complete the signing | ||
| 4772 | (probably it shouldn't work this way but I was only interested | ||
| 4773 | in hacking together an online CA that could be used for issuing | ||
| 4774 | test certificates). | ||
| 4775 | |||
| 4776 | The "-spkac" capability doesn't support multiple files (I think). | ||
| 4777 | |||
| 4778 | Any CHALLENGE provided in the SPKAC is simply ignored. | ||
| 4779 | |||
| 4780 | The interactions between the identification fields you provide | ||
| 4781 | and those identified in your lib/ssleay.conf are the same as if | ||
| 4782 | you did an ordinary "ca -in infile -out outfile" -- that is, if | ||
| 4783 | something is marked as required in the ssleay.conf file and it | ||
| 4784 | isn't found in the -spkac file, the certificate won't be issued. | ||
| 4785 | |||
| 4786 | - Now, you pick up the output from /tmp/cert and pass it back to | ||
| 4787 | the Navigator prepending the Content-type string described earlier. | ||
| 4788 | |||
| 4789 | - In order to run the ca command out of a CGI program, you must | ||
| 4790 | provide a password to decrypt the CA's private key. You can | ||
| 4791 | do this by using "echo MyKeyPassword | $SSLDIR/bin/ca ..." | ||
| 4792 | I think there's a way to not encrypt the key file in the first | ||
| 4793 | place, but I didn't see how to do that, so I made a small change | ||
| 4794 | to the library that allows the password to be accepted from a pipe. | ||
| 4795 | Either way is UTTERLY INSECURE and a real CA would never do that. | ||
| 4796 | |||
| 4797 | [ You can use the 'ssleay rsa' command to remove the password | ||
| 4798 | from the private key, or you can use the '-key' option to the | ||
| 4799 | ca command to specify the decryption key on the command line | ||
| 4800 | or use the -nodes option when generating the key. | ||
| 4801 | ca will try to clear the command line version of the password | ||
| 4802 | but for quite a few operating systems, this is not possible. | ||
| 4803 | - eric ] | ||
| 4804 | |||
| 4805 | So, what do you have to do to make use of this stuff to create an online | ||
| 4806 | demo CA capability with SSLeay? | ||
| 4807 | |||
| 4808 | 1 Create an HTML form for your users. The form should contain | ||
| 4809 | fields for all of the required or optional fields in ssleay.conf. | ||
| 4810 | The form must contain a KEYGEN tag somewhere with at least a NAME | ||
| 4811 | attribute. | ||
| 4812 | |||
| 4813 | 2 Create a CGI program to process the form input submitted by the | ||
| 4814 | browser. The CGI program must URL-decode the variables and create | ||
| 4815 | the file described above, containing subject identification info | ||
| 4816 | as well as the SPKAC block. It should then run the the ca program | ||
| 4817 | with the -spkac option. If it works (check the exit status), | ||
| 4818 | return the new certificate with the appropriate MIME type. If not, | ||
| 4819 | return the output of the ca command with MIME type "text/plain". | ||
| 4820 | |||
| 4821 | 3 Set up your web server to accept connections signed by your demo | ||
| 4822 | CA. This probably involves obtaining the PEM-encoded CA certificate | ||
| 4823 | (ordinarily in $SSLDIR/CA/cacert.pem) and installing it into a | ||
| 4824 | server database. See your server manual for instructions. | ||
| 4825 | |||
| 4826 | |||
| 4827 | ==== obj.doc ======================================================== | ||
| 4828 | |||
| 4829 | The Object library. | ||
| 4830 | |||
| 4831 | As part of my Crypto library, I found I required a method of identifying various | ||
| 4832 | objects. These objects normally had 3 different values associated with | ||
| 4833 | them, a short text name, a long (or lower case) text name, and an | ||
| 4834 | ASN.1 Object Identifier (which is a sequence of numbers). | ||
| 4835 | This library contains a static list of objects and functions to lookup | ||
| 4836 | according to one type and to return the other types. | ||
| 4837 | |||
| 4838 | To use these routines, 'Object.h' needs to be included. | ||
| 4839 | |||
| 4840 | For each supported object, #define entries are defined as follows | ||
| 4841 | #define SN_Algorithm "Algorithm" | ||
| 4842 | #define LN_algorithm "algorithm" | ||
| 4843 | #define NID_algorithm 38 | ||
| 4844 | #define OBJ_algorithm 1L,3L,14L,3L,2L | ||
| 4845 | |||
| 4846 | SN_ stands for short name. | ||
| 4847 | LN_ stands for either long name or lowercase name. | ||
| 4848 | NID_ stands for Numeric ID. I each object has a unique NID and this | ||
| 4849 | should be used internally to identify objects. | ||
| 4850 | OBJ_ stands for ASN.1 Object Identifier or ASN1_OBJECT as defined in the | ||
| 4851 | ASN1 routines. These values are used in ASN1 encoding. | ||
| 4852 | |||
| 4853 | The following functions are to be used to return pointers into a static | ||
| 4854 | definition of these types. What this means is "don't try to free() any | ||
| 4855 | pointers returned from these functions. | ||
| 4856 | |||
| 4857 | ASN1_OBJECT *OBJ_nid2obj( | ||
| 4858 | int n); | ||
| 4859 | Return the ASN1_OBJECT that corresponds to a NID of n. | ||
| 4860 | |||
| 4861 | char *OBJ_nid2ln( | ||
| 4862 | int n); | ||
| 4863 | Return the long/lower case name of the object represented by the | ||
| 4864 | NID of n. | ||
| 4865 | |||
| 4866 | char *OBJ_nid2sn( | ||
| 4867 | int n); | ||
| 4868 | Return the short name for the object represented by the NID of n. | ||
| 4869 | |||
| 4870 | ASN1_OBJECT *OBJ_dup( | ||
| 4871 | ASN1_OBJECT *o); | ||
| 4872 | Duplicate and return a new ASN1_OBJECT that is the same as the | ||
| 4873 | passed parameter. | ||
| 4874 | |||
| 4875 | int OBJ_obj2nid( | ||
| 4876 | ASN1_OBJECT *o); | ||
| 4877 | Given ASN1_OBJECT o, return the NID that corresponds. | ||
| 4878 | |||
| 4879 | int OBJ_ln2nid( | ||
| 4880 | char *s); | ||
| 4881 | Given the long/lower case name 's', return the NID of the object. | ||
| 4882 | |||
| 4883 | int OBJ_sn2nid( | ||
| 4884 | char *s); | ||
| 4885 | Given the short name 's', return the NID of the object. | ||
| 4886 | |||
| 4887 | char *OBJ_bsearch( | ||
| 4888 | char *key, | ||
| 4889 | char *base, | ||
| 4890 | int num, | ||
| 4891 | int size, | ||
| 4892 | int (*cmp)()); | ||
| 4893 | Since I have come across a few platforms that do not have the | ||
| 4894 | bsearch() function, OBJ_bsearch is my version of that function. | ||
| 4895 | Feel free to use this function, but you may as well just use the | ||
| 4896 | normal system bsearch(3) if it is present. This version also | ||
| 4897 | has tolerance of being passed NULL pointers. | ||
| 4898 | |||
| 4899 | ==== keys =========================================================== | ||
| 4900 | |||
| 4901 | EVP_PKEY_DSA | ||
| 4902 | EVP_PKEY_DSA2 | ||
| 4903 | EVP_PKEY_DSA3 | ||
| 4904 | EVP_PKEY_DSA4 | ||
| 4905 | |||
| 4906 | EVP_PKEY_RSA | ||
| 4907 | EVP_PKEY_RSA2 | ||
| 4908 | |||
| 4909 | valid DSA pkey types | ||
| 4910 | NID_dsa | ||
| 4911 | NID_dsaWithSHA | ||
| 4912 | NID_dsaWithSHA1 | ||
| 4913 | NID_dsaWithSHA1_2 | ||
| 4914 | |||
| 4915 | valid RSA pkey types | ||
| 4916 | NID_rsaEncryption | ||
| 4917 | NID_rsa | ||
| 4918 | |||
| 4919 | NID_dsaWithSHA NID_dsaWithSHA DSA SHA | ||
| 4920 | NID_dsa NID_dsaWithSHA1 DSA SHA1 | ||
| 4921 | NID_md2 NID_md2WithRSAEncryption RSA-pkcs1 MD2 | ||
| 4922 | NID_md5 NID_md5WithRSAEncryption RSA-pkcs1 MD5 | ||
| 4923 | NID_mdc2 NID_mdc2WithRSA RSA-none MDC2 | ||
| 4924 | NID_ripemd160 NID_ripemd160WithRSA RSA-pkcs1 RIPEMD160 | ||
| 4925 | NID_sha NID_shaWithRSAEncryption RSA-pkcs1 SHA | ||
| 4926 | NID_sha1 NID_sha1WithRSAEncryption RSA-pkcs1 SHA1 | ||
| 4927 | |||
| 4928 | ==== rand.doc ======================================================== | ||
| 4929 | |||
| 4930 | My Random number library. | ||
| 4931 | |||
| 4932 | These routines can be used to generate pseudo random numbers and can be | ||
| 4933 | used to 'seed' the pseudo random number generator (RNG). The RNG make no | ||
| 4934 | effort to reproduce the same random number stream with each execution. | ||
| 4935 | Various other routines in the SSLeay library 'seed' the RNG when suitable | ||
| 4936 | 'random' input data is available. Read the section at the end for details | ||
| 4937 | on the design of the RNG. | ||
| 4938 | |||
| 4939 | void RAND_bytes( | ||
| 4940 | unsigned char *buf, | ||
| 4941 | int num); | ||
| 4942 | This routine puts 'num' random bytes into 'buf'. One should make | ||
| 4943 | sure RAND_seed() has been called before using this routine. | ||
| 4944 | |||
| 4945 | void RAND_seed( | ||
| 4946 | unsigned char *buf, | ||
| 4947 | int num); | ||
| 4948 | This routine adds more 'seed' data the RNG state. 'num' bytes | ||
| 4949 | are added to the RNG state, they are taken from 'buf'. This | ||
| 4950 | routine can be called with sensitive data such as user entered | ||
| 4951 | passwords. This sensitive data is in no way recoverable from | ||
| 4952 | the RAND library routines or state. Try to pass as much data | ||
| 4953 | from 'random' sources as possible into the RNG via this function. | ||
| 4954 | Also strongly consider using the RAND_load_file() and | ||
| 4955 | RAND_write_file() routines. | ||
| 4956 | |||
| 4957 | void RAND_cleanup(); | ||
| 4958 | When a program has finished with the RAND library, if it so | ||
| 4959 | desires, it can 'zero' all RNG state. | ||
| 4960 | |||
| 4961 | The following 3 routines are convenience routines that can be used to | ||
| 4962 | 'save' and 'restore' data from/to the RNG and it's state. | ||
| 4963 | Since the more 'random' data that is feed as seed data the better, why not | ||
| 4964 | keep it around between executions of the program? Of course the | ||
| 4965 | application should pass more 'random' data in via RAND_seed() and | ||
| 4966 | make sure no-one can read the 'random' data file. | ||
| 4967 | |||
| 4968 | char *RAND_file_name( | ||
| 4969 | char *buf, | ||
| 4970 | int size); | ||
| 4971 | This routine returns a 'default' name for the location of a 'rand' | ||
| 4972 | file. The 'rand' file should keep a sequence of random bytes used | ||
| 4973 | to initialise the RNG. The filename is put in 'buf'. Buf is 'size' | ||
| 4974 | bytes long. Buf is returned if things go well, if they do not, | ||
| 4975 | NULL is returned. The 'rand' file name is generated in the | ||
| 4976 | following way. First, if there is a 'RANDFILE' environment | ||
| 4977 | variable, it is returned. Second, if there is a 'HOME' environment | ||
| 4978 | variable, $HOME/.rand is returned. Third, NULL is returned. NULL | ||
| 4979 | is also returned if a buf would overflow. | ||
| 4980 | |||
| 4981 | int RAND_load_file( | ||
| 4982 | char *file, | ||
| 4983 | long number); | ||
| 4984 | This function 'adds' the 'file' into the RNG state. It does this by | ||
| 4985 | doing a RAND_seed() on the value returned from a stat() system call | ||
| 4986 | on the file and if 'number' is non-zero, upto 'number' bytes read | ||
| 4987 | from the file. The number of bytes passed to RAND_seed() is returned. | ||
| 4988 | |||
| 4989 | int RAND_write_file( | ||
| 4990 | char *file), | ||
| 4991 | RAND_write_file() writes N random bytes to the file 'file', where | ||
| 4992 | N is the size of the internal RND state (currently 1k). | ||
| 4993 | This is a suitable method of saving RNG state for reloading via | ||
| 4994 | RAND_load_file(). | ||
| 4995 | |||
| 4996 | What follows is a description of this RNG and a description of the rational | ||
| 4997 | behind it's design. | ||
| 4998 | |||
| 4999 | It should be noted that this RNG is intended to be used to generate | ||
| 5000 | 'random' keys for various ciphers including generation of DH and RSA keys. | ||
| 5001 | |||
| 5002 | It should also be noted that I have just created a system that I am happy with. | ||
| 5003 | It may be overkill but that does not worry me. I have not spent that much | ||
| 5004 | time on this algorithm so if there are glaring errors, please let me know. | ||
| 5005 | Speed has not been a consideration in the design of these routines. | ||
| 5006 | |||
| 5007 | First up I will state the things I believe I need for a good RNG. | ||
| 5008 | 1) A good hashing algorithm to mix things up and to convert the RNG 'state' | ||
| 5009 | to random numbers. | ||
| 5010 | 2) An initial source of random 'state'. | ||
| 5011 | 3) The state should be very large. If the RNG is being used to generate | ||
| 5012 | 4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum). | ||
| 5013 | If your RNG state only has 128 bits, you are obviously limiting the | ||
| 5014 | search space to 128 bits, not 2048. I'm probably getting a little | ||
| 5015 | carried away on this last point but it does indicate that it may not be | ||
| 5016 | a bad idea to keep quite a lot of RNG state. It should be easier to | ||
| 5017 | break a cipher than guess the RNG seed data. | ||
| 5018 | 4) Any RNG seed data should influence all subsequent random numbers | ||
| 5019 | generated. This implies that any random seed data entered will have | ||
| 5020 | an influence on all subsequent random numbers generated. | ||
| 5021 | 5) When using data to seed the RNG state, the data used should not be | ||
| 5022 | extractable from the RNG state. I believe this should be a | ||
| 5023 | requirement because one possible source of 'secret' semi random | ||
| 5024 | data would be a private key or a password. This data must | ||
| 5025 | not be disclosed by either subsequent random numbers or a | ||
| 5026 | 'core' dump left by a program crash. | ||
| 5027 | 6) Given the same initial 'state', 2 systems should deviate in their RNG state | ||
| 5028 | (and hence the random numbers generated) over time if at all possible. | ||
| 5029 | 7) Given the random number output stream, it should not be possible to determine | ||
| 5030 | the RNG state or the next random number. | ||
| 5031 | |||
| 5032 | |||
| 5033 | The algorithm is as follows. | ||
| 5034 | |||
| 5035 | There is global state made up of a 1023 byte buffer (the 'state'), a | ||
| 5036 | working message digest ('md') and a counter ('count'). | ||
| 5037 | |||
| 5038 | Whenever seed data is added, it is inserted into the 'state' as | ||
| 5039 | follows. | ||
| 5040 | The input is chopped up into units of 16 bytes (or less for | ||
| 5041 | the last block). Each of these blocks is run through the MD5 | ||
| 5042 | message digest. The data passed to the MD5 digest is the | ||
| 5043 | current 'md', the same number of bytes from the 'state' | ||
| 5044 | (the location determined by in incremented looping index) as | ||
| 5045 | the current 'block' and the new key data 'block'. The result | ||
| 5046 | of this is kept in 'md' and also xored into the 'state' at the | ||
| 5047 | same locations that were used as input into the MD5. | ||
| 5048 | I believe this system addresses points 1 (MD5), 3 (the 'state'), | ||
| 5049 | 4 (via the 'md'), 5 (by the use of MD5 and xor). | ||
| 5050 | |||
| 5051 | When bytes are extracted from the RNG, the following process is used. | ||
| 5052 | For each group of 8 bytes (or less), we do the following, | ||
| 5053 | Input into MD5, the top 8 bytes from 'md', the byte that are | ||
| 5054 | to be overwritten by the random bytes and bytes from the | ||
| 5055 | 'state' (incrementing looping index). From this digest output | ||
| 5056 | (which is kept in 'md'), the top (upto) 8 bytes are | ||
| 5057 | returned to the caller and the bottom (upto) 8 bytes are xored | ||
| 5058 | into the 'state'. | ||
| 5059 | Finally, after we have finished 'generation' random bytes for the | ||
| 5060 | called, 'count' (which is incremented) and 'md' are fed into MD5 and | ||
| 5061 | the results are kept in 'md'. | ||
| 5062 | I believe the above addressed points 1 (use of MD5), 6 (by | ||
| 5063 | hashing into the 'state' the 'old' data from the caller that | ||
| 5064 | is about to be overwritten) and 7 (by not using the 8 bytes | ||
| 5065 | given to the caller to update the 'state', but they are used | ||
| 5066 | to update 'md'). | ||
| 5067 | |||
| 5068 | So of the points raised, only 2 is not addressed, but sources of | ||
| 5069 | random data will always be a problem. | ||
| 5070 | |||
| 5071 | |||
| 5072 | ==== rc2.doc ======================================================== | ||
| 5073 | |||
| 5074 | The RC2 library. | ||
| 5075 | |||
| 5076 | RC2 is a block cipher that operates on 64bit (8 byte) quantities. It | ||
| 5077 | uses variable size key, but 128bit (16 byte) key would normally be considered | ||
| 5078 | good. It can be used in all the modes that DES can be used. This | ||
| 5079 | library implements the ecb, cbc, cfb64, ofb64 modes. | ||
| 5080 | |||
| 5081 | I have implemented this library from an article posted to sci.crypt on | ||
| 5082 | 11-Feb-1996. I personally don't know how far to trust the RC2 cipher. | ||
| 5083 | While it is capable of having a key of any size, not much reseach has | ||
| 5084 | publically been done on it at this point in time (Apr-1996) | ||
| 5085 | since the cipher has only been public for a few months :-) | ||
| 5086 | It is of a similar speed to DES and IDEA, so unless it is required for | ||
| 5087 | meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable | ||
| 5088 | to stick to IDEA, or for the paranoid, Tripple DES. | ||
| 5089 | |||
| 5090 | Mind you, having said all that, I should mention that I just read alot and | ||
| 5091 | implement ciphers, I'm a 'babe in the woods' when it comes to evaluating | ||
| 5092 | ciphers :-). | ||
| 5093 | |||
| 5094 | For all calls that have an 'input' and 'output' variables, they can be the | ||
| 5095 | same. | ||
| 5096 | |||
| 5097 | This library requires the inclusion of 'rc2.h'. | ||
| 5098 | |||
| 5099 | All of the encryption functions take what is called an RC2_KEY as an | ||
| 5100 | argument. An RC2_KEY is an expanded form of the RC2 key. | ||
| 5101 | For all modes of the RC2 algorithm, the RC2_KEY used for | ||
| 5102 | decryption is the same one that was used for encryption. | ||
| 5103 | |||
| 5104 | The define RC2_ENCRYPT is passed to specify encryption for the functions | ||
| 5105 | that require an encryption/decryption flag. RC2_DECRYPT is passed to | ||
| 5106 | specify decryption. | ||
| 5107 | |||
| 5108 | Please note that any of the encryption modes specified in my DES library | ||
| 5109 | could be used with RC2. I have only implemented ecb, cbc, cfb64 and | ||
| 5110 | ofb64 for the following reasons. | ||
| 5111 | - ecb is the basic RC2 encryption. | ||
| 5112 | - cbc is the normal 'chaining' form for block ciphers. | ||
| 5113 | - cfb64 can be used to encrypt single characters, therefore input and output | ||
| 5114 | do not need to be a multiple of 8. | ||
| 5115 | - ofb64 is similar to cfb64 but is more like a stream cipher, not as | ||
| 5116 | secure (not cipher feedback) but it does not have an encrypt/decrypt mode. | ||
| 5117 | - If you want triple RC2, thats 384 bits of key and you must be totally | ||
| 5118 | obsessed with security. Still, if you want it, it is simple enough to | ||
| 5119 | copy the function from the DES library and change the des_encrypt to | ||
| 5120 | RC2_encrypt; an exercise left for the paranoid reader :-). | ||
| 5121 | |||
| 5122 | The functions are as follows: | ||
| 5123 | |||
| 5124 | void RC2_set_key( | ||
| 5125 | RC2_KEY *ks; | ||
| 5126 | int len; | ||
| 5127 | unsigned char *key; | ||
| 5128 | int bits; | ||
| 5129 | RC2_set_key converts an 'len' byte key into a RC2_KEY. | ||
| 5130 | A 'ks' is an expanded form of the 'key' which is used to | ||
| 5131 | perform actual encryption. It can be regenerated from the RC2 key | ||
| 5132 | so it only needs to be kept when encryption or decryption is about | ||
| 5133 | to occur. Don't save or pass around RC2_KEY's since they | ||
| 5134 | are CPU architecture dependent, 'key's are not. RC2 is an | ||
| 5135 | interesting cipher in that it can be used with a variable length | ||
| 5136 | key. 'len' is the length of 'key' to be used as the key. | ||
| 5137 | A 'len' of 16 is recomended. The 'bits' argument is an | ||
| 5138 | interesting addition which I only found out about in Aug 96. | ||
| 5139 | BSAFE uses this parameter to 'limit' the number of bits used | ||
| 5140 | for the key. To use the 'key' unmodified, set bits to 1024. | ||
| 5141 | This is what old versions of my RC2 library did (SSLeay 0.6.3). | ||
| 5142 | RSAs BSAFE library sets this parameter to be 128 if 128 bit | ||
| 5143 | keys are being used. So to be compatable with BSAFE, set it | ||
| 5144 | to 128, if you don't want to reduce RC2's key length, leave it | ||
| 5145 | at 1024. | ||
| 5146 | |||
| 5147 | void RC2_encrypt( | ||
| 5148 | unsigned long *data, | ||
| 5149 | RC2_KEY *key, | ||
| 5150 | int encrypt); | ||
| 5151 | This is the RC2 encryption function that gets called by just about | ||
| 5152 | every other RC2 routine in the library. You should not use this | ||
| 5153 | function except to implement 'modes' of RC2. I say this because the | ||
| 5154 | functions that call this routine do the conversion from 'char *' to | ||
| 5155 | long, and this needs to be done to make sure 'non-aligned' memory | ||
| 5156 | access do not occur. | ||
| 5157 | Data is a pointer to 2 unsigned long's and key is the | ||
| 5158 | RC2_KEY to use. Encryption or decryption is indicated by 'encrypt'. | ||
| 5159 | which can have the values RC2_ENCRYPT or RC2_DECRYPT. | ||
| 5160 | |||
| 5161 | void RC2_ecb_encrypt( | ||
| 5162 | unsigned char *in, | ||
| 5163 | unsigned char *out, | ||
| 5164 | RC2_KEY *key, | ||
| 5165 | int encrypt); | ||
| 5166 | This is the basic Electronic Code Book form of RC2 (in DES this | ||
| 5167 | mode is called Electronic Code Book so I'm going to use the term | ||
| 5168 | for rc2 as well. | ||
| 5169 | Input is encrypted into output using the key represented by | ||
| 5170 | key. Depending on the encrypt, encryption or | ||
| 5171 | decryption occurs. Input is 8 bytes long and output is 8 bytes. | ||
| 5172 | |||
| 5173 | void RC2_cbc_encrypt( | ||
| 5174 | unsigned char *in, | ||
| 5175 | unsigned char *out, | ||
| 5176 | long length, | ||
| 5177 | RC2_KEY *ks, | ||
| 5178 | unsigned char *ivec, | ||
| 5179 | int encrypt); | ||
| 5180 | This routine implements RC2 in Cipher Block Chaining mode. | ||
| 5181 | Input, which should be a multiple of 8 bytes is encrypted | ||
| 5182 | (or decrypted) to output which will also be a multiple of 8 bytes. | ||
| 5183 | The number of bytes is in length (and from what I've said above, | ||
| 5184 | should be a multiple of 8). If length is not a multiple of 8, bad | ||
| 5185 | things will probably happen. ivec is the initialisation vector. | ||
| 5186 | This function updates iv after each call so that it can be passed to | ||
| 5187 | the next call to RC2_cbc_encrypt(). | ||
| 5188 | |||
| 5189 | void RC2_cfb64_encrypt( | ||
| 5190 | unsigned char *in, | ||
| 5191 | unsigned char *out, | ||
| 5192 | long length, | ||
| 5193 | RC2_KEY *schedule, | ||
| 5194 | unsigned char *ivec, | ||
| 5195 | int *num, | ||
| 5196 | int encrypt); | ||
| 5197 | This is one of the more useful functions in this RC2 library, it | ||
| 5198 | implements CFB mode of RC2 with 64bit feedback. | ||
| 5199 | This allows you to encrypt an arbitrary number of bytes, | ||
| 5200 | you do not require 8 byte padding. Each call to this | ||
| 5201 | routine will encrypt the input bytes to output and then update ivec | ||
| 5202 | and num. Num contains 'how far' we are though ivec. | ||
| 5203 | 'Encrypt' is used to indicate encryption or decryption. | ||
| 5204 | CFB64 mode operates by using the cipher to generate a stream | ||
| 5205 | of bytes which is used to encrypt the plain text. | ||
| 5206 | The cipher text is then encrypted to generate the next 64 bits to | ||
| 5207 | be xored (incrementally) with the next 64 bits of plain | ||
| 5208 | text. As can be seen from this, to encrypt or decrypt, | ||
| 5209 | the same 'cipher stream' needs to be generated but the way the next | ||
| 5210 | block of data is gathered for encryption is different for | ||
| 5211 | encryption and decryption. | ||
| 5212 | |||
| 5213 | void RC2_ofb64_encrypt( | ||
| 5214 | unsigned char *in, | ||
| 5215 | unsigned char *out, | ||
| 5216 | long length, | ||
| 5217 | RC2_KEY *schedule, | ||
| 5218 | unsigned char *ivec, | ||
| 5219 | int *num); | ||
| 5220 | This functions implements OFB mode of RC2 with 64bit feedback. | ||
| 5221 | This allows you to encrypt an arbitrary number of bytes, | ||
| 5222 | you do not require 8 byte padding. Each call to this | ||
| 5223 | routine will encrypt the input bytes to output and then update ivec | ||
| 5224 | and num. Num contains 'how far' we are though ivec. | ||
| 5225 | This is in effect a stream cipher, there is no encryption or | ||
| 5226 | decryption mode. | ||
| 5227 | |||
| 5228 | For reading passwords, I suggest using des_read_pw_string() from my DES library. | ||
| 5229 | To generate a password from a text string, I suggest using MD5 (or MD2) to | ||
| 5230 | produce a 16 byte message digest that can then be passed directly to | ||
| 5231 | RC2_set_key(). | ||
| 5232 | |||
| 5233 | ===== | ||
| 5234 | For more information about the specific RC2 modes in this library | ||
| 5235 | (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the | ||
| 5236 | documentation on my DES library. What is said about DES is directly | ||
| 5237 | applicable for RC2. | ||
| 5238 | |||
| 5239 | |||
| 5240 | ==== rc4.doc ======================================================== | ||
| 5241 | |||
| 5242 | The RC4 library. | ||
| 5243 | RC4 is a stream cipher that operates on a byte stream. It can be used with | ||
| 5244 | any length key but I would recommend normally using 16 bytes. | ||
| 5245 | |||
| 5246 | This library requires the inclusion of 'rc4.h'. | ||
| 5247 | |||
| 5248 | The RC4 encryption function takes what is called an RC4_KEY as an argument. | ||
| 5249 | The RC4_KEY is generated by the RC4_set_key function from the key bytes. | ||
| 5250 | |||
| 5251 | RC4, being a stream cipher, does not have an encryption or decryption mode. | ||
| 5252 | It produces a stream of bytes that the input stream is xor'ed against and | ||
| 5253 | so decryption is just a case of 'encrypting' again with the same key. | ||
| 5254 | |||
| 5255 | I have only put in one 'mode' for RC4 which is the normal one. This means | ||
| 5256 | there is no initialisation vector and there is no feedback of the cipher | ||
| 5257 | text into the cipher. This implies that you should not ever use the | ||
| 5258 | same key twice if you can help it. If you do, you leave yourself open to | ||
| 5259 | known plain text attacks; if you know the plain text and | ||
| 5260 | corresponding cipher text in one message, all messages that used the same | ||
| 5261 | key can have the cipher text decoded for the corresponding positions in the | ||
| 5262 | cipher stream. | ||
| 5263 | |||
| 5264 | The main positive feature of RC4 is that it is a very fast cipher; about 4 | ||
| 5265 | times faster that DES. This makes it ideally suited to protocols where the | ||
| 5266 | key is randomly chosen, like SSL. | ||
| 5267 | |||
| 5268 | The functions are as follows: | ||
| 5269 | |||
| 5270 | void RC4_set_key( | ||
| 5271 | RC4_KEY *key; | ||
| 5272 | int len; | ||
| 5273 | unsigned char *data); | ||
| 5274 | This function initialises the RC4_KEY structure with the key passed | ||
| 5275 | in 'data', which is 'len' bytes long. The key data can be any | ||
| 5276 | length but 16 bytes seems to be a good number. | ||
| 5277 | |||
| 5278 | void RC4( | ||
| 5279 | RC4_KEY *key; | ||
| 5280 | unsigned long len; | ||
| 5281 | unsigned char *in; | ||
| 5282 | unsigned char *out); | ||
| 5283 | Do the actual RC4 encryption/decryption. Using the 'key', 'len' | ||
| 5284 | bytes are transformed from 'in' to 'out'. As mentioned above, | ||
| 5285 | decryption is the operation as encryption. | ||
| 5286 | |||
| 5287 | ==== ref.doc ======================================================== | ||
| 5288 | |||
| 5289 | I have lots more references etc, and will update this list in the future, | ||
| 5290 | 30 Aug 1996 - eay | ||
| 5291 | |||
| 5292 | |||
| 5293 | SSL The SSL Protocol - from Netscapes. | ||
| 5294 | |||
| 5295 | RC4 Newsgroups: sci.crypt | ||
| 5296 | From: sterndark@netcom.com (David Sterndark) | ||
| 5297 | Subject: RC4 Algorithm revealed. | ||
| 5298 | Message-ID: <sternCvKL4B.Hyy@netcom.com> | ||
| 5299 | |||
| 5300 | RC2 Newsgroups: sci.crypt | ||
| 5301 | From: pgut01@cs.auckland.ac.nz (Peter Gutmann) | ||
| 5302 | Subject: Specification for Ron Rivests Cipher No.2 | ||
| 5303 | Message-ID: <4fk39f$f70@net.auckland.ac.nz> | ||
| 5304 | |||
| 5305 | MD2 RFC1319 The MD2 Message-Digest Algorithm | ||
| 5306 | MD5 RFC1321 The MD5 Message-Digest Algorithm | ||
| 5307 | |||
| 5308 | X509 Certificates | ||
| 5309 | RFC1421 Privacy Enhancement for Internet Electronic Mail: Part I | ||
| 5310 | RFC1422 Privacy Enhancement for Internet Electronic Mail: Part II | ||
| 5311 | RFC1423 Privacy Enhancement for Internet Electronic Mail: Part III | ||
| 5312 | RFC1424 Privacy Enhancement for Internet Electronic Mail: Part IV | ||
| 5313 | |||
| 5314 | RSA and various standard encoding | ||
| 5315 | PKCS#1 RSA Encryption Standard | ||
| 5316 | PKCS#5 Password-Based Encryption Standard | ||
| 5317 | PKCS#7 Cryptographic Message Syntax Standard | ||
| 5318 | A Layman's Guide to a Subset of ASN.1, BER, and DER | ||
| 5319 | An Overview of the PKCS Standards | ||
| 5320 | Some Examples of the PKCS Standards | ||
| 5321 | |||
| 5322 | IDEA Chapter 3 The Block Cipher IDEA | ||
| 5323 | |||
| 5324 | RSA, prime number generation and bignum algorithms | ||
| 5325 | Introduction To Algorithms, | ||
| 5326 | Thomas Cormen, Charles Leiserson, Ronald Rivest, | ||
| 5327 | Section 29 Arithmetic Circuits | ||
| 5328 | Section 33 Number-Theoretic Algorithms | ||
| 5329 | |||
| 5330 | Fast Private Key algorithm | ||
| 5331 | Fast Decipherment Algorithm for RSA Public-Key Cryptosystem | ||
| 5332 | J.-J. Quisquater and C. Couvreur, Electronics Letters, | ||
| 5333 | 14th October 1982, Vol. 18 No. 21 | ||
| 5334 | |||
| 5335 | Prime number generation and bignum algorithms. | ||
| 5336 | PGP-2.3a | ||
| 5337 | |||
| 5338 | ==== rsa.doc ======================================================== | ||
| 5339 | |||
| 5340 | The RSA encryption and utility routines. | ||
| 5341 | |||
| 5342 | The RSA routines are built on top of a big number library (the BN library). | ||
| 5343 | There are support routines in the X509 library for loading and manipulating | ||
| 5344 | the various objects in the RSA library. When errors are returned, read | ||
| 5345 | about the ERR library for how to access the error codes. | ||
| 5346 | |||
| 5347 | All RSA encryption is done according to the PKCS-1 standard which is | ||
| 5348 | compatible with PEM and RSAref. This means that any values being encrypted | ||
| 5349 | must be less than the size of the modulus in bytes, minus 10, bytes long. | ||
| 5350 | |||
| 5351 | This library uses RAND_bytes()() for it's random data, make sure to feed | ||
| 5352 | RAND_seed() with lots of interesting and varied data before using these | ||
| 5353 | routines. | ||
| 5354 | |||
| 5355 | The RSA library has one specific data type, the RSA structure. | ||
| 5356 | It is composed of 8 BIGNUM variables (see the BN library for details) and | ||
| 5357 | can hold either a private RSA key or a public RSA key. | ||
| 5358 | Some RSA libraries have different structures for public and private keys, I | ||
| 5359 | don't. For my libraries, a public key is determined by the fact that the | ||
| 5360 | RSA->d value is NULL. These routines will operate on any size RSA keys. | ||
| 5361 | While I'm sure 4096 bit keys are very very secure, they take a lot longer | ||
| 5362 | to process that 1024 bit keys :-). | ||
| 5363 | |||
| 5364 | The function in the RSA library are as follows. | ||
| 5365 | |||
| 5366 | RSA *RSA_new(); | ||
| 5367 | This function creates a new RSA object. The sub-fields of the RSA | ||
| 5368 | type are also malloced so you should always use this routine to | ||
| 5369 | create RSA variables. | ||
| 5370 | |||
| 5371 | void RSA_free( | ||
| 5372 | RSA *rsa); | ||
| 5373 | This function 'frees' an RSA structure. This routine should always | ||
| 5374 | be used to free the RSA structure since it will also 'free' any | ||
| 5375 | sub-fields of the RSA type that need freeing. | ||
| 5376 | |||
| 5377 | int RSA_size( | ||
| 5378 | RSA *rsa); | ||
| 5379 | This function returns the size of the RSA modulus in bytes. Why do | ||
| 5380 | I need this you may ask, well the reason is that when you encrypt | ||
| 5381 | with RSA, the output string will be the size of the RSA modulus. | ||
| 5382 | So the output for the RSA_encrypt and the input for the RSA_decrypt | ||
| 5383 | routines need to be RSA_size() bytes long, because this is how many | ||
| 5384 | bytes are expected. | ||
| 5385 | |||
| 5386 | For the following 4 RSA encryption routines, it should be noted that | ||
| 5387 | RSA_private_decrypt() should be used on the output from | ||
| 5388 | RSA_public_encrypt() and RSA_public_decrypt() should be used on | ||
| 5389 | the output from RSA_private_encrypt(). | ||
| 5390 | |||
| 5391 | int RSA_public_encrypt( | ||
| 5392 | int from_len; | ||
| 5393 | unsigned char *from | ||
| 5394 | unsigned char *to | ||
| 5395 | RSA *rsa); | ||
| 5396 | This function implements RSA public encryption, the rsa variable | ||
| 5397 | should be a public key (but can be a private key). 'from_len' | ||
| 5398 | bytes taken from 'from' and encrypted and put into 'to'. 'to' needs | ||
| 5399 | to be at least RSA_size(rsa) bytes long. The number of bytes | ||
| 5400 | written into 'to' is returned. -1 is returned on an error. The | ||
| 5401 | operation performed is | ||
| 5402 | to = from^rsa->e mod rsa->n. | ||
| 5403 | |||
| 5404 | int RSA_private_encrypt( | ||
| 5405 | int from_len; | ||
| 5406 | unsigned char *from | ||
| 5407 | unsigned char *to | ||
| 5408 | RSA *rsa); | ||
| 5409 | This function implements RSA private encryption, the rsa variable | ||
| 5410 | should be a private key. 'from_len' bytes taken from | ||
| 5411 | 'from' and encrypted and put into 'to'. 'to' needs | ||
| 5412 | to be at least RSA_size(rsa) bytes long. The number of bytes | ||
| 5413 | written into 'to' is returned. -1 is returned on an error. The | ||
| 5414 | operation performed is | ||
| 5415 | to = from^rsa->d mod rsa->n. | ||
| 5416 | |||
| 5417 | int RSA_public_decrypt( | ||
| 5418 | int from_len; | ||
| 5419 | unsigned char *from | ||
| 5420 | unsigned char *to | ||
| 5421 | RSA *rsa); | ||
| 5422 | This function implements RSA public decryption, the rsa variable | ||
| 5423 | should be a public key (but can be a private key). 'from_len' | ||
| 5424 | bytes are taken from 'from' and decrypted. The decrypted data is | ||
| 5425 | put into 'to'. The number of bytes encrypted is returned. -1 is | ||
| 5426 | returned to indicate an error. The operation performed is | ||
| 5427 | to = from^rsa->e mod rsa->n. | ||
| 5428 | |||
| 5429 | int RSA_private_decrypt( | ||
| 5430 | int from_len; | ||
| 5431 | unsigned char *from | ||
| 5432 | unsigned char *to | ||
| 5433 | RSA *rsa); | ||
| 5434 | This function implements RSA private decryption, the rsa variable | ||
| 5435 | should be a private key. 'from_len' bytes are taken | ||
| 5436 | from 'from' and decrypted. The decrypted data is | ||
| 5437 | put into 'to'. The number of bytes encrypted is returned. -1 is | ||
| 5438 | returned to indicate an error. The operation performed is | ||
| 5439 | to = from^rsa->d mod rsa->n. | ||
| 5440 | |||
| 5441 | int RSA_mod_exp( | ||
| 5442 | BIGNUM *n; | ||
| 5443 | BIGNUM *p; | ||
| 5444 | RSA *rsa); | ||
| 5445 | Normally you will never use this routine. | ||
| 5446 | This is really an internal function which is called by | ||
| 5447 | RSA_private_encrypt() and RSA_private_decrypt(). It performs | ||
| 5448 | n=n^p mod rsa->n except that it uses the 5 extra variables in the | ||
| 5449 | RSA structure to make this more efficient. | ||
| 5450 | |||
| 5451 | RSA *RSA_generate_key( | ||
| 5452 | int bits; | ||
| 5453 | unsigned long e; | ||
| 5454 | void (*callback)(); | ||
| 5455 | char *cb_arg; | ||
| 5456 | This routine is used to generate RSA private keys. It takes | ||
| 5457 | quite a period of time to run and should only be used to | ||
| 5458 | generate initial private keys that should then be stored | ||
| 5459 | for later use. The passed callback function | ||
| 5460 | will be called periodically so that feedback can be given | ||
| 5461 | as to how this function is progressing. | ||
| 5462 | 'bits' is the length desired for the modulus, so it would be 1024 | ||
| 5463 | to generate a 1024 bit private key. | ||
| 5464 | 'e' is the value to use for the public exponent 'e'. Traditionally | ||
| 5465 | it is set to either 3 or 0x10001. | ||
| 5466 | The callback function (if not NULL) is called in the following | ||
| 5467 | situations. | ||
| 5468 | when we have generated a suspected prime number to test, | ||
| 5469 | callback(0,num1++,cb_arg). When it passes a prime number test, | ||
| 5470 | callback(1,num2++,cb_arg). When it is rejected as one of | ||
| 5471 | the 2 primes required due to gcd(prime,e value) != 0, | ||
| 5472 | callback(2,num3++,cb_arg). When finally accepted as one | ||
| 5473 | of the 2 primes, callback(3,num4++,cb_arg). | ||
| 5474 | |||
| 5475 | |||
| 5476 | ==== rsaref.doc ======================================================== | ||
| 5477 | |||
| 5478 | This package can be compiled to use the RSAref library. | ||
| 5479 | This library is not allowed outside of the USA but inside the USA it is | ||
| 5480 | claimed by RSA to be the only RSA public key library that can be used | ||
| 5481 | besides BSAFE.. | ||
| 5482 | |||
| 5483 | There are 2 files, rsaref/rsaref.c and rsaref/rsaref.h that contain the glue | ||
| 5484 | code to use RSAref. These files were written by looking at the PGP | ||
| 5485 | source code and seeing which routines it used to access RSAref. | ||
| 5486 | I have also been sent by some-one a copy of the RSAref header file that | ||
| 5487 | contains the library error codes. | ||
| 5488 | |||
| 5489 | [ Jun 1996 update - I have recently gotten hold of RSAref 2.0 from | ||
| 5490 | South Africa and have been doing some performace tests. ] | ||
| 5491 | |||
| 5492 | They have now been tested against the recently announced RSAEURO | ||
| 5493 | library. | ||
| 5494 | |||
| 5495 | There are 2 ways to use SSLeay and RSAref. First, to build so that | ||
| 5496 | the programs must be linked with RSAref, add '-DRSAref' to CFLAG in the top | ||
| 5497 | level makefile and -lrsaref (or where ever you are keeping RSAref) to | ||
| 5498 | EX_LIBS. | ||
| 5499 | |||
| 5500 | To build a makefile via util/mk1mf.pl to do this, use the 'rsaref' option. | ||
| 5501 | |||
| 5502 | The second method is to build as per normal and link applications with | ||
| 5503 | the RSAglue library. The correct library order would be | ||
| 5504 | cc -o cmd cmd.o -lssl -lRSAglue -lcrypto -lrsaref -ldes | ||
| 5505 | The RSAglue library is built in the rsa directory and is NOT | ||
| 5506 | automatically installed. | ||
| 5507 | |||
| 5508 | Be warned that the RSAEURO library, that is claimed to be compatible | ||
| 5509 | with RSAref contains a different value for the maximum number of bits | ||
| 5510 | supported. This changes structure sizes and so if you are using | ||
| 5511 | RSAEURO, change the value of RSAref_MAX_BITS in rsa/rsaref.h | ||
| 5512 | |||
| 5513 | |||
| 5514 | ==== s_mult.doc ======================================================== | ||
| 5515 | |||
| 5516 | s_mult is a test program I hacked up on a Sunday for testing non-blocking | ||
| 5517 | IO. It has a select loop at it's centre that handles multiple readers | ||
| 5518 | and writers. | ||
| 5519 | |||
| 5520 | Try the following command | ||
| 5521 | ssleay s_mult -echo -nbio -ssl -v | ||
| 5522 | echo - sends any sent text back to the sender | ||
| 5523 | nbio - turns on non-blocking IO | ||
| 5524 | ssl - accept SSL connections, default is normal text | ||
| 5525 | v - print lots | ||
| 5526 | type Q<cr> to quit | ||
| 5527 | |||
| 5528 | In another window, run the following | ||
| 5529 | ssleay s_client -pause </etc/termcap | ||
| 5530 | |||
| 5531 | The pause option puts in a 1 second pause in each read(2)/write(2) call | ||
| 5532 | so the other end will have read()s fail. | ||
| 5533 | |||
| 5534 | ==== session.doc ======================================================== | ||
| 5535 | |||
| 5536 | I have just checked over and re-worked the session stuff. | ||
| 5537 | The following brief example will ignore all setup information to do with | ||
| 5538 | authentication. | ||
| 5539 | |||
| 5540 | Things operate as follows. | ||
| 5541 | |||
| 5542 | The SSL environment has a 'context', a SSL_CTX structure. This holds the | ||
| 5543 | cached SSL_SESSIONS (which can be reused) and the certificate lookup | ||
| 5544 | information. Each SSL structure needs to be associated with a SSL_CTX. | ||
| 5545 | Normally only one SSL_CTX structure is needed per program. | ||
| 5546 | |||
| 5547 | SSL_CTX *SSL_CTX_new(void ); | ||
| 5548 | void SSL_CTX_free(SSL_CTX *); | ||
| 5549 | These 2 functions create and destroy SSL_CTX structures | ||
| 5550 | |||
| 5551 | The SSL_CTX has a session_cache_mode which is by default, | ||
| 5552 | in SSL_SESS_CACHE_SERVER mode. What this means is that the library | ||
| 5553 | will automatically add new session-id's to the cache apon sucsessful | ||
| 5554 | SSL_accept() calls. | ||
| 5555 | If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added | ||
| 5556 | to the cache. | ||
| 5557 | SSL_set_session_cache_mode(ctx,mode) will set the 'mode' and | ||
| 5558 | SSL_get_session_cache_mode(ctx) will get the cache 'mode'. | ||
| 5559 | The modes can be | ||
| 5560 | SSL_SESS_CACHE_OFF - no caching | ||
| 5561 | SSL_SESS_CACHE_CLIENT - only SSL_connect() | ||
| 5562 | SSL_SESS_CACHE_SERVER - only SSL_accept() | ||
| 5563 | SSL_SESS_NO_CACHE_BOTH - Either SSL_accept() or SSL_connect(). | ||
| 5564 | If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are | ||
| 5565 | not automatically removed each 255, SSL_connect()s or SSL_accept()s. | ||
| 5566 | |||
| 5567 | By default, apon every 255 successful SSL_connect() or SSL_accept()s, | ||
| 5568 | the cache is flush. Please note that this could be expensive on | ||
| 5569 | a heavily loaded SSL server, in which case, turn this off and | ||
| 5570 | clear the cache of old entries 'manually' (with one of the functions | ||
| 5571 | listed below) every few hours. Perhaps I should up this number, it is hard | ||
| 5572 | to say. Remember, the '255' new calls is just a mechanims to get called | ||
| 5573 | every now and then, in theory at most 255 new session-id's will have been | ||
| 5574 | added but if 100 are added every minute, you would still have | ||
| 5575 | 500 in the cache before any would start being flushed (assuming a 3 minute | ||
| 5576 | timeout).. | ||
| 5577 | |||
| 5578 | int SSL_CTX_sess_hits(SSL_CTX *ctx); | ||
| 5579 | int SSL_CTX_sess_misses(SSL_CTX *ctx); | ||
| 5580 | int SSL_CTX_sess_timeouts(SSL_CTX *ctx); | ||
| 5581 | These 3 functions return statistics about the SSL_CTX. These 3 are the | ||
| 5582 | number of session id reuses. hits is the number of reuses, misses are the | ||
| 5583 | number of lookups that failed, and timeouts is the number of cached | ||
| 5584 | entries ignored because they had timeouted. | ||
| 5585 | |||
| 5586 | ctx->new_session_cb is a function pointer to a function of type | ||
| 5587 | int new_session_callback(SSL *ssl,SSL_SESSION *new); | ||
| 5588 | This function, if set in the SSL_CTX structure is called whenever a new | ||
| 5589 | SSL_SESSION is added to the cache. If the callback returns non-zero, it | ||
| 5590 | means that the application will have to do a SSL_SESSION_free() | ||
| 5591 | on the structure (this is | ||
| 5592 | to do with the cache keeping the reference counts correct, without the | ||
| 5593 | application needing to know about it. | ||
| 5594 | The 'active' parameter is the current SSL session for which this connection | ||
| 5595 | was created. | ||
| 5596 | |||
| 5597 | void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,int (*cb)()); | ||
| 5598 | to set the callback, | ||
| 5599 | int (*cb)() SSL_CTX_sess_get_new_cb(SSL_CTX *ctx) | ||
| 5600 | to get the callback. | ||
| 5601 | |||
| 5602 | If the 'get session' callback is set, when a session id is looked up and | ||
| 5603 | it is not in the session-id cache, this callback is called. The callback is | ||
| 5604 | of the form | ||
| 5605 | SSL_SESSION *get_session_callback(unsigned char *sess_id,int sess_id_len, | ||
| 5606 | int *copy); | ||
| 5607 | |||
| 5608 | The get_session_callback is intended to return null if no session id is found. | ||
| 5609 | The reference count on the SSL_SESSION in incremented by the SSL library, | ||
| 5610 | if copy is 1. Otherwise, the reference count is not modified. | ||
| 5611 | |||
| 5612 | void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and | ||
| 5613 | int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback. | ||
| 5614 | |||
| 5615 | These callbacks are basically indended to be used by processes to | ||
| 5616 | send their session-id's to other processes. I currently have not implemented | ||
| 5617 | non-blocking semantics for these callbacks, it is upto the appication | ||
| 5618 | to make the callbacks effiecent if they require blocking (perhaps | ||
| 5619 | by 'saving' them and then 'posting them' when control returns from | ||
| 5620 | the SSL_accept(). | ||
| 5621 | |||
| 5622 | LHASH *SSL_CTX_sessions(SSL_CTX *ctx) | ||
| 5623 | This returns the session cache. The lhash strucutre can be accessed for | ||
| 5624 | statistics about the cache. | ||
| 5625 | |||
| 5626 | void lh_stats(LHASH *lh, FILE *out); | ||
| 5627 | void lh_node_stats(LHASH *lh, FILE *out); | ||
| 5628 | void lh_node_usage_stats(LHASH *lh, FILE *out); | ||
| 5629 | |||
| 5630 | can be used to print details about it's activity and current state. | ||
| 5631 | You can also delve directly into the lhash structure for 14 different | ||
| 5632 | counters that are kept against the structure. When I wrote the lhash library, | ||
| 5633 | I was interested in gathering statistics :-). | ||
| 5634 | Have a read of doc/lhash.doc in the SSLeay distribution area for more details | ||
| 5635 | on the lhash library. | ||
| 5636 | |||
| 5637 | Now as mentioned ealier, when a SSL is created, it needs a SSL_CTX. | ||
| 5638 | SSL * SSL_new(SSL_CTX *); | ||
| 5639 | |||
| 5640 | This stores a session. A session is secret information shared between 2 | ||
| 5641 | SSL contexts. It will only be created if both ends of the connection have | ||
| 5642 | authenticated their peer to their satisfaction. It basically contains | ||
| 5643 | the information required to use a particular secret key cipher. | ||
| 5644 | |||
| 5645 | To retrieve the SSL_CTX being used by a SSL, | ||
| 5646 | SSL_CTX *SSL_get_SSL_CTX(SSL *s); | ||
| 5647 | |||
| 5648 | Now when a SSL session is established between to programs, the 'session' | ||
| 5649 | information that is cached in the SSL_CTX can me manipulated by the | ||
| 5650 | following functions. | ||
| 5651 | int SSL_set_session(SSL *s, SSL_SESSION *session); | ||
| 5652 | This will set the SSL_SESSION to use for the next SSL_connect(). If you use | ||
| 5653 | this function on an already 'open' established SSL connection, 'bad things | ||
| 5654 | will happen'. This function is meaning-less when used on a ssl strucutre | ||
| 5655 | that is just about to be used in a SSL_accept() call since the | ||
| 5656 | SSL_accept() will either create a new session or retrieve one from the | ||
| 5657 | cache. | ||
| 5658 | |||
| 5659 | SSL_SESSION *SSL_get_session(SSL *s); | ||
| 5660 | This will return the SSL_SESSION for the current SSL, NULL if there is | ||
| 5661 | no session associated with the SSL structure. | ||
| 5662 | |||
| 5663 | The SSL sessions are kept in the SSL_CTX in a hash table, to remove a | ||
| 5664 | session | ||
| 5665 | void SSL_CTX_remove_session(SSL_CTX *,SSL_SESSION *c); | ||
| 5666 | and to add one | ||
| 5667 | int SSL_CTX_add_session(SSL_CTX *s, SSL_SESSION *c); | ||
| 5668 | SSL_CTX_add_session() returns 1 if the session was already in the cache (so it | ||
| 5669 | was not added). | ||
| 5670 | Whenever a new session is created via SSL_connect()/SSL_accept(), | ||
| 5671 | they are automatically added to the cache, depending on the session_cache_mode | ||
| 5672 | settings. SSL_set_session() | ||
| 5673 | does not add it to the cache. Just call SSL_CTX_add_session() if you do want the | ||
| 5674 | session added. For a 'client' this would not normally be the case. | ||
| 5675 | SSL_CTX_add_session() is not normally ever used, except for doing 'evil' things | ||
| 5676 | which the next 2 funtions help you do. | ||
| 5677 | |||
| 5678 | int i2d_SSL_SESSION(SSL_SESSION *in,unsigned char **pp); | ||
| 5679 | SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a,unsigned char **pp,long length); | ||
| 5680 | These 2 functions are in the standard ASN1 library form and can be used to | ||
| 5681 | load and save to a byte format, the SSL_SESSION structure. | ||
| 5682 | With these functions, you can save and read these structures to a files or | ||
| 5683 | arbitary byte string. | ||
| 5684 | The PEM_write_SSL_SESSION(fp,x) and PEM_read_SSL_SESSION(fp,x,cb) will | ||
| 5685 | write to a file pointer in base64 encoding. | ||
| 5686 | |||
| 5687 | What you can do with this, is pass session information between separate | ||
| 5688 | processes. Please note, that you will probably also need to modify the | ||
| 5689 | timeout information on the SSL_SESSIONs. | ||
| 5690 | |||
| 5691 | long SSL_get_time(SSL_SESSION *s) | ||
| 5692 | will return the 'time' that the session | ||
| 5693 | was loaded. The timeout is relative to this time. This information is | ||
| 5694 | saved when the SSL_SESSION is converted to binarary but it is stored | ||
| 5695 | in as a unix long, which is rather OS dependant, but easy to convert back. | ||
| 5696 | |||
| 5697 | long SSL_set_time(SSL_SESSION *s,long t) will set the above mentioned time. | ||
| 5698 | The time value is just the value returned from time(3), and should really | ||
| 5699 | be defined by be to be time_t. | ||
| 5700 | |||
| 5701 | long SSL_get_timeout(SSL_SESSION *s); | ||
| 5702 | long SSL_set_timeout(SSL_SESSION *s,long t); | ||
| 5703 | These 2 retrieve and set the timeout which is just a number of secconds | ||
| 5704 | from the 'SSL_get_time()' value. When this time period has elapesed, | ||
| 5705 | the session will no longer be in the cache (well it will actually be removed | ||
| 5706 | the next time it is attempted to be retrieved, so you could 'bump' | ||
| 5707 | the timeout so it remains valid). | ||
| 5708 | The 'time' and 'timeout' are set on a session when it is created, not reset | ||
| 5709 | each time it is reused. If you did wish to 'bump it', just after establishing | ||
| 5710 | a connection, do a | ||
| 5711 | SSL_set_time(ssl,time(NULL)); | ||
| 5712 | |||
| 5713 | You can also use | ||
| 5714 | SSL_CTX_set_timeout(SSL_CTX *ctx,unsigned long t) and | ||
| 5715 | SSL_CTX_get_timeout(SSL_CTX *ctx) to manipulate the default timeouts for | ||
| 5716 | all SSL connections created against a SSL_CTX. If you set a timeout in | ||
| 5717 | an SSL_CTX, all new SSL's created will inherit the timeout. It can be over | ||
| 5718 | written by the SSL_set_timeout(SSL *s,unsigned long t) function call. | ||
| 5719 | If you 'set' the timeout back to 0, the system default will be used. | ||
| 5720 | |||
| 5721 | SSL_SESSION *SSL_SESSION_new(); | ||
| 5722 | void SSL_SESSION_free(SSL_SESSION *ses); | ||
| 5723 | These 2 functions are used to create and dispose of SSL_SESSION functions. | ||
| 5724 | You should not ever normally need to use them unless you are using | ||
| 5725 | i2d_SSL_SESSION() and/or d2i_SSL_SESSION(). If you 'load' a SSL_SESSION | ||
| 5726 | via d2i_SSL_SESSION(), you will need to SSL_SESSION_free() it. | ||
| 5727 | Both SSL_set_session() and SSL_CTX_add_session() will 'take copies' of the | ||
| 5728 | structure (via reference counts) when it is passed to them. | ||
| 5729 | |||
| 5730 | SSL_CTX_flush_sessions(ctx,time); | ||
| 5731 | The first function will clear all sessions from the cache, which have expired | ||
| 5732 | relative to 'time' (which could just be time(NULL)). | ||
| 5733 | |||
| 5734 | SSL_CTX_flush_sessions(ctx,0); | ||
| 5735 | This is a special case that clears everything. | ||
| 5736 | |||
| 5737 | As a final comment, a 'session' is not enough to establish a new | ||
| 5738 | connection. If a session has timed out, a certificate and private key | ||
| 5739 | need to have been associated with the SSL structure. | ||
| 5740 | SSL_copy_session_id(SSL *to,SSL *from); will copy not only the session | ||
| 5741 | strucutre but also the private key and certificate associated with | ||
| 5742 | 'from'. | ||
| 5743 | |||
| 5744 | EXAMPLES. | ||
| 5745 | |||
| 5746 | So lets play at being a wierd SSL server. | ||
| 5747 | |||
| 5748 | /* setup a context */ | ||
| 5749 | ctx=SSL_CTX_new(); | ||
| 5750 | |||
| 5751 | /* Lets load some session from binary into the cache, why one would do | ||
| 5752 | * this is not toally clear, but passing between programs does make sense | ||
| 5753 | * Perhaps you are using 4096 bit keys and are happy to keep them | ||
| 5754 | * valid for a week, to avoid the RSA overhead of 15 seconds, I'm not toally | ||
| 5755 | * sure, perhaps this is a process called from an SSL inetd and this is being | ||
| 5756 | * passed to the application. */ | ||
| 5757 | session=d2i_SSL_SESSION(....) | ||
| 5758 | SSL_CTX_add_session(ctx,session); | ||
| 5759 | |||
| 5760 | /* Lets even add a session from a file */ | ||
| 5761 | session=PEM_read_SSL_SESSION(....) | ||
| 5762 | SSL_CTX_add_session(ctx,session); | ||
| 5763 | |||
| 5764 | /* create a new SSL structure */ | ||
| 5765 | ssl=SSL_new(ctx); | ||
| 5766 | |||
| 5767 | /* At this point we want to be able to 'create' new session if | ||
| 5768 | * required, so we need a certificate and RSAkey. */ | ||
| 5769 | SSL_use_RSAPrivateKey_file(ssl,...) | ||
| 5770 | SSL_use_certificate_file(ssl,...) | ||
| 5771 | |||
| 5772 | /* Now since we are a server, it make little sence to load a session against | ||
| 5773 | * the ssl strucutre since a SSL_accept() will either create a new session or | ||
| 5774 | * grab an existing one from the cache. */ | ||
| 5775 | |||
| 5776 | /* grab a socket descriptor */ | ||
| 5777 | fd=accept(...); | ||
| 5778 | |||
| 5779 | /* associated it with the ssl strucutre */ | ||
| 5780 | SSL_set_fd(ssl,fd); | ||
| 5781 | |||
| 5782 | SSL_accept(ssl); /* 'do' SSL using out cert and RSA key */ | ||
| 5783 | |||
| 5784 | /* Lets print out the session details or lets save it to a file, | ||
| 5785 | * perhaps with a secret key cipher, so that we can pass it to the FBI | ||
| 5786 | * when they want to decode the session :-). While we have RSA | ||
| 5787 | * this does not matter much but when I do SSLv3, this will allow a mechanism | ||
| 5788 | * for the server/client to record the information needed to decode | ||
| 5789 | * the traffic that went over the wire, even when using Diffie-Hellman */ | ||
| 5790 | PEM_write_SSL_SESSION(SSL_get_session(ssl),stdout,....) | ||
| 5791 | |||
| 5792 | Lets 'connect' back to the caller using the same session id. | ||
| 5793 | |||
| 5794 | ssl2=SSL_new(ctx); | ||
| 5795 | fd2=connect(them); | ||
| 5796 | SSL_set_fd(ssl2,fd2); | ||
| 5797 | SSL_set_session(ssl2,SSL_get_session(ssl)); | ||
| 5798 | SSL_connect(ssl2); | ||
| 5799 | |||
| 5800 | /* what the hell, lets accept no more connections using this session */ | ||
| 5801 | SSL_CTX_remove_session(SSL_get_SSL_CTX(ssl),SSL_get_session(ssl)); | ||
| 5802 | |||
| 5803 | /* we could have just as easily used ssl2 since they both are using the | ||
| 5804 | * same session. | ||
| 5805 | * You will note that both ssl and ssl2 are still using the session, and | ||
| 5806 | * the SSL_SESSION structure will be free()ed when both ssl and ssl2 | ||
| 5807 | * finish using the session. Also note that you could continue to initiate | ||
| 5808 | * connections using this session by doing SSL_get_session(ssl) to get the | ||
| 5809 | * existing session, but SSL_accept() will not be able to find it to | ||
| 5810 | * use for incoming connections. | ||
| 5811 | * Of corse, the session will timeout at the far end and it will no | ||
| 5812 | * longer be accepted after a while. The time and timeout are ignored except | ||
| 5813 | * by SSL_accept(). */ | ||
| 5814 | |||
| 5815 | /* Since we have had our server running for 10 weeks, and memory is getting | ||
| 5816 | * short, perhaps we should clear the session cache to remove those | ||
| 5817 | * 100000 session entries that have expired. Some may consider this | ||
| 5818 | * a memory leak :-) */ | ||
| 5819 | |||
| 5820 | SSL_CTX_flush_sessions(ctx,time(NULL)); | ||
| 5821 | |||
| 5822 | /* Ok, after a bit more time we wish to flush all sessions from the cache | ||
| 5823 | * so that all new connections will be authenticated and incure the | ||
| 5824 | * public key operation overhead */ | ||
| 5825 | |||
| 5826 | SSL_CTX_flush_sessions(ctx,0); | ||
| 5827 | |||
| 5828 | /* As a final note, to copy everything to do with a SSL, use */ | ||
| 5829 | SSL_copy_session_id(SSL *to,SSL *from); | ||
| 5830 | /* as this also copies the certificate and RSA key so new session can | ||
| 5831 | * be established using the same details */ | ||
| 5832 | |||
| 5833 | |||
| 5834 | ==== sha.doc ======================================================== | ||
| 5835 | |||
| 5836 | The SHA (Secure Hash Algorithm) library. | ||
| 5837 | SHA is a message digest algorithm that can be used to condense an arbitrary | ||
| 5838 | length message down to a 20 byte hash. The functions all need to be passed | ||
| 5839 | a SHA_CTX which is used to hold the SHA context during multiple SHA_Update() | ||
| 5840 | function calls. The normal method of use for this library is as follows | ||
| 5841 | This library contains both SHA and SHA-1 digest algorithms. SHA-1 is | ||
| 5842 | an update to SHA (which should really be called SHA-0 now) which | ||
| 5843 | tweaks the algorithm slightly. The SHA-1 algorithm is used by simply | ||
| 5844 | using SHA1_Init(), SHA1_Update(), SHA1_Final() and SHA1() instead of the | ||
| 5845 | SHA*() calls | ||
| 5846 | |||
| 5847 | SHA_Init(...); | ||
| 5848 | SHA_Update(...); | ||
| 5849 | ... | ||
| 5850 | SHA_Update(...); | ||
| 5851 | SHA_Final(...); | ||
| 5852 | |||
| 5853 | This library requires the inclusion of 'sha.h'. | ||
| 5854 | |||
| 5855 | The functions are as follows: | ||
| 5856 | |||
| 5857 | void SHA_Init( | ||
| 5858 | SHA_CTX *c); | ||
| 5859 | This function needs to be called to initiate a SHA_CTX structure for | ||
| 5860 | use. | ||
| 5861 | |||
| 5862 | void SHA_Update( | ||
| 5863 | SHA_CTX *c; | ||
| 5864 | unsigned char *data; | ||
| 5865 | unsigned long len); | ||
| 5866 | This updates the message digest context being generated with 'len' | ||
| 5867 | bytes from the 'data' pointer. The number of bytes can be any | ||
| 5868 | length. | ||
| 5869 | |||
| 5870 | void SHA_Final( | ||
| 5871 | unsigned char *md; | ||
| 5872 | SHA_CTX *c; | ||
| 5873 | This function is called when a message digest of the data digested | ||
| 5874 | with SHA_Update() is wanted. The message digest is put in the 'md' | ||
| 5875 | array and is SHA_DIGEST_LENGTH (20) bytes long. | ||
| 5876 | |||
| 5877 | unsigned char *SHA( | ||
| 5878 | unsigned char *d; | ||
| 5879 | unsigned long n; | ||
| 5880 | unsigned char *md; | ||
| 5881 | This function performs a SHA_Init(), followed by a SHA_Update() | ||
| 5882 | followed by a SHA_Final() (using a local SHA_CTX). | ||
| 5883 | The resulting digest is put into 'md' if it is not NULL. | ||
| 5884 | Regardless of the value of 'md', the message | ||
| 5885 | digest is returned from the function. If 'md' was NULL, the message | ||
| 5886 | digest returned is being stored in a static structure. | ||
| 5887 | |||
| 5888 | |||
| 5889 | ==== speed.doc ======================================================== | ||
| 5890 | |||
| 5891 | To get an idea of the performance of this library, use | ||
| 5892 | ssleay speed | ||
| 5893 | |||
| 5894 | perl util/sp-diff.pl file1 file2 | ||
| 5895 | |||
| 5896 | will print out the relative differences between the 2 files which are | ||
| 5897 | expected to be the output from the speed program. | ||
| 5898 | |||
| 5899 | The performace of the library is very dependant on the Compiler | ||
| 5900 | quality and various flags used to build. | ||
| 5901 | |||
| 5902 | --- | ||
| 5903 | |||
| 5904 | These are some numbers I did comparing RSAref and SSLeay on a Pentium 100. | ||
| 5905 | [ These numbers are all out of date, as of SSL - 0.6.1 the RSA | ||
| 5906 | operations are about 2 times faster, so check the version number ] | ||
| 5907 | |||
| 5908 | RSA performance. | ||
| 5909 | |||
| 5910 | SSLeay 0.6.0 | ||
| 5911 | Pentium 100, 32meg, Windows NT Workstation 3.51 | ||
| 5912 | linux - gcc v 2.7.0 -O3 -fomit-frame-pointer -m486 | ||
| 5913 | and | ||
| 5914 | Windows NT - Windows NT 3.51 - Visual C++ 4.1 - 586 code + 32bit assember | ||
| 5915 | Windows 3.1 - Windows NT 3.51 - Visual C++ 1.52c - 286 code + 32bit assember | ||
| 5916 | NT Dos Shell- Windows NT 3.51 - Visual C++ 1.52c - 286 code + 16bit assember | ||
| 5917 | |||
| 5918 | Times are how long it takes to do an RSA private key operation. | ||
| 5919 | |||
| 5920 | 512bits 1024bits | ||
| 5921 | ------------------------------- | ||
| 5922 | SSLeay NT dll 0.042s 0.202s see above | ||
| 5923 | SSLeay linux 0.046s 0.218s Assember inner loops (normal build) | ||
| 5924 | SSLeay linux 0.067s 0.380s Pure C code with BN_LLONG defined | ||
| 5925 | SSLeay W3.1 dll 0.108s 0.478s see above | ||
| 5926 | SSLeay linux 0.109s 0.713s C without BN_LLONG. | ||
| 5927 | RSAref2.0 linux 0.149s 0.936s | ||
| 5928 | SSLeay MS-DOS 0.197s 1.049s see above | ||
| 5929 | |||
| 5930 | 486DX66, 32meg, Windows NT Server 3.51 | ||
| 5931 | 512bits 1024bits | ||
| 5932 | ------------------------------- | ||
| 5933 | SSLeay NT dll 0.084s 0.495s <- SSLeay 0.6.3 | ||
| 5934 | SSLeay NT dll 0.154s 0.882s | ||
| 5935 | SSLeay W3.1 dll 0.335s 1.538s | ||
| 5936 | SSLeay MS-DOS 0.490s 2.790s | ||
| 5937 | |||
| 5938 | What I find cute is that I'm still faster than RSAref when using standard C, | ||
| 5939 | without using the 'long long' data type :-), %35 faster for 512bit and we | ||
| 5940 | scale up to 3.2 times faster for the 'default linux' build. I should mention | ||
| 5941 | that people should 'try' to use either x86-lnx.s (elf), x86-lnxa.s or | ||
| 5942 | x86-sol.s for any x86 based unix they are building on. The only problems | ||
| 5943 | with be with syntax but the performance gain is quite large, especially for | ||
| 5944 | servers. The code is very simple, you just need to modify the 'header'. | ||
| 5945 | |||
| 5946 | The message is, if you are stuck using RSAref, the RSA performance will be | ||
| 5947 | bad. Considering the code was compiled for a pentium, the 486DX66 number | ||
| 5948 | would indicate 'Use RSAref and turn you Pentium 100 into a 486DX66' :-). | ||
| 5949 | [ As of verson 0.6.1, it would be correct to say 'turn you pentium 100 | ||
| 5950 | into a 486DX33' :-) ] | ||
| 5951 | |||
| 5952 | I won't tell people if the DLL's are using RSAref or my stuff if no-one | ||
| 5953 | asks :-). | ||
| 5954 | |||
| 5955 | eric | ||
| 5956 | |||
| 5957 | PS while I know I could speed things up further, I will probably not do | ||
| 5958 | so due to the effort involved. I did do some timings on the | ||
| 5959 | SSLeay bignum format -> RSAref number format conversion that occurs | ||
| 5960 | each time RSAref is used by SSLeay, and the numbers are trivial. | ||
| 5961 | 0.00012s a call for 512bit vs 0.149s for the time spent in the function. | ||
| 5962 | 0.00018s for 1024bit vs 0.938s. Insignificant. | ||
| 5963 | So the 'way to go', to support faster RSA libraries, if people are keen, | ||
| 5964 | is to write 'glue' code in a similar way that I do for RSAref and send it | ||
| 5965 | to me :-). | ||
| 5966 | My base library still has the advantage of being able to operate on | ||
| 5967 | any size numbers, and is not that far from the performance from the | ||
| 5968 | leaders in the field. (-%30?) | ||
| 5969 | [ Well as of 0.6.1 I am now the leader in the filed on x86 (we at | ||
| 5970 | least very close :-) ] | ||
| 5971 | |||
| 5972 | I suppose I should also mention some other numbers RSAref numbers, again | ||
| 5973 | on my Pentium. | ||
| 5974 | DES CBC EDE-DES MD5 | ||
| 5975 | RSAref linux 830k/s 302k/s 4390k/s | ||
| 5976 | SSLeay linux 855k/s 319k/s 10025k/s | ||
| 5977 | SSLeay NT 1158k/s 410k/s 10470k/s | ||
| 5978 | SSLeay w31 378k/s 143k/s 2383k/s (fully 16bit) | ||
| 5979 | |||
| 5980 | Got to admit that Visual C++ 4.[01] is a damn fine compiler :-) | ||
| 5981 | -- | ||
| 5982 | Eric Young | BOOL is tri-state according to Bill Gates. | ||
| 5983 | AARNet: eay@cryptsoft.com | RTFM Win32 GetMessage(). | ||
| 5984 | |||
| 5985 | |||
| 5986 | |||
| 5987 | |||
| 5988 | ==== ssl-ciph.doc ======================================================== | ||
| 5989 | |||
| 5990 | This is a quick high level summery of how things work now. | ||
| 5991 | |||
| 5992 | Each SSLv2 and SSLv3 cipher is composed of 4 major attributes plus a few extra | ||
| 5993 | minor ones. | ||
| 5994 | |||
| 5995 | They are 'The key exchange algorithm', which is RSA for SSLv2 but can also | ||
| 5996 | be Diffle-Hellman for SSLv3. | ||
| 5997 | |||
| 5998 | An 'Authenticion algorithm', which can be RSA, Diffle-Helman, DSS or | ||
| 5999 | none. | ||
| 6000 | |||
| 6001 | The cipher | ||
| 6002 | |||
| 6003 | The MAC digest. | ||
| 6004 | |||
| 6005 | A cipher can also be an export cipher and is either an SSLv2 or a | ||
| 6006 | SSLv3 ciphers. | ||
| 6007 | |||
| 6008 | To specify which ciphers to use, one can either specify all the ciphers, | ||
| 6009 | one at a time, or use 'aliases' to specify the preference and order for | ||
| 6010 | the ciphers. | ||
| 6011 | |||
| 6012 | There are a large number of aliases, but the most importaint are | ||
| 6013 | kRSA, kDHr, kDHd and kEDH for key exchange types. | ||
| 6014 | |||
| 6015 | aRSA, aDSS, aNULL and aDH for authentication | ||
| 6016 | DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers | ||
| 6017 | MD5, SHA0 and SHA1 digests | ||
| 6018 | |||
| 6019 | Now where this becomes interesting is that these can be put together to | ||
| 6020 | specify the order and ciphers you wish to use. | ||
| 6021 | |||
| 6022 | To speed this up there are also aliases for certian groups of ciphers. | ||
| 6023 | The main ones are | ||
| 6024 | SSLv2 - all SSLv2 ciphers | ||
| 6025 | SSLv3 - all SSLv3 ciphers | ||
| 6026 | EXP - all export ciphers | ||
| 6027 | LOW - all low strngth ciphers (no export ciphers, normally single DES) | ||
| 6028 | MEDIUM - 128 bit encryption | ||
| 6029 | HIGH - Triple DES | ||
| 6030 | |||
| 6031 | These aliases can be joined in a : separated list which specifies to | ||
| 6032 | add ciphers, move them to the current location and delete them. | ||
| 6033 | |||
| 6034 | A simpler way to look at all of this is to use the 'ssleay ciphers -v' command. | ||
| 6035 | The default library cipher spec is | ||
| 6036 | !ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP | ||
| 6037 | which means, first, remove from consideration any ciphers that do not | ||
| 6038 | authenticate. Next up, use ciphers using RC4 and RSA. Next include the HIGH, | ||
| 6039 | MEDIUM and the LOW security ciphers. Finish up by adding all the export | ||
| 6040 | ciphers on the end, then 'pull' all the SSLv2 and export ciphers to | ||
| 6041 | the end of the list. | ||
| 6042 | |||
| 6043 | The results are | ||
| 6044 | $ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP' | ||
| 6045 | |||
| 6046 | RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1 | ||
| 6047 | RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 | ||
| 6048 | EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 | ||
| 6049 | EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 | ||
| 6050 | DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1 | ||
| 6051 | IDEA-CBC-MD5 SSLv3 Kx=RSA Au=RSA Enc=IDEA(128) Mac=SHA1 | ||
| 6052 | EDH-RSA-DES-CBC-SHA SSLv3 Kx=DH Au=RSA Enc=DES(56) Mac=SHA1 | ||
| 6053 | EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH Au=DSS Enc=DES(56) Mac=SHA1 | ||
| 6054 | DES-CBC-SHA SSLv3 Kx=RSA Au=RSA Enc=DES(56) Mac=SHA1 | ||
| 6055 | DES-CBC3-MD5 SSLv2 Kx=RSA Au=RSA Enc=3DES(168) Mac=MD5 | ||
| 6056 | DES-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=DES(56) Mac=MD5 | ||
| 6057 | IDEA-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=IDEA(128) Mac=MD5 | ||
| 6058 | RC2-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC2(128) Mac=MD5 | ||
| 6059 | RC4-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 | ||
| 6060 | EXP-EDH-RSA-DES-CBC SSLv3 Kx=DH(512) Au=RSA Enc=DES(40) Mac=SHA1 export | ||
| 6061 | EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512) Au=DSS Enc=DES(40) Mac=SHA1 export | ||
| 6062 | EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 export | ||
| 6063 | EXP-RC2-CBC-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export | ||
| 6064 | EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export | ||
| 6065 | EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export | ||
| 6066 | EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export | ||
| 6067 | |||
| 6068 | I would recoment people use the 'ssleay ciphers -v "text"' | ||
| 6069 | command to check what they are going to use. | ||
| 6070 | |||
| 6071 | Anyway, I'm falling asleep here so I'll do some more tomorrow. | ||
| 6072 | |||
| 6073 | eric | ||
| 6074 | |||
| 6075 | ==== ssl.doc ======================================================== | ||
| 6076 | |||
| 6077 | SSL_CTX_sessions(SSL_CTX *ctx) - the session-id hash table. | ||
| 6078 | |||
| 6079 | /* Session-id cache stats */ | ||
| 6080 | SSL_CTX_sess_number | ||
| 6081 | SSL_CTX_sess_connect | ||
| 6082 | SSL_CTX_sess_connect_good | ||
| 6083 | SSL_CTX_sess_accept | ||
| 6084 | SSL_CTX_sess_accept_good | ||
| 6085 | SSL_CTX_sess_hits | ||
| 6086 | SSL_CTX_sess_cb_hits | ||
| 6087 | SSL_CTX_sess_misses | ||
| 6088 | SSL_CTX_sess_timeouts | ||
| 6089 | |||
| 6090 | /* Session-id application notification callbacks */ | ||
| 6091 | SSL_CTX_sess_set_new_cb | ||
| 6092 | SSL_CTX_sess_get_new_cb | ||
| 6093 | SSL_CTX_sess_set_get_cb | ||
| 6094 | SSL_CTX_sess_get_get_cb | ||
| 6095 | |||
| 6096 | /* Session-id cache operation mode */ | ||
| 6097 | SSL_CTX_set_session_cache_mode | ||
| 6098 | SSL_CTX_get_session_cache_mode | ||
| 6099 | |||
| 6100 | /* Set default timeout values to use. */ | ||
| 6101 | SSL_CTX_set_timeout | ||
| 6102 | SSL_CTX_get_timeout | ||
| 6103 | |||
| 6104 | /* Global SSL initalisation informational callback */ | ||
| 6105 | SSL_CTX_set_info_callback | ||
| 6106 | SSL_CTX_get_info_callback | ||
| 6107 | SSL_set_info_callback | ||
| 6108 | SSL_get_info_callback | ||
| 6109 | |||
| 6110 | /* If the SSL_accept/SSL_connect returned with -1, these indicate when | ||
| 6111 | * we should re-call *. | ||
| 6112 | SSL_want | ||
| 6113 | SSL_want_nothing | ||
| 6114 | SSL_want_read | ||
| 6115 | SSL_want_write | ||
| 6116 | SSL_want_x509_lookup | ||
| 6117 | |||
| 6118 | /* Where we are in SSL initalisation, used in non-blocking, perhaps | ||
| 6119 | * have a look at ssl/bio_ssl.c */ | ||
| 6120 | SSL_state | ||
| 6121 | SSL_is_init_finished | ||
| 6122 | SSL_in_init | ||
| 6123 | SSL_in_connect_init | ||
| 6124 | SSL_in_accept_init | ||
| 6125 | |||
| 6126 | /* Used to set the 'inital' state so SSL_in_connect_init and SSL_in_accept_init | ||
| 6127 | * can be used to work out which function to call. */ | ||
| 6128 | SSL_set_connect_state | ||
| 6129 | SSL_set_accept_state | ||
| 6130 | |||
| 6131 | /* Where to look for certificates for authentication */ | ||
| 6132 | SSL_set_default_verify_paths /* calles SSL_load_verify_locations */ | ||
| 6133 | SSL_load_verify_locations | ||
| 6134 | |||
| 6135 | /* get info from an established connection */ | ||
| 6136 | SSL_get_session | ||
| 6137 | SSL_get_certificate | ||
| 6138 | SSL_get_SSL_CTX | ||
| 6139 | |||
| 6140 | SSL_CTX_new | ||
| 6141 | SSL_CTX_free | ||
| 6142 | SSL_new | ||
| 6143 | SSL_clear | ||
| 6144 | SSL_free | ||
| 6145 | |||
| 6146 | SSL_CTX_set_cipher_list | ||
| 6147 | SSL_get_cipher | ||
| 6148 | SSL_set_cipher_list | ||
| 6149 | SSL_get_cipher_list | ||
| 6150 | SSL_get_shared_ciphers | ||
| 6151 | |||
| 6152 | SSL_accept | ||
| 6153 | SSL_connect | ||
| 6154 | SSL_read | ||
| 6155 | SSL_write | ||
| 6156 | |||
| 6157 | SSL_debug | ||
| 6158 | |||
| 6159 | SSL_get_read_ahead | ||
| 6160 | SSL_set_read_ahead | ||
| 6161 | SSL_set_verify | ||
| 6162 | |||
| 6163 | SSL_pending | ||
| 6164 | |||
| 6165 | SSL_set_fd | ||
| 6166 | SSL_set_rfd | ||
| 6167 | SSL_set_wfd | ||
| 6168 | SSL_set_bio | ||
| 6169 | SSL_get_fd | ||
| 6170 | SSL_get_rbio | ||
| 6171 | SSL_get_wbio | ||
| 6172 | |||
| 6173 | SSL_use_RSAPrivateKey | ||
| 6174 | SSL_use_RSAPrivateKey_ASN1 | ||
| 6175 | SSL_use_RSAPrivateKey_file | ||
| 6176 | SSL_use_PrivateKey | ||
| 6177 | SSL_use_PrivateKey_ASN1 | ||
| 6178 | SSL_use_PrivateKey_file | ||
| 6179 | SSL_use_certificate | ||
| 6180 | SSL_use_certificate_ASN1 | ||
| 6181 | SSL_use_certificate_file | ||
| 6182 | |||
| 6183 | ERR_load_SSL_strings | ||
| 6184 | SSL_load_error_strings | ||
| 6185 | |||
| 6186 | /* human readable version of the 'state' of the SSL connection. */ | ||
| 6187 | SSL_state_string | ||
| 6188 | SSL_state_string_long | ||
| 6189 | /* These 2 report what kind of IO operation the library was trying to | ||
| 6190 | * perform last. Probably not very usefull. */ | ||
| 6191 | SSL_rstate_string | ||
| 6192 | SSL_rstate_string_long | ||
| 6193 | |||
| 6194 | SSL_get_peer_certificate | ||
| 6195 | |||
| 6196 | SSL_SESSION_new | ||
| 6197 | SSL_SESSION_print_fp | ||
| 6198 | SSL_SESSION_print | ||
| 6199 | SSL_SESSION_free | ||
| 6200 | i2d_SSL_SESSION | ||
| 6201 | d2i_SSL_SESSION | ||
| 6202 | |||
| 6203 | SSL_get_time | ||
| 6204 | SSL_set_time | ||
| 6205 | SSL_get_timeout | ||
| 6206 | SSL_set_timeout | ||
| 6207 | SSL_copy_session_id | ||
| 6208 | SSL_set_session | ||
| 6209 | SSL_CTX_add_session | ||
| 6210 | SSL_CTX_remove_session | ||
| 6211 | SSL_CTX_flush_sessions | ||
| 6212 | |||
| 6213 | BIO_f_ssl | ||
| 6214 | |||
| 6215 | /* used to hold information as to why a certificate verification failed */ | ||
| 6216 | SSL_set_verify_result | ||
| 6217 | SSL_get_verify_result | ||
| 6218 | |||
| 6219 | /* can be used by the application to associate data with an SSL structure. | ||
| 6220 | * It needs to be 'free()ed' by the application */ | ||
| 6221 | SSL_set_app_data | ||
| 6222 | SSL_get_app_data | ||
| 6223 | |||
| 6224 | /* The following all set values that are kept in the SSL_CTX but | ||
| 6225 | * are used as the default values when an SSL session is created. | ||
| 6226 | * They are over writen by the relevent SSL_xxxx functions */ | ||
| 6227 | |||
| 6228 | /* SSL_set_verify */ | ||
| 6229 | void SSL_CTX_set_default_verify | ||
| 6230 | |||
| 6231 | /* This callback, if set, totaly overrides the normal SSLeay verification | ||
| 6232 | * functions and should return 1 on sucesss and 0 on failure */ | ||
| 6233 | void SSL_CTX_set_cert_verify_callback | ||
| 6234 | |||
| 6235 | /* The following are the same as the equivilent SSL_xxx functions. | ||
| 6236 | * Only one copy of this information is kept and if a particular | ||
| 6237 | * SSL structure has a local override, it is totally separate structure. | ||
| 6238 | */ | ||
| 6239 | int SSL_CTX_use_RSAPrivateKey | ||
| 6240 | int SSL_CTX_use_RSAPrivateKey_ASN1 | ||
| 6241 | int SSL_CTX_use_RSAPrivateKey_file | ||
| 6242 | int SSL_CTX_use_PrivateKey | ||
| 6243 | int SSL_CTX_use_PrivateKey_ASN1 | ||
| 6244 | int SSL_CTX_use_PrivateKey_file | ||
| 6245 | int SSL_CTX_use_certificate | ||
| 6246 | int SSL_CTX_use_certificate_ASN1 | ||
| 6247 | int SSL_CTX_use_certificate_file | ||
| 6248 | |||
| 6249 | |||
| 6250 | ==== ssl_ctx.doc ======================================================== | ||
| 6251 | |||
| 6252 | This is now a bit dated, quite a few of the SSL_ functions could be | ||
| 6253 | SSL_CTX_ functions. I will update this in the future. 30 Aug 1996 | ||
| 6254 | |||
| 6255 | From eay@orb.mincom.oz.au Mon Dec 11 21:37:08 1995 | ||
| 6256 | Received: by orb.mincom.oz.au id AA00696 | ||
| 6257 | (5.65c/IDA-1.4.4 for eay); Mon, 11 Dec 1995 11:37:08 +1000 | ||
| 6258 | Date: Mon, 11 Dec 1995 11:37:08 +1000 (EST) | ||
| 6259 | From: Eric Young <eay@mincom.oz.au> | ||
| 6260 | X-Sender: eay@orb | ||
| 6261 | To: sameer <sameer@c2.org> | ||
| 6262 | Cc: Eric Young <eay@mincom.oz.au> | ||
| 6263 | Subject: Re: PEM_readX509 oesn't seem to be working | ||
| 6264 | In-Reply-To: <199512110102.RAA12521@infinity.c2.org> | ||
| 6265 | Message-Id: <Pine.SOL.3.91.951211112115.28608D-100000@orb> | ||
| 6266 | Mime-Version: 1.0 | ||
| 6267 | Content-Type: TEXT/PLAIN; charset=US-ASCII | ||
| 6268 | Status: RO | ||
| 6269 | X-Status: | ||
| 6270 | |||
| 6271 | On Sun, 10 Dec 1995, sameer wrote: | ||
| 6272 | > OK, that's solved. I've found out that it is saying "no | ||
| 6273 | > certificate set" in SSL_accept because s->conn == NULL | ||
| 6274 | > so there is some place I need to initialize s->conn that I am | ||
| 6275 | > not initializing it. | ||
| 6276 | |||
| 6277 | The full order of things for a server should be. | ||
| 6278 | |||
| 6279 | ctx=SSL_CTX_new(); | ||
| 6280 | |||
| 6281 | /* The next line should not really be using ctx->cert but I'll leave it | ||
| 6282 | * this way right now... I don't want a X509_ routine to know about an SSL | ||
| 6283 | * structure, there should be an SSL_load_verify_locations... hmm, I may | ||
| 6284 | * add it tonight. | ||
| 6285 | */ | ||
| 6286 | X509_load_verify_locations(ctx->cert,CAfile,CApath); | ||
| 6287 | |||
| 6288 | /* Ok now for each new connection we do the following */ | ||
| 6289 | con=SSL_new(ctx); | ||
| 6290 | SSL_set_fd(con,s); | ||
| 6291 | SSL_set_verify(con,verify,verify_callback); | ||
| 6292 | |||
| 6293 | /* set the certificate and private key to use. */ | ||
| 6294 | SSL_use_certificate_ASN1(con,X509_certificate); | ||
| 6295 | SSL_use_RSAPrivateKey_ASN1(con,RSA_private_key); | ||
| 6296 | |||
| 6297 | SSL_accept(con); | ||
| 6298 | |||
| 6299 | SSL_read(con)/SSL_write(con); | ||
| 6300 | |||
| 6301 | There is a bit more than that but that is basically the structure. | ||
| 6302 | |||
| 6303 | Create a context and specify where to lookup certificates. | ||
| 6304 | |||
| 6305 | foreach connection | ||
| 6306 | { | ||
| 6307 | create a SSL structure | ||
| 6308 | set the certificate and private key | ||
| 6309 | do a SSL_accept | ||
| 6310 | |||
| 6311 | we should now be ok | ||
| 6312 | } | ||
| 6313 | |||
| 6314 | eric | ||
| 6315 | -- | ||
| 6316 | Eric Young | Signature removed since it was generating | ||
| 6317 | AARNet: eay@mincom.oz.au | more followups than the message contents :-) | ||
| 6318 | |||
| 6319 | |||
| 6320 | |||
| 6321 | ==== ssleay.doc ======================================================== | ||
| 6322 | |||
| 6323 | SSLeay: a cryptographic kitchen sink. | ||
| 6324 | |||
| 6325 | 1st December 1995 | ||
| 6326 | Way back at the start of April 1995, I was looking for a mindless | ||
| 6327 | programming project. A friend of mine (Tim Hudson) said "why don't you do SSL, | ||
| 6328 | it has DES encryption in it and I would not mind using it in a SSL telnet". | ||
| 6329 | While it was true I had written a DES library in previous years, litle | ||
| 6330 | did I know what an expansive task SSL would turn into. | ||
| 6331 | |||
| 6332 | First of all, the SSL protocol contains DES encryption. Well and good. My | ||
| 6333 | DES library was fast and portable. It also contained the RSA's RC4 stream | ||
| 6334 | cipher. Again, not a problem, some-one had just posted to sci.crypt | ||
| 6335 | something that was claimed to be RC4. It also contained IDEA, I had the | ||
| 6336 | specifications, not a problem to implement. MD5, an RFC, trivial, at most | ||
| 6337 | I could spend a week or so trying to see if I could speed up the | ||
| 6338 | implementation. All in all a nice set of ciphers. | ||
| 6339 | Then the first 'expantion of the scope', RSA public key | ||
| 6340 | encryption. Since I did not knowing a thing about public key encryption | ||
| 6341 | or number theory, this appeared quite a daunting task. Just writing a | ||
| 6342 | big number library would be problomatic in itself, let alone making it fast. | ||
| 6343 | At this point the scope of 'implementing SSL' expands eponentialy. | ||
| 6344 | First of all, the RSA private keys were being kept in ASN.1 format. | ||
| 6345 | Thankfully the RSA PKCS series of documents explains this format. So I now | ||
| 6346 | needed to be able to encode and decode arbitary ASN.1 objects. The Public | ||
| 6347 | keys were embeded in X509 certificates. Hmm... these are not only | ||
| 6348 | ASN.1 objects but they make up a heirachy of authentication. To | ||
| 6349 | authenticate a X509 certificate one needs to retrieve it's issuers | ||
| 6350 | certificate etc etc. Hmm..., so I also need to implement some kind | ||
| 6351 | of certificate management software. I would also have to implement | ||
| 6352 | software to authenticate certificates. At this point the support code made | ||
| 6353 | the SSL part of my library look quite small. | ||
| 6354 | Around this time, the first version of SSLeay was released. | ||
| 6355 | |||
| 6356 | Ah, but here was the problem, I was not happy with the code so far. As may | ||
| 6357 | have become obvious, I had been treating all of this as a learning | ||
| 6358 | exersize, so I have completely written the library myself. As such, due | ||
| 6359 | to the way it had grown like a fungus, much of the library was not | ||
| 6360 | 'elagent' or neat. There were global and static variables all over the | ||
| 6361 | place, the SSL part did not even handle non-blocking IO. | ||
| 6362 | The Great rewrite began. | ||
| 6363 | |||
| 6364 | As of this point in time, the 'Great rewrite' has almost finished. So what | ||
| 6365 | follows is an approximate list of what is actually SSLeay 0.5.0 | ||
| 6366 | |||
| 6367 | /********* This needs to be updated for 0.6.0+ *************/ | ||
| 6368 | |||
| 6369 | --- | ||
| 6370 | The library contains the following routines. Please note that most of these | ||
| 6371 | functions are not specfic for SSL or any other particular cipher | ||
| 6372 | implementation. I have tried to make all the routines as general purpose | ||
| 6373 | as possible. So you should not think of this library as an SSL | ||
| 6374 | implemtation, but rather as a library of cryptographic functions | ||
| 6375 | that also contains SSL. I refer to each of these function groupings as | ||
| 6376 | libraries since they are often capable of functioning as independant | ||
| 6377 | libraries | ||
| 6378 | |||
| 6379 | First up, the general ciphers and message digests supported by the library. | ||
| 6380 | |||
| 6381 | MD2 rfc???, a standard 'by parts' interface to this algorithm. | ||
| 6382 | MD5 rfc???, the same type of interface as for the MD2 library except a | ||
| 6383 | different algorithm. | ||
| 6384 | SHA THe Secure Hash Algorithm. Again the same type of interface as | ||
| 6385 | MD2/MD5 except the digest is 20 bytes. | ||
| 6386 | SHA1 The 'revised' version of SHA. Just about identical to SHA except | ||
| 6387 | for one tweak of an inner loop. | ||
| 6388 | DES This is my libdes library that has been floating around for the last | ||
| 6389 | few years. It has been enhanced for no other reason than completeness. | ||
| 6390 | It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and | ||
| 6391 | triple DES modes of ecb, cbc, cfb64 and ofb64. cfb64 and ofb64 are | ||
| 6392 | functional interfaces to the 64 bit modes of cfb and ofb used in | ||
| 6393 | such a way thay they function as single character interfaces. | ||
| 6394 | RC4 The RSA Inc. stream cipher. | ||
| 6395 | RC2 The RSA Inc. block cipher. | ||
| 6396 | IDEA An implmentation of the IDEA cipher, the library supports ecb, cbc, | ||
| 6397 | cfb64 and ofb64 modes of operation. | ||
| 6398 | |||
| 6399 | Now all the above mentioned ciphers and digests libraries support high | ||
| 6400 | speed, minimal 'crap in the way' type interfaces. For fastest and | ||
| 6401 | lowest level access, these routines should be used directly. | ||
| 6402 | |||
| 6403 | Now there was also the matter of public key crypto systems. These are | ||
| 6404 | based on large integer arithmatic. | ||
| 6405 | |||
| 6406 | BN This is my large integer library. It supports all the normal | ||
| 6407 | arithmentic operations. It uses malloc extensivly and as such has | ||
| 6408 | no limits of the size of the numbers being manipulated. If you | ||
| 6409 | wish to use 4000 bit RSA moduli, these routines will handle it. | ||
| 6410 | This library also contains routines to 'generate' prime numbers and | ||
| 6411 | to test for primality. The RSA and DH libraries sit on top of this | ||
| 6412 | library. As of this point in time, I don't support SHA, but | ||
| 6413 | when I do add it, it will just sit on top of the routines contained | ||
| 6414 | in this library. | ||
| 6415 | RSA This implements the RSA public key algorithm. It also contains | ||
| 6416 | routines that will generate a new private/public key pair. | ||
| 6417 | All the RSA functions conform to the PKCS#1 standard. | ||
| 6418 | DH This is an implementation of the | ||
| 6419 | Diffie-Hellman protocol. There are all the require routines for | ||
| 6420 | the protocol, plus extra routines that can be used to generate a | ||
| 6421 | strong prime for use with a specified generator. While this last | ||
| 6422 | routine is not generally required by applications implementing DH, | ||
| 6423 | It is present for completeness and because I thing it is much | ||
| 6424 | better to be able to 'generate' your own 'magic' numbers as oposed | ||
| 6425 | to using numbers suplied by others. I conform to the PKCS#3 | ||
| 6426 | standard where required. | ||
| 6427 | |||
| 6428 | You may have noticed the preceeding section mentions the 'generation' of | ||
| 6429 | prime numbers. Now this requries the use of 'random numbers'. | ||
| 6430 | |||
| 6431 | RAND This psuedo-random number library is based on MD5 at it's core | ||
| 6432 | and a large internal state (2k bytes). Once you have entered enough | ||
| 6433 | seed data into this random number algorithm I don't feel | ||
| 6434 | you will ever need to worry about it generating predictable output. | ||
| 6435 | Due to the way I am writing a portable library, I have left the | ||
| 6436 | issue of how to get good initial random seed data upto the | ||
| 6437 | application but I do have support routines for saving and loading a | ||
| 6438 | persistant random number state for use between program runs. | ||
| 6439 | |||
| 6440 | Now to make all these ciphers easier to use, a higher level | ||
| 6441 | interface was required. In this form, the same function would be used to | ||
| 6442 | encrypt 'by parts', via any one of the above mentioned ciphers. | ||
| 6443 | |||
| 6444 | EVP The Digital EnVeloPe library is quite large. At it's core are | ||
| 6445 | function to perform encryption and decryption by parts while using | ||
| 6446 | an initial parameter to specify which of the 17 different ciphers | ||
| 6447 | or 4 different message digests to use. On top of these are implmented | ||
| 6448 | the digital signature functions, sign, verify, seal and open. | ||
| 6449 | Base64 encoding of binary data is also done in this library. | ||
| 6450 | |||
| 6451 | PEM rfc???? describe the format for Privacy Enhanced eMail. | ||
| 6452 | As part of this standard, methods of encoding digital enveloped | ||
| 6453 | data is an ascii format are defined. As such, I use a form of these | ||
| 6454 | to encode enveloped data. While at this point in time full support | ||
| 6455 | for PEM has not been built into the library, a minimal subset of | ||
| 6456 | the secret key and Base64 encoding is present. These reoutines are | ||
| 6457 | mostly used to Ascii encode binary data with a 'type' associated | ||
| 6458 | with it and perhaps details of private key encryption used to | ||
| 6459 | encrypt the data. | ||
| 6460 | |||
| 6461 | PKCS7 This is another Digital Envelope encoding standard which uses ASN.1 | ||
| 6462 | to encode the data. At this point in time, while there are some | ||
| 6463 | routines to encode and decode this binary format, full support is | ||
| 6464 | not present. | ||
| 6465 | |||
| 6466 | As Mentioned, above, there are several different ways to encode | ||
| 6467 | data structures. | ||
| 6468 | |||
| 6469 | ASN1 This library is more a set of primatives used to encode the packing | ||
| 6470 | and unpacking of data structures. It is used by the X509 | ||
| 6471 | certificate standard and by the PKCS standards which are used by | ||
| 6472 | this library. It also contains routines for duplicating and signing | ||
| 6473 | the structures asocisated with X509. | ||
| 6474 | |||
| 6475 | X509 The X509 library contains routines for packing and unpacking, | ||
| 6476 | verifying and just about every thing else you would want to do with | ||
| 6477 | X509 certificates. | ||
| 6478 | |||
| 6479 | PKCS7 PKCS-7 is a standard for encoding digital envelope data | ||
| 6480 | structures. At this point in time the routines will load and save | ||
| 6481 | DER forms of these structees. They need to be re-worked to support | ||
| 6482 | the BER form which is the normal way PKCS-7 is encoded. If the | ||
| 6483 | previous 2 sentances don't make much sense, don't worry, this | ||
| 6484 | library is not used by this version of SSLeay anyway. | ||
| 6485 | |||
| 6486 | OBJ ASN.1 uses 'object identifiers' to identify objects. A set of | ||
| 6487 | functions were requred to translate from ASN.1 to an intenger, to a | ||
| 6488 | character string. This library provieds these translations | ||
| 6489 | |||
| 6490 | Now I mentioned an X509 library. X509 specified a hieachy of certificates | ||
| 6491 | which needs to be traversed to authenticate particular certificates. | ||
| 6492 | |||
| 6493 | METH This library is used to push 'methods' of retrieving certificates | ||
| 6494 | into the library. There are some supplied 'methods' with SSLeay | ||
| 6495 | but applications can add new methods if they so desire. | ||
| 6496 | This library has not been finished and is not being used in this | ||
| 6497 | version. | ||
| 6498 | |||
| 6499 | Now all the above are required for use in the initial point of this project. | ||
| 6500 | |||
| 6501 | SSL The SSL protocol. This is a full implmentation of SSL v 2. It | ||
| 6502 | support both server and client authentication. SSL v 3 support | ||
| 6503 | will be added when the SSL v 3 specification is released in it's | ||
| 6504 | final form. | ||
| 6505 | |||
| 6506 | Now quite a few of the above mentioned libraries rely on a few 'complex' | ||
| 6507 | data structures. For each of these I have a library. | ||
| 6508 | |||
| 6509 | Lhash This is a hash table library which is used extensivly. | ||
| 6510 | |||
| 6511 | STACK An implemetation of a Stack data structure. | ||
| 6512 | |||
| 6513 | BUF A simple character array structure that also support a function to | ||
| 6514 | check that the array is greater that a certain size, if it is not, | ||
| 6515 | it is realloced so that is it. | ||
| 6516 | |||
| 6517 | TXT_DB A simple memory based text file data base. The application can specify | ||
| 6518 | unique indexes that will be enforced at update time. | ||
| 6519 | |||
| 6520 | CONF Most of the programs written for this library require a configuration | ||
| 6521 | file. Instead of letting programs constantly re-implment this | ||
| 6522 | subsystem, the CONF library provides a consistant and flexable | ||
| 6523 | interface to not only configuration files but also environment | ||
| 6524 | variables. | ||
| 6525 | |||
| 6526 | But what about when something goes wrong? | ||
| 6527 | The one advantage (and perhaps disadvantage) of all of these | ||
| 6528 | functions being in one library was the ability to implement a | ||
| 6529 | single error reporting system. | ||
| 6530 | |||
| 6531 | ERR This library is used to report errors. The error system records | ||
| 6532 | library number, function number (in the library) and reason | ||
| 6533 | number. Multiple errors can be reported so that an 'error' trace | ||
| 6534 | is created. The errors can be printed in numeric or textual form. | ||
| 6535 | |||
| 6536 | |||
| 6537 | ==== ssluse.doc ======================================================== | ||
| 6538 | |||
| 6539 | We have an SSL_CTX which contains global information for lots of | ||
| 6540 | SSL connections. The session-id cache and the certificate verificate cache. | ||
| 6541 | It also contains default values for use when certificates are used. | ||
| 6542 | |||
| 6543 | SSL_CTX | ||
| 6544 | default cipher list | ||
| 6545 | session-id cache | ||
| 6546 | certificate cache | ||
| 6547 | default session-id timeout period | ||
| 6548 | New session-id callback | ||
| 6549 | Required session-id callback | ||
| 6550 | session-id stats | ||
| 6551 | Informational callback | ||
| 6552 | Callback that is set, overrides the SSLeay X509 certificate | ||
| 6553 | verification | ||
| 6554 | The default Certificate/Private Key pair | ||
| 6555 | Default read ahead mode. | ||
| 6556 | Default verify mode and verify callback. These are not used | ||
| 6557 | if the over ride callback mentioned above is used. | ||
| 6558 | |||
| 6559 | Each SSL can have the following defined for it before a connection is made. | ||
| 6560 | |||
| 6561 | Certificate | ||
| 6562 | Private key | ||
| 6563 | Ciphers to use | ||
| 6564 | Certificate verify mode and callback | ||
| 6565 | IO object to use in the comunication. | ||
| 6566 | Some 'read-ahead' mode information. | ||
| 6567 | A previous session-id to re-use. | ||
| 6568 | |||
| 6569 | A connection is made by using SSL_connect or SSL_accept. | ||
| 6570 | When non-blocking IO is being used, there are functions that can be used | ||
| 6571 | to determin where and why the SSL_connect or SSL_accept did not complete. | ||
| 6572 | This information can be used to recall the functions when the 'error' | ||
| 6573 | condition has dissapeared. | ||
| 6574 | |||
| 6575 | After the connection has been made, information can be retrived about the | ||
| 6576 | SSL session and the session-id values that have been decided apon. | ||
| 6577 | The 'peer' certificate can be retrieved. | ||
| 6578 | |||
| 6579 | The session-id values include | ||
| 6580 | 'start time' | ||
| 6581 | 'timeout length' | ||
| 6582 | |||
| 6583 | |||
| 6584 | |||
| 6585 | ==== stack.doc ======================================================== | ||
| 6586 | |||
| 6587 | The stack data structure is used to store an ordered list of objects. | ||
| 6588 | It is basically misnamed to call it a stack but it can function that way | ||
| 6589 | and that is what I originally used it for. Due to the way element | ||
| 6590 | pointers are kept in a malloc()ed array, the most efficient way to use this | ||
| 6591 | structure is to add and delete elements from the end via sk_pop() and | ||
| 6592 | sk_push(). If you wish to do 'lookups' sk_find() is quite efficient since | ||
| 6593 | it will sort the stack (if required) and then do a binary search to lookup | ||
| 6594 | the requested item. This sorting occurs automatically so just sk_push() | ||
| 6595 | elements on the stack and don't worry about the order. Do remember that if | ||
| 6596 | you do a sk_find(), the order of the elements will change. | ||
| 6597 | |||
| 6598 | You should never need to 'touch' this structure directly. | ||
| 6599 | typedef struct stack_st | ||
| 6600 | { | ||
| 6601 | unsigned int num; | ||
| 6602 | char **data; | ||
| 6603 | int sorted; | ||
| 6604 | |||
| 6605 | unsigned int num_alloc; | ||
| 6606 | int (*comp)(); | ||
| 6607 | } STACK; | ||
| 6608 | |||
| 6609 | 'num' holds the number of elements in the stack, 'data' is the array of | ||
| 6610 | elements. 'sorted' is 1 is the list has been sorted, 0 if not. | ||
| 6611 | |||
| 6612 | num_alloc is the number of 'nodes' allocated in 'data'. When num becomes | ||
| 6613 | larger than num_alloc, data is realloced to a larger size. | ||
| 6614 | If 'comp' is set, it is a function that is used to compare 2 of the items | ||
| 6615 | in the stack. The function should return -1, 0 or 1, depending on the | ||
| 6616 | ordering. | ||
| 6617 | |||
| 6618 | #define sk_num(sk) ((sk)->num) | ||
| 6619 | #define sk_value(sk,n) ((sk)->data[n]) | ||
| 6620 | |||
| 6621 | These 2 macros should be used to access the number of elements in the | ||
| 6622 | 'stack' and to access a pointer to one of the values. | ||
| 6623 | |||
| 6624 | STACK *sk_new(int (*c)()); | ||
| 6625 | This creates a new stack. If 'c', the comparison function, is not | ||
| 6626 | specified, the various functions that operate on a sorted 'stack' will not | ||
| 6627 | work (sk_find()). NULL is returned on failure. | ||
| 6628 | |||
| 6629 | void sk_free(STACK *); | ||
| 6630 | This function free()'s a stack structure. The elements in the | ||
| 6631 | stack will not be freed so one should 'pop' and free all elements from the | ||
| 6632 | stack before calling this function or call sk_pop_free() instead. | ||
| 6633 | |||
| 6634 | void sk_pop_free(STACK *st; void (*func)()); | ||
| 6635 | This function calls 'func' for each element on the stack, passing | ||
| 6636 | the element as the argument. sk_free() is then called to free the 'stack' | ||
| 6637 | structure. | ||
| 6638 | |||
| 6639 | int sk_insert(STACK *sk,char *data,int where); | ||
| 6640 | This function inserts 'data' into stack 'sk' at location 'where'. | ||
| 6641 | If 'where' is larger that the number of elements in the stack, the element | ||
| 6642 | is put at the end. This function tends to be used by other 'stack' | ||
| 6643 | functions. Returns 0 on failure, otherwise the number of elements in the | ||
| 6644 | new stack. | ||
| 6645 | |||
| 6646 | char *sk_delete(STACK *st,int loc); | ||
| 6647 | Remove the item a location 'loc' from the stack and returns it. | ||
| 6648 | Returns NULL if the 'loc' is out of range. | ||
| 6649 | |||
| 6650 | char *sk_delete_ptr(STACK *st, char *p); | ||
| 6651 | If the data item pointed to by 'p' is in the stack, it is deleted | ||
| 6652 | from the stack and returned. NULL is returned if the element is not in the | ||
| 6653 | stack. | ||
| 6654 | |||
| 6655 | int sk_find(STACK *st,char *data); | ||
| 6656 | Returns the location that contains a value that is equal to | ||
| 6657 | the 'data' item. If the comparison function was not set, this function | ||
| 6658 | does a linear search. This function actually qsort()s the stack if it is not | ||
| 6659 | in order and then uses bsearch() to do the initial search. If the | ||
| 6660 | search fails,, -1 is returned. For mutliple items with the same | ||
| 6661 | value, the index of the first in the array is returned. | ||
| 6662 | |||
| 6663 | int sk_push(STACK *st,char *data); | ||
| 6664 | Append 'data' to the stack. 0 is returned if there is a failure | ||
| 6665 | (due to a malloc failure), else 1. This is | ||
| 6666 | sk_insert(st,data,sk_num(st)); | ||
| 6667 | |||
| 6668 | int sk_unshift(STACK *st,char *data); | ||
| 6669 | Prepend 'data' to the front (location 0) of the stack. This is | ||
| 6670 | sk_insert(st,data,0); | ||
| 6671 | |||
| 6672 | char *sk_shift(STACK *st); | ||
| 6673 | Return and delete from the stack the first element in the stack. | ||
| 6674 | This is sk_delete(st,0); | ||
| 6675 | |||
| 6676 | char *sk_pop(STACK *st); | ||
| 6677 | Return and delete the last element on the stack. This is | ||
| 6678 | sk_delete(st,sk_num(sk)-1); | ||
| 6679 | |||
| 6680 | void sk_zero(STACK *st); | ||
| 6681 | Removes all items from the stack. It does not 'free' | ||
| 6682 | pointers but is a quick way to clear a 'stack of references'. | ||
| 6683 | |||
| 6684 | ==== threads.doc ======================================================== | ||
| 6685 | |||
| 6686 | How to compile SSLeay for multi-threading. | ||
| 6687 | |||
| 6688 | Well basically it is quite simple, set the compiler flags and build. | ||
| 6689 | I have only really done much testing under Solaris and Windows NT. | ||
| 6690 | If you library supports localtime_r() and gmtime_r() add, | ||
| 6691 | -DTHREADS to the makefile parameters. You can probably survive with out | ||
| 6692 | this define unless you are going to have multiple threads generating | ||
| 6693 | certificates at once. It will not affect the SSL side of things. | ||
| 6694 | |||
| 6695 | The approach I have taken to doing locking is to make the application provide | ||
| 6696 | callbacks to perform locking and so that the SSLeay library can distinguish | ||
| 6697 | between threads (for the error state). | ||
| 6698 | |||
| 6699 | To have a look at an example program, 'cd mt; vi mttest.c'. | ||
| 6700 | To build under solaris, sh solaris.sh, for Windows NT or Windows 95, | ||
| 6701 | win32.bat | ||
| 6702 | |||
| 6703 | This will build mttest which will fire up 10 threads that talk SSL | ||
| 6704 | to each other 10 times. | ||
| 6705 | To enable everything to work, the application needs to call | ||
| 6706 | |||
| 6707 | CRYPTO_set_id_callback(id_function); | ||
| 6708 | CRYPTO_set_locking_callback(locking_function); | ||
| 6709 | |||
| 6710 | before any multithreading is started. | ||
| 6711 | id_function does not need to be defined under Windows NT or 95, the | ||
| 6712 | correct function will be called if it is not. Under unix, getpid() | ||
| 6713 | is call if the id_callback is not defined, for solaris this is wrong | ||
| 6714 | (since threads id's are not pid's) but under IRIX it is correct | ||
| 6715 | (threads are just processes sharing the data segement). | ||
| 6716 | |||
| 6717 | The locking_callback is used to perform locking by the SSLeay library. | ||
| 6718 | eg. | ||
| 6719 | |||
| 6720 | void solaris_locking_callback(mode,type,file,line) | ||
| 6721 | int mode; | ||
| 6722 | int type; | ||
| 6723 | char *file; | ||
| 6724 | int line; | ||
| 6725 | { | ||
| 6726 | if (mode & CRYPTO_LOCK) | ||
| 6727 | mutex_lock(&(lock_cs[type])); | ||
| 6728 | else | ||
| 6729 | mutex_unlock(&(lock_cs[type])); | ||
| 6730 | } | ||
| 6731 | |||
| 6732 | Now in this case I have used mutexes instead of read/write locks, since they | ||
| 6733 | are faster and there are not many read locks in SSLeay, you may as well | ||
| 6734 | always use write locks. file and line are __FILE__ and __LINE__ from | ||
| 6735 | the compile and can be usefull when debugging. | ||
| 6736 | |||
| 6737 | Now as you can see, 'type' can be one of a range of values, these values are | ||
| 6738 | defined in crypto/crypto.h | ||
| 6739 | CRYPTO_get_lock_name(type) will return a text version of what the lock is. | ||
| 6740 | There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup | ||
| 6741 | for multi-threading can be | ||
| 6742 | |||
| 6743 | static mutex_t lock_cs[CRYPTO_NUM_LOCKS]; | ||
| 6744 | |||
| 6745 | void thread_setup() | ||
| 6746 | { | ||
| 6747 | int i; | ||
| 6748 | |||
| 6749 | for (i=0; i<CRYPTO_NUM_LOCKS; i++) | ||
| 6750 | mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL); | ||
| 6751 | CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id); | ||
| 6752 | CRYPTO_set_locking_callback((void (*)())solaris_locking_callback); | ||
| 6753 | } | ||
| 6754 | |||
| 6755 | As a final note, under Windows NT or Windows 95, you have to be careful | ||
| 6756 | not to mix the various threaded, unthreaded and debug libraries. | ||
| 6757 | Normally if they are mixed incorrectly, mttest will crash just after printing | ||
| 6758 | out some usage statistics at the end. This is because the | ||
| 6759 | different system libraries use different malloc routines and if | ||
| 6760 | data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a | ||
| 6761 | different library malloc, things get very confused. | ||
| 6762 | |||
| 6763 | The default SSLeay DLL builds use /MD, so if you use this on your | ||
| 6764 | application, things will work as expected. If you use /MDd, | ||
| 6765 | you will probably have to rebuild SSLeay using this flag. | ||
| 6766 | I should modify util/mk1mf.pl so it does all this correctly, but | ||
| 6767 | this has not been done yet. | ||
| 6768 | |||
| 6769 | One last warning. Because locking overheads are actually quite large, the | ||
| 6770 | statistics collected against the SSL_CTX for successfull connections etc | ||
| 6771 | are not locked when updated. This does make it possible for these | ||
| 6772 | values to be slightly lower than they should be, if you are | ||
| 6773 | running multithreaded on a multi-processor box, but this does not really | ||
| 6774 | matter much. | ||
| 6775 | |||
| 6776 | |||
| 6777 | ==== txt_db.doc ======================================================== | ||
| 6778 | |||
| 6779 | TXT_DB, a simple text based in memory database. | ||
| 6780 | |||
| 6781 | It holds rows of ascii data, for which the only special character is '\0'. | ||
| 6782 | The rows can be of an unlimited length. | ||
| 6783 | |||
| 6784 | ==== why.doc ======================================================== | ||
| 6785 | |||
| 6786 | This file is more of a note for other people who wish to understand why | ||
| 6787 | the build environment is the way it is :-). | ||
| 6788 | |||
| 6789 | The include files 'depend' as follows. | ||
| 6790 | Each of | ||
| 6791 | crypto/*/*.c includes crypto/cryptlib.h | ||
| 6792 | ssl/*.c include ssl/ssl_locl.h | ||
| 6793 | apps/*.c include apps/apps.h | ||
| 6794 | crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h | ||
| 6795 | all include e_os.h which contains OS/environment specific information. | ||
| 6796 | If you need to add something todo with a particular environment, | ||
| 6797 | add it to this file. It is worth remembering that quite a few libraries, | ||
| 6798 | like lhash, des, md, sha etc etc do not include crypto/cryptlib.h. This | ||
| 6799 | is because these libraries should be 'independantly compilable' and so I | ||
| 6800 | try to keep them this way. | ||
| 6801 | e_os.h is not so much a part of SSLeay, as the placing in one spot all the | ||
| 6802 | evil OS dependant muck. | ||
| 6803 | |||
| 6804 | I wanted to automate as many things as possible. This includes | ||
| 6805 | error number generation. A | ||
| 6806 | make errors | ||
| 6807 | will scan the source files for error codes, append them to the correct | ||
| 6808 | header files, and generate the functions to print the text version | ||
| 6809 | of the error numbers. So don't even think about adding error numbers by | ||
| 6810 | hand, put them in the form | ||
| 6811 | XXXerr(XXXX_F_XXXX,YYYY_R_YYYY); | ||
| 6812 | on line and it will be automatically picked up my a make errors. | ||
| 6813 | |||
| 6814 | In a similar vein, programs to be added into ssleay in the apps directory | ||
| 6815 | just need to have an entry added to E_EXE in makefile.ssl and | ||
| 6816 | everthing will work as expected. Don't edit progs.h by hand. | ||
| 6817 | |||
| 6818 | make links re-generates the symbolic links that are used. The reason why | ||
| 6819 | I keep everything in its own directory, and don't put all the | ||
| 6820 | test programs and header files in 'test' and 'include' is because I want | ||
| 6821 | to keep the 'sub-libraries' independant. I still 'pull' out | ||
| 6822 | indervidual libraries for use in specific projects where the code is | ||
| 6823 | required. I have used the 'lhash' library in just about every software | ||
| 6824 | project I have worked on :-). | ||
| 6825 | |||
| 6826 | make depend generates dependancies and | ||
| 6827 | make dclean removes them. | ||
| 6828 | |||
| 6829 | You will notice that I use perl quite a bit when I could be using 'sed'. | ||
| 6830 | The reason I decided to do this was to just stick to one 'extra' program. | ||
| 6831 | For Windows NT, I have perl and no sed. | ||
| 6832 | |||
| 6833 | The util/mk1mf.pl program can be used to generate a single makefile. | ||
| 6834 | I use this because makefiles under Microsoft are horrific. | ||
| 6835 | Each C compiler seems to have different linker formats, which have | ||
| 6836 | to be used because the retarted C compilers explode when you do | ||
| 6837 | cl -o file *.o. | ||
| 6838 | |||
| 6839 | Now some would argue that I should just use the single makefile. I don't | ||
| 6840 | like it during develoment for 2 reasons. First, the actuall make | ||
| 6841 | command takes a long time. For my current setup, if I'm in | ||
| 6842 | crypto/bn and I type make, only the crypto/bn directory gets rebuilt, | ||
| 6843 | which is nice when you are modifying prototypes in bn.h which | ||
| 6844 | half the SSLeay depends on. The second is that to add a new souce file | ||
| 6845 | I just plonk it in at the required spot in the local makefile. This | ||
| 6846 | then alows me to keep things local, I don't need to modify a 'global' | ||
| 6847 | tables (the make for unix, the make for NT, the make for w31...). | ||
| 6848 | When I am ripping apart a library structure, it is nice to only | ||
| 6849 | have to worry about one directory :-). | ||
| 6850 | |||
| 6851 | Having said all this, for the hell of it I put together 2 files that | ||
| 6852 | #include all the souce code (generated by doing a ls */*.o after a build). | ||
| 6853 | crypto.c takes only 30 seconds to build under NT and 2 minutes under linux | ||
| 6854 | for my pentium100. Much faster that the normal build :-). | ||
| 6855 | Again, the problem is that when using libraries, every program linked | ||
| 6856 | to libcrypto.a would suddenly get 330k of library when it may only need | ||
| 6857 | 1k. This technique does look like a nice way to do shared libraries though. | ||
| 6858 | |||
| 6859 | Oh yes, as a final note, to 'build' a distribution, I just type | ||
| 6860 | make dist. | ||
| 6861 | This cleans and packages everything. The directory needs to be called | ||
| 6862 | SSLeay since the make does a 'cd ..' and renames and tars things up. | ||
| 6863 | |||
| 6864 | ==== req.1 ======================================================== | ||
| 6865 | |||
| 6866 | The 'req' command is used to manipulate and deal with pkcs#10 | ||
| 6867 | certificate requests. | ||
| 6868 | |||
| 6869 | It's default mode of operation is to load a certificate and then | ||
| 6870 | write it out again. | ||
| 6871 | |||
| 6872 | By default the 'req' is read from stdin in 'PEM' format. | ||
| 6873 | The -inform option can be used to specify 'pem' format or 'der' | ||
| 6874 | format. PEM format is the base64 encoding of the DER format. | ||
| 6875 | |||
| 6876 | By default 'req' then writes the request back out. -outform can be used | ||
| 6877 | to indicate the desired output format, be it 'pem' or 'der'. | ||
| 6878 | |||
| 6879 | To specify an input file, use the '-in' option and the '-out' option | ||
| 6880 | can be used to specify the output file. | ||
| 6881 | |||
| 6882 | If you wish to perform a command and not output the certificate | ||
| 6883 | request afterwards, use the '-noout' option. | ||
| 6884 | |||
| 6885 | When a certificate is loaded, it can be printed in a human readable | ||
| 6886 | ascii format via the '-text' option. | ||
| 6887 | |||
| 6888 | To check that the signature on a certificate request is correct, use | ||
| 6889 | the '-verify' option to make sure that the private key contained in the | ||
| 6890 | certificate request corresponds to the signature. | ||
| 6891 | |||
| 6892 | Besides the default mode, there is also the 'generate a certificate | ||
| 6893 | request' mode. There are several flags that trigger this mode. | ||
| 6894 | |||
| 6895 | -new will generate a new RSA key (if required) and then prompts | ||
| 6896 | the user for details for the certificate request. | ||
| 6897 | -newkey has an argument that is the number of bits to make the new | ||
| 6898 | key. This function also triggers '-new'. | ||
| 6899 | |||
| 6900 | The '-new' option can have a key to use specified instead of having to | ||
| 6901 | load one, '-key' is used to specify the file containg the key. | ||
| 6902 | -keyform can be used to specify the format of the key. Only | ||
| 6903 | 'pem' and 'der' formats are supported, later, 'netscape' format may be added. | ||
| 6904 | |||
| 6905 | Finally there is the '-x509' options which makes req output a self | ||
| 6906 | signed x509 certificate instead of a certificate request. | ||
| 6907 | |||
| 6908 | Now as you may have noticed, there are lots of default options that | ||
| 6909 | cannot be specified via the command line. They are held in a 'template' | ||
| 6910 | or 'configuration file'. The -config option specifies which configuration | ||
| 6911 | file to use. See conf.doc for details on the syntax of this file. | ||
| 6912 | |||
| 6913 | The req command uses the 'req' section of the config file. | ||
| 6914 | |||
| 6915 | --- | ||
| 6916 | # The following variables are defined. For this example I will populate | ||
| 6917 | # the various values | ||
| 6918 | [ req ] | ||
| 6919 | default_bits = 512 # default number of bits to use. | ||
| 6920 | default_keyfile = testkey.pem # Where to write the generated keyfile | ||
| 6921 | # if not specified. | ||
| 6922 | distinguished_name= req_dn # The section that contains the | ||
| 6923 | # information about which 'object' we | ||
| 6924 | # want to put in the DN. | ||
| 6925 | attributes = req_attr # The objects we want for the | ||
| 6926 | # attributes field. | ||
| 6927 | encrypt_rsa_key = no # Should we encrypt newly generated | ||
| 6928 | # keys. I strongly recommend 'yes'. | ||
| 6929 | |||
| 6930 | # The distinguished name section. For the following entries, the | ||
| 6931 | # object names must exist in the SSLeay header file objects.h. If they | ||
| 6932 | # do not, they will be silently ignored. The entries have the following | ||
| 6933 | # format. | ||
| 6934 | # <object_name> => string to prompt with | ||
| 6935 | # <object_name>_default => default value for people | ||
| 6936 | # <object_name>_value => Automatically use this value for this field. | ||
| 6937 | # <object_name>_min => minimum number of characters for data (def. 0) | ||
| 6938 | # <object_name>_max => maximum number of characters for data (def. inf.) | ||
| 6939 | # All of these entries are optional except for the first one. | ||
| 6940 | [ req_dn ] | ||
| 6941 | countryName = Country Name (2 letter code) | ||
| 6942 | countryName_default = AU | ||
| 6943 | |||
| 6944 | stateOrProvinceName = State or Province Name (full name) | ||
| 6945 | stateOrProvinceName_default = Queensland | ||
| 6946 | |||
| 6947 | localityName = Locality Name (eg, city) | ||
| 6948 | |||
| 6949 | organizationName = Organization Name (eg, company) | ||
| 6950 | organizationName_default = Mincom Pty Ltd | ||
| 6951 | |||
| 6952 | organizationalUnitName = Organizational Unit Name (eg, section) | ||
| 6953 | organizationalUnitName_default = MTR | ||
| 6954 | |||
| 6955 | commonName = Common Name (eg, YOUR name) | ||
| 6956 | commonName_max = 64 | ||
| 6957 | |||
| 6958 | emailAddress = Email Address | ||
| 6959 | emailAddress_max = 40 | ||
| 6960 | |||
| 6961 | # The next section is the attributes section. This is exactly the | ||
| 6962 | # same as for the previous section except that the resulting objects are | ||
| 6963 | # put in the attributes field. | ||
| 6964 | [ req_attr ] | ||
| 6965 | challengePassword = A challenge password | ||
| 6966 | challengePassword_min = 4 | ||
| 6967 | challengePassword_max = 20 | ||
| 6968 | |||
| 6969 | unstructuredName = An optional company name | ||
| 6970 | |||
| 6971 | ---- | ||
| 6972 | Also note that the order that attributes appear in this file is the | ||
| 6973 | order they will be put into the distinguished name. | ||
| 6974 | |||
| 6975 | Once this request has been generated, it can be sent to a CA for | ||
| 6976 | certifying. | ||
| 6977 | |||
| 6978 | ---- | ||
| 6979 | A few quick examples.... | ||
| 6980 | |||
| 6981 | To generate a new request and a new key | ||
| 6982 | req -new | ||
| 6983 | |||
| 6984 | To generate a new request and a 1058 bit key | ||
| 6985 | req -newkey 1058 | ||
| 6986 | |||
| 6987 | To generate a new request using a pre-existing key | ||
| 6988 | req -new -key key.pem | ||
| 6989 | |||
| 6990 | To generate a self signed x509 certificate from a certificate | ||
| 6991 | request using a supplied key, and we want to see the text form of the | ||
| 6992 | output certificate (which we will put in the file selfSign.pem | ||
| 6993 | req -x509 -in req.pem -key key.pem -text -out selfSign.pem | ||
| 6994 | |||
| 6995 | Verify that the signature is correct on a certificate request. | ||
| 6996 | req -verify -in req.pem | ||
| 6997 | |||
| 6998 | Verify that the signature was made using a specified public key. | ||
| 6999 | req -verify -in req.pem -key key.pem | ||
| 7000 | |||
| 7001 | Print the contents of a certificate request | ||
| 7002 | req -text -in req.pem | ||
| 7003 | |||
| 7004 | ==== danger ======================================================== | ||
| 7005 | |||
| 7006 | If you specify a SSLv2 cipher, and the mode is SSLv23 and the server | ||
| 7007 | can talk SSLv3, it will claim there is no cipher since you should be | ||
| 7008 | using SSLv3. | ||
| 7009 | |||
| 7010 | When tracing debug stuff, remember BIO_s_socket() is different to | ||
| 7011 | BIO_s_connect(). | ||
| 7012 | |||
| 7013 | BSD/OS assember is not working | ||
| 7014 | |||
diff --git a/src/lib/libssl/src/doc/ssluse.doc b/src/lib/libssl/src/doc/ssluse.doc deleted file mode 100644 index 2e3a26cbf3..0000000000 --- a/src/lib/libssl/src/doc/ssluse.doc +++ /dev/null | |||
| @@ -1,45 +0,0 @@ | |||
| 1 | We have an SSL_CTX which contains global information for lots of | ||
| 2 | SSL connections. The session-id cache and the certificate verificate cache. | ||
| 3 | It also contains default values for use when certificates are used. | ||
| 4 | |||
| 5 | SSL_CTX | ||
| 6 | default cipher list | ||
| 7 | session-id cache | ||
| 8 | certificate cache | ||
| 9 | default session-id timeout period | ||
| 10 | New session-id callback | ||
| 11 | Required session-id callback | ||
| 12 | session-id stats | ||
| 13 | Informational callback | ||
| 14 | Callback that is set, overrides the SSLeay X509 certificate | ||
| 15 | verification | ||
| 16 | The default Certificate/Private Key pair | ||
| 17 | Default read ahead mode. | ||
| 18 | Default verify mode and verify callback. These are not used | ||
| 19 | if the over ride callback mentioned above is used. | ||
| 20 | |||
| 21 | Each SSL can have the following defined for it before a connection is made. | ||
| 22 | |||
| 23 | Certificate | ||
| 24 | Private key | ||
| 25 | Ciphers to use | ||
| 26 | Certificate verify mode and callback | ||
| 27 | IO object to use in the comunication. | ||
| 28 | Some 'read-ahead' mode information. | ||
| 29 | A previous session-id to re-use. | ||
| 30 | |||
| 31 | A connection is made by using SSL_connect or SSL_accept. | ||
| 32 | When non-blocking IO is being used, there are functions that can be used | ||
| 33 | to determin where and why the SSL_connect or SSL_accept did not complete. | ||
| 34 | This information can be used to recall the functions when the 'error' | ||
| 35 | condition has dissapeared. | ||
| 36 | |||
| 37 | After the connection has been made, information can be retrived about the | ||
| 38 | SSL session and the session-id values that have been decided apon. | ||
| 39 | The 'peer' certificate can be retrieved. | ||
| 40 | |||
| 41 | The session-id values include | ||
| 42 | 'start time' | ||
| 43 | 'timeout length' | ||
| 44 | |||
| 45 | |||
diff --git a/src/lib/libssl/src/doc/stack.doc b/src/lib/libssl/src/doc/stack.doc deleted file mode 100644 index 7c20b1b664..0000000000 --- a/src/lib/libssl/src/doc/stack.doc +++ /dev/null | |||
| @@ -1,96 +0,0 @@ | |||
| 1 | The stack data structure is used to store an ordered list of objects. | ||
| 2 | It is basically misnamed to call it a stack but it can function that way | ||
| 3 | and that is what I originally used it for. Due to the way element | ||
| 4 | pointers are kept in a malloc()ed array, the most efficient way to use this | ||
| 5 | structure is to add and delete elements from the end via sk_pop() and | ||
| 6 | sk_push(). If you wish to do 'lookups' sk_find() is quite efficient since | ||
| 7 | it will sort the stack (if required) and then do a binary search to lookup | ||
| 8 | the requested item. This sorting occurs automatically so just sk_push() | ||
| 9 | elements on the stack and don't worry about the order. Do remember that if | ||
| 10 | you do a sk_find(), the order of the elements will change. | ||
| 11 | |||
| 12 | You should never need to 'touch' this structure directly. | ||
| 13 | typedef struct stack_st | ||
| 14 | { | ||
| 15 | unsigned int num; | ||
| 16 | char **data; | ||
| 17 | int sorted; | ||
| 18 | |||
| 19 | unsigned int num_alloc; | ||
| 20 | int (*comp)(); | ||
| 21 | } STACK; | ||
| 22 | |||
| 23 | 'num' holds the number of elements in the stack, 'data' is the array of | ||
| 24 | elements. 'sorted' is 1 is the list has been sorted, 0 if not. | ||
| 25 | |||
| 26 | num_alloc is the number of 'nodes' allocated in 'data'. When num becomes | ||
| 27 | larger than num_alloc, data is realloced to a larger size. | ||
| 28 | If 'comp' is set, it is a function that is used to compare 2 of the items | ||
| 29 | in the stack. The function should return -1, 0 or 1, depending on the | ||
| 30 | ordering. | ||
| 31 | |||
| 32 | #define sk_num(sk) ((sk)->num) | ||
| 33 | #define sk_value(sk,n) ((sk)->data[n]) | ||
| 34 | |||
| 35 | These 2 macros should be used to access the number of elements in the | ||
| 36 | 'stack' and to access a pointer to one of the values. | ||
| 37 | |||
| 38 | STACK *sk_new(int (*c)()); | ||
| 39 | This creates a new stack. If 'c', the comparison function, is not | ||
| 40 | specified, the various functions that operate on a sorted 'stack' will not | ||
| 41 | work (sk_find()). NULL is returned on failure. | ||
| 42 | |||
| 43 | void sk_free(STACK *); | ||
| 44 | This function free()'s a stack structure. The elements in the | ||
| 45 | stack will not be freed so one should 'pop' and free all elements from the | ||
| 46 | stack before calling this function or call sk_pop_free() instead. | ||
| 47 | |||
| 48 | void sk_pop_free(STACK *st; void (*func)()); | ||
| 49 | This function calls 'func' for each element on the stack, passing | ||
| 50 | the element as the argument. sk_free() is then called to free the 'stack' | ||
| 51 | structure. | ||
| 52 | |||
| 53 | int sk_insert(STACK *sk,char *data,int where); | ||
| 54 | This function inserts 'data' into stack 'sk' at location 'where'. | ||
| 55 | If 'where' is larger that the number of elements in the stack, the element | ||
| 56 | is put at the end. This function tends to be used by other 'stack' | ||
| 57 | functions. Returns 0 on failure, otherwise the number of elements in the | ||
| 58 | new stack. | ||
| 59 | |||
| 60 | char *sk_delete(STACK *st,int loc); | ||
| 61 | Remove the item a location 'loc' from the stack and returns it. | ||
| 62 | Returns NULL if the 'loc' is out of range. | ||
| 63 | |||
| 64 | char *sk_delete_ptr(STACK *st, char *p); | ||
| 65 | If the data item pointed to by 'p' is in the stack, it is deleted | ||
| 66 | from the stack and returned. NULL is returned if the element is not in the | ||
| 67 | stack. | ||
| 68 | |||
| 69 | int sk_find(STACK *st,char *data); | ||
| 70 | Returns the location that contains a value that is equal to | ||
| 71 | the 'data' item. If the comparison function was not set, this function | ||
| 72 | does a linear search. This function actually qsort()s the stack if it is not | ||
| 73 | in order and then uses bsearch() to do the initial search. If the | ||
| 74 | search fails,, -1 is returned. For mutliple items with the same | ||
| 75 | value, the index of the first in the array is returned. | ||
| 76 | |||
| 77 | int sk_push(STACK *st,char *data); | ||
| 78 | Append 'data' to the stack. 0 is returned if there is a failure | ||
| 79 | (due to a malloc failure), else 1. This is | ||
| 80 | sk_insert(st,data,sk_num(st)); | ||
| 81 | |||
| 82 | int sk_unshift(STACK *st,char *data); | ||
| 83 | Prepend 'data' to the front (location 0) of the stack. This is | ||
| 84 | sk_insert(st,data,0); | ||
| 85 | |||
| 86 | char *sk_shift(STACK *st); | ||
| 87 | Return and delete from the stack the first element in the stack. | ||
| 88 | This is sk_delete(st,0); | ||
| 89 | |||
| 90 | char *sk_pop(STACK *st); | ||
| 91 | Return and delete the last element on the stack. This is | ||
| 92 | sk_delete(st,sk_num(sk)-1); | ||
| 93 | |||
| 94 | void sk_zero(STACK *st); | ||
| 95 | Removes all items from the stack. It does not 'free' | ||
| 96 | pointers but is a quick way to clear a 'stack of references'. | ||
diff --git a/src/lib/libssl/src/doc/threads.doc b/src/lib/libssl/src/doc/threads.doc deleted file mode 100644 index 251061e896..0000000000 --- a/src/lib/libssl/src/doc/threads.doc +++ /dev/null | |||
| @@ -1,90 +0,0 @@ | |||
| 1 | How to compile SSLeay for multi-threading. | ||
| 2 | |||
| 3 | Well basically it is quite simple, set the compiler flags and build. | ||
| 4 | I have only really done much testing under Solaris and Windows NT. | ||
| 5 | If you library supports localtime_r() and gmtime_r() add, | ||
| 6 | -DTHREADS to the makefile parameters. You can probably survive with out | ||
| 7 | this define unless you are going to have multiple threads generating | ||
| 8 | certificates at once. It will not affect the SSL side of things. | ||
| 9 | |||
| 10 | The approach I have taken to doing locking is to make the application provide | ||
| 11 | callbacks to perform locking and so that the SSLeay library can distinguish | ||
| 12 | between threads (for the error state). | ||
| 13 | |||
| 14 | To have a look at an example program, 'cd mt; vi mttest.c'. | ||
| 15 | To build under solaris, sh solaris.sh, for Windows NT or Windows 95, | ||
| 16 | win32.bat | ||
| 17 | |||
| 18 | This will build mttest which will fire up 10 threads that talk SSL | ||
| 19 | to each other 10 times. | ||
| 20 | To enable everything to work, the application needs to call | ||
| 21 | |||
| 22 | CRYPTO_set_id_callback(id_function); | ||
| 23 | CRYPTO_set_locking_callback(locking_function); | ||
| 24 | |||
| 25 | before any multithreading is started. | ||
| 26 | id_function does not need to be defined under Windows NT or 95, the | ||
| 27 | correct function will be called if it is not. Under unix, getpid() | ||
| 28 | is call if the id_callback is not defined, for solaris this is wrong | ||
| 29 | (since threads id's are not pid's) but under IRIX it is correct | ||
| 30 | (threads are just processes sharing the data segement). | ||
| 31 | |||
| 32 | The locking_callback is used to perform locking by the SSLeay library. | ||
| 33 | eg. | ||
| 34 | |||
| 35 | void solaris_locking_callback(mode,type,file,line) | ||
| 36 | int mode; | ||
| 37 | int type; | ||
| 38 | char *file; | ||
| 39 | int line; | ||
| 40 | { | ||
| 41 | if (mode & CRYPTO_LOCK) | ||
| 42 | mutex_lock(&(lock_cs[type])); | ||
| 43 | else | ||
| 44 | mutex_unlock(&(lock_cs[type])); | ||
| 45 | } | ||
| 46 | |||
| 47 | Now in this case I have used mutexes instead of read/write locks, since they | ||
| 48 | are faster and there are not many read locks in SSLeay, you may as well | ||
| 49 | always use write locks. file and line are __FILE__ and __LINE__ from | ||
| 50 | the compile and can be usefull when debugging. | ||
| 51 | |||
| 52 | Now as you can see, 'type' can be one of a range of values, these values are | ||
| 53 | defined in crypto/crypto.h | ||
| 54 | CRYPTO_get_lock_name(type) will return a text version of what the lock is. | ||
| 55 | There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup | ||
| 56 | for multi-threading can be | ||
| 57 | |||
| 58 | static mutex_t lock_cs[CRYPTO_NUM_LOCKS]; | ||
| 59 | |||
| 60 | void thread_setup() | ||
| 61 | { | ||
| 62 | int i; | ||
| 63 | |||
| 64 | for (i=0; i<CRYPTO_NUM_LOCKS; i++) | ||
| 65 | mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL); | ||
| 66 | CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id); | ||
| 67 | CRYPTO_set_locking_callback((void (*)())solaris_locking_callback); | ||
| 68 | } | ||
| 69 | |||
| 70 | As a final note, under Windows NT or Windows 95, you have to be careful | ||
| 71 | not to mix the various threaded, unthreaded and debug libraries. | ||
| 72 | Normally if they are mixed incorrectly, mttest will crash just after printing | ||
| 73 | out some usage statistics at the end. This is because the | ||
| 74 | different system libraries use different malloc routines and if | ||
| 75 | data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a | ||
| 76 | different library malloc, things get very confused. | ||
| 77 | |||
| 78 | The default SSLeay DLL builds use /MD, so if you use this on your | ||
| 79 | application, things will work as expected. If you use /MDd, | ||
| 80 | you will probably have to rebuild SSLeay using this flag. | ||
| 81 | I should modify util/mk1mf.pl so it does all this correctly, but | ||
| 82 | this has not been done yet. | ||
| 83 | |||
| 84 | One last warning. Because locking overheads are actually quite large, the | ||
| 85 | statistics collected against the SSL_CTX for successfull connections etc | ||
| 86 | are not locked when updated. This does make it possible for these | ||
| 87 | values to be slightly lower than they should be, if you are | ||
| 88 | running multithreaded on a multi-processor box, but this does not really | ||
| 89 | matter much. | ||
| 90 | |||
diff --git a/src/lib/libssl/src/doc/txt_db.doc b/src/lib/libssl/src/doc/txt_db.doc deleted file mode 100644 index 3a5b0d50a1..0000000000 --- a/src/lib/libssl/src/doc/txt_db.doc +++ /dev/null | |||
| @@ -1,4 +0,0 @@ | |||
| 1 | TXT_DB, a simple text based in memory database. | ||
| 2 | |||
| 3 | It holds rows of ascii data, for which the only special character is '\0'. | ||
| 4 | The rows can be of an unlimited length. | ||
diff --git a/src/lib/libssl/src/doc/verify b/src/lib/libssl/src/doc/verify deleted file mode 100644 index b78d96159d..0000000000 --- a/src/lib/libssl/src/doc/verify +++ /dev/null | |||
| @@ -1,22 +0,0 @@ | |||
| 1 | X509_verify_cert_chain( | ||
| 2 | CERT_STORE *cert_store, | ||
| 3 | STACK /* X509 */ *certs, | ||
| 4 | int *verify_result, | ||
| 5 | int (*verify_error_callback)() | ||
| 6 | char *argument_to_callback, /* SSL */ | ||
| 7 | |||
| 8 | app_verify_callback( | ||
| 9 | char *app_verify_arg, /* from SSL_CTX */ | ||
| 10 | STACK /* X509 */ *certs, | ||
| 11 | int *verify_result, | ||
| 12 | int (*verify_error_callback)() | ||
| 13 | SSL *s, | ||
| 14 | |||
| 15 | int X509_verify_cert( | ||
| 16 | CERT_STORE *cert_store, | ||
| 17 | X509 *x509, | ||
| 18 | int *verify_result, | ||
| 19 | int (*verify_error_callback)(), | ||
| 20 | char *arg, | ||
| 21 | |||
| 22 | |||
diff --git a/src/lib/libssl/src/doc/why.doc b/src/lib/libssl/src/doc/why.doc deleted file mode 100644 index a1ac84bd27..0000000000 --- a/src/lib/libssl/src/doc/why.doc +++ /dev/null | |||
| @@ -1,79 +0,0 @@ | |||
| 1 | This file is more of a note for other people who wish to understand why | ||
| 2 | the build environment is the way it is :-). | ||
| 3 | |||
| 4 | The include files 'depend' as follows. | ||
| 5 | Each of | ||
| 6 | crypto/*/*.c includes crypto/cryptlib.h | ||
| 7 | ssl/*.c include ssl/ssl_locl.h | ||
| 8 | apps/*.c include apps/apps.h | ||
| 9 | crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h | ||
| 10 | all include e_os.h which contains OS/environment specific information. | ||
| 11 | If you need to add something todo with a particular environment, | ||
| 12 | add it to this file. It is worth remembering that quite a few libraries, | ||
| 13 | like lhash, des, md, sha etc etc do not include crypto/cryptlib.h. This | ||
| 14 | is because these libraries should be 'independantly compilable' and so I | ||
| 15 | try to keep them this way. | ||
| 16 | e_os.h is not so much a part of SSLeay, as the placing in one spot all the | ||
| 17 | evil OS dependant muck. | ||
| 18 | |||
| 19 | I wanted to automate as many things as possible. This includes | ||
| 20 | error number generation. A | ||
| 21 | make errors | ||
| 22 | will scan the source files for error codes, append them to the correct | ||
| 23 | header files, and generate the functions to print the text version | ||
| 24 | of the error numbers. So don't even think about adding error numbers by | ||
| 25 | hand, put them in the form | ||
| 26 | XXXerr(XXXX_F_XXXX,YYYY_R_YYYY); | ||
| 27 | on line and it will be automatically picked up my a make errors. | ||
| 28 | |||
| 29 | In a similar vein, programs to be added into ssleay in the apps directory | ||
| 30 | just need to have an entry added to E_EXE in makefile.ssl and | ||
| 31 | everthing will work as expected. Don't edit progs.h by hand. | ||
| 32 | |||
| 33 | make links re-generates the symbolic links that are used. The reason why | ||
| 34 | I keep everything in its own directory, and don't put all the | ||
| 35 | test programs and header files in 'test' and 'include' is because I want | ||
| 36 | to keep the 'sub-libraries' independant. I still 'pull' out | ||
| 37 | indervidual libraries for use in specific projects where the code is | ||
| 38 | required. I have used the 'lhash' library in just about every software | ||
| 39 | project I have worked on :-). | ||
| 40 | |||
| 41 | make depend generates dependancies and | ||
| 42 | make dclean removes them. | ||
| 43 | |||
| 44 | You will notice that I use perl quite a bit when I could be using 'sed'. | ||
| 45 | The reason I decided to do this was to just stick to one 'extra' program. | ||
| 46 | For Windows NT, I have perl and no sed. | ||
| 47 | |||
| 48 | The util/mk1mf.pl program can be used to generate a single makefile. | ||
| 49 | I use this because makefiles under Microsoft are horrific. | ||
| 50 | Each C compiler seems to have different linker formats, which have | ||
| 51 | to be used because the retarted C compilers explode when you do | ||
| 52 | cl -o file *.o. | ||
| 53 | |||
| 54 | Now some would argue that I should just use the single makefile. I don't | ||
| 55 | like it during develoment for 2 reasons. First, the actuall make | ||
| 56 | command takes a long time. For my current setup, if I'm in | ||
| 57 | crypto/bn and I type make, only the crypto/bn directory gets rebuilt, | ||
| 58 | which is nice when you are modifying prototypes in bn.h which | ||
| 59 | half the SSLeay depends on. The second is that to add a new souce file | ||
| 60 | I just plonk it in at the required spot in the local makefile. This | ||
| 61 | then alows me to keep things local, I don't need to modify a 'global' | ||
| 62 | tables (the make for unix, the make for NT, the make for w31...). | ||
| 63 | When I am ripping apart a library structure, it is nice to only | ||
| 64 | have to worry about one directory :-). | ||
| 65 | |||
| 66 | Having said all this, for the hell of it I put together 2 files that | ||
| 67 | #include all the souce code (generated by doing a ls */*.o after a build). | ||
| 68 | crypto.c takes only 30 seconds to build under NT and 2 minutes under linux | ||
| 69 | for my pentium100. Much faster that the normal build :-). | ||
| 70 | Again, the problem is that when using libraries, every program linked | ||
| 71 | to libcrypto.a would suddenly get 330k of library when it may only need | ||
| 72 | 1k. This technique does look like a nice way to do shared libraries though. | ||
| 73 | |||
| 74 | Oh yes, as a final note, to 'build' a distribution, I just type | ||
| 75 | make dist. | ||
| 76 | This cleans and packages everything. The directory needs to be called | ||
| 77 | SSLeay since the make does a 'cd ..' and renames and tars things up. | ||
| 78 | |||
| 79 | |||
