Updates from 1.0.0-stable branch.
[openssl.git] / doc / ssleay.txt
1
2 Bundle of old SSLeay documentation files [OBSOLETE!]
3
4 *** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! ***
5
6 OBSOLETE means that nothing in this document should be trusted.  This
7 document is provided mostly for historical purposes (it wasn't even up
8 to date at the time SSLeay 0.8.1 was released) and as inspiration.  If
9 you copy some snippet of code from this document, please _check_ that
10 it really is correct from all points of view.  For example, you can
11 check with the other documents in this directory tree, or by comparing
12 with relevant parts of the include files.
13
14 People have done the mistake of trusting what's written here.  Please
15 don't do that.
16
17 *** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! ***
18
19
20 ==== readme ========================================================
21
22 This is the old 0.6.6 docuementation.  Most of the cipher stuff is still
23 relevent but I'm working (very slowly) on new documentation.
24 The current version can be found online at
25
26 http://www.cryptsoft.com/ssleay/doc
27
28 ==== API.doc ========================================================
29
30 SSL - SSLv2/v3/v23 etc.
31
32 BIO - methods and how they plug together
33
34 MEM - memory allocation callback
35
36 CRYPTO - locking for threads
37
38 EVP - Ciphers/Digests/signatures
39
40 RSA - methods
41
42 X509 - certificate retrieval
43
44 X509 - validation
45
46 X509 - X509v3 extensions
47
48 Objects - adding object identifiers
49
50 ASN.1 - parsing
51
52 PEM - parsing
53
54 ==== ssl/readme =====================================================
55
56 22 Jun 1996
57 This file belongs in ../apps, but I'll leave it here because it deals
58 with SSL :-)  It is rather dated but it gives you an idea of how
59 things work.
60 ===
61
62 17 Jul 1995
63 I have been changing things quite a bit and have not fully updated
64 this file, so take what you read with a grain of salt
65 eric
66 ===
67 The s_client and s_server programs can be used to test SSL capable
68 IP/port addresses and the verification of the X509 certificates in use
69 by these services.  I strongly advise having a look at the code to get
70 an idea of how to use the authentication under SSLeay.  Any feedback
71 on changes and improvements would be greatly accepted.
72
73 This file will probably be gibberish unless you have read
74 rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM
75 authentication.
76
77 A Brief outline (and examples) how to use them to do so.
78
79 NOTE:
80 The environment variable SSL_CIPER is used to specify the prefered
81 cipher to use, play around with setting it's value to combinations of
82 RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL
83 in a : separated list.
84
85 This directory contains 3 X509 certificates which can be used by these programs.
86 client.pem: a file containing a certificate and private key to be used
87         by s_client.
88 server.pem :a file containing a certificate and private key to be used
89         by s_server.
90 eay1024.pem:the certificate used to sign client.pem and server.pem.
91         This would be your CA's certificate.  There is also a link
92         from the file a8556381.0 to eay1024.PEM.  The value a8556381
93         is returned by 'x509 -hash -noout <eay1024.pem' and is the
94         value used by X509 verification routines to 'find' this
95         certificte when search a directory for it.
96         [the above is not true any more, the CA cert is 
97          ../certs/testca.pem which is signed by ../certs/mincomca.pem]
98
99 When testing the s_server, you may get
100 bind: Address already in use
101 errors.  These indicate the port is still being held by the unix
102 kernel and you are going to have to wait for it to let go of it.  If
103 this is the case, remember to use the port commands on the s_server and
104 s_client to talk on an alternative port.
105
106 =====
107 s_client.
108 This program can be used to connect to any IP/hostname:port that is
109 talking SSL.  Once connected, it will attempt to authenticate the
110 certificate it was passed and if everything works as expected, a 2
111 directional channel will be open.  Any text typed will be sent to the
112 other end.  type Q<cr> to exit.  Flags are as follows.
113 -host arg       : Arg is the host or IP address to connect to.
114 -port arg       : Arg is the port to connect to (https is 443).
115 -verify arg     : Turn on authentication of the server certificate.
116                 : Arg specifies the 'depth', this will covered below.
117 -cert arg       : The optional certificate to use.  This certificate
118                 : will be returned to the server if the server
119                 : requests it for client authentication.
120 -key arg        : The private key that matches the certificate
121                 : specified by the -cert option.  If this is not
122                 : specified (but -cert is), the -cert file will be
123                 : searched for the Private key.  Both files are
124                 : assumed to be in PEM format.
125 -CApath arg     : When to look for certificates when 'verifying' the
126                 : certificate from the server.
127 -CAfile arg     : A file containing certificates to be used for
128                 : 'verifying' the server certificate.
129 -reconnect      : Once a connection has been made, drop it and
130                 : reconnect with same session-id.  This is for testing :-).
131
132 The '-verify n' parameter specifies not only to verify the servers
133 certificate but to also only take notice of 'n' levels.  The best way
134 to explain is to show via examples.
135 Given
136 s_server -cert server.PEM is running.
137
138 s_client
139         CONNECTED
140         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
141         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
142         verify error:num=1:unable to get issuer certificate
143         verify return:1
144         CIPHER is CBC-DES-MD5
145 What has happened is that the 'SSLeay demo server' certificate's
146 issuer ('CA') could not be found but because verify is not on, we
147 don't care and the connection has been made anyway.  It is now 'up'
148 using CBC-DES-MD5 mode.  This is an unauthenticate secure channel.
149 You may not be talking to the right person but the data going to them
150 is encrypted.
151
152 s_client -verify 0
153         CONNECTED
154         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
155         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
156         verify error:num=1:unable to get issuer certificate
157         verify return:1
158         CIPHER is CBC-DES-MD5
159 We are 'verifying' but only to depth 0, so since the 'SSLeay demo server'
160 certificate passed the date and checksum, we are happy to proceed.
161
162 s_client -verify 1
163         CONNECTED
164         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
165         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
166         verify error:num=1:unable to get issuer certificate
167         verify return:0
168         ERROR
169         verify error:unable to get issuer certificate
170 In this case we failed to make the connection because we could not
171 authenticate the certificate because we could not find the
172 'CA' certificate.
173
174 s_client -verify 1 -CAfile eay1024.PEM
175         CONNECTED
176         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
177         verify return:1
178         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
179         verify return:1
180         CIPHER is CBC-DES-MD5
181 We loaded the certificates from the file eay1024.PEM.  Everything
182 checked out and so we made the connection.
183
184 s_client -verify 1 -CApath .
185         CONNECTED
186         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
187         verify return:1
188         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
189         verify return:1
190         CIPHER is CBC-DES-MD5
191 We looked in out local directory for issuer certificates and 'found'
192 a8556381.0 and so everything is ok.
193
194 It is worth noting that 'CA' is a self certified certificate.  If you
195 are passed one of these, it will fail to 'verify' at depth 0 because
196 we need to lookup the certifier of a certificate from some information
197 that we trust and keep locally.
198
199 SSL_CIPHER=CBC3-DES-MD5:RC4-MD5
200 export SSL_CIPHER
201 s_client -verify 10 -CApath . -reconnect
202         CONNECTED
203         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
204         verify return:1
205         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
206         verify return:1
207         drop the connection and reconnect with the same session id
208         CIPHER is CBC3-DES-MD5
209 This has done a full connection and then re-estabished it with the
210 same session id but a new socket.  No RSA stuff occures on the second
211 connection.  Note that we said we would prefer to use CBC3-DES-MD5
212 encryption and so, since the server supports it, we are.
213
214 =====
215 s_server
216 This program accepts SSL connections on a specified port
217 Once connected, it will estabish an SSL connection and optionaly
218 attempt to authenticate the client.  A 2 directional channel will be
219 open.  Any text typed will be sent to the other end.  Type Q<cr> to exit.
220 Flags are as follows.
221 -port arg       : Arg is the port to listen on.
222 -verify arg     : Turn on authentication of the client if they have a
223                 : certificate.  Arg specifies the 'depth'.
224 -Verify arg     : Turn on authentication of the client. If they don't
225                 : have a valid certificate, drop the connection.
226 -cert arg       : The certificate to use.  This certificate
227                 : will be passed to the client.  If it is not
228                 : specified, it will default to server.PEM
229 -key arg        : The private key that matches the certificate
230                 : specified by the -cert option.  If this is not
231                 : specified (but -cert is), the -cert file will be
232                 : searched for the Private key.  Both files are
233                 : assumed to be in PEM format.  Default is server.PEM
234 -CApath arg     : When to look for certificates when 'verifying' the
235                 : certificate from the client.
236 -CAfile arg     : A file containing certificates to be used for
237                 : 'verifying' the client certificate.
238
239 For the following 'demo'  I will specify the s_server command and
240 the s_client command and then list the output from the s_server.
241 s_server
242 s_client
243         CONNECTED
244         CIPHER is CBC-DES-MD5
245 Everything up and running
246
247 s_server -verify 0
248 s_client  
249         CONNECTED
250         CIPHER is CBC-DES-MD5
251 Ok since no certificate was returned and we don't care.
252
253 s_server -verify 0
254 ./s_client -cert client.PEM
255         CONNECTED
256         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
257         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
258         verify error:num=1:unable to get issuer certificate
259         verify return:1
260         CIPHER is CBC-DES-MD5
261 Ok since we were only verifying to level 0
262
263 s_server -verify 4
264 s_client -cert client.PEM
265         CONNECTED
266         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
267         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
268         verify error:num=1:unable to get issuer certificate
269         verify return:0
270         ERROR
271         verify error:unable to get issuer certificate
272 Bad because we could not authenticate the returned certificate.
273
274 s_server -verify 4 -CApath .
275 s_client -cert client.PEM
276         CONNECTED
277         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
278         verify return:1
279         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
280         verify return:1
281         CIPHER is CBC-DES-MD5
282 Ok because we could authenticate the returned certificate :-).
283
284 s_server -Verify 0 -CApath .
285 s_client
286         CONNECTED
287         ERROR
288         SSL error:function is:REQUEST_CERTIFICATE
289                  :error is   :client end did not return a certificate
290 Error because no certificate returned.
291
292 s_server -Verify 4 -CApath .
293 s_client -cert client.PEM
294         CONNECTED
295         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
296         verify return:1
297         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
298         verify return:1
299         CIPHER is CBC-DES-MD5
300 Full authentication of the client.
301
302 So in summary to do full authentication of both ends
303 s_server -Verify 9 -CApath .
304 s_client -cert client.PEM -CApath . -verify 9
305 From the server side
306         CONNECTED
307         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
308         verify return:1
309         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
310         verify return:1
311         CIPHER is CBC-DES-MD5
312 From the client side
313         CONNECTED
314         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
315         verify return:1
316         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
317         verify return:1
318         CIPHER is CBC-DES-MD5
319
320 For general probing of the 'internet https' servers for the
321 distribution area, run
322 s_client -host www.netscape.com -port 443 -verify 4 -CApath ../rsa/hash
323 Then enter
324 GET /
325 and you should be talking to the https server on that host.
326
327 www.rsa.com was refusing to respond to connections on 443 when I was
328 testing.
329
330 have fun :-).
331
332 eric
333
334 ==== a_verify.doc ========================================================
335
336 From eay@mincom.com Fri Oct  4 18:29:06 1996
337 Received: by orb.mincom.oz.au id AA29080
338   (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000
339 Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST)
340 From: Eric Young <eay@mincom.oz.au>
341 X-Sender: eay@orb
342 To: wplatzer <wplatzer@iaik.tu-graz.ac.at>
343 Cc: Eric Young <eay@mincom.oz.au>, SSL Mailing List <ssl-users@mincom.com>
344 Subject: Re: Netscape's Public Key
345 In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at>
346 Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb>
347 Mime-Version: 1.0
348 Content-Type: TEXT/PLAIN; charset=US-ASCII
349 Status: RO
350 X-Status: 
351
352 On Thu, 3 Oct 1996, wplatzer wrote:
353 > I get Public Key from Netscape (Gold 3.0b4), but cannot do anything
354 > with it... It looks like (asn1parse):
355
356 > 0:d=0 hl=3 l=180 cons: SEQUENCE
357 > 3:d=1 hl=2 l= 96 cons: SEQUENCE
358 > 5:d=2 hl=2 l= 92 cons: SEQUENCE
359 > 7:d=3 hl=2 l= 13 cons: SEQUENCE
360 > 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption
361 > 20:d=4 hl=2 l= 0 prim: NULL
362 > 22:d=3 hl=2 l= 75 prim: BIT STRING
363 > 99:d=2 hl=2 l= 0 prim: IA5STRING :
364 > 101:d=1 hl=2 l= 13 cons: SEQUENCE
365 > 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption
366 > 114:d=2 hl=2 l= 0 prim: NULL
367 > 116:d=1 hl=2 l= 65 prim: BIT STRING
368
369 > The first BIT STRING is the public key and the second BIT STRING is 
370 > the signature.
371 > But a public key consists of the public exponent and the modulus. Are 
372 > both numbers in the first BIT STRING?
373 > Is there a document simply describing this coding stuff (checking 
374 > signature, get the public key, etc.)?
375
376 Minimal in SSLeay.  If you want to see what the modulus and exponent are,
377 try asn1parse -offset 25 -length 75 <key.pem
378 asn1parse will currently stuff up on the 'length 75' part (fixed in next 
379 release) but it will print the stuff.  If you are after more 
380 documentation on ASN.1, have a look at www.rsa.com and get their PKCS 
381 documents, most of my initial work on SSLeay was done using them.
382
383 As for SSLeay,
384 util/crypto.num and util/ssl.num are lists of all exported functions in 
385 the library (but not macros :-(.
386
387 The ones for extracting public keys from certificates and certificate 
388 requests are EVP_PKEY *      X509_REQ_extract_key(X509_REQ *req);
389 EVP_PKEY *      X509_extract_key(X509 *x509);
390
391 To verify a signature on a signed ASN.1 object
392 int X509_verify(X509 *a,EVP_PKEY *key);
393 int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key);
394 int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key);
395 int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key);
396
397 I should mention that EVP_PKEY can be used to hold a public or a private key,
398 since for  things like RSA and DSS, a public key is just a subset of what 
399 is stored for the private key.
400
401 To sign any of the above structures
402
403 int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md);
404 int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md);
405 int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md);
406 int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md);
407
408 where md is the message digest to sign with.
409
410 There are all defined in x509.h and all the _sign and _verify functions are
411 actually macros to the ASN1_sign() and ASN1_verify() functions.
412 These functions will put the correct algorithm identifiers in the correct 
413 places in the structures.
414
415 eric
416 --
417 Eric Young                  | BOOL is tri-state according to Bill Gates.
418 AARNet: eay@mincom.oz.au    | RTFM Win32 GetMessage().
419
420 ==== x509 =======================================================
421
422 X509_verify()
423 X509_sign()
424
425 X509_get_version()
426 X509_get_serialNumber()
427 X509_get_issuer()
428 X509_get_subject()
429 X509_get_notBefore()
430 X509_get_notAfter()
431 X509_get_pubkey()
432
433 X509_set_version()
434 X509_set_serialNumber()
435 X509_set_issuer()
436 X509_set_subject()
437 X509_set_notBefore()
438 X509_set_notAfter()
439 X509_set_pubkey()
440
441 X509_get_extensions()
442 X509_set_extensions()
443
444 X509_EXTENSIONS_clear()
445 X509_EXTENSIONS_retrieve()
446 X509_EXTENSIONS_add()
447 X509_EXTENSIONS_delete()
448
449 ==== x509 attribute ================================================
450
451 PKCS7
452         STACK of X509_ATTRIBUTES
453                 ASN1_OBJECT
454                 STACK of ASN1_TYPE
455
456 So it is
457
458 p7.xa[].obj
459 p7.xa[].data[]
460
461 get_obj_by_nid(STACK , nid)
462 get_num_by_nid(STACK , nid)
463 get_data_by_nid(STACK , nid, index)
464
465 X509_ATTRIBUTE *X509_ATTRIBUTE_new(void );
466 void            X509_ATTRIBUTE_free(X509_ATTRIBUTE *a);
467
468 X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **ex,
469                         int nid, STACK *value);
470
471 X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **ex,
472                         int nid, STACK *value);
473
474 int             X509_ATTRIBUTE_set_object(X509_ATTRIBUTE *ex,ASN1_OBJECT *obj);
475 int             X509_ATTRIBUTE_add_data(X509_ATTRIBUTE *ex, int index,
476                         ASN1_TYPE *value);
477
478 ASN1_OBJECT *   X509_ATTRIBUTE_get_object(X509_ATTRIBUTE *ex);
479 int             X509_ATTRIBUTE_get_num(X509_ATTRIBUTE *ne);
480 ASN1_TYPE *     X509_ATTRIBUTE_get_data(X509_ATTRIBUTE *ne,int index);
481
482 ASN1_TYPE *     X509_ATTRIBUTE_get_data_by_NID(X509_ATTRIBUTE *ne,
483                         ASN1_OBJECT *obj);
484
485 X509_ATTRIBUTE *PKCS7_get_s_att_by_NID(PKCS7 *p7,int nid);
486 X509_ATTRIBUTE *PKCS7_get_u_att_by_NID(PKCS7 *p7,int nid);
487
488 ==== x509 v3 ========================================================
489
490 The 'new' system.
491
492 The X509_EXTENSION_METHOD includes extensions and attributes and/or names. 
493 Basically everthing that can be added to an X509 with an OID identifying it.
494
495 It operates via 2 methods per object id.
496 int a2i_XXX(X509 *x,char *str,int len);
497 int i2a_XXX(BIO *bp,X509 *x);
498
499 The a2i_XXX function will add the object with a value converted from the
500 string into the X509.  Len can be -1 in which case the length is calculated
501 via strlen(str).   Applications can always use direct knowledge to load and
502 unload the relevent objects themselves.
503
504 i2a_XXX will print to the passed BIO, a text representation of the
505 relevet object.  Use a memory BIO if you want it printed to a buffer :-).
506
507 X509_add_by_NID(X509 *x,int nid,char *str,int len);
508 X509_add_by_OBJ(X509 *x,ASN1_OBJECT *obj,char *str,int len);
509
510 X509_print_by_name(BIO *bp,X509 *x);
511 X509_print_by_NID(BIO *bp,X509 *x);
512 X509_print_by_OBJ(BIO *bp,X509 *x);
513
514 ==== verify ========================================================
515
516 X509_verify_cert_chain(
517         CERT_STORE *cert_store,
518         STACK /* X509 */ *certs,
519         int *verify_result,
520         int (*verify_error_callback)()
521         char *argument_to_callback, /* SSL */
522
523 app_verify_callback(
524         char *app_verify_arg, /* from SSL_CTX */
525         STACK /* X509 */ *certs,
526         int *verify_result,
527         int (*verify_error_callback)()
528         SSL *s,
529
530 int X509_verify_cert(
531         CERT_STORE *cert_store,
532         X509 *x509,
533         int *verify_result,
534         int (*verify_error_callback)(),
535         char *arg,
536
537 ==== apps.doc ========================================================
538
539 The applications
540
541 Ok, where to begin....
542 In the begining, when SSLeay was small (April 1995), there
543 were but few applications, they did happily cohabit in
544 the one bin directory.  Then over time, they did multiply and grow,
545 and they started to look like microsoft software; 500k to print 'hello world'.
546 A new approach was needed.  They were coalessed into one 'Monolithic'
547 application, ssleay.  This one program is composed of many programs that
548 can all be compiled independantly.
549
550 ssleay has 3 modes of operation.
551 1) If the ssleay binary has the name of one of its component programs, it
552 executes that program and then exits.  This can be achieved by using hard or
553 symbolic links, or failing that, just renaming the binary.
554 2) If the first argument to ssleay is the name of one of the component
555 programs, that program runs that program and then exits.
556 3) If there are no arguments, ssleay enters a 'command' mode.  Each line is
557 interpreted as a program name plus arguments.  After each 'program' is run,
558 ssleay returns to the comand line.
559
560 dgst    - message digests
561 enc     - encryption and base64 encoding
562
563 ans1parse - 'pulls' appart ASN.1 encoded objects like certificates.
564
565 dh      - Diffle-Hellman parameter manipulation.
566 rsa     - RSA manipulations.
567 crl     - Certificate revokion list manipulations
568 x509    - X509 cert fiddles, including signing.
569 pkcs7   - pkcs7 manipulation, only DER versions right now.
570
571 genrsa  - generate an RSA private key.
572 gendh   - Generate a set of Diffle-Hellman parameters.
573 req     - Generate a PKCS#10 object, a certificate request.
574
575 s_client - SSL client program
576 s_server - SSL server program
577 s_time   - A SSL protocol timing program
578 s_mult   - Another SSL server, but it multiplexes
579            connections.
580 s_filter - under development
581
582 errstr  - Convert SSLeay error numbers to strings.
583 ca      - Sign certificate requests, and generate
584           certificate revokion lists
585 crl2pkcs7 - put a crl and certifcates into a pkcs7 object.
586 speed   - Benchmark the ciphers.
587 verify  - Check certificates
588 hashdir - under development
589
590 [ there a now a few more options, play with the program to see what they
591   are ]
592
593 ==== asn1.doc ========================================================
594
595 The ASN.1 Routines.
596
597 ASN.1 is a specification for how to encode structured 'data' in binary form.
598 The approach I have take to the manipulation of structures and their encoding
599 into ASN.1 is as follows.
600
601 For each distinct structure there are 4 function of the following form
602 TYPE *TYPE_new(void);
603 void TYPE_free(TYPE *);
604 TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length);
605 long i2d_TYPE(TYPE *a,unsigned char **pp);      /* CHECK RETURN VALUE */
606
607 where TYPE is the type of the 'object'.  The TYPE that have these functions
608 can be in one of 2 forms, either the internal C malloc()ed data structure
609 or in the DER (a variant of ASN.1 encoding) binary encoding which is just
610 an array of unsigned bytes.  The 'i2d' functions converts from the internal
611 form to the DER form and the 'd2i' functions convert from the DER form to
612 the internal form.
613
614 The 'new' function returns a malloc()ed version of the structure with all
615 substructures either created or left as NULL pointers.  For 'optional'
616 fields, they are normally left as NULL to indicate no value.  For variable
617 size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the
618 STACK data type is used to hold the values.  Have a read of stack.doc
619 and have a look at the relevant header files to see what I mean.  If there
620 is an error while malloc()ing the structure, NULL is returned.
621
622 The 'free' function will free() all the sub components of a particular
623 structure.  If any of those sub components have been 'removed', replace
624 them with NULL pointers, the 'free' functions are tolerant of NULL fields.
625
626 The 'd2i' function copies a binary representation into a C structure.  It
627 operates as follows.  'a' is a pointer to a pointer to
628 the structure to populate, 'pp' is a pointer to a pointer to where the DER
629 byte string is located and 'length' is the length of the '*pp' data.
630 If there are no errors, a pointer to the populated structure is returned.
631 If there is an error, NULL is returned.  Errors can occur because of
632 malloc() failures but normally they will be due to syntax errors in the DER
633 encoded data being parsed. It is also an error if there was an
634 attempt to read more that 'length' bytes from '*p'.  If
635 everything works correctly, the value in '*p' is updated
636 to point at the location just beyond where the DER
637 structure was read from.  In this way, chained calls to 'd2i' type
638 functions can be made, with the pointer into the 'data' array being
639 'walked' along the input byte array.
640 Depending on the value passed for 'a', different things will be done.  If
641 'a' is NULL, a new structure will be malloc()ed and returned.  If '*a' is
642 NULL, a new structure will be malloc()ed and put into '*a' and returned.
643 If '*a' is not NULL, the structure in '*a' will be populated, or in the
644 case of an error, free()ed and then returned.
645 Having these semantics means that a structure
646 can call a 'd2i' function to populate a field and if the field is currently
647 NULL, the structure will be created.
648
649 The 'i2d' function type is used to copy a C structure to a byte array.
650 The parameter 'a' is the structure to convert and '*p' is where to put it.
651 As for the 'd2i' type structure, 'p' is updated to point after the last
652 byte written.  If p is NULL, no data is written.  The function also returns
653 the number of bytes written.  Where this becomes useful is that if the
654 function is called with a NULL 'p' value, the length is returned.  This can
655 then be used to malloc() an array of bytes and then the same function can
656 be recalled passing the malloced array to be written to. e.g.
657
658 int len;
659 unsigned char *bytes,*p;
660 len=i2d_X509(x,NULL);   /* get the size of the ASN1 encoding of 'x' */
661 if ((bytes=(unsigned char *)malloc(len)) == NULL)
662         goto err;
663 p=bytes;
664 i2d_X509(x,&p);
665
666 Please note that a new variable, 'p' was passed to i2d_X509.  After the
667 call to i2d_X509 p has been incremented by len bytes.
668
669 Now the reason for this functional organisation is that it allows nested
670 structures to be built up by calling these functions as required.  There
671 are various macros used to help write the general 'i2d', 'd2i', 'new' and
672 'free' functions.  They are discussed in another file and would only be
673 used by some-one wanting to add new structures to the library.  As you
674 might be able to guess, the process of writing ASN.1 files can be a bit CPU
675 expensive for complex structures.  I'm willing to live with this since the
676 simpler library code make my life easier and hopefully most programs using
677 these routines will have their execution profiles dominated by cipher or
678 message digest routines.
679 What follows is a list of 'TYPE' values and the corresponding ASN.1
680 structure and where it is used.
681
682 TYPE                    ASN.1
683 ASN1_INTEGER            INTEGER
684 ASN1_BIT_STRING         BIT STRING
685 ASN1_OCTET_STRING       OCTET STRING
686 ASN1_OBJECT             OBJECT IDENTIFIER
687 ASN1_PRINTABLESTRING    PrintableString
688 ASN1_T61STRING          T61String
689 ASN1_IA5STRING          IA5String
690 ASN1_UTCTIME            UTCTime
691 ASN1_TYPE               Any of the above mentioned types plus SEQUENCE and SET
692
693 Most of the above mentioned types are actualled stored in the
694 ASN1_BIT_STRING type and macros are used to differentiate between them.
695 The 3 types used are
696
697 typedef struct asn1_object_st
698         {
699         /* both null if a dynamic ASN1_OBJECT, one is
700          * defined if a 'static' ASN1_OBJECT */
701         char *sn,*ln;
702         int nid;
703         int length;
704         unsigned char *data;
705         } ASN1_OBJECT;
706 This is used to store ASN1 OBJECTS.  Read 'objects.doc' for details ono
707 routines to manipulate this structure.  'sn' and 'ln' are used to hold text
708 strings that represent the object (short name and long or lower case name).
709 These are used by the 'OBJ' library.  'nid' is a number used by the OBJ
710 library to uniquely identify objects.  The ASN1 routines will populate the
711 'length' and 'data' fields which will contain the bit string representing
712 the object.
713
714 typedef struct asn1_bit_string_st
715         {
716         int length;
717         int type;
718         unsigned char *data;
719         } ASN1_BIT_STRING;
720 This structure is used to hold all the other base ASN1 types except for
721 ASN1_UTCTIME (which is really just a 'char *').  Length is the number of
722 bytes held in data and type is the ASN1 type of the object (there is a list
723 in asn1.h).
724
725 typedef struct asn1_type_st
726         {
727         int type;
728         union   {
729                 char *ptr;
730                 ASN1_INTEGER *          integer;
731                 ASN1_BIT_STRING *       bit_string;
732                 ASN1_OCTET_STRING *     octet_string;
733                 ASN1_OBJECT *           object;
734                 ASN1_PRINTABLESTRING *  printablestring;
735                 ASN1_T61STRING *        t61string;
736                 ASN1_IA5STRING *        ia5string;
737                 ASN1_UTCTIME *          utctime;
738                 ASN1_BIT_STRING *       set;
739                 ASN1_BIT_STRING *       sequence;
740                 } value;
741         } ASN1_TYPE;
742 This structure is used in a few places when 'any' type of object can be
743 expected.
744
745 X509                    Certificate
746 X509_CINF               CertificateInfo
747 X509_ALGOR              AlgorithmIdentifier
748 X509_NAME               Name                    
749 X509_NAME_ENTRY         A single sub component of the name.
750 X509_VAL                Validity
751 X509_PUBKEY             SubjectPublicKeyInfo
752 The above mentioned types are declared in x509.h. They are all quite
753 straight forward except for the X509_NAME/X509_NAME_ENTRY pair.
754 A X509_NAME is a STACK (see stack.doc) of X509_NAME_ENTRY's.
755 typedef struct X509_name_entry_st
756         {
757         ASN1_OBJECT *object;
758         ASN1_BIT_STRING *value;
759         int set;
760         int size;       /* temp variable */
761         } X509_NAME_ENTRY;
762 The size is a temporary variable used by i2d_NAME and set is the set number
763 for the particular NAME_ENTRY.  A X509_NAME is encoded as a sequence of
764 sequence of sets.  Normally each set contains only a single item.
765 Sometimes it contains more.  Normally throughout this library there will be
766 only one item per set.  The set field contains the 'set' that this entry is
767 a member of.  So if you have just created a X509_NAME structure and
768 populated it with X509_NAME_ENTRYs, you should then traverse the X509_NAME
769 (which is just a STACK) and set the 'set/' field to incrementing numbers.
770 For more details on why this is done, read the ASN.1 spec for Distinguished
771 Names.
772
773 X509_REQ                CertificateRequest
774 X509_REQ_INFO           CertificateRequestInfo
775 These are used to hold certificate requests.
776
777 X509_CRL                CertificateRevocationList
778 These are used to hold a certificate revocation list
779
780 RSAPrivateKey           PrivateKeyInfo
781 RSAPublicKey            PublicKeyInfo
782 Both these 'function groups' operate on 'RSA' structures (see rsa.doc).
783 The difference is that the RSAPublicKey operations only manipulate the m
784 and e fields in the RSA structure.
785
786 DSAPrivateKey           DSS private key
787 DSAPublicKey            DSS public key
788 Both these 'function groups' operate on 'DSS' structures (see dsa.doc).
789 The difference is that the RSAPublicKey operations only manipulate the 
790 XXX fields in the DSA structure.
791
792 DHparams                DHParameter
793 This is used to hold the p and g value for The Diffie-Hellman operation.
794 The function deal with the 'DH' strucure (see dh.doc).
795
796 Now all of these function types can be used with several other functions to give
797 quite useful set of general manipulation routines.  Normally one would
798 not uses these functions directly but use them via macros. 
799
800 char *ASN1_dup(int (*i2d)(),char *(*d2i)(),char *x);
801 'x' is the input structure case to a 'char *', 'i2d' is the 'i2d_TYPE'
802 function for the type that 'x' is and d2i is the 'd2i_TYPE' function for the
803 type that 'x' is.  As is obvious from the parameters, this function
804 duplicates the strucutre by transforming it into the DER form and then
805 re-loading it into a new strucutre and returning the new strucutre.  This
806 is obviously a bit cpu intensive but when faced with a complex dynamic
807 structure this is the simplest programming approach.  There are macros for
808 duplicating the major data types but is simple to add extras.
809
810 char *ASN1_d2i_fp(char *(*new)(),char *(*d2i)(),FILE *fp,unsigned char **x);
811 'x' is a pointer to a pointer of the 'desired type'.  new and d2i are the
812 corresponding 'TYPE_new' and 'd2i_TYPE' functions for the type and 'fp' is
813 an open file pointer to read from.  This function reads from 'fp' as much
814 data as it can and then uses 'd2i' to parse the bytes to load and return
815 the parsed strucutre in 'x' (if it was non-NULL) and to actually return the
816 strucutre.  The behavior of 'x' is as per all the other d2i functions.
817
818 char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x);
819 The 'BIO' is the new IO type being used in SSLeay (see bio.doc).  This
820 function is the same as ASN1_d2i_fp() except for the BIO argument.
821 ASN1_d2i_fp() actually calls this function.
822
823 int ASN1_i2d_fp(int (*i2d)(),FILE *out,unsigned char *x);
824 'x' is converted to bytes by 'i2d' and then written to 'out'.  ASN1_i2d_fp
825 and ASN1_d2i_fp are not really symetric since ASN1_i2d_fp will read all
826 available data from the file pointer before parsing a single item while
827 ASN1_i2d_fp can be used to write a sequence of data objects.  To read a
828 series of objects from a file I would sugest loading the file into a buffer
829 and calling the relevent 'd2i' functions.
830
831 char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x);
832 This function is the same as ASN1_i2d_fp() except for the BIO argument.
833 ASN1_i2d_fp() actually calls this function.
834
835 char *  PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
836 This function will read the next PEM encoded (base64) object of the same
837 type as 'x' (loaded by the d2i function).  'name' is the name that is in
838 the '-----BEGIN name-----' that designates the start of that object type.
839 If the data is encrypted, 'cb' will be called to prompt for a password.  If
840 it is NULL a default function will be used to prompt from the password.
841 'x' is delt with as per the standard 'd2i' function interface.  This
842 function can be used to read a series of objects from a file.  While any
843 data type can be encrypted (see PEM_ASN1_write) only RSA private keys tend
844 to be encrypted.
845
846 char *  PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *fp,
847         char **x,int (*cb)());
848 Same as PEM_ASN1_read() except using a BIO.  This is called by
849 PEM_ASN1_read().
850
851 int     PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,EVP_CIPHER *enc,
852                 unsigned char *kstr,int klen,int (*callback)());
853
854 int     PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *fp,
855                 char *x,EVP_CIPHER *enc,unsigned char *kstr,int klen,
856                 int (*callback)());
857
858 int ASN1_sign(int (*i2d)(), X509_ALGOR *algor1, X509_ALGOR *algor2,
859         ASN1_BIT_STRING *signature, char *data, RSA *rsa, EVP_MD *type);
860 int ASN1_verify(int (*i2d)(), X509_ALGOR *algor1,
861         ASN1_BIT_STRING *signature,char *data, RSA *rsa);
862
863 int ASN1_BIT_STRING_cmp(ASN1_BIT_STRING *a, ASN1_BIT_STRING *b);
864 ASN1_BIT_STRING *ASN1_BIT_STRING_type_new(int type );
865
866 int ASN1_UTCTIME_check(ASN1_UTCTIME *a);
867 void ASN1_UTCTIME_print(BIO *fp,ASN1_UTCTIME *a);
868 ASN1_UTCTIME *ASN1_UTCTIME_dup(ASN1_UTCTIME *a);
869
870 ASN1_BIT_STRING *d2i_asn1_print_type(ASN1_BIT_STRING **a,unsigned char **pp,
871                 long length,int type);
872
873 int             i2d_ASN1_SET(STACK *a, unsigned char **pp,
874                         int (*func)(), int ex_tag, int ex_class);
875 STACK *         d2i_ASN1_SET(STACK **a, unsigned char **pp, long length,
876                         char *(*func)(), int ex_tag, int ex_class);
877
878 int i2a_ASN1_OBJECT(BIO *bp,ASN1_OBJECT *object);
879 int i2a_ASN1_INTEGER(BIO *bp, ASN1_INTEGER *a);
880 int a2i_ASN1_INTEGER(BIO *bp,ASN1_INTEGER *bs,char *buf,int size);
881
882 int ASN1_INTEGER_set(ASN1_INTEGER *a, long v);
883 long ASN1_INTEGER_get(ASN1_INTEGER *a);
884 ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai);
885 BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn);
886
887 /* given a string, return the correct type.  Max is the maximum number
888  * of bytes to parse.  It stops parsing when 'max' bytes have been
889  * processed or a '\0' is hit */
890 int ASN1_PRINTABLE_type(unsigned char *s,int max);
891
892 void ASN1_parse(BIO *fp,unsigned char *pp,long len);
893
894 int i2d_ASN1_bytes(ASN1_BIT_STRING *a, unsigned char **pp, int tag, int class);
895 ASN1_BIT_STRING *d2i_ASN1_bytes(ASN1_OCTET_STRING **a, unsigned char **pp,
896         long length, int Ptag, int Pclass);
897
898 /* PARSING */
899 int asn1_Finish(ASN1_CTX *c);
900
901 /* SPECIALS */
902 int ASN1_get_object(unsigned char **pp, long *plength, int *ptag,
903         int *pclass, long omax);
904 int ASN1_check_infinite_end(unsigned char **p,long len);
905 void ASN1_put_object(unsigned char **pp, int constructed, int length,
906         int tag, int class);
907 int ASN1_object_size(int constructed, int length, int tag);
908
909 X509 *  X509_get_cert(CERTIFICATE_CTX *ctx,X509_NAME * name,X509 *tmp_x509);
910 int     X509_add_cert(CERTIFICATE_CTX *ctx,X509 *);
911
912 char *  X509_cert_verify_error_string(int n);
913 int     X509_add_cert_file(CERTIFICATE_CTX *c,char *file, int type);
914 char *  X509_gmtime (char *s, long adj);
915 int     X509_add_cert_dir (CERTIFICATE_CTX *c,char *dir, int type);
916 int     X509_load_verify_locations (CERTIFICATE_CTX *ctx,
917                 char *file_env, char *dir_env);
918 int     X509_set_default_verify_paths(CERTIFICATE_CTX *cts);
919 X509 *  X509_new_D2i_X509(int len, unsigned char *p);
920 char *  X509_get_default_cert_area(void );
921 char *  X509_get_default_cert_dir(void );
922 char *  X509_get_default_cert_file(void );
923 char *  X509_get_default_cert_dir_env(void );
924 char *  X509_get_default_cert_file_env(void );
925 char *  X509_get_default_private_dir(void );
926 X509_REQ *X509_X509_TO_req(X509 *x, RSA *rsa);
927 int     X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)()); 
928
929 CERTIFICATE_CTX *CERTIFICATE_CTX_new();
930 void CERTIFICATE_CTX_free(CERTIFICATE_CTX *c);
931
932 void X509_NAME_print(BIO *fp, X509_NAME *name, int obase);
933 int             X509_print_fp(FILE *fp,X509 *x);
934 int             X509_print(BIO *fp,X509 *x);
935
936 X509_INFO *     X509_INFO_new(void);
937 void            X509_INFO_free(X509_INFO *a);
938
939 char *          X509_NAME_oneline(X509_NAME *a);
940
941 #define X509_verify(x,rsa)
942 #define X509_REQ_verify(x,rsa)
943 #define X509_CRL_verify(x,rsa)
944
945 #define X509_sign(x,rsa,md)
946 #define X509_REQ_sign(x,rsa,md)
947 #define X509_CRL_sign(x,rsa,md)
948
949 #define X509_dup(x509)
950 #define d2i_X509_fp(fp,x509)
951 #define i2d_X509_fp(fp,x509)
952 #define d2i_X509_bio(bp,x509)
953 #define i2d_X509_bio(bp,x509)
954
955 #define X509_CRL_dup(crl)
956 #define d2i_X509_CRL_fp(fp,crl)
957 #define i2d_X509_CRL_fp(fp,crl)
958 #define d2i_X509_CRL_bio(bp,crl)
959 #define i2d_X509_CRL_bio(bp,crl)
960
961 #define X509_REQ_dup(req)
962 #define d2i_X509_REQ_fp(fp,req)
963 #define i2d_X509_REQ_fp(fp,req)
964 #define d2i_X509_REQ_bio(bp,req)
965 #define i2d_X509_REQ_bio(bp,req)
966
967 #define RSAPrivateKey_dup(rsa)
968 #define d2i_RSAPrivateKey_fp(fp,rsa)
969 #define i2d_RSAPrivateKey_fp(fp,rsa)
970 #define d2i_RSAPrivateKey_bio(bp,rsa)
971 #define i2d_RSAPrivateKey_bio(bp,rsa)
972
973 #define X509_NAME_dup(xn)
974 #define X509_NAME_ENTRY_dup(ne)
975
976 void X509_REQ_print_fp(FILE *fp,X509_REQ *req);
977 void X509_REQ_print(BIO *fp,X509_REQ *req);
978
979 RSA *X509_REQ_extract_key(X509_REQ *req);
980 RSA *X509_extract_key(X509 *x509);
981
982 int             X509_issuer_and_serial_cmp(X509 *a, X509 *b);
983 unsigned long   X509_issuer_and_serial_hash(X509 *a);
984
985 X509_NAME *     X509_get_issuer_name(X509 *a);
986 int             X509_issuer_name_cmp(X509 *a, X509 *b);
987 unsigned long   X509_issuer_name_hash(X509 *a);
988
989 X509_NAME *     X509_get_subject_name(X509 *a);
990 int             X509_subject_name_cmp(X509 *a,X509 *b);
991 unsigned long   X509_subject_name_hash(X509 *x);
992
993 int             X509_NAME_cmp (X509_NAME *a, X509_NAME *b);
994 unsigned long   X509_NAME_hash(X509_NAME *x);
995
996
997 ==== bio.doc ========================================================
998
999 BIO Routines
1000
1001 This documentation is rather sparse, you are probably best 
1002 off looking at the code for specific details.
1003
1004 The BIO library is a IO abstraction that was originally 
1005 inspired by the need to have callbacks to perform IO to FILE 
1006 pointers when using Windows 3.1 DLLs.  There are two types 
1007 of BIO; a source/sink type and a filter type.
1008 The source/sink methods are as follows:
1009 -       BIO_s_mem()  memory buffer - a read/write byte array that
1010         grows until memory runs out :-).
1011 -       BIO_s_file()  FILE pointer - A wrapper around the normal 
1012         'FILE *' commands, good for use with stdin/stdout.
1013 -       BIO_s_fd()  File descriptor - A wrapper around file 
1014         descriptors, often used with pipes.
1015 -       BIO_s_socket()  Socket - Used around sockets.  It is 
1016         mostly in the Microsoft world that sockets are different 
1017         from file descriptors and there are all those ugly winsock 
1018         commands.
1019 -       BIO_s_null()  Null - read nothing and write nothing.; a 
1020         useful endpoint for filter type BIO's specifically things 
1021         like the message digest BIO.
1022
1023 The filter types are
1024 -       BIO_f_buffer()  IO buffering - does output buffering into 
1025         larger chunks and performs input buffering to allow gets() 
1026         type functions.
1027 -       BIO_f_md()  Message digest - a transparent filter that can 
1028         be asked to return a message digest for the data that has 
1029         passed through it.
1030 -       BIO_f_cipher()  Encrypt or decrypt all data passing 
1031         through the filter.
1032 -       BIO_f_base64()  Base64 decode on read and encode on write.
1033 -       BIO_f_ssl()  A filter that performs SSL encryption on the 
1034         data sent through it.
1035
1036 Base BIO functions.
1037 The BIO library has a set of base functions that are 
1038 implemented for each particular type.  Filter BIOs will 
1039 normally call the equivalent function on the source/sink BIO 
1040 that they are layered on top of after they have performed 
1041 some modification to the data stream.  Multiple filter BIOs 
1042 can be 'push' into a stack of modifers, so to read from a 
1043 file, unbase64 it, then decrypt it, a BIO_f_cipher, 
1044 BIO_f_base64 and a BIO_s_file would probably be used.  If a 
1045 sha-1 and md5 message digest needed to be generated, a stack 
1046 two BIO_f_md() BIOs and a BIO_s_null() BIO could be used.
1047 The base functions are
1048 -       BIO *BIO_new(BIO_METHOD *type); Create  a new BIO of  type 'type'.
1049 -       int BIO_free(BIO *a); Free a BIO structure.  Depending on 
1050         the configuration, this will free the underlying data 
1051         object for a source/sink BIO.
1052 -       int BIO_read(BIO *b, char *data, int len); Read upto 'len' 
1053         bytes into 'data'. 
1054 -       int BIO_gets(BIO *bp,char *buf, int size); Depending on 
1055         the BIO, this can either be a 'get special' or a get one 
1056         line of data, as per fgets();
1057 -       int BIO_write(BIO *b, char *data, int len); Write 'len' 
1058         bytes from 'data' to the 'b' BIO.
1059 -       int BIO_puts(BIO *bp,char *buf); Either a 'put special' or 
1060         a write null terminated string as per fputs().
1061 -       long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg);  A 
1062         control function which is used to manipulate the BIO 
1063         structure and modify it's state and or report on it.  This 
1064         function is just about never used directly, rather it 
1065         should be used in conjunction with BIO_METHOD specific 
1066         macros.
1067 -       BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the
1068         top of the 'old' BIO list.  new_top should be a filter BIO.
1069         All writes will go through 'new_top' first and last on read.
1070         'old' is returned.
1071 -       BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if
1072         there are no more.
1073
1074 If a particular low level BIO method is not supported 
1075 (normally BIO_gets()), -2 will be returned if that method is 
1076 called.  Otherwise the IO methods (read, write, gets, puts) 
1077 will return the number of bytes read or written, and 0 or -1 
1078 for error (or end of input).  For the -1 case, 
1079 BIO_should_retry(bio) can be called to determine if it was a 
1080 genuine error or a temporary problem.  -2 will also be 
1081 returned if the BIO has not been initalised yet, in all 
1082 cases, the correct error codes are set (accessible via the 
1083 ERR library).
1084
1085
1086 The following functions are convenience functions:
1087 -       int BIO_printf(BIO *bio, char * format, ..);  printf but 
1088         to a BIO handle.
1089 -       long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a 
1090         convenience function to allow a different argument types 
1091         to be passed to BIO_ctrl().
1092 -       int BIO_dump(BIO *b,char *bytes,int len); output 'len' 
1093         bytes from 'bytes' in a hex dump debug format.
1094 -       long BIO_debug_callback(BIO *bio, int cmd, char *argp, int 
1095         argi, long argl, long ret) - a default debug BIO callback, 
1096         this is mentioned below.  To use this one normally has to 
1097         use the BIO_set_callback_arg() function to assign an 
1098         output BIO for the callback to use.
1099 -       BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack'
1100         of BIOs, this function scan the list and returns the first
1101         that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX.
1102 -       void BIO_free_all(BIO *bio); Free the bio and all other BIOs
1103         in the list.  It walks the bio->next_bio list.
1104
1105
1106
1107 Extra commands are normally implemented as macros calling BIO_ctrl().
1108 -       BIO_number_read(BIO *bio) - the number of bytes processed 
1109         by BIO_read(bio,.).
1110 -       BIO_number_written(BIO *bio) - the number of bytes written 
1111         by BIO_write(bio,.).
1112 -       BIO_reset(BIO *bio) - 'reset' the BIO.
1113 -       BIO_eof(BIO *bio) - non zero if we are at the current end 
1114         of input.
1115 -       BIO_set_close(BIO *bio, int close_flag) - set the close flag.
1116 -       BIO_get_close(BIO *bio) - return the close flag.
1117         BIO_pending(BIO *bio) - return the number of bytes waiting 
1118         to be read (normally buffered internally).
1119 -       BIO_flush(BIO *bio) - output any data waiting to be output.
1120 -       BIO_should_retry(BIO *io) - after a BIO_read/BIO_write 
1121         operation returns 0 or -1, a call to this function will 
1122         return non zero if you should retry the call later (this 
1123         is for non-blocking IO).
1124 -       BIO_should_read(BIO *io) - we should retry when data can 
1125         be read.
1126 -       BIO_should_write(BIO *io) - we should retry when data can 
1127         be written.
1128 -       BIO_method_name(BIO *io) - return a string for the method name.
1129 -       BIO_method_type(BIO *io) - return the unique ID of the BIO method.
1130 -       BIO_set_callback(BIO *io,  long (*callback)(BIO *io, int 
1131         cmd, char *argp, int argi, long argl, long ret); - sets 
1132         the debug callback.
1133 -       BIO_get_callback(BIO *io) - return the assigned function 
1134         as mentioned above.
1135 -       BIO_set_callback_arg(BIO *io, char *arg)  - assign some 
1136         data against the BIO.  This is normally used by the debug 
1137         callback but could in reality be used for anything.  To 
1138         get an idea of how all this works, have a look at the code 
1139         in the default debug callback mentioned above.  The 
1140         callback can modify the return values.
1141
1142 Details of the BIO_METHOD structure.
1143 typedef struct bio_method_st
1144         {
1145         int type;
1146         char *name;
1147         int (*bwrite)();
1148         int (*bread)();
1149         int (*bputs)();
1150         int (*bgets)();
1151         long (*ctrl)();
1152         int (*create)();
1153         int (*destroy)();
1154         } BIO_METHOD;
1155
1156 The 'type' is the numeric type of the BIO, these are listed in buffer.h;
1157 'Name' is a textual representation of the BIO 'type'.
1158 The 7 function pointers point to the respective function 
1159 methods, some of which can be NULL if not implemented.
1160 The BIO structure
1161 typedef struct bio_st
1162         {
1163         BIO_METHOD *method;
1164         long (*callback)(BIO * bio, int mode, char *argp, int 
1165                 argi, long argl, long ret);
1166         char *cb_arg; /* first argument for the callback */
1167         int init;
1168         int shutdown;
1169         int flags;      /* extra storage */
1170         int num;
1171         char *ptr;
1172         struct bio_st *next_bio; /* used by filter BIOs */
1173         int references;
1174         unsigned long num_read;
1175         unsigned long num_write;
1176         } BIO;
1177
1178 -       'Method' is the BIO method.
1179 -       'callback', when configured, is called before and after 
1180         each BIO method is called for that particular BIO.  This 
1181         is intended primarily for debugging and of informational feedback.
1182 -       'init' is 0 when the BIO can be used for operation.  
1183         Often, after a BIO is created, a number of operations may 
1184         need to be performed before it is available for use.  An 
1185         example is for BIO_s_sock().  A socket needs to be 
1186         assigned to the BIO before it can be used.
1187 -       'shutdown', this flag indicates if the underlying 
1188         communication primitive being used should be closed/freed 
1189         when the BIO is closed.
1190 -       'flags' is used to hold extra state.  It is primarily used 
1191         to hold information about why a non-blocking operation 
1192         failed and to record startup protocol information for the 
1193         SSL BIO.
1194 -       'num' and 'ptr' are used to hold instance specific state 
1195         like file descriptors or local data structures.
1196 -       'next_bio' is used by filter BIOs to hold the pointer of the
1197         next BIO in the chain. written data is sent to this BIO and
1198         data read is taken from it.
1199 -       'references' is used to indicate the number of pointers to 
1200         this structure.  This needs to be '1' before a call to 
1201         BIO_free() is made if the BIO_free() function is to 
1202         actually free() the structure, otherwise the reference 
1203         count is just decreased.  The actual BIO subsystem does 
1204         not really use this functionality but it is useful when 
1205         used in more advanced applicaion.
1206 -       num_read and num_write are the total number of bytes 
1207         read/written via the 'read()' and 'write()' methods.
1208
1209 BIO_ctrl operations.
1210 The following is the list of standard commands passed as the 
1211 second parameter to BIO_ctrl() and should be supported by 
1212 all BIO as best as possible.  Some are optional, some are 
1213 manditory, in any case, where is makes sense, a filter BIO 
1214 should pass such requests to underlying BIO's.
1215 -       BIO_CTRL_RESET  - Reset the BIO back to an initial state.
1216 -       BIO_CTRL_EOF    - return 0 if we are not at the end of input, 
1217         non 0 if we are.
1218 -       BIO_CTRL_INFO   - BIO specific special command, normal
1219         information return.
1220 -       BIO_CTRL_SET    - set IO specific parameter.
1221 -       BIO_CTRL_GET    - get IO specific parameter.
1222 -       BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one 
1223         of BIO_CLOSE or BIO_NOCLOSE.
1224 -       BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag.
1225 -       BIO_CTRL_PENDING - Return the number of bytes available 
1226         for instant reading
1227 -       BIO_CTRL_FLUSH  - Output pending data, return number of bytes output.
1228 -       BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned) 
1229         should we 'retry' when IO is possible on the underlying IO object.
1230 -       BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on.
1231
1232 The following command is a special BIO_s_file() specific option.
1233 -       BIO_CTRL_SET_FILENAME - specify a file to open for IO.
1234
1235 The BIO_CTRL_RETRY_TYPE needs a little more explanation.  
1236 When performing non-blocking IO, or say reading on a memory 
1237 BIO, when no data is present (or cannot be written), 
1238 BIO_read() and/or BIO_write() will return -1.  
1239 BIO_should_retry(bio) will return true if this is due to an 
1240 IO condition rather than an actual error.  In the case of 
1241 BIO_s_mem(), a read when there is no data will return -1 and 
1242 a should retry when there is more 'read' data.
1243 The retry type is deduced from 2 macros
1244 BIO_should_read(bio) and BIO_should_write(bio).
1245 Now while it may appear obvious that a BIO_read() failure 
1246 should indicate that a retry should be performed when more 
1247 read data is available, this is often not true when using 
1248 things like an SSL BIO.  During the SSL protocol startup 
1249 multiple reads and writes are performed, triggered by any 
1250 SSL_read or SSL_write.
1251 So to write code that will transparently handle either a 
1252 socket or SSL BIO,
1253         i=BIO_read(bio,..)
1254         if (I == -1)
1255                 {
1256                 if (BIO_should_retry(bio))
1257                         {
1258                         if (BIO_should_read(bio))
1259                                 {
1260                                 /* call us again when BIO can be read */
1261                                 }
1262                         if (BIO_should_write(bio))
1263                                 {
1264                                 /* call us again when BIO can be written */
1265                                 }
1266                         }
1267                 }
1268
1269 At this point in time only read and write conditions can be 
1270 used but in the future I can see the situation for other 
1271 conditions, specifically with SSL there could be a condition 
1272 of a X509 certificate lookup taking place and so the non-
1273 blocking BIO_read would require a retry when the certificate 
1274 lookup subsystem has finished it's lookup.  This is all 
1275 makes more sense and is easy to use in a event loop type 
1276 setup.
1277 When using the SSL BIO, either SSL_read() or SSL_write()s 
1278 can be called during the protocol startup and things will 
1279 still work correctly.
1280 The nice aspect of the use of the BIO_should_retry() macro 
1281 is that all the errno codes that indicate a non-fatal error 
1282 are encapsulated in one place.  The Windows specific error 
1283 codes and WSAGetLastError() calls are also hidden from the 
1284 application.
1285
1286 Notes on each BIO method.
1287 Normally buffer.h is just required but depending on the 
1288 BIO_METHOD, ssl.h or evp.h will also be required.
1289
1290 BIO_METHOD *BIO_s_mem(void);
1291 -       BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) - 
1292         set the underlying BUF_MEM structure for the BIO to use.
1293 -       BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL, 
1294         set it to point to the memory array and return the number 
1295         of bytes available.
1296 A read/write BIO.  Any data written is appended to the 
1297 memory array and any read is read from the front.  This BIO 
1298 can be used for read/write at the same time. BIO_gets() is 
1299 supported in the fgets() sense.
1300 BIO_CTRL_INFO can be used to retrieve pointers to the memory 
1301 buffer and it's length.
1302
1303 BIO_METHOD *BIO_s_file(void);
1304 -       BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use.
1305 -       BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use.
1306 -       BIO_read_filename(BIO *bio, char *name) - read from file.
1307 -       BIO_write_filename(BIO *bio, char *name) - write to file.
1308 -       BIO_append_filename(BIO *bio, char *name) - append to file.
1309 This BIO sits over the normal system fread()/fgets() type 
1310 functions. Gets() is supported.  This BIO in theory could be 
1311 used for read and write but it is best to think of each BIO 
1312 of this type as either a read or a write BIO, not both.
1313
1314 BIO_METHOD *BIO_s_socket(void);
1315 BIO_METHOD *BIO_s_fd(void);
1316 -       BIO_sock_should_retry(int i) - the underlying function 
1317         used to determine if a call should be retried; the 
1318         argument is the '0' or '-1' returned by the previous BIO 
1319         operation.
1320 -       BIO_fd_should_retry(int i) - same as the 
1321 -       BIO_sock_should_retry() except that it is different internally.
1322 -       BIO_set_fd(BIO *bio, int fd, int close_flag) - set the 
1323         file descriptor to use
1324 -       BIO_get_fd(BIO *bio, int *fd) - get the file descriptor.
1325 These two methods are very similar.  Gets() is not 
1326 supported, if you want this functionality, put a 
1327 BIO_f_buffer() onto it.  This BIO is bi-directional if the 
1328 underlying file descriptor is.  This is normally the case 
1329 for sockets but not the case for stdio descriptors.
1330
1331 BIO_METHOD *BIO_s_null(void);
1332 Read and write as much data as you like, it all disappears 
1333 into this BIO.
1334
1335 BIO_METHOD *BIO_f_buffer(void);
1336 -       BIO_get_buffer_num_lines(BIO *bio) - return the number of 
1337         complete lines in the buffer.
1338 -       BIO_set_buffer_size(BIO *bio, long size) - set the size of 
1339         the buffers.
1340 This type performs input and output buffering.  It performs 
1341 both at the same time.  The size of the buffer can be set 
1342 via the set buffer size option.  Data buffered for output is 
1343 only written when the buffer fills.
1344
1345 BIO_METHOD *BIO_f_ssl(void);
1346 -       BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL 
1347         structure to use.
1348 -       BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure 
1349         in use.
1350 The SSL bio is a little different from normal BIOs because 
1351 the underlying SSL structure is a little different.  A SSL 
1352 structure performs IO via a read and write BIO.  These can 
1353 be different and are normally set via the
1354 SSL_set_rbio()/SSL_set_wbio() calls.  The SSL_set_fd() calls 
1355 are just wrappers that create socket BIOs and then call 
1356 SSL_set_bio() where the read and write BIOs are the same.  
1357 The BIO_push() operation makes the SSLs IO BIOs the same, so 
1358 make sure the BIO pushed is capable of two directional 
1359 traffic.  If it is not, you will have to install the BIOs 
1360 via the more conventional SSL_set_bio() call.  BIO_pop() will retrieve
1361 the 'SSL read' BIO.
1362
1363 BIO_METHOD *BIO_f_md(void);
1364 -       BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest 
1365         to use.
1366 -       BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest 
1367         method in use in mdp, return 0 if not set yet.
1368 -       BIO_reset() reinitializes the digest (EVP_DigestInit()) 
1369         and passes the reset to the underlying BIOs.
1370 All data read or written via BIO_read() or BIO_write() to 
1371 this BIO will be added to the calculated digest.  This 
1372 implies that this BIO is only one directional.  If read and 
1373 write operations are performed, two separate BIO_f_md() BIOs 
1374 are reuqired to generate digests on both the input and the 
1375 output.  BIO_gets(BIO *bio, char *md, int size) will place the 
1376 generated digest into 'md' and return the number of bytes.  
1377 The EVP_MAX_MD_SIZE should probably be used to size the 'md' 
1378 array.  Reading the digest will also reset it.
1379
1380 BIO_METHOD *BIO_f_cipher(void);
1381 -       BIO_reset() reinitializes the cipher.
1382 -       BIO_flush() should be called when the last bytes have been 
1383         output to flush the final block of block ciphers.
1384 -       BIO_get_cipher_status(BIO *b), when called after the last 
1385         read from a cipher BIO, returns non-zero if the data 
1386         decrypted correctly, otherwise, 0.
1387 -       BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key, 
1388         unsigned char *iv, int encrypt)   This function is used to 
1389         setup a cipher BIO.  The length of key and iv are 
1390         specified by the choice of EVP_CIPHER.  Encrypt is 1 to 
1391         encrypt and 0 to decrypt.
1392
1393 BIO_METHOD *BIO_f_base64(void);
1394 -       BIO_flush() should be called when the last bytes have been output.
1395 This BIO base64 encodes when writing and base64 decodes when 
1396 reading.  It will scan the input until a suitable begin line 
1397 is found.  After reading data, BIO_reset() will reset the 
1398 BIO to start scanning again.  Do not mix reading and writing 
1399 on the same base64 BIO.  It is meant as a single stream BIO.
1400
1401 Directions      type
1402 both            BIO_s_mem()
1403 one/both        BIO_s_file()
1404 both            BIO_s_fd()
1405 both            BIO_s_socket() 
1406 both            BIO_s_null()
1407 both            BIO_f_buffer()
1408 one             BIO_f_md()  
1409 one             BIO_f_cipher()  
1410 one             BIO_f_base64()  
1411 both            BIO_f_ssl()
1412
1413 It is easy to mix one and two directional BIOs, all one has 
1414 to do is to keep two separate BIO pointers for reading and 
1415 writing and be careful about usage of underlying BIOs.  The 
1416 SSL bio by it's very nature has to be two directional but 
1417 the BIO_push() command will push the one BIO into the SSL 
1418 BIO for both reading and writing.
1419
1420 The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c.
1421
1422
1423 ==== blowfish.doc ========================================================
1424
1425 The Blowfish library.
1426
1427 Blowfish is a block cipher that operates on 64bit (8 byte) quantities.  It
1428 uses variable size key, but 128bit (16 byte) key would normally be considered
1429 good.  It can be used in all the modes that DES can be used.  This
1430 library implements the ecb, cbc, cfb64, ofb64 modes.
1431
1432 Blowfish is quite a bit faster that DES, and much faster than IDEA or
1433 RC2.  It is one of the faster block ciphers.
1434
1435 For all calls that have an 'input' and 'output' variables, they can be the
1436 same.
1437
1438 This library requires the inclusion of 'blowfish.h'.
1439
1440 All of the encryption functions take what is called an BF_KEY as an 
1441 argument.  An BF_KEY is an expanded form of the Blowfish key.
1442 For all modes of the Blowfish algorithm, the BF_KEY used for
1443 decryption is the same one that was used for encryption.
1444
1445 The define BF_ENCRYPT is passed to specify encryption for the functions
1446 that require an encryption/decryption flag. BF_DECRYPT is passed to
1447 specify decryption.
1448
1449 Please note that any of the encryption modes specified in my DES library
1450 could be used with Blowfish.  I have only implemented ecb, cbc, cfb64 and
1451 ofb64 for the following reasons.
1452 - ecb is the basic Blowfish encryption.
1453 - cbc is the normal 'chaining' form for block ciphers.
1454 - cfb64 can be used to encrypt single characters, therefore input and output
1455   do not need to be a multiple of 8.
1456 - ofb64 is similar to cfb64 but is more like a stream cipher, not as
1457   secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
1458 - If you want triple Blowfish, thats 384 bits of key and you must be totally
1459   obsessed with security.  Still, if you want it, it is simple enough to
1460   copy the function from the DES library and change the des_encrypt to
1461   BF_encrypt; an exercise left for the paranoid reader :-).
1462
1463 The functions are as follows:
1464
1465 void BF_set_key(
1466 BF_KEY *ks;
1467 int len;
1468 unsigned char *key;
1469         BF_set_key converts an 'len' byte key into a BF_KEY.
1470         A 'ks' is an expanded form of the 'key' which is used to
1471         perform actual encryption.  It can be regenerated from the Blowfish key
1472         so it only needs to be kept when encryption or decryption is about
1473         to occur.  Don't save or pass around BF_KEY's since they
1474         are CPU architecture dependent, 'key's are not.  Blowfish is an
1475         interesting cipher in that it can be used with a variable length
1476         key.  'len' is the length of 'key' to be used as the key.
1477         A 'len' of 16 is recomended by me, but blowfish can use upto
1478         72 bytes.  As a warning, blowfish has a very very slow set_key
1479         function, it actually runs BF_encrypt 521 times.
1480         
1481 void BF_encrypt(unsigned long *data, BF_KEY *key);
1482 void BF_decrypt(unsigned long *data, BF_KEY *key);
1483         These are the Blowfish encryption function that gets called by just
1484         about every other Blowfish routine in the library.  You should not
1485         use this function except to implement 'modes' of Blowfish.
1486         I say this because the
1487         functions that call this routine do the conversion from 'char *' to
1488         long, and this needs to be done to make sure 'non-aligned' memory
1489         access do not occur.
1490         Data is a pointer to 2 unsigned long's and key is the
1491         BF_KEY to use. 
1492
1493 void BF_ecb_encrypt(
1494 unsigned char *in,
1495 unsigned char *out,
1496 BF_KEY *key,
1497 int encrypt);
1498         This is the basic Electronic Code Book form of Blowfish (in DES this
1499         mode is called Electronic Code Book so I'm going to use the term
1500         for blowfish as well.
1501         Input is encrypted into output using the key represented by
1502         key.  Depending on the encrypt, encryption or
1503         decryption occurs.  Input is 8 bytes long and output is 8 bytes.
1504         
1505 void BF_cbc_encrypt(
1506 unsigned char *in,
1507 unsigned char *out,
1508 long length,
1509 BF_KEY *ks,
1510 unsigned char *ivec,
1511 int encrypt);
1512         This routine implements Blowfish in Cipher Block Chaining mode.
1513         Input, which should be a multiple of 8 bytes is encrypted
1514         (or decrypted) to output which will also be a multiple of 8 bytes.
1515         The number of bytes is in length (and from what I've said above,
1516         should be a multiple of 8).  If length is not a multiple of 8, bad 
1517         things will probably happen.  ivec is the initialisation vector.
1518         This function updates iv after each call so that it can be passed to
1519         the next call to BF_cbc_encrypt().
1520         
1521 void BF_cfb64_encrypt(
1522 unsigned char *in,
1523 unsigned char *out,
1524 long length,
1525 BF_KEY *schedule,
1526 unsigned char *ivec,
1527 int *num,
1528 int encrypt);
1529         This is one of the more useful functions in this Blowfish library, it
1530         implements CFB mode of Blowfish with 64bit feedback.
1531         This allows you to encrypt an arbitrary number of bytes,
1532         you do not require 8 byte padding.  Each call to this
1533         routine will encrypt the input bytes to output and then update ivec
1534         and num.  Num contains 'how far' we are though ivec.
1535         'Encrypt' is used to indicate encryption or decryption.
1536         CFB64 mode operates by using the cipher to generate a stream
1537         of bytes which is used to encrypt the plain text.
1538         The cipher text is then encrypted to generate the next 64 bits to
1539         be xored (incrementally) with the next 64 bits of plain
1540         text.  As can be seen from this, to encrypt or decrypt,
1541         the same 'cipher stream' needs to be generated but the way the next
1542         block of data is gathered for encryption is different for
1543         encryption and decryption.
1544         
1545 void BF_ofb64_encrypt(
1546 unsigned char *in,
1547 unsigned char *out,
1548 long length,
1549 BF_KEY *schedule,
1550 unsigned char *ivec,
1551 int *num);
1552         This functions implements OFB mode of Blowfish with 64bit feedback.
1553         This allows you to encrypt an arbitrary number of bytes,
1554         you do not require 8 byte padding.  Each call to this
1555         routine will encrypt the input bytes to output and then update ivec
1556         and num.  Num contains 'how far' we are though ivec.
1557         This is in effect a stream cipher, there is no encryption or
1558         decryption mode.
1559         
1560 For reading passwords, I suggest using des_read_pw_string() from my DES library.
1561 To generate a password from a text string, I suggest using MD5 (or MD2) to
1562 produce a 16 byte message digest that can then be passed directly to
1563 BF_set_key().
1564
1565 =====
1566 For more information about the specific Blowfish modes in this library
1567 (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
1568 documentation on my DES library.  What is said about DES is directly
1569 applicable for Blowfish.
1570
1571
1572 ==== bn.doc ========================================================
1573
1574 The Big Number library.
1575
1576 #include "bn.h" when using this library.
1577
1578 This big number library was written for use in implementing the RSA and DH
1579 public key encryption algorithms.  As such, features such as negative
1580 numbers have not been extensively tested but they should work as expected.
1581 This library uses dynamic memory allocation for storing its data structures
1582 and so there are no limit on the size of the numbers manipulated by these
1583 routines but there is always the requirement to check return codes from
1584 functions just in case a memory allocation error has occurred.
1585
1586 The basic object in this library is a BIGNUM.  It is used to hold a single
1587 large integer.  This type should be considered opaque and fields should not
1588 be modified or accessed directly.
1589 typedef struct bignum_st
1590         {
1591         int top;        /* Index of last used d. */
1592         BN_ULONG *d;    /* Pointer to an array of 'BITS2' bit chunks. */
1593         int max;        /* Size of the d array. */
1594         int neg;
1595         } BIGNUM;
1596 The big number is stored in a malloced array of BN_ULONG's.  A BN_ULONG can
1597 be either 16, 32 or 64 bits in size, depending on the 'number of  bits'
1598 specified in bn.h. 
1599 The 'd' field is this array.  'max' is the size of the 'd' array that has
1600 been allocated.  'top' is the 'last' entry being used, so for a value of 4,
1601 bn.d[0]=4 and bn.top=1.  'neg' is 1 if the number is negative.
1602 When a BIGNUM is '0', the 'd' field can be NULL and top == 0.
1603
1604 Various routines in this library require the use of 'temporary' BIGNUM
1605 variables during their execution.  Due to the use of dynamic memory
1606 allocation to create BIGNUMs being rather expensive when used in
1607 conjunction with repeated subroutine calls, the BN_CTX structure is
1608 used.  This structure contains BN_CTX BIGNUMs.  BN_CTX
1609 is the maximum number of temporary BIGNUMs any publicly exported 
1610 function will use.
1611
1612 #define BN_CTX  12
1613 typedef struct bignum_ctx
1614         {
1615         int tos;                        /* top of stack */
1616         BIGNUM *bn[BN_CTX];     /* The variables */
1617         } BN_CTX;
1618
1619 The functions that follow have been grouped according to function.  Most
1620 arithmetic functions return a result in the first argument, sometimes this
1621 first argument can also be an input parameter, sometimes it cannot.  These
1622 restrictions are documented.
1623
1624 extern BIGNUM *BN_value_one;
1625 There is one variable defined by this library, a BIGNUM which contains the
1626 number 1.  This variable is useful for use in comparisons and assignment.
1627
1628 Get Size functions.
1629
1630 int BN_num_bits(BIGNUM *a);
1631         This function returns the size of 'a' in bits.
1632         
1633 int BN_num_bytes(BIGNUM *a);
1634         This function (macro) returns the size of 'a' in bytes.
1635         For conversion of BIGNUMs to byte streams, this is the number of
1636         bytes the output string will occupy.  If the output byte
1637         format specifies that the 'top' bit indicates if the number is
1638         signed, so an extra '0' byte is required if the top bit on a
1639         positive number is being written, it is upto the application to
1640         make this adjustment.  Like I said at the start, I don't
1641         really support negative numbers :-).
1642
1643 Creation/Destruction routines.
1644
1645 BIGNUM *BN_new();
1646         Return a new BIGNUM object.  The number initially has a value of 0.  If
1647         there is an error, NULL is returned.
1648         
1649 void    BN_free(BIGNUM *a);
1650         Free()s a BIGNUM.
1651         
1652 void    BN_clear(BIGNUM *a);
1653         Sets 'a' to a value of 0 and also zeros all unused allocated
1654         memory.  This function is used to clear a variable of 'sensitive'
1655         data that was held in it.
1656         
1657 void    BN_clear_free(BIGNUM *a);
1658         This function zeros the memory used by 'a' and then free()'s it.
1659         This function should be used to BN_free() BIGNUMS that have held
1660         sensitive numeric values like RSA private key values.  Both this
1661         function and BN_clear tend to only be used by RSA and DH routines.
1662
1663 BN_CTX *BN_CTX_new(void);
1664         Returns a new BN_CTX.  NULL on error.
1665         
1666 void    BN_CTX_free(BN_CTX *c);
1667         Free a BN_CTX structure.  The BIGNUMs in 'c' are BN_clear_free()ed.
1668         
1669 BIGNUM *bn_expand(BIGNUM *b, int bits);
1670         This is an internal function that should not normally be used.  It
1671         ensures that 'b' has enough room for a 'bits' bit number.  It is
1672         mostly used by the various BIGNUM routines.  If there is an error,
1673         NULL is returned. if not, 'b' is returned.
1674         
1675 BIGNUM *BN_copy(BIGNUM *to, BIGNUM *from);
1676         The 'from' is copied into 'to'.  NULL is returned if there is an
1677         error, otherwise 'to' is returned.
1678
1679 BIGNUM *BN_dup(BIGNUM *a);
1680         A new BIGNUM is created and returned containing the value of 'a'.
1681         NULL is returned on error.
1682
1683 Comparison and Test Functions.
1684
1685 int BN_is_zero(BIGNUM *a)
1686         Return 1 if 'a' is zero, else 0.
1687
1688 int BN_is_one(a)
1689         Return 1 is 'a' is one, else 0.
1690
1691 int BN_is_word(a,w)
1692         Return 1 if 'a' == w, else 0.  'w' is a BN_ULONG.
1693
1694 int BN_cmp(BIGNUM *a, BIGNUM *b);
1695         Return -1 if 'a' is less than 'b', 0 if 'a' and 'b' are the same
1696         and 1 is 'a' is greater than 'b'.  This is a signed comparison.
1697         
1698 int BN_ucmp(BIGNUM *a, BIGNUM *b);
1699         This function is the same as BN_cmp except that the comparison
1700         ignores the sign of the numbers.
1701         
1702 Arithmetic Functions
1703 For all of these functions, 0 is returned if there is an error and 1 is
1704 returned for success.  The return value should always be checked.  eg.
1705 if (!BN_add(r,a,b)) goto err;
1706 Unless explicitly mentioned, the 'return' value can be one of the
1707 'parameters' to the function.
1708
1709 int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b);
1710         Add 'a' and 'b' and return the result in 'r'.  This is r=a+b.
1711         
1712 int BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b);
1713         Subtract 'a' from 'b' and put the result in 'r'. This is r=a-b.
1714         
1715 int BN_lshift(BIGNUM *r, BIGNUM *a, int n);
1716         Shift 'a' left by 'n' bits.  This is r=a*(2^n).
1717         
1718 int BN_lshift1(BIGNUM *r, BIGNUM *a);
1719         Shift 'a' left by 1 bit.  This form is more efficient than
1720         BN_lshift(r,a,1).  This is r=a*2.
1721         
1722 int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
1723         Shift 'a' right by 'n' bits.  This is r=int(a/(2^n)).
1724         
1725 int BN_rshift1(BIGNUM *r, BIGNUM *a);
1726         Shift 'a' right by 1 bit.  This form is more efficient than
1727         BN_rshift(r,a,1).  This is r=int(a/2).
1728         
1729 int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b);
1730         Multiply a by b and return the result in 'r'. 'r' must not be
1731         either 'a' or 'b'.  It has to be a different BIGNUM.
1732         This is r=a*b.
1733
1734 int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
1735         Multiply a by a and return the result in 'r'. 'r' must not be
1736         'a'.  This function is alot faster than BN_mul(r,a,a).  This is r=a*a.
1737
1738 int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
1739         Divide 'm' by 'd' and return the result in 'dv' and the remainder
1740         in 'rem'.  Either of 'dv' or 'rem' can be NULL in which case that
1741         value is not returned.  'ctx' needs to be passed as a source of
1742         temporary BIGNUM variables.
1743         This is dv=int(m/d), rem=m%d.
1744         
1745 int BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
1746         Find the remainder of 'm' divided by 'd' and return it in 'rem'.
1747         'ctx' holds the temporary BIGNUMs required by this function.
1748         This function is more efficient than BN_div(NULL,rem,m,d,ctx);
1749         This is rem=m%d.
1750
1751 int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BIGNUM *m,BN_CTX *ctx);
1752         Multiply 'a' by 'b' and return the remainder when divided by 'm'.
1753         'ctx' holds the temporary BIGNUMs required by this function.
1754         This is r=(a*b)%m.
1755
1756 int BN_mod_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx);
1757         Raise 'a' to the 'p' power and return the remainder when divided by
1758         'm'.  'ctx' holds the temporary BIGNUMs required by this function.
1759         This is r=(a^p)%m.
1760
1761 int BN_reciprocal(BIGNUM *r, BIGNUM *m, BN_CTX *ctx);
1762         Return the reciprocal of 'm'.  'ctx' holds the temporary variables
1763         required.  This function returns -1 on error, otherwise it returns
1764         the number of bits 'r' is shifted left to make 'r' into an integer.
1765         This number of bits shifted is required in BN_mod_mul_reciprocal().
1766         This is r=(1/m)<<(BN_num_bits(m)+1).
1767         
1768 int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y, BIGNUM *m, 
1769         BIGNUM *i, int nb, BN_CTX *ctx);
1770         This function is used to perform an efficient BN_mod_mul()
1771         operation.  If one is going to repeatedly perform BN_mod_mul() with
1772         the same modulus is worth calculating the reciprocal of the modulus
1773         and then using this function.  This operation uses the fact that
1774         a/b == a*r where r is the reciprocal of b.  On modern computers
1775         multiplication is very fast and big number division is very slow.
1776         'x' is multiplied by 'y' and then divided by 'm' and the remainder
1777         is returned.  'i' is the reciprocal of 'm' and 'nb' is the number
1778         of bits as returned from BN_reciprocal().  Normal usage is as follows.
1779         bn=BN_reciprocal(i,m);
1780         for (...)
1781                 { BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); }
1782         This is r=(x*y)%m.  Internally it is approximately
1783         r=(x*y)-m*(x*y/m) or r=(x*y)-m*((x*y*i) >> bn)
1784         This function is used in BN_mod_exp() and BN_is_prime().
1785
1786 Assignment Operations
1787
1788 int BN_one(BIGNUM *a)
1789         Set 'a' to hold the value one.
1790         This is a=1.
1791         
1792 int BN_zero(BIGNUM *a)
1793         Set 'a' to hold the value zero.
1794         This is a=0.
1795         
1796 int BN_set_word(BIGNUM *a, unsigned long w);
1797         Set 'a' to hold the value of 'w'.  'w' is an unsigned long.
1798         This is a=w.
1799
1800 unsigned long BN_get_word(BIGNUM *a);
1801         Returns 'a' in an unsigned long.  Not remarkably, often 'a' will
1802         be bigger than a word, in which case 0xffffffffL is returned.
1803
1804 Word Operations
1805 These functions are much more efficient that the normal bignum arithmetic
1806 operations.
1807
1808 BN_ULONG BN_mod_word(BIGNUM *a, unsigned long w);
1809         Return the remainder of 'a' divided by 'w'.
1810         This is return(a%w).
1811         
1812 int BN_add_word(BIGNUM *a, unsigned long w);
1813         Add 'w' to 'a'.  This function does not take the sign of 'a' into
1814         account.  This is a+=w;
1815         
1816 Bit operations.
1817
1818 int BN_is_bit_set(BIGNUM *a, int n);
1819         This function return 1 if bit 'n' is set in 'a' else 0.
1820
1821 int BN_set_bit(BIGNUM *a, int n);
1822         This function sets bit 'n' to 1 in 'a'. 
1823         This is a&= ~(1<<n);
1824
1825 int BN_clear_bit(BIGNUM *a, int n);
1826         This function sets bit 'n' to zero in 'a'.  Return 0 if less
1827         than 'n' bits in 'a' else 1.  This is a&= ~(1<<n);
1828
1829 int BN_mask_bits(BIGNUM *a, int n);
1830         Truncate 'a' to n bits long.  This is a&= ~((~0)<<n)
1831
1832 Format conversion routines.
1833
1834 BIGNUM *BN_bin2bn(unsigned char *s, int len,BIGNUM *ret);
1835         This function converts 'len' bytes in 's' into a BIGNUM which
1836         is put in 'ret'.  If ret is NULL, a new BIGNUM is created.
1837         Either this new BIGNUM or ret is returned.  The number is
1838         assumed to be in bigendian form in 's'.  By this I mean that
1839         to 'ret' is created as follows for 'len' == 5.
1840         ret = s[0]*2^32 + s[1]*2^24 + s[2]*2^16 + s[3]*2^8 + s[4];
1841         This function cannot be used to convert negative numbers.  It
1842         is always assumed the number is positive.  The application
1843         needs to diddle the 'neg' field of th BIGNUM its self.
1844         The better solution would be to save the numbers in ASN.1 format
1845         since this is a defined standard for storing big numbers.
1846         Look at the functions
1847
1848         ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai);
1849         BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn);
1850         int i2d_ASN1_INTEGER(ASN1_INTEGER *a,unsigned char **pp);
1851         ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **a,unsigned char **pp,
1852                 long length;
1853
1854 int BN_bn2bin(BIGNUM *a, unsigned char *to);
1855         This function converts 'a' to a byte string which is put into
1856         'to'.  The representation is big-endian in that the most
1857         significant byte of 'a' is put into to[0].  This function
1858         returns the number of bytes used to hold 'a'.  BN_num_bytes(a)
1859         would return the same value and can be used to determine how
1860         large 'to' needs to be.  If the number is negative, this
1861         information is lost.  Since this library was written to
1862         manipulate large positive integers, the inability to save and
1863         restore them is not considered to be a problem by me :-).
1864         As for BN_bin2bn(), look at the ASN.1 integer encoding funtions
1865         for SSLeay.  They use BN_bin2bn() and BN_bn2bin() internally.
1866         
1867 char *BN_bn2ascii(BIGNUM *a);
1868         This function returns a malloc()ed string that contains the
1869         ascii hexadecimal encoding of 'a'.  The number is in bigendian
1870         format with a '-' in front if the number is negative.
1871
1872 int BN_ascii2bn(BIGNUM **bn, char *a);
1873         The inverse of BN_bn2ascii.  The function returns the number of
1874         characters from 'a' were processed in generating a the bignum.
1875         error is inticated by 0 being returned.  The number is a
1876         hex digit string, optionally with a leading '-'.  If *bn
1877         is null, a BIGNUM is created and returned via that variable.
1878         
1879 int BN_print_fp(FILE *fp, BIGNUM *a);
1880         'a' is printed to file pointer 'fp'.  It is in the same format
1881         that is output from BN_bn2ascii().  0 is returned on error,
1882         1 if things are ok.
1883
1884 int BN_print(BIO *bp, BIGNUM *a);
1885         Same as BN_print except that the output is done to the SSLeay libraries
1886         BIO routines.  BN_print_fp() actually calls this function.
1887
1888 Miscellaneous Routines.
1889
1890 int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
1891         This function returns in 'rnd' a random BIGNUM that is bits
1892         long.  If bottom is 1, the number returned is odd.  If top is set,
1893         the top 2 bits of the number are set.  This is useful because if
1894         this is set, 2 'n; bit numbers multiplied together will return a 2n
1895         bit number.  If top was not set, they could produce a 2n-1 bit
1896         number.
1897
1898 BIGNUM *BN_mod_inverse(BIGNUM *a, BIGNUM *n,BN_CTX *ctx);
1899         This function create a new BIGNUM and returns it.  This number
1900         is the inverse mod 'n' of 'a'.  By this it is meant that the
1901         returned value 'r' satisfies (a*r)%n == 1.  This function is
1902         used in the generation of RSA keys.  'ctx', as per usual,
1903         is used to hold temporary variables that are required by the
1904         function.  NULL is returned on error.
1905
1906 int BN_gcd(BIGNUM *r,BIGNUM *a,BIGNUM *b,BN_CTX *ctx);
1907         'r' has the greatest common divisor of 'a' and 'b'.  'ctx' is
1908         used for temporary variables and 0 is returned on error.
1909
1910 int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(),BN_CTX *ctx,
1911         char *cb_arg);
1912         This function is used to check if a BIGNUM ('p') is prime.
1913         It performs this test by using the Miller-Rabin randomised
1914         primality test.  This is a probalistic test that requires a
1915         number of rounds to ensure the number is prime to a high
1916         degree of probability.  Since this can take quite some time, a
1917         callback function can be passed and it will be called each
1918         time 'p' passes a round of the prime testing.  'callback' will
1919         be called as follows, callback(1,n,cb_arg) where n is the number of
1920         the round, just passed.  As per usual 'ctx' contains temporary
1921         variables used.  If ctx is NULL, it does not matter, a local version
1922         will be malloced.  This parameter is present to save some mallocing
1923         inside the function but probably could be removed.
1924         0 is returned on error.
1925         'ncheck' is the number of Miller-Rabin tests to run.  It is
1926         suggested to use the value 'BN_prime_checks' by default.
1927
1928 BIGNUM *BN_generate_prime(
1929 int bits,
1930 int strong,
1931 BIGNUM *a,
1932 BIGNUM *rems,
1933 void (*callback)());
1934 char *cb_arg
1935         This function is used to generate prime numbers.  It returns a
1936         new BIGNUM that has a high probability of being a prime.
1937         'bits' is the number of bits that
1938         are to be in the prime.  If 'strong' is true, the returned prime
1939         will also be a strong prime ((p-1)/2 is also prime).
1940         While searching for the prime ('p'), we
1941         can add the requirement that the prime fill the following
1942         condition p%a == rem.  This can be used to help search for
1943         primes with specific features, which is required when looking
1944         for primes suitable for use with certain 'g' values in the
1945         Diffie-Hellman key exchange algorithm.  If 'a' is NULL,
1946         this condition is not checked.  If rem is NULL, rem is assumed
1947         to be 1.  Since this search for a prime
1948         can take quite some time, if callback is not NULL, it is called
1949         in the following situations.
1950         We have a suspected prime (from a quick sieve),
1951         callback(0,sus_prime++,cb_arg). Each item to be passed to BN_is_prime().
1952         callback(1,round++,cb_arg).  Each successful 'round' in BN_is_prime().
1953         callback(2,round,cb_arg). For each successful BN_is_prime() test.
1954
1955 Hints
1956 -----
1957
1958 DSA wants 64*32 to use word mont mul, but RSA wants to use full.
1959
1960 ==== callback.doc ========================================================
1961
1962 Callback functions used in SSLeay.
1963
1964 --------------------------
1965 The BIO library.  
1966
1967 Each BIO structure can have a callback defined against it.  This callback is
1968 called 2 times for each BIO 'function'.  It is passed 6 parameters.
1969 BIO_debug_callback() is an example callback which is defined in
1970 crypto/buffer/bio_cb.c and is used in apps/dgst.c  This is intended mostly
1971 for debuging or to notify the application of IO.
1972
1973 long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl,
1974         long ret);
1975 bio is the BIO being called, cmd is the type of BIO function being called.
1976 Look at the BIO_CB_* defines in buffer.h.  Argp and argi are the arguments
1977 passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts().  In the case of
1978 BIO_ctrl(), argl is also defined.  The first time the callback is called,
1979 before the underlying function has been executed, 0 is passed as 'ret', and
1980 if the return code from the callback is not > 0, the call is aborted
1981 and the returned <= 0 value is returned.
1982 The second time the callback is called, the 'cmd' value also has
1983 BIO_CB_RETURN logically 'or'ed with it.  The 'ret' value is the value returned
1984 from the actuall function call and whatever the callback returns is returned
1985 from the BIO function.
1986
1987 BIO_set_callback(b,cb) can be used to set the callback function
1988 (b is a BIO), and BIO_set_callback_arg(b,arg) can be used to
1989 set the cb_arg argument in the BIO strucutre.  This field is only intended
1990 to be used by application, primarily in the callback function since it is
1991 accessable since the BIO is passed.
1992
1993 --------------------------
1994 The PEM library.
1995
1996 The pem library only really uses one type of callback,
1997 static int def_callback(char *buf, int num, int verify);
1998 which is used to return a password string if required.
1999 'buf' is the buffer to put the string in.  'num' is the size of 'buf'
2000 and 'verify' is used to indicate that the password should be checked.
2001 This last flag is mostly used when reading a password for encryption.
2002
2003 For all of these functions, a NULL callback will call the above mentioned
2004 default callback.  This default function does not work under Windows 3.1.
2005 For other machines, it will use an application defined prompt string
2006 (EVP_set_pw_prompt(), which defines a library wide prompt string)
2007 if defined, otherwise it will use it's own PEM password prompt.
2008 It will then call EVP_read_pw_string() to get a password from the console.
2009 If your application wishes to use nice fancy windows to retrieve passwords,
2010 replace this function.  The callback should return the number of bytes read
2011 into 'buf'.  If the number of bytes <= 0, it is considered an error.
2012
2013 Functions that take this callback are listed below.  For the 'read' type
2014 functions, the callback will only be required if the PEM data is encrypted.
2015
2016 For the Write functions, normally a password can be passed in 'kstr', of
2017 'klen' bytes which will be used if the 'enc' cipher is not NULL.  If
2018 'kstr' is NULL, the callback will be used to retrieve a password.
2019
2020 int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len,
2021         int (*callback)());
2022 char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)());
2023 char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
2024 int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x,
2025         EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
2026 int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,
2027         EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
2028 STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)());
2029 STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)());
2030
2031 #define PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb)
2032 #define PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb)
2033 #define PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb)
2034 #define PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb)
2035 #define PEM_read_SSL_SESSION(fp,x,cb)
2036 #define PEM_read_X509(fp,x,cb)
2037 #define PEM_read_X509_REQ(fp,x,cb)
2038 #define PEM_read_X509_CRL(fp,x,cb)
2039 #define PEM_read_RSAPrivateKey(fp,x,cb)
2040 #define PEM_read_DSAPrivateKey(fp,x,cb)
2041 #define PEM_read_PrivateKey(fp,x,cb)
2042 #define PEM_read_PKCS7(fp,x,cb)
2043 #define PEM_read_DHparams(fp,x,cb)
2044 #define PEM_read_bio_SSL_SESSION(bp,x,cb)
2045 #define PEM_read_bio_X509(bp,x,cb)
2046 #define PEM_read_bio_X509_REQ(bp,x,cb)
2047 #define PEM_read_bio_X509_CRL(bp,x,cb)
2048 #define PEM_read_bio_RSAPrivateKey(bp,x,cb)
2049 #define PEM_read_bio_DSAPrivateKey(bp,x,cb)
2050 #define PEM_read_bio_PrivateKey(bp,x,cb)
2051 #define PEM_read_bio_PKCS7(bp,x,cb)
2052 #define PEM_read_bio_DHparams(bp,x,cb)
2053 int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
2054 RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)());
2055
2056 Now you will notice that macros like
2057 #define PEM_write_X509(fp,x) \
2058                 PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \
2059                                         (char *)x, NULL,NULL,0,NULL)
2060 Don't do encryption normally.  If you want to PEM encrypt your X509 structure,
2061 either just call PEM_ASN1_write directly or just define your own
2062 macro variant.  As you can see, this macro just sets all encryption related
2063 parameters to NULL.
2064
2065
2066 --------------------------
2067 The SSL library.
2068
2069 #define SSL_set_info_callback(ssl,cb)
2070 #define SSL_CTX_set_info_callback(ctx,cb)
2071 void callback(SSL *ssl,int location,int ret)
2072 This callback is called each time around the SSL_connect()/SSL_accept() 
2073 state machine.  So it will be called each time the SSL protocol progresses.
2074 It is mostly present for use when debugging.  When SSL_connect() or
2075 SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or
2076 SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned.
2077 Have a look at the SSL_CB_* defines in ssl.h.  If an info callback is defined
2078 against the SSL_CTX, it is called unless there is one set against the SSL.
2079 Have a look at
2080 void client_info_callback() in apps/s_client() for an example.
2081
2082 Certificate verification.
2083 void SSL_set_verify(SSL *s, int mode, int (*callback) ());
2084 void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)());
2085 This callback is used to help verify client and server X509 certificates.
2086 It is actually passed to X509_cert_verify(), along with the SSL structure
2087 so you have to read about X509_cert_verify() :-).  The SSL_CTX version is used
2088 if the SSL version is not defined.  X509_cert_verify() is the function used
2089 by the SSL part of the library to verify certificates.  This function is
2090 nearly always defined by the application.
2091
2092 void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg);
2093 int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain);
2094 This call is used to replace the SSLeay certificate verification code.
2095 The 'arg' is kept in the SSL_CTX and is passed to the callback.
2096 If the callback returns 0, the certificate is rejected, otherwise it
2097 is accepted.  The callback is replacing the X509_cert_verify() call.
2098 This feature is not often used, but if you wished to implement
2099 some totally different certificate authentication system, this 'hook' is
2100 vital.
2101
2102 SSLeay keeps a cache of session-ids against each SSL_CTX.  These callbacks can
2103 be used to notify the application when a SSL_SESSION is added to the cache
2104 or to retrieve a SSL_SESSION that is not in the cache from the application.
2105 #define SSL_CTX_sess_set_get_cb(ctx,cb)
2106 SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy);
2107 If defined, this callback is called to return the SESSION_ID for the
2108 session-id in 'session_id', of 'session_id_len' bytes.  'copy' is set to 1
2109 if the server is to 'take a copy' of the SSL_SESSION structure.  It is 0
2110 if the SSL_SESSION is being 'passed in' so the SSLeay library is now
2111 responsible for 'free()ing' the structure.  Basically it is used to indicate
2112 if the reference count on the SSL_SESSION structure needs to be incremented.
2113
2114 #define SSL_CTX_sess_set_new_cb(ctx,cb)
2115 int callback(SSL *s, SSL_SESSION *sess);
2116 When a new connection is established, if the SSL_SESSION is going to be added
2117 to the cache, this callback is called.  Return 1 if a 'copy' is required,
2118 otherwise, return 0.  This return value just causes the reference count
2119 to be incremented (on return of a 1), this means the application does
2120 not need to worry about incrementing the refernece count (and the
2121 locking that implies in a multi-threaded application).
2122
2123 void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)());
2124 This sets the SSL password reading function.
2125 It is mostly used for windowing applications
2126 and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey()
2127 calls inside the SSL library.   The only reason this is present is because the
2128 calls to PEM_* functions is hidden in the SSLeay library so you have to
2129 pass in the callback some how.
2130
2131 #define SSL_CTX_set_client_cert_cb(ctx,cb)
2132 int callback(SSL *s,X509 **x509, EVP_PKEY **pkey);
2133 Called when a client certificate is requested but there is not one set
2134 against the SSL_CTX or the SSL.  If the callback returns 1, x509 and
2135 pkey need to point to valid data.  The library will free these when
2136 required so if the application wants to keep these around, increment
2137 their reference counts.  If 0 is returned, no client cert is
2138 available.  If -1 is returned, it is assumed that the callback needs
2139 to be called again at a later point in time.  SSL_connect will return
2140 -1 and SSL_want_x509_lookup(ssl) returns true.  Remember that
2141 application data can be attached to an SSL structure via the
2142 SSL_set_app_data(SSL *ssl,char *data) call.
2143
2144 --------------------------
2145 The X509 library.
2146
2147 int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(),
2148         int *error,char *arg,STACK *cert_chain);
2149 int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg,
2150         STACK *cert_chain);
2151
2152 X509_cert_verify() is used to authenticate X509 certificates.  The 'ctx' holds
2153 the details of the various caches and files used to locate certificates.
2154 'xs' is the certificate to verify and 'cb' is the application callback (more
2155 detail later).  'error' will be set to the error code and 'arg' is passed
2156 to the 'cb' callback.  Look at the VERIFY_* defines in crypto/x509/x509.h
2157
2158 When ever X509_cert_verify() makes a 'negative' decision about a
2159 certitificate, the callback is called.  If everything checks out, the
2160 callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self
2161 signed cert that is not the passed certificate).
2162
2163 The callback is passed the X509_cert_verify opinion of the certificate 
2164 in 'ok', the certificate in 'xs', the issuer certificate in 'xi',
2165 the 'depth' of the certificate in the verification 'chain', the
2166 VERIFY_* code in 'error' and the argument passed to X509_cert_verify()
2167 in 'arg'. cert_chain is a list of extra certs to use if they are not
2168 in the cache.
2169
2170 The callback can be used to look at the error reason, and then return 0
2171 for an 'error' or '1' for ok.  This will override the X509_cert_verify()
2172 opinion of the certificates validity.  Processing will continue depending on
2173 the return value.  If one just wishes to use the callback for informational
2174 reason, just return the 'ok' parameter.
2175
2176 --------------------------
2177 The BN and DH library.
2178
2179 BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add,
2180         BIGNUM *rem,void (*callback)(int,int));
2181 int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int),
2182
2183 Read doc/bn.doc for the description of these 2.
2184
2185 DH *DH_generate_parameters(int prime_len,int generator,
2186         void (*callback)(int,int));
2187 Read doc/bn.doc for the description of the callback, since it is just passed
2188 to BN_generate_prime(), except that it is also called as
2189 callback(3,0) by this function.
2190
2191 --------------------------
2192 The CRYPTO library.
2193
2194 void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file,
2195         int line));
2196 void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount,
2197         int type,char *file, int line));
2198 void CRYPTO_set_id_callback(unsigned long (*func)(void));
2199
2200 Read threads.doc for info on these ones.
2201
2202
2203 ==== cipher.doc ========================================================
2204
2205 The Cipher subroutines.
2206
2207 These routines require "evp.h" to be included.
2208
2209 These functions are a higher level interface to the various cipher
2210 routines found in this library.  As such, they allow the same code to be
2211 used to encrypt and decrypt via different ciphers with only a change
2212 in an initial parameter.  These routines also provide buffering for block
2213 ciphers.
2214
2215 These routines all take a pointer to the following structure to specify
2216 which cipher to use.  If you wish to use a new cipher with these routines,
2217 you would probably be best off looking an how an existing cipher is
2218 implemented and copying it.  At this point in time, I'm not going to go
2219 into many details.  This structure should be considered opaque
2220
2221 typedef struct pem_cipher_st
2222         {
2223         int type;
2224         int block_size;
2225         int key_len;
2226         int iv_len;
2227         void (*enc_init)();     /* init for encryption */
2228         void (*dec_init)();     /* init for decryption */
2229         void (*do_cipher)();    /* encrypt data */
2230         } EVP_CIPHER;
2231         
2232 The type field is the object NID of the cipher type
2233 (read the section on Objects for an explanation of what a NID is).
2234 The cipher block_size is how many bytes need to be passed
2235 to the cipher at a time.  Key_len is the
2236 length of the key the cipher requires and iv_len is the length of the
2237 initialisation vector required.  enc_init is the function
2238 called to initialise the ciphers context for encryption and dec_init is the
2239 function to initialise for decryption (they need to be different, especially
2240 for the IDEA cipher).
2241
2242 One reason for specifying the Cipher via a pointer to a structure
2243 is that if you only use des-cbc, only the des-cbc routines will
2244 be included when you link the program.  If you passed an integer
2245 that specified which cipher to use, the routine that mapped that
2246 integer to a set of cipher functions would cause all the ciphers
2247 to be link into the code.  This setup also allows new ciphers
2248 to be added by the application (with some restrictions).
2249
2250 The thirteen ciphers currently defined in this library are
2251
2252 EVP_CIPHER *EVP_des_ecb();     /* DES in ecb mode,     iv=0, block=8, key= 8 */
2253 EVP_CIPHER *EVP_des_ede();     /* DES in ecb ede mode, iv=0, block=8, key=16 */
2254 EVP_CIPHER *EVP_des_ede3();    /* DES in ecb ede mode, iv=0, block=8, key=24 */
2255 EVP_CIPHER *EVP_des_cfb();     /* DES in cfb mode,     iv=8, block=1, key= 8 */
2256 EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */
2257 EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */
2258 EVP_CIPHER *EVP_des_ofb();     /* DES in ofb mode,     iv=8, block=1, key= 8 */
2259 EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */
2260 EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */
2261 EVP_CIPHER *EVP_des_cbc();     /* DES in cbc mode,     iv=8, block=8, key= 8 */
2262 EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */
2263 EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */
2264 EVP_CIPHER *EVP_desx_cbc();    /* DES in desx cbc mode,iv=8, block=8, key=24 */
2265 EVP_CIPHER *EVP_rc4();         /* RC4,                 iv=0, block=1, key=16 */
2266 EVP_CIPHER *EVP_idea_ecb();    /* IDEA in ecb mode,    iv=0, block=8, key=16 */
2267 EVP_CIPHER *EVP_idea_cfb();    /* IDEA in cfb mode,    iv=8, block=1, key=16 */
2268 EVP_CIPHER *EVP_idea_ofb();    /* IDEA in ofb mode,    iv=8, block=1, key=16 */
2269 EVP_CIPHER *EVP_idea_cbc();    /* IDEA in cbc mode,    iv=8, block=8, key=16 */
2270 EVP_CIPHER *EVP_rc2_ecb();     /* RC2 in ecb mode,     iv=0, block=8, key=16 */
2271 EVP_CIPHER *EVP_rc2_cfb();     /* RC2 in cfb mode,     iv=8, block=1, key=16 */
2272 EVP_CIPHER *EVP_rc2_ofb();     /* RC2 in ofb mode,     iv=8, block=1, key=16 */
2273 EVP_CIPHER *EVP_rc2_cbc();     /* RC2 in cbc mode,     iv=8, block=8, key=16 */
2274 EVP_CIPHER *EVP_bf_ecb();      /* Blowfish in ecb mode,iv=0, block=8, key=16 */
2275 EVP_CIPHER *EVP_bf_cfb();      /* Blowfish in cfb mode,iv=8, block=1, key=16 */
2276 EVP_CIPHER *EVP_bf_ofb();      /* Blowfish in ofb mode,iv=8, block=1, key=16 */
2277 EVP_CIPHER *EVP_bf_cbc();      /* Blowfish in cbc mode,iv=8, block=8, key=16 */
2278
2279 The meaning of the compound names is as follows.
2280 des     The base cipher is DES.
2281 idea    The base cipher is IDEA
2282 rc4     The base cipher is RC4-128
2283 rc2     The base cipher is RC2-128
2284 ecb     Electronic Code Book form of the cipher.
2285 cbc     Cipher Block Chaining form of the cipher.
2286 cfb     64 bit Cipher Feedback form of the cipher.
2287 ofb     64 bit Output Feedback form of the cipher.
2288 ede     The cipher is used in Encrypt, Decrypt, Encrypt mode.  The first
2289         and last keys are the same.
2290 ede3    The cipher is used in Encrypt, Decrypt, Encrypt mode.
2291
2292 All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument.
2293 The state of the cipher is kept in this structure.
2294
2295 typedef struct EVP_CIPHER_Ctx_st
2296         {
2297         EVP_CIPHER *cipher;
2298         int encrypt;            /* encrypt or decrypt */
2299         int buf_len;            /* number we have left */
2300         unsigned char buf[8];
2301         union   {
2302                 .... /* cipher specific stuff */
2303                 } c;
2304         } EVP_CIPHER_CTX;
2305
2306 Cipher is a pointer the the EVP_CIPHER for the current context.  The encrypt
2307 flag indicates encryption or decryption.  buf_len is the number of bytes
2308 currently being held in buf.
2309 The 'c' union holds the cipher specify context.
2310
2311 The following functions are to be used.
2312
2313 int EVP_read_pw_string(
2314 char *buf,
2315 int len,
2316 char *prompt,
2317 int verify,
2318         This function is the same as des_read_pw_string() (des.doc).
2319
2320 void EVP_set_pw_prompt(char *prompt);
2321         This function sets the 'default' prompt to use to use in
2322         EVP_read_pw_string when the prompt parameter is NULL.  If the
2323         prompt parameter is NULL, this 'default prompt' feature is turned
2324         off.  Be warned, this is a global variable so weird things
2325         will happen if it is used under Win16 and care must be taken
2326         with a multi-threaded version of the library.
2327
2328 char *EVP_get_pw_prompt();
2329         This returns a pointer to the default prompt string.  NULL
2330         if it is not set.
2331
2332 int EVP_BytesToKey(
2333 EVP_CIPHER *type,
2334 EVP_MD *md,
2335 unsigned char *salt,
2336 unsigned char *data,
2337 int datal,
2338 int count,
2339 unsigned char *key,
2340 unsigned char *iv);
2341         This function is used to generate a key and an initialisation vector
2342         for a specified cipher from a key string and a salt.  Type
2343         specifies the cipher the 'key' is being generated for.  Md is the
2344         message digest algorithm to use to generate the key and iv.  The salt
2345         is an optional 8 byte object that is used to help seed the key
2346         generator.
2347         If the salt value is NULL, it is just not used.  Datal is the
2348         number of bytes to use from 'data' in the key generation.  
2349         This function returns the key size for the specified cipher, if
2350         data is NULL, this value is returns and no other
2351         computation is performed.  Count is
2352         the number of times to loop around the key generator.  I would
2353         suggest leaving it's value as 1.  Key and iv are the structures to
2354         place the returning iv and key in.  If they are NULL, no value is
2355         generated for that particular value.
2356         The algorithm used is as follows
2357         
2358         /* M[] is an array of message digests
2359          * MD() is the message digest function */
2360         M[0]=MD(data . salt);
2361         for (i=1; i<count; i++) M[0]=MD(M[0]);
2362
2363         i=1
2364         while (data still needed for key and iv)
2365                 {
2366                 M[i]=MD(M[i-1] . data . salt);
2367                 for (i=1; i<count; i++) M[i]=MD(M[i]);
2368                 i++;
2369                 }
2370
2371         If the salt is NULL, it is not used.
2372         The digests are concatenated together.
2373         M = M[0] . M[1] . M[2] .......
2374
2375         For key= 8, iv=8 => key=M[0.. 8], iv=M[ 9 .. 16].
2376         For key=16, iv=0 => key=M[0..16].
2377         For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24].
2378         For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32].
2379
2380         This routine will produce DES-CBC keys and iv that are compatible
2381         with the PKCS-5 standard when md2 or md5 are used.  If md5 is
2382         used, the salt is NULL and count is 1, this routine will produce
2383         the password to key mapping normally used with RC4.
2384         I have attempted to logically extend the PKCS-5 standard to
2385         generate keys and iv for ciphers that require more than 16 bytes,
2386         if anyone knows what the correct standard is, please inform me.
2387         When using sha or sha1, things are a bit different under this scheme,
2388         since sha produces a 20 byte digest.  So for ciphers requiring
2389         24 bits of data, 20 will come from the first MD and 4 will
2390         come from the second.
2391
2392         I have considered having a separate function so this 'routine'
2393         can be used without the requirement of passing a EVP_CIPHER *,
2394         but I have decided to not bother.  If you wish to use the
2395         function without official EVP_CIPHER structures, just declare
2396         a local one and set the key_len and iv_len fields to the
2397         length you desire.
2398
2399 The following routines perform encryption and decryption 'by parts'.  By
2400 this I mean that there are groups of 3 routines.  An Init function that is
2401 used to specify a cipher and initialise data structures.  An Update routine
2402 that does encryption/decryption, one 'chunk' at a time.  And finally a
2403 'Final' function that finishes the encryption/decryption process.
2404 All these functions take a EVP_CIPHER pointer to specify which cipher to
2405 encrypt/decrypt with.  They also take a EVP_CIPHER_CTX object as an
2406 argument.  This structure is used to hold the state information associated
2407 with the operation in progress.
2408
2409 void EVP_EncryptInit(
2410 EVP_CIPHER_CTX *ctx,
2411 EVP_CIPHER *type,
2412 unsigned char *key,
2413 unsigned char *iv);
2414         This function initialise a EVP_CIPHER_CTX for encryption using the
2415         cipher passed in the 'type' field.  The cipher is initialised to use
2416         'key' as the key and 'iv' for the initialisation vector (if one is
2417         required).  If the type, key or iv is NULL, the value currently in the
2418         EVP_CIPHER_CTX is reused.  So to perform several decrypt
2419         using the same cipher, key and iv, initialise with the cipher,
2420         key and iv the first time and then for subsequent calls,
2421         reuse 'ctx' but pass NULL for type, key and iv.  You must make sure
2422         to pass a key that is large enough for a particular cipher.  I
2423         would suggest using the EVP_BytesToKey() function.
2424
2425 void EVP_EncryptUpdate(
2426 EVP_CIPHER_CTX *ctx,
2427 unsigned char *out,
2428 int *outl,
2429 unsigned char *in,
2430 int inl);
2431         This function takes 'inl' bytes from 'in' and outputs bytes
2432         encrypted by the cipher 'ctx' was initialised with into 'out'.  The
2433         number of bytes written to 'out' is put into outl.  If a particular
2434         cipher encrypts in blocks, less or more bytes than input may be
2435         output.  Currently the largest block size used by supported ciphers
2436         is 8 bytes, so 'out' should have room for 'inl+7' bytes.  Normally
2437         EVP_EncryptInit() is called once, followed by lots and lots of
2438         calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal
2439         call.
2440
2441 void EVP_EncryptFinal(
2442 EVP_CIPHER_CTX *ctx,
2443 unsigned char *out,
2444 int *outl);
2445         Because quite a large number of ciphers are block ciphers, there is
2446         often an incomplete block to write out at the end of the
2447         encryption.  EVP_EncryptFinal() performs processing on this last
2448         block.  The last block in encoded in such a way that it is possible
2449         to determine how many bytes in the last block are valid.  For 8 byte
2450         block size ciphers, if only 5 bytes in the last block are valid, the
2451         last three bytes will be filled with the value 3.  If only 2 were
2452         valid, the other 6 would be filled with sixes.  If all 8 bytes are
2453         valid, a extra 8 bytes are appended to the cipher stream containing
2454         nothing but 8 eights.  These last bytes are output into 'out' and
2455         the number of bytes written is put into 'outl'  These last bytes
2456         are output into 'out' and the number of bytes written is put into
2457         'outl'.  This form of block cipher finalisation is compatible with
2458         PKCS-5.  Please remember that even if you are using ciphers like
2459         RC4 that has no blocking and so the function will not write
2460         anything into 'out', it would still be a good idea to pass a
2461         variable for 'out' that can hold 8 bytes just in case the cipher is
2462         changed some time in the future.  It should also be remembered
2463         that the EVP_CIPHER_CTX contains the password and so when one has
2464         finished encryption with a particular EVP_CIPHER_CTX, it is good
2465         practice to zero the structure 
2466         (ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)).
2467         
2468 void EVP_DecryptInit(
2469 EVP_CIPHER_CTX *ctx,
2470 EVP_CIPHER *type,
2471 unsigned char *key,
2472 unsigned char *iv);
2473         This function is basically the same as EVP_EncryptInit() accept that
2474         is prepares the EVP_CIPHER_CTX for decryption.
2475
2476 void EVP_DecryptUpdate(
2477 EVP_CIPHER_CTX *ctx,
2478 unsigned char *out,
2479 int *outl,
2480 unsigned char *in,
2481 int inl);
2482         This function is basically the same as EVP_EncryptUpdate()
2483         except that it performs decryption.  There is one
2484         fundamental difference though.  'out' can not be the same as
2485         'in' for any ciphers with a block size greater than 1 if more
2486         than one call to EVP_DecryptUpdate() will be made.  This
2487         is because this routine can hold a 'partial' block between
2488         calls.  When a partial block is decrypted (due to more bytes
2489         being passed via this function, they will be written to 'out'
2490         overwriting the input bytes in 'in' that have not been read
2491         yet.  From this it should also be noted that 'out' should
2492         be at least one 'block size' larger than 'inl'.  This problem
2493         only occurs on the second and subsequent call to
2494         EVP_DecryptUpdate() when using a block cipher.
2495
2496 int EVP_DecryptFinal(
2497 EVP_CIPHER_CTX *ctx,
2498 unsigned char *out,
2499 int *outl);
2500         This function is different to EVP_EncryptFinal in that it 'removes'
2501         any padding bytes appended when the data was encrypted.  Due to the
2502         way in which 1 to 8 bytes may have been appended when encryption
2503         using a block cipher, 'out' can end up with 0 to 7 bytes being put
2504         into it.  When decoding the padding bytes, it is possible to detect
2505         an incorrect decryption.  If the decryption appears to be wrong, 0
2506         is returned.  If everything seems ok, 1 is returned.  For ciphers
2507         with a block size of 1 (RC4), this function would normally not
2508         return any bytes and would always return 1.  Just because this
2509         function returns 1 does not mean the decryption was correct. It
2510         would normally be wrong due to either the wrong key/iv or
2511         corruption of the cipher data fed to EVP_DecryptUpdate().
2512         As for EVP_EncryptFinal, it is a good idea to zero the
2513         EVP_CIPHER_CTX after use since the structure contains the key used
2514         to decrypt the data.
2515         
2516 The following Cipher routines are convenience routines that call either
2517 EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX
2518 was setup to encrypt or decrypt.  
2519
2520 void EVP_CipherInit(
2521 EVP_CIPHER_CTX *ctx,
2522 EVP_CIPHER *type,
2523 unsigned char *key,
2524 unsigned char *iv,
2525 int enc);
2526         This function take arguments that are the same as EVP_EncryptInit()
2527         and EVP_DecryptInit() except for the extra 'enc' flag.  If 1, the
2528         EVP_CIPHER_CTX is setup for encryption, if 0, decryption.
2529
2530 void EVP_CipherUpdate(
2531 EVP_CIPHER_CTX *ctx,
2532 unsigned char *out,
2533 int *outl,
2534 unsigned char *in,
2535 int inl);
2536         Again this function calls either EVP_EncryptUpdate() or
2537         EVP_DecryptUpdate() depending on state in the 'ctx' structure.
2538         As noted for EVP_DecryptUpdate(), when this routine is used
2539         for decryption with block ciphers, 'out' should not be the
2540         same as 'in'.
2541
2542 int EVP_CipherFinal(
2543 EVP_CIPHER_CTX *ctx,
2544 unsigned char *outm,
2545 int *outl);
2546         This routine call EVP_EncryptFinal() or EVP_DecryptFinal()
2547         depending on the state information in 'ctx'.  1 is always returned
2548         if the mode is encryption, otherwise the return value is the return
2549         value of EVP_DecryptFinal().
2550
2551 ==== cipher.m ========================================================
2552
2553 Date: Tue, 15 Oct 1996 08:16:14 +1000 (EST)
2554 From: Eric Young <eay@mincom.com>
2555 X-Sender: eay@orb
2556 To: Roland Haring <rharing@tandem.cl>
2557 Cc: ssl-users@mincom.com
2558 Subject: Re: Symmetric encryption with ssleay
2559 In-Reply-To: <m0vBpyq-00001aC@tandemnet.tandem.cl>
2560 Message-Id: <Pine.SOL.3.91.961015075623.11394A-100000@orb>
2561 Mime-Version: 1.0
2562 Content-Type: TEXT/PLAIN; charset=US-ASCII
2563 Sender: ssl-lists-owner@mincom.com
2564 Precedence: bulk
2565 Status: RO
2566 X-Status: 
2567
2568 On Fri, 11 Oct 1996, Roland Haring wrote:
2569 > THE_POINT:
2570 >       Would somebody be so kind to give me the minimum basic 
2571 >       calls I need to do to libcrypto.a to get some text encrypted
2572 >       and decrypted again? ...hopefully with code included to do
2573 >       base64 encryption and decryption ... e.g. that sign-it.c code
2574 >       posted some while ago was a big help :-) (please, do not point
2575 >       me to apps/enc.c where I suspect my Heissenbug to be hidden :-)
2576
2577 Ok, the base64 encoding stuff in 'enc.c' does the wrong thing sometimes 
2578 when the data is less than a line long (this is for decoding).  I'll dig 
2579 up the exact fix today and post it.  I am taking longer on 0.6.5 than I 
2580 intended so I'll just post this patch.
2581
2582 The documentation to read is in
2583 doc/cipher.doc,
2584 doc/encode.doc (very sparse :-).
2585 and perhaps
2586 doc/digest.doc,
2587
2588 The basic calls to encrypt with say triple DES are
2589
2590 Given
2591 char key[EVP_MAX_KEY_LENGTH];
2592 char iv[EVP_MAX_IV_LENGTH];
2593 EVP_CIPHER_CTX ctx;
2594 unsigned char out[512+8];
2595 int outl;
2596
2597 /* optional generation of key/iv data from text password using md5
2598  * via an upward compatable verson of PKCS#5. */
2599 EVP_BytesToKey(EVP_des_ede3_cbc,EVP_md5,NULL,passwd,strlen(passwd),
2600         key,iv);
2601
2602 /* Initalise the EVP_CIPHER_CTX */
2603 EVP_EncryptInit(ctx,EVP_des_ede3_cbc,key,iv);
2604
2605 while (....)
2606         {
2607         /* This is processing 512 bytes at a time, the bytes are being
2608          * copied into 'out', outl bytes are output.  'out' should not be the
2609          * same as 'in' for reasons mentioned in the documentation. */
2610         EVP_EncryptUpdate(ctx,out,&outl,in,512);
2611         }
2612
2613 /* Output the last 'block'.  If the cipher is a block cipher, the last
2614  * block is encoded in such a way so that a wrong decryption will normally be
2615  * detected - again, one of the PKCS standards. */
2616
2617 EVP_EncryptFinal(ctx,out,&outl);
2618
2619 To decrypt, use the EVP_DecryptXXXXX functions except that EVP_DecryptFinal()
2620 will return 0 if the decryption fails (only detectable on block ciphers).
2621
2622 You can also use
2623 EVP_CipherInit()
2624 EVP_CipherUpdate()
2625 EVP_CipherFinal()
2626 which does either encryption or decryption depending on an extra 
2627 parameter to EVP_CipherInit().
2628
2629
2630 To do the base64 encoding,
2631 EVP_EncodeInit()
2632 EVP_EncodeUpdate()
2633 EVP_EncodeFinal()
2634
2635 EVP_DecodeInit()
2636 EVP_DecodeUpdate()
2637 EVP_DecodeFinal()
2638
2639 where the encoding is quite simple, but the decoding can be a bit more 
2640 fun (due to dud input).
2641
2642 EVP_DecodeUpdate() returns -1 for an error on an input line, 0 if the 
2643 'last line' was just processed, and 1 if more lines should be submitted.
2644
2645 EVP_DecodeFinal() returns -1 for an error or 1 if things are ok.
2646
2647 So the loop becomes
2648 EVP_DecodeInit(....)
2649 for (;;)
2650         {
2651         i=EVP_DecodeUpdate(....);
2652         if (i < 0) goto err;
2653
2654         /* process the data */
2655
2656         if (i == 0) break;
2657         }
2658 EVP_DecodeFinal(....);
2659 /* process the data */
2660
2661 The problem in 'enc.c' is that I was stuff the processing up after the 
2662 EVP_DecodeFinal(...) when the for(..) loop was not being run (one line of 
2663 base64 data) and this was because 'enc.c' tries to scan over a file until
2664 it hits the first valid base64 encoded line.
2665
2666 hope this helps a bit.
2667 eric
2668 --
2669 Eric Young                  | BOOL is tri-state according to Bill Gates.
2670 AARNet: eay@mincom.oz.au    | RTFM Win32 GetMessage().
2671
2672 ==== conf.doc ========================================================
2673
2674 The CONF library.
2675
2676 The CONF library is a simple set of routines that can be used to configure
2677 programs.  It is a superset of the genenv() function with some extra
2678 structure.
2679
2680 The library consists of 5 functions.
2681
2682 LHASH *CONF_load(LHASH *config,char *file);
2683 This function is called to load in a configuration file.  Multiple
2684 configuration files can be loaded, with each subsequent 'load' overwriting
2685 any already defined 'variables'.  If there is an error, NULL is returned.
2686 If config is NULL, a new LHASH structure is created and returned, otherwise
2687 the new data in the 'file' is loaded into the 'config' structure.
2688
2689 void CONF_free(LHASH *config);
2690 This function free()s the data in config.
2691
2692 char *CONF_get_string(LHASH *config,char *section,char *name);
2693 This function returns the string found in 'config' that corresponds to the
2694 'section' and 'name' specified.  Classes and the naming system used will be
2695 discussed later in this document.  If the variable is not defined, an NULL
2696 is returned.
2697
2698 long CONF_get_long(LHASH *config,char *section, char *name);
2699 This function is the same as CONF_get_string() except that it converts the
2700 string to an long and returns it.  If variable is not a number or the
2701 variable does not exist, 0 is returned.  This is a little problematic but I
2702 don't know of a simple way around it.
2703
2704 STACK *CONF_get_section(LHASH *config, char *section);
2705 This function returns a 'stack' of CONF_VALUE items that are all the
2706 items defined in a particular section.  DO NOT free() any of the
2707 variable returned.  They will disappear when CONF_free() is called.
2708
2709 The 'lookup' model.
2710 The configuration file is divided into 'sections'.  Each section is started by
2711 a line of the form '[ section ]'.  All subsequent variable definitions are
2712 of this section.  A variable definition is a simple alpha-numeric name
2713 followed by an '=' and then the data.  A section or variable name can be
2714 described by a regular expression of the following form '[A-Za-z0-9_]+'.
2715 The value of the variable is the text after the '=' until the end of the
2716 line, stripped of leading and trailing white space.
2717 At this point I should mention that a '#' is a comment character, \ is the
2718 escape character, and all three types of quote can be used to stop any
2719 special interpretation of the data.
2720 Now when the data is being loaded, variable expansion can occur.  This is
2721 done by expanding any $NAME sequences into the value represented by the
2722 variable NAME.  If the variable is not in the current section, the different
2723 section can be specified by using the $SECTION::NAME form.  The ${NAME} form
2724 also works and is very useful for expanding variables inside strings.
2725
2726 When a variable is looked up, there are 2 special section. 'default', which
2727 is the initial section, and 'ENV' which is the processes environment
2728 variables (accessed via getenv()).  When a variable is looked up, it is
2729 first 'matched' with it's section (if one was specified), if this fails, the
2730 'default' section is matched.
2731 If the 'lhash' variable passed was NULL, the environment is searched.
2732
2733 Now why do we bother with sections?  So we can have multiple programs using
2734 the same configuration file, or multiple instances of the same program
2735 using different variables.  It also provides a nice mechanism to override
2736 the processes environment variables (eg ENV::HOME=/tmp).  If there is a
2737 program specific variable missing, we can have default values.
2738 Multiple configuration files can be loaded, with each new value clearing
2739 any predefined values.  A system config file can provide 'default' values,
2740 and application/usr specific files can provide overriding values.
2741
2742 Examples
2743
2744 # This is a simple example
2745 SSLEAY_HOME     = /usr/local/ssl
2746 ENV::PATH       = $SSLEAY_HOME/bin:$PATH        # override my path
2747
2748 [X509]
2749 cert_dir        = $SSLEAY_HOME/certs    # /usr/local/ssl/certs
2750
2751 [SSL]
2752 CIPHER          = DES-EDE-MD5:RC4-MD5
2753 USER_CERT       = $HOME/${USER}di'r 5'  # /home/eay/eaydir 5
2754 USER_CERT       = $HOME/\${USER}di\'r   # /home/eay/${USER}di'r
2755 USER_CERT       = "$HOME/${US"ER}di\'r  # $HOME/${USER}di'r
2756
2757 TEST            = 1234\
2758 5678\
2759 9ab                                     # TEST=123456789ab
2760 TTT             = 1234\n\n              # TTT=1234<nl><nl>
2761
2762
2763
2764 ==== des.doc ========================================================
2765
2766 The DES library.
2767
2768 Please note that this library was originally written to operate with
2769 eBones, a version of Kerberos that had had encryption removed when it left
2770 the USA and then put back in.  As such there are some routines that I will
2771 advise not using but they are still in the library for historical reasons.
2772 For all calls that have an 'input' and 'output' variables, they can be the
2773 same.
2774
2775 This library requires the inclusion of 'des.h'.
2776
2777 All of the encryption functions take what is called a des_key_schedule as an 
2778 argument.  A des_key_schedule is an expanded form of the des key.
2779 A des_key is 8 bytes of odd parity, the type used to hold the key is a
2780 des_cblock.  A des_cblock is an array of 8 bytes, often in this library
2781 description I will refer to input bytes when the function specifies
2782 des_cblock's as input or output, this just means that the variable should
2783 be a multiple of 8 bytes.
2784
2785 The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to
2786 specify decryption.  The functions and global variable are as follows:
2787
2788 int des_check_key;
2789         DES keys are supposed to be odd parity.  If this variable is set to
2790         a non-zero value, des_set_key() will check that the key has odd
2791         parity and is not one of the known weak DES keys.  By default this
2792         variable is turned off;
2793         
2794 void des_set_odd_parity(
2795 des_cblock *key );
2796         This function takes a DES key (8 bytes) and sets the parity to odd.
2797         
2798 int des_is_weak_key(
2799 des_cblock *key );
2800         This function returns a non-zero value if the DES key passed is a
2801         weak, DES key.  If it is a weak key, don't use it, try a different
2802         one.  If you are using 'random' keys, the chances of hitting a weak
2803         key are 1/2^52 so it is probably not worth checking for them.
2804         
2805 int des_set_key(
2806 des_cblock *key,
2807 des_key_schedule schedule);
2808         Des_set_key converts an 8 byte DES key into a des_key_schedule.
2809         A des_key_schedule is an expanded form of the key which is used to
2810         perform actual encryption.  It can be regenerated from the DES key
2811         so it only needs to be kept when encryption or decryption is about
2812         to occur.  Don't save or pass around des_key_schedule's since they
2813         are CPU architecture dependent, DES keys are not.  If des_check_key
2814         is non zero, zero is returned if the key has the wrong parity or
2815         the key is a weak key, else 1 is returned.
2816         
2817 int des_key_sched(
2818 des_cblock *key,
2819 des_key_schedule schedule);
2820         An alternative name for des_set_key().
2821
2822 int des_rw_mode;                /* defaults to DES_PCBC_MODE */
2823         This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default).
2824         This specifies the function to use in the enc_read() and enc_write()
2825         functions.
2826
2827 void des_encrypt(
2828 unsigned long *data,
2829 des_key_schedule ks,
2830 int enc);
2831         This is the DES encryption function that gets called by just about
2832         every other DES routine in the library.  You should not use this
2833         function except to implement 'modes' of DES.  I say this because the
2834         functions that call this routine do the conversion from 'char *' to
2835         long, and this needs to be done to make sure 'non-aligned' memory
2836         access do not occur.  The characters are loaded 'little endian',
2837         have a look at my source code for more details on how I use this
2838         function.
2839         Data is a pointer to 2 unsigned long's and ks is the
2840         des_key_schedule to use.  enc, is non zero specifies encryption,
2841         zero if decryption.
2842
2843 void des_encrypt2(
2844 unsigned long *data,
2845 des_key_schedule ks,
2846 int enc);
2847         This functions is the same as des_encrypt() except that the DES
2848         initial permutation (IP) and final permutation (FP) have been left
2849         out.  As for des_encrypt(), you should not use this function.
2850         It is used by the routines in my library that implement triple DES.
2851         IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same
2852         as des_encrypt() des_encrypt() des_encrypt() except faster :-).
2853
2854 void des_ecb_encrypt(
2855 des_cblock *input,
2856 des_cblock *output,
2857 des_key_schedule ks,
2858 int enc);
2859         This is the basic Electronic Code Book form of DES, the most basic
2860         form.  Input is encrypted into output using the key represented by
2861         ks.  If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise
2862         decryption occurs.  Input is 8 bytes long and output is 8 bytes.
2863         (the des_cblock structure is 8 chars).
2864         
2865 void des_ecb3_encrypt(
2866 des_cblock *input,
2867 des_cblock *output,
2868 des_key_schedule ks1,
2869 des_key_schedule ks2,
2870 des_key_schedule ks3,
2871 int enc);
2872         This is the 3 key EDE mode of ECB DES.  What this means is that 
2873         the 8 bytes of input is encrypted with ks1, decrypted with ks2 and
2874         then encrypted again with ks3, before being put into output;
2875         C=E(ks3,D(ks2,E(ks1,M))).  There is a macro, des_ecb2_encrypt()
2876         that only takes 2 des_key_schedules that implements,
2877         C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1.
2878         
2879 void des_cbc_encrypt(
2880 des_cblock *input,
2881 des_cblock *output,
2882 long length,
2883 des_key_schedule ks,
2884 des_cblock *ivec,
2885 int enc);
2886         This routine implements DES in Cipher Block Chaining mode.
2887         Input, which should be a multiple of 8 bytes is encrypted
2888         (or decrypted) to output which will also be a multiple of 8 bytes.
2889         The number of bytes is in length (and from what I've said above,
2890         should be a multiple of 8).  If length is not a multiple of 8, I'm
2891         not being held responsible :-).  ivec is the initialisation vector.
2892         This function does not modify this variable.  To correctly implement
2893         cbc mode, you need to do one of 2 things; copy the last 8 bytes of
2894         cipher text for use as the next ivec in your application,
2895         or use des_ncbc_encrypt(). 
2896         Only this routine has this problem with updating the ivec, all
2897         other routines that are implementing cbc mode update ivec.
2898         
2899 void des_ncbc_encrypt(
2900 des_cblock *input,
2901 des_cblock *output,
2902 long length,
2903 des_key_schedule sk,
2904 des_cblock *ivec,
2905 int enc);
2906         For historical reasons, des_cbc_encrypt() did not update the
2907         ivec with the value requires so that subsequent calls to
2908         des_cbc_encrypt() would 'chain'.  This was needed so that the same
2909         'length' values would not need to be used when decrypting.
2910         des_ncbc_encrypt() does the right thing.  It is the same as
2911         des_cbc_encrypt accept that ivec is updates with the correct value
2912         to pass in subsequent calls to des_ncbc_encrypt().  I advise using
2913         des_ncbc_encrypt() instead of des_cbc_encrypt();
2914
2915 void des_xcbc_encrypt(
2916 des_cblock *input,
2917 des_cblock *output,
2918 long length,
2919 des_key_schedule sk,
2920 des_cblock *ivec,
2921 des_cblock *inw,
2922 des_cblock *outw,
2923 int enc);
2924         This is RSA's DESX mode of DES.  It uses inw and outw to
2925         'whiten' the encryption.  inw and outw are secret (unlike the iv)
2926         and are as such, part of the key.  So the key is sort of 24 bytes.
2927         This is much better than cbc des.
2928         
2929 void des_3cbc_encrypt(
2930 des_cblock *input,
2931 des_cblock *output,
2932 long length,
2933 des_key_schedule sk1,
2934 des_key_schedule sk2,
2935 des_cblock *ivec1,
2936 des_cblock *ivec2,
2937 int enc);
2938         This function is flawed, do not use it.  I have left it in the
2939         library because it is used in my des(1) program and will function
2940         correctly when used by des(1).  If I removed the function, people
2941         could end up unable to decrypt files.
2942         This routine implements outer triple cbc encryption using 2 ks and
2943         2 ivec's.  Use des_ede2_cbc_encrypt() instead.
2944         
2945 void des_ede3_cbc_encrypt(
2946 des_cblock *input,
2947 des_cblock *output, 
2948 long length,
2949 des_key_schedule ks1,
2950 des_key_schedule ks2, 
2951 des_key_schedule ks3, 
2952 des_cblock *ivec,
2953 int enc);
2954         This function implements outer triple CBC DES encryption with 3
2955         keys.  What this means is that each 'DES' operation
2956         inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))).
2957         Again, this is cbc mode so an ivec is requires.
2958         This mode is used by SSL.
2959         There is also a des_ede2_cbc_encrypt() that only uses 2
2960         des_key_schedule's, the first being reused for the final
2961         encryption.  C=E(ks1,D(ks2,E(ks1,M))).  This form of triple DES
2962         is used by the RSAref library.
2963         
2964 void des_pcbc_encrypt(
2965 des_cblock *input,
2966 des_cblock *output,
2967 long length,
2968 des_key_schedule ks,
2969 des_cblock *ivec,
2970 int enc);
2971         This is Propagating Cipher Block Chaining mode of DES.  It is used
2972         by Kerberos v4.  It's parameters are the same as des_ncbc_encrypt().
2973         
2974 void des_cfb_encrypt(
2975 unsigned char *in,
2976 unsigned char *out,
2977 int numbits,
2978 long length,
2979 des_key_schedule ks,
2980 des_cblock *ivec,
2981 int enc);
2982         Cipher Feedback Back mode of DES.  This implementation 'feeds back'
2983         in numbit blocks.  The input (and output) is in multiples of numbits
2984         bits.  numbits should to be a multiple of 8 bits.  Length is the
2985         number of bytes input.  If numbits is not a multiple of 8 bits,
2986         the extra bits in the bytes will be considered padding.  So if
2987         numbits is 12, for each 2 input bytes, the 4 high bits of the
2988         second byte will be ignored.  So to encode 72 bits when using
2989         a numbits of 12 take 12 bytes.  To encode 72 bits when using
2990         numbits of 9 will take 16 bytes.  To encode 80 bits when using
2991         numbits of 16 will take 10 bytes. etc, etc.  This padding will
2992         apply to both input and output.
2993
2994         
2995 void des_cfb64_encrypt(
2996 unsigned char *in,
2997 unsigned char *out,
2998 long length,
2999 des_key_schedule ks,
3000 des_cblock *ivec,
3001 int *num,
3002 int enc);
3003         This is one of the more useful functions in this DES library, it
3004         implements CFB mode of DES with 64bit feedback.  Why is this
3005         useful you ask?  Because this routine will allow you to encrypt an
3006         arbitrary number of bytes, no 8 byte padding.  Each call to this
3007         routine will encrypt the input bytes to output and then update ivec
3008         and num.  num contains 'how far' we are though ivec.  If this does
3009         not make much sense, read more about cfb mode of DES :-).
3010         
3011 void des_ede3_cfb64_encrypt(
3012 unsigned char *in,
3013 unsigned char *out,
3014 long length,
3015 des_key_schedule ks1,
3016 des_key_schedule ks2,
3017 des_key_schedule ks3,
3018 des_cblock *ivec,
3019 int *num,
3020 int enc);
3021         Same as des_cfb64_encrypt() accept that the DES operation is
3022         triple DES.  As usual, there is a macro for
3023         des_ede2_cfb64_encrypt() which reuses ks1.
3024
3025 void des_ofb_encrypt(
3026 unsigned char *in,
3027 unsigned char *out,
3028 int numbits,
3029 long length,
3030 des_key_schedule ks,
3031 des_cblock *ivec);
3032         This is a implementation of Output Feed Back mode of DES.  It is
3033         the same as des_cfb_encrypt() in that numbits is the size of the
3034         units dealt with during input and output (in bits).
3035         
3036 void des_ofb64_encrypt(
3037 unsigned char *in,
3038 unsigned char *out,
3039 long length,
3040 des_key_schedule ks,
3041 des_cblock *ivec,
3042 int *num);
3043         The same as des_cfb64_encrypt() except that it is Output Feed Back
3044         mode.
3045
3046 void des_ede3_ofb64_encrypt(
3047 unsigned char *in,
3048 unsigned char *out,
3049 long length,
3050 des_key_schedule ks1,
3051 des_key_schedule ks2,
3052 des_key_schedule ks3,
3053 des_cblock *ivec,
3054 int *num);
3055         Same as des_ofb64_encrypt() accept that the DES operation is
3056         triple DES.  As usual, there is a macro for
3057         des_ede2_ofb64_encrypt() which reuses ks1.
3058
3059 int des_read_pw_string(
3060 char *buf,
3061 int length,
3062 char *prompt,
3063 int verify);
3064         This routine is used to get a password from the terminal with echo
3065         turned off.  Buf is where the string will end up and length is the
3066         size of buf.  Prompt is a string presented to the 'user' and if
3067         verify is set, the key is asked for twice and unless the 2 copies
3068         match, an error is returned.  A return code of -1 indicates a
3069         system error, 1 failure due to use interaction, and 0 is success.
3070
3071 unsigned long des_cbc_cksum(
3072 des_cblock *input,
3073 des_cblock *output,
3074 long length,
3075 des_key_schedule ks,
3076 des_cblock *ivec);
3077         This function produces an 8 byte checksum from input that it puts in
3078         output and returns the last 4 bytes as a long.  The checksum is
3079         generated via cbc mode of DES in which only the last 8 byes are
3080         kept.  I would recommend not using this function but instead using
3081         the EVP_Digest routines, or at least using MD5 or SHA.  This
3082         function is used by Kerberos v4 so that is why it stays in the
3083         library.
3084         
3085 char *des_fcrypt(
3086 const char *buf,
3087 const char *salt
3088 char *ret);
3089         This is my fast version of the unix crypt(3) function.  This version
3090         takes only a small amount of space relative to other fast
3091         crypt() implementations.  This is different to the normal crypt
3092         in that the third parameter is the buffer that the return value
3093         is written into.  It needs to be at least 14 bytes long.  This
3094         function is thread safe, unlike the normal crypt.
3095
3096 char *crypt(
3097 const char *buf,
3098 const char *salt);
3099         This function calls des_fcrypt() with a static array passed as the
3100         third parameter.  This emulates the normal non-thread safe semantics
3101         of crypt(3).
3102
3103 void des_string_to_key(
3104 char *str,
3105 des_cblock *key);
3106         This function takes str and converts it into a DES key.  I would
3107         recommend using MD5 instead and use the first 8 bytes of output.
3108         When I wrote the first version of these routines back in 1990, MD5
3109         did not exist but I feel these routines are still sound.  This
3110         routines is compatible with the one in MIT's libdes.
3111         
3112 void des_string_to_2keys(
3113 char *str,
3114 des_cblock *key1,
3115 des_cblock *key2);
3116         This function takes str and converts it into 2 DES keys.
3117         I would recommend using MD5 and using the 16 bytes as the 2 keys.
3118         I have nothing against these 2 'string_to_key' routines, it's just
3119         that if you say that your encryption key is generated by using the
3120         16 bytes of an MD5 hash, every-one knows how you generated your
3121         keys.
3122
3123 int des_read_password(
3124 des_cblock *key,
3125 char *prompt,
3126 int verify);
3127         This routine combines des_read_pw_string() with des_string_to_key().
3128
3129 int des_read_2passwords(
3130 des_cblock *key1,
3131 des_cblock *key2,
3132 char *prompt,
3133 int verify);
3134         This routine combines des_read_pw_string() with des_string_to_2key().
3135
3136 void des_random_seed(
3137 des_cblock key);
3138         This routine sets a starting point for des_random_key().
3139         
3140 void des_random_key(
3141 des_cblock ret);
3142         This function return a random key.  Make sure to 'seed' the random
3143         number generator (with des_random_seed()) before using this function.
3144         I personally now use a MD5 based random number system.
3145
3146 int des_enc_read(
3147 int fd,
3148 char *buf,
3149 int len,
3150 des_key_schedule ks,
3151 des_cblock *iv);
3152         This function will write to a file descriptor the encrypted data
3153         from buf.  This data will be preceded by a 4 byte 'byte count' and
3154         will be padded out to 8 bytes.  The encryption is either CBC of
3155         PCBC depending on the value of des_rw_mode.  If it is DES_PCBC_MODE,
3156         pcbc is used, if DES_CBC_MODE, cbc is used.  The default is to use
3157         DES_PCBC_MODE.
3158
3159 int des_enc_write(
3160 int fd,
3161 char *buf,
3162 int len,
3163 des_key_schedule ks,
3164 des_cblock *iv);
3165         This routines read stuff written by des_enc_read() and decrypts it.
3166         I have used these routines quite a lot but I don't believe they are
3167         suitable for non-blocking io.  If you are after a full
3168         authentication/encryption over networks, have a look at SSL instead.
3169
3170 unsigned long des_quad_cksum(
3171 des_cblock *input,
3172 des_cblock *output,
3173 long length,
3174 int out_count,
3175 des_cblock *seed);
3176         This is a function from Kerberos v4 that is not anything to do with
3177         DES but was needed.  It is a cksum that is quicker to generate than
3178         des_cbc_cksum();  I personally would use MD5 routines now.
3179 =====
3180 Modes of DES
3181 Quite a bit of the following information has been taken from
3182         AS 2805.5.2
3183         Australian Standard
3184         Electronic funds transfer - Requirements for interfaces,
3185         Part 5.2: Modes of operation for an n-bit block cipher algorithm
3186         Appendix A
3187
3188 There are several different modes in which DES can be used, they are
3189 as follows.
3190
3191 Electronic Codebook Mode (ECB) (des_ecb_encrypt())
3192 - 64 bits are enciphered at a time.
3193 - The order of the blocks can be rearranged without detection.
3194 - The same plaintext block always produces the same ciphertext block
3195   (for the same key) making it vulnerable to a 'dictionary attack'.
3196 - An error will only affect one ciphertext block.
3197
3198 Cipher Block Chaining Mode (CBC) (des_cbc_encrypt())
3199 - a multiple of 64 bits are enciphered at a time.
3200 - The CBC mode produces the same ciphertext whenever the same
3201   plaintext is encrypted using the same key and starting variable.
3202 - The chaining operation makes the ciphertext blocks dependent on the
3203   current and all preceding plaintext blocks and therefore blocks can not
3204   be rearranged.
3205 - The use of different starting variables prevents the same plaintext
3206   enciphering to the same ciphertext.
3207 - An error will affect the current and the following ciphertext blocks.
3208
3209 Cipher Feedback Mode (CFB) (des_cfb_encrypt())
3210 - a number of bits (j) <= 64 are enciphered at a time.
3211 - The CFB mode produces the same ciphertext whenever the same
3212   plaintext is encrypted using the same key and starting variable.
3213 - The chaining operation makes the ciphertext variables dependent on the
3214   current and all preceding variables and therefore j-bit variables are
3215   chained together and can not be rearranged.
3216 - The use of different starting variables prevents the same plaintext
3217   enciphering to the same ciphertext.
3218 - The strength of the CFB mode depends on the size of k (maximal if
3219   j == k).  In my implementation this is always the case.
3220 - Selection of a small value for j will require more cycles through
3221   the encipherment algorithm per unit of plaintext and thus cause
3222   greater processing overheads.
3223 - Only multiples of j bits can be enciphered.
3224 - An error will affect the current and the following ciphertext variables.
3225
3226 Output Feedback Mode (OFB) (des_ofb_encrypt())
3227 - a number of bits (j) <= 64 are enciphered at a time.
3228 - The OFB mode produces the same ciphertext whenever the same
3229   plaintext enciphered using the same key and starting variable.  More
3230   over, in the OFB mode the same key stream is produced when the same
3231   key and start variable are used.  Consequently, for security reasons
3232   a specific start variable should be used only once for a given key.
3233 - The absence of chaining makes the OFB more vulnerable to specific attacks.
3234 - The use of different start variables values prevents the same
3235   plaintext enciphering to the same ciphertext, by producing different
3236   key streams.
3237 - Selection of a small value for j will require more cycles through
3238   the encipherment algorithm per unit of plaintext and thus cause
3239   greater processing overheads.
3240 - Only multiples of j bits can be enciphered.
3241 - OFB mode of operation does not extend ciphertext errors in the
3242   resultant plaintext output.  Every bit error in the ciphertext causes
3243   only one bit to be in error in the deciphered plaintext.
3244 - OFB mode is not self-synchronising.  If the two operation of
3245   encipherment and decipherment get out of synchronism, the system needs
3246   to be re-initialised.
3247 - Each re-initialisation should use a value of the start variable
3248  different from the start variable values used before with the same
3249  key.  The reason for this is that an identical bit stream would be
3250  produced each time from the same parameters.  This would be
3251  susceptible to a ' known plaintext' attack.
3252
3253 Triple ECB Mode (des_ecb3_encrypt())
3254 - Encrypt with key1, decrypt with key2 and encrypt with key3 again.
3255 - As for ECB encryption but increases the key length to 168 bits.
3256   There are theoretic attacks that can be used that make the effective
3257   key length 112 bits, but this attack also requires 2^56 blocks of
3258   memory, not very likely, even for the NSA.
3259 - If both keys are the same it is equivalent to encrypting once with
3260   just one key.
3261 - If the first and last key are the same, the key length is 112 bits.
3262   There are attacks that could reduce the key space to 55 bit's but it
3263   requires 2^56 blocks of memory.
3264 - If all 3 keys are the same, this is effectively the same as normal
3265   ecb mode.
3266
3267 Triple CBC Mode (des_ede3_cbc_encrypt())
3268 - Encrypt with key1, decrypt with key2 and then encrypt with key3.
3269 - As for CBC encryption but increases the key length to 168 bits with
3270   the same restrictions as for triple ecb mode.
3271
3272 ==== digest.doc ========================================================
3273
3274
3275 The Message Digest subroutines.
3276
3277 These routines require "evp.h" to be included.
3278
3279 These functions are a higher level interface to the various message digest
3280 routines found in this library.  As such, they allow the same code to be
3281 used to digest via different algorithms with only a change in an initial
3282 parameter.  They are basically just a front-end to the MD2, MD5, SHA
3283 and SHA1
3284 routines.
3285
3286 These routines all take a pointer to the following structure to specify
3287 which message digest algorithm to use.
3288 typedef struct evp_md_st
3289         {
3290         int type;
3291         int pkey_type;
3292         int md_size;
3293         void (*init)();
3294         void (*update)();
3295         void (*final)();
3296
3297         int required_pkey_type; /*EVP_PKEY_xxx */
3298         int (*sign)();
3299         int (*verify)();
3300         } EVP_MD;
3301
3302 If additional message digest algorithms are to be supported, a structure of
3303 this type needs to be declared and populated and then the Digest routines
3304 can be used with that algorithm.  The type field is the object NID of the
3305 digest type (read the section on Objects for an explanation).  The pkey_type
3306 is the Object type to use when the a message digest is generated by there
3307 routines and then is to be signed with the pkey algorithm.  Md_size is
3308 the size of the message digest returned.  Init, update
3309 and final are the relevant functions to perform the message digest function
3310 by parts.  One reason for specifying the message digest to use via this
3311 mechanism is that if you only use md5, only the md5 routines will
3312 be included in you linked program.  If you passed an integer
3313 that specified which message digest to use, the routine that mapped that
3314 integer to a set of message digest functions would cause all the message
3315 digests functions to be link into the code.  This setup also allows new
3316 message digest functions to be added by the application.
3317
3318 The six message digests defined in this library are
3319
3320 EVP_MD *EVP_md2(void);  /* RSA sign/verify */
3321 EVP_MD *EVP_md5(void);  /* RSA sign/verify */
3322 EVP_MD *EVP_sha(void);  /* RSA sign/verify */
3323 EVP_MD *EVP_sha1(void); /* RSA sign/verify */
3324 EVP_MD *EVP_dss(void);  /* DSA sign/verify */
3325 EVP_MD *EVP_dss1(void); /* DSA sign/verify */
3326
3327 All the message digest routines take a EVP_MD_CTX pointer as an argument.
3328 The state of the message digest is kept in this structure.
3329
3330 typedef struct pem_md_ctx_st
3331         {
3332         EVP_MD *digest;
3333         union   {
3334                 unsigned char base[4]; /* this is used in my library as a
3335                                         * 'pointer' to all union elements
3336                                         * structures. */
3337                 MD2_CTX md2;
3338                 MD5_CTX md5;
3339                 SHA_CTX sha;
3340                 } md;
3341         } EVP_MD_CTX;
3342
3343 The Digest functions are as follows.
3344
3345 void EVP_DigestInit(
3346 EVP_MD_CTX *ctx,
3347 EVP_MD *type);
3348         This function is used to initialise the EVP_MD_CTX.  The message
3349         digest that will associated with 'ctx' is specified by 'type'.
3350
3351 void EVP_DigestUpdate(
3352 EVP_MD_CTX *ctx,
3353 unsigned char *data,
3354 unsigned int cnt);
3355         This function is used to pass more data to the message digest
3356         function.  'cnt' bytes are digested from 'data'.
3357
3358 void EVP_DigestFinal(
3359 EVP_MD_CTX *ctx,
3360 unsigned char *md,
3361 unsigned int *len);
3362         This function finishes the digestion and puts the message digest
3363         into 'md'.  The length of the message digest is put into len;
3364         EVP_MAX_MD_SIZE is the size of the largest message digest that
3365         can be returned from this function.  Len can be NULL if the
3366         size of the digest is not required.
3367         
3368
3369 ==== encode.doc ========================================================
3370
3371
3372 void    EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
3373 void    EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,
3374                 int *outl,unsigned char *in,int inl);
3375 void    EVP_EncodeFinal(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl);
3376 int     EVP_EncodeBlock(unsigned char *t, unsigned char *f, int n);
3377
3378 void    EVP_DecodeInit(EVP_ENCODE_CTX *ctx);
3379 int     EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl,
3380                 unsigned char *in, int inl);
3381 int     EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned
3382                 char *out, int *outl);
3383 int     EVP_DecodeBlock(unsigned char *t, unsigned
3384                 char *f, int n);
3385
3386
3387 ==== envelope.doc ========================================================
3388
3389 The following routines are use to create 'digital' envelopes.
3390 By this I mean that they perform various 'higher' level cryptographic
3391 functions.  Have a read of 'cipher.doc' and 'digest.doc' since those
3392 routines are used by these functions.
3393 cipher.doc contains documentation about the cipher part of the
3394 envelope library and digest.doc contatins the description of the
3395 message digests supported.
3396
3397 To 'sign' a document involves generating a message digest and then encrypting
3398 the digest with an private key.
3399
3400 #define EVP_SignInit(a,b)               EVP_DigestInit(a,b)
3401 #define EVP_SignUpdate(a,b,c)           EVP_DigestUpdate(a,b,c)
3402 Due to the fact this operation is basically just an extended message
3403 digest, the first 2 functions are macro calls to Digest generating
3404 functions.
3405
3406 int     EVP_SignFinal(
3407 EVP_MD_CTX *ctx,
3408 unsigned char *md,
3409 unsigned int *s,
3410 EVP_PKEY *pkey);
3411         This finalisation function finishes the generation of the message
3412 digest and then encrypts the digest (with the correct message digest 
3413 object identifier) with the EVP_PKEY private key.  'ctx' is the message digest
3414 context.  'md' will end up containing the encrypted message digest.  This
3415 array needs to be EVP_PKEY_size(pkey) bytes long.  's' will actually
3416 contain the exact length.  'pkey' of course is the private key.  It is
3417 one of EVP_PKEY_RSA or EVP_PKEY_DSA type.
3418 If there is an error, 0 is returned, otherwise 1.
3419                 
3420 Verify is used to check an signed message digest.
3421
3422 #define EVP_VerifyInit(a,b)             EVP_DigestInit(a,b)
3423 #define EVP_VerifyUpdate(a,b,c)         EVP_DigestUpdate(a,b,c)
3424 Since the first step is to generate a message digest, the first 2 functions
3425 are macros.
3426
3427 int EVP_VerifyFinal(
3428 EVP_MD_CTX *ctx,
3429 unsigned char *md,
3430 unsigned int s,
3431 EVP_PKEY *pkey);
3432         This function finishes the generation of the message digest and then
3433 compares it with the supplied encrypted message digest.  'md' contains the
3434 's' bytes of encrypted message digest.  'pkey' is used to public key decrypt
3435 the digest.  It is then compared with the message digest just generated.
3436 If they match, 1 is returned else 0.
3437
3438 int     EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek,
3439                 int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk);
3440 Must have at least one public key, error is 0.  I should also mention that
3441 the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size.
3442
3443 #define EVP_SealUpdate(a,b,c,d,e)       EVP_EncryptUpdate(a,b,c,d,e)    
3444 void    EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl);
3445
3446
3447 int     EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek,
3448                 int ekl,unsigned char *iv,EVP_PKEY *priv);
3449 0 on failure
3450
3451 #define EVP_OpenUpdate(a,b,c,d,e)       EVP_DecryptUpdate(a,b,c,d,e)
3452
3453 int     EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
3454 Decrypt final return code
3455
3456
3457 ==== error.doc ========================================================
3458
3459 The error routines.
3460
3461 The 'error' system I've implemented is intended to server 2 purpose, to
3462 record the reason why a command failed and to record where in the libraries
3463 the failure occurred.  It is more or less setup to record a 'trace' of which
3464 library components were being traversed when the error occurred.
3465
3466 When an error is recorded, it is done so a as single unsigned long which is
3467 composed of three parts.  The top byte is the 'library' number, the middle
3468 12 bytes is the function code, and the bottom 12 bits is the 'reason' code.
3469
3470 Each 'library', or should a say, 'section' of the SSLeay library has a
3471 different unique 'library' error number.  Each function in the library has
3472 a number that is unique for that library.  Each 'library' also has a number
3473 for each 'error reason' that is only unique for that 'library'.
3474
3475 Due to the way these error routines record a 'error trace', there is an
3476 array per thread that is used to store the error codes.
3477 The various functions in this library are used to access
3478 and manipulate this array.
3479
3480 void ERR_put_error(int lib, int func,int reason);
3481         This routine records an error in library 'lib', function 'func'
3482 and reason 'reason'.  As errors get 'put' into the buffer, they wrap
3483 around and overwrite old errors if too many are written.  It is assumed
3484 that the last errors are the most important.
3485
3486 unsigned long ERR_get_error(void );
3487         This function returns the last error added to the error buffer.
3488 In effect it is popping the value off the buffer so repeated calls will
3489 continue to return values until there are no more errors to return in which
3490 case 0 is returned.
3491
3492 unsigned long ERR_peek_error(void );
3493         This function returns the value of the last error added to the
3494 error buffer but does not 'pop' it from the buffer.
3495
3496 void ERR_clear_error(void );
3497         This function clears the error buffer, discarding all unread
3498 errors.
3499
3500 While the above described error system obviously produces lots of different
3501 error number, a method for 'reporting' these errors in a human readable
3502 form is required.  To achieve this, each library has the option of
3503 'registering' error strings.
3504
3505 typedef struct ERR_string_data_st
3506         {
3507         unsigned long error;
3508         char *string;
3509         } ERR_STRING_DATA;
3510
3511 The 'ERR_STRING_DATA' contains an error code and the corresponding text
3512 string.  To add new function error strings for a library, the
3513 ERR_STRING_DATA needs to be 'registered' with the library.
3514
3515 void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err);
3516         This function 'registers' the array of ERR_STRING_DATA pointed to by
3517 'err' as error text strings for the error library 'lib'.
3518
3519 void ERR_free_strings(void);
3520         This function free()s all the loaded error strings.
3521
3522 char *ERR_error_string(unsigned long error,char *buf);
3523         This function returns a text string that is a human readable
3524 version of the error represented by 'error'.  Buff should be at least 120
3525 bytes long and if it is NULL, the return value is a pointer to a static
3526 variable that will contain the error string, otherwise 'buf' is returned.
3527 If there is not a text string registered for a particular error, a text
3528 string containing the error number is returned instead.
3529
3530 void ERR_print_errors(BIO *bp);
3531 void ERR_print_errors_fp(FILE *fp);
3532         This function is a convenience routine that prints the error string
3533 for each error until all errors have been accounted for.
3534
3535 char *ERR_lib_error_string(unsigned long e);
3536 char *ERR_func_error_string(unsigned long e);
3537 char *ERR_reason_error_string(unsigned long e);
3538 The above three functions return the 3 different components strings for the
3539 error 'e'.  ERR_error_string() uses these functions.
3540
3541 void ERR_load_ERR_strings(void );
3542         This function 'registers' the error strings for the 'ERR' module.
3543
3544 void ERR_load_crypto_strings(void );
3545         This function 'register' the error strings for just about every
3546 library in the SSLeay package except for the SSL routines.  There is no
3547 need to ever register any error text strings and you will probably save in
3548 program size.  If on the other hand you do 'register' all errors, it is
3549 quite easy to determine why a particular routine failed.
3550
3551 As a final footnote as to why the error system is designed as it is.
3552 1) I did not want a single 'global' error code.
3553 2) I wanted to know which subroutine a failure occurred in.
3554 3) For Windows NT etc, it should be simple to replace the 'key' routines
3555    with code to pass error codes back to the application.
3556 4) I wanted the option of meaningful error text strings.
3557
3558 Late breaking news - the changes to support threads.
3559
3560 Each 'thread' has an 'ERR_STATE' state associated with it.
3561 ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling
3562 thread/process.
3563
3564 ERR_remove_state(unsigned long pid); will 'free()' this state.  If pid == 0
3565 the current 'thread/process' will have it's error state removed.
3566 If you do not remove the error state of a thread, this could be considered a
3567 form of memory leak, so just after 'reaping' a thread that has died,
3568 call ERR_remove_state(pid).
3569
3570 Have a read of thread.doc for more details for what is required for
3571 multi-threading support.  All the other error routines will
3572 work correctly when using threads.
3573
3574
3575 ==== idea.doc ========================================================
3576
3577 The IDEA library.
3578 IDEA is a block cipher that operates on 64bit (8 byte) quantities.  It
3579 uses a 128bit (16 byte) key.  It can be used in all the modes that DES can
3580 be used.  This library implements the ecb, cbc, cfb64 and ofb64 modes.
3581
3582 For all calls that have an 'input' and 'output' variables, they can be the
3583 same.
3584
3585 This library requires the inclusion of 'idea.h'.
3586
3587 All of the encryption functions take what is called an IDEA_KEY_SCHEDULE as an 
3588 argument.  An IDEA_KEY_SCHEDULE is an expanded form of the idea key.
3589 For all modes of the IDEA algorithm, the IDEA_KEY_SCHEDULE used for
3590 decryption is different to the one used for encryption.
3591
3592 The define IDEA_ENCRYPT is passed to specify encryption for the functions
3593 that require an encryption/decryption flag. IDEA_DECRYPT is passed to
3594 specify decryption.  For some mode there is no encryption/decryption
3595 flag since this is determined by the IDEA_KEY_SCHEDULE.
3596
3597 So to encrypt you would do the following
3598 idea_set_encrypt_key(key,encrypt_ks);
3599 idea_ecb_encrypt(...,encrypt_ks);
3600 idea_cbc_encrypt(....,encrypt_ks,...,IDEA_ENCRYPT);
3601
3602 To Decrypt
3603 idea_set_encrypt_key(key,encrypt_ks);
3604 idea_set_decrypt_key(encrypt_ks,decrypt_ks);
3605 idea_ecb_encrypt(...,decrypt_ks);
3606 idea_cbc_encrypt(....,decrypt_ks,...,IDEA_DECRYPT);
3607
3608 Please note that any of the encryption modes specified in my DES library
3609 could be used with IDEA.  I have only implemented ecb, cbc, cfb64 and
3610 ofb64 for the following reasons.
3611 - ecb is the basic IDEA encryption.
3612 - cbc is the normal 'chaining' form for block ciphers.
3613 - cfb64 can be used to encrypt single characters, therefore input and output
3614   do not need to be a multiple of 8.
3615 - ofb64 is similar to cfb64 but is more like a stream cipher, not as
3616   secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
3617 - If you want triple IDEA, thats 384 bits of key and you must be totally
3618   obsessed with security.  Still, if you want it, it is simple enough to
3619   copy the function from the DES library and change the des_encrypt to
3620   idea_encrypt; an exercise left for the paranoid reader :-).
3621
3622 The functions are as follows:
3623
3624 void idea_set_encrypt_key(
3625 unsigned char *key;
3626 IDEA_KEY_SCHEDULE *ks);
3627         idea_set_encrypt_key converts a 16 byte IDEA key into an
3628         IDEA_KEY_SCHEDULE.  The IDEA_KEY_SCHEDULE is an expanded form of
3629         the key which can be used to perform IDEA encryption.
3630         An IDEA_KEY_SCHEDULE is an expanded form of the key which is used to
3631         perform actual encryption.  It can be regenerated from the IDEA key
3632         so it only needs to be kept when encryption is about
3633         to occur.  Don't save or pass around IDEA_KEY_SCHEDULE's since they
3634         are CPU architecture dependent, IDEA keys are not.
3635         
3636 void idea_set_decrypt_key(
3637 IDEA_KEY_SCHEDULE *encrypt_ks,
3638 IDEA_KEY_SCHEDULE *decrypt_ks);
3639         This functions converts an encryption IDEA_KEY_SCHEDULE into a
3640         decryption IDEA_KEY_SCHEDULE.  For all decryption, this conversion
3641         of the key must be done.  In some modes of IDEA, an
3642         encryption/decryption flag is also required, this is because these
3643         functions involve block chaining and the way this is done changes
3644         depending on which of encryption of decryption is being done.
3645         Please note that there is no quick way to generate the decryption
3646         key schedule other than generating the encryption key schedule and
3647         then converting it.
3648
3649 void idea_encrypt(
3650 unsigned long *data,
3651 IDEA_KEY_SCHEDULE *ks);
3652         This is the IDEA encryption function that gets called by just about
3653         every other IDEA routine in the library.  You should not use this
3654         function except to implement 'modes' of IDEA.  I say this because the
3655         functions that call this routine do the conversion from 'char *' to
3656         long, and this needs to be done to make sure 'non-aligned' memory
3657         access do not occur.
3658         Data is a pointer to 2 unsigned long's and ks is the
3659         IDEA_KEY_SCHEDULE to use.  Encryption or decryption depends on the
3660         IDEA_KEY_SCHEDULE.
3661
3662 void idea_ecb_encrypt(
3663 unsigned char *input,
3664 unsigned char *output,
3665 IDEA_KEY_SCHEDULE *ks);
3666         This is the basic Electronic Code Book form of IDEA (in DES this
3667         mode is called Electronic Code Book so I'm going to use the term
3668         for idea as well :-).
3669         Input is encrypted into output using the key represented by
3670         ks.  Depending on the IDEA_KEY_SCHEDULE, encryption or
3671         decryption occurs.  Input is 8 bytes long and output is 8 bytes.
3672         
3673 void idea_cbc_encrypt(
3674 unsigned char *input,
3675 unsigned char *output,
3676 long length,
3677 IDEA_KEY_SCHEDULE *ks,
3678 unsigned char *ivec,
3679 int enc);
3680         This routine implements IDEA in Cipher Block Chaining mode.
3681         Input, which should be a multiple of 8 bytes is encrypted
3682         (or decrypted) to output which will also be a multiple of 8 bytes.
3683         The number of bytes is in length (and from what I've said above,
3684         should be a multiple of 8).  If length is not a multiple of 8, bad 
3685         things will probably happen.  ivec is the initialisation vector.
3686         This function updates iv after each call so that it can be passed to
3687         the next call to idea_cbc_encrypt().
3688         
3689 void idea_cfb64_encrypt(
3690 unsigned char *in,
3691 unsigned char *out,
3692 long length,
3693 des_key_schedule ks,
3694 des_cblock *ivec,
3695 int *num,
3696 int enc);
3697         This is one of the more useful functions in this IDEA library, it
3698         implements CFB mode of IDEA with 64bit feedback.
3699         This allows you to encrypt an arbitrary number of bytes,
3700         you do not require 8 byte padding.  Each call to this
3701         routine will encrypt the input bytes to output and then update ivec
3702         and num.  Num contains 'how far' we are though ivec.
3703         Enc is used to indicate encryption or decryption.
3704         One very important thing to remember is that when decrypting, use
3705         the encryption form of the key.
3706         CFB64 mode operates by using the cipher to
3707         generate a stream of bytes which is used to encrypt the plain text.
3708         The cipher text is then encrypted to generate the next 64 bits to
3709         be xored (incrementally) with the next 64 bits of plain
3710         text.  As can be seen from this, to encrypt or decrypt,
3711         the same 'cipher stream' needs to be generated but the way the next
3712         block of data is gathered for encryption is different for
3713         encryption and decryption.  What this means is that to encrypt
3714         idea_set_encrypt_key(key,ks);
3715         idea_cfb64_encrypt(...,ks,..,IDEA_ENCRYPT)
3716         do decrypt
3717         idea_set_encrypt_key(key,ks)
3718         idea_cfb64_encrypt(...,ks,...,IDEA_DECRYPT)
3719         Note: The same IDEA_KEY_SCHEDULE but different encryption flags.
3720         For idea_cbc or idea_ecb, idea_set_decrypt_key() would need to be
3721         used to generate the IDEA_KEY_SCHEDULE for decryption.
3722         The reason I'm stressing this point is that I just wasted 3 hours
3723         today trying to decrypt using this mode and the decryption form of
3724         the key :-(.
3725         
3726 void idea_ofb64_encrypt(
3727 unsigned char *in,
3728 unsigned char *out,
3729 long length,
3730 des_key_schedule ks,
3731 des_cblock *ivec,
3732 int *num);
3733         This functions implements OFB mode of IDEA with 64bit feedback.
3734         This allows you to encrypt an arbitrary number of bytes,
3735         you do not require 8 byte padding.  Each call to this
3736         routine will encrypt the input bytes to output and then update ivec
3737         and num.  Num contains 'how far' we are though ivec.
3738         This is in effect a stream cipher, there is no encryption or
3739         decryption mode.  The same key and iv should be used to
3740         encrypt and decrypt.
3741         
3742 For reading passwords, I suggest using des_read_pw_string() from my DES library.
3743 To generate a password from a text string, I suggest using MD5 (or MD2) to
3744 produce a 16 byte message digest that can then be passed directly to
3745 idea_set_encrypt_key().
3746
3747 =====
3748 For more information about the specific IDEA modes in this library
3749 (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
3750 documentation on my DES library.  What is said about DES is directly
3751 applicable for IDEA.
3752
3753
3754 ==== legal.doc ========================================================
3755
3756 From eay@mincom.com Thu Jun 27 00:25:45 1996
3757 Received: by orb.mincom.oz.au id AA15821
3758   (5.65c/IDA-1.4.4 for eay); Wed, 26 Jun 1996 14:25:45 +1000
3759 Date: Wed, 26 Jun 1996 14:25:45 +1000 (EST)
3760 From: Eric Young <eay@mincom.oz.au>
3761 X-Sender: eay@orb
3762 To: Ken Toll <ktoll@ren.digitalage.com>
3763 Cc: Eric Young <eay@mincom.oz.au>, ssl-talk@netscape.com
3764 Subject: Re: Unidentified subject!
3765 In-Reply-To: <9606261950.ZM28943@ren.digitalage.com>
3766 Message-Id: <Pine.SOL.3.91.960626131156.28573K-100000@orb>
3767 Mime-Version: 1.0
3768 Content-Type: TEXT/PLAIN; charset=US-ASCII
3769 Status: O
3770 X-Status: 
3771
3772
3773 This is a little off topic but since SSLeay is a free implementation of
3774 the SSLv2 protocol, I feel it is worth responding on the topic of if it 
3775 is actually legal for Americans to use free cryptographic software.
3776
3777 On Wed, 26 Jun 1996, Ken Toll wrote:
3778 > Is the U.S the only country that SSLeay cannot be used commercially 
3779 > (because of RSAref) or is that going to be an issue with every country 
3780 > that a client/server application (non-web browser/server) is deployed 
3781 > and sold?
3782
3783 >From what I understand, the software patents that apply to algorithms 
3784 like RSA and DH only apply in the USA.  The IDEA algorithm I believe is 
3785 patened in europe (USA?), but considing how little it is used by other SSL 
3786 implementations, it quite easily be left out of the SSLeay build
3787 (this can be done with a compile flag).
3788
3789 Actually if the RSA patent did apply outside the USA, it could be rather
3790 interesting since RSA is not alowed to let RSA toolkits outside of the USA
3791 [1], and since these are the only forms that they will alow the algorithm
3792 to be used in, it would mean that non-one outside of the USA could produce
3793 public key software which would be a very strong statment for
3794 international patent law to make :-).  This logic is a little flawed but
3795 it still points out some of the more interesting permutations of USA
3796 patent law and ITAR restrictions. 
3797
3798 Inside the USA there is also the unresolved issue of RC4/RC2 which were
3799 made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2).  I have
3800 copies of the origional postings if people are interested.  RSA I believe 
3801 claim that they were 'trade-secrets' and that some-one broke an NDA in 
3802 revealing them.  Other claim they reverse engineered the algorithms from 
3803 compiled binaries.  If the algorithms were reverse engineered, I believe 
3804 RSA had no legal leg to stand on.  If an NDA was broken, I don't know.
3805 Regardless, RSA, I believe, is willing to go to court over the issue so 
3806 licencing is probably the best idea, or at least talk to them.
3807 If there are people who actually know more about this, pease let me know, I 
3808 don't want to vilify or spread miss-information if I can help it.
3809
3810 If you are not producing a web browser, it is easy to build SSLeay with
3811 RC2/RC4 removed. Since RC4 is the defacto standard cipher in 
3812 all web software (and it is damn fast) it is more or less required for 
3813 www use. For non www use of SSL, especially for an application where 
3814 interoperability with other vendors is not critical just leave it out.
3815
3816 Removing IDEA, RC2 and RC4 would only leave DES and Triple DES but 
3817 they should be ok.  Considing that Triple DES can encrypt at rates of
3818 410k/sec on a pentium 100, and 940k/sec on a P6/200, this is quite 
3819 reasonable performance.  Single DES clocks in at 1160k/s and 2467k/s
3820 respectivly is actually quite fast for those not so paranoid (56 bit key).[1]
3821
3822 > Is it possible to get a certificate for commercial use outside of the U.S.?
3823 yes.
3824
3825 Thawte Consulting issues certificates (they are the people who sell the
3826         Sioux httpd server and are based in South Africa)
3827 Verisign will issue certificates for Sioux (sold from South Africa), so this
3828         proves that they will issue certificate for OS use if they are
3829         happy with the quality of the software.
3830
3831 (The above mentioned companies just the ones that I know for sure are issuing
3832  certificates outside the USA).
3833
3834 There is always the point that if you are using SSL for an intra net, 
3835 SSLeay provides programs that can be used so you can issue your own 
3836 certificates.  They need polishing but at least it is a good starting point.
3837
3838 I am not doing anything outside Australian law by implementing these
3839 algorithms (to the best of my knowedge).  It is another example of how 
3840 the world legal system does not cope with the internet very well.
3841
3842 I may start making shared libraries available (I have now got DLL's for 
3843 Windows).  This will mean that distributions into the usa could be 
3844 shipped with a version with a reduced cipher set and the versions outside 
3845 could use the DLL/shared library with all the ciphers (and without RSAref).
3846
3847 This could be completly hidden from the application, so this would not 
3848 even require a re-linking.
3849
3850 This is the reverse of what people were talking about doing to get around 
3851 USA export regulations :-)
3852
3853 eric
3854
3855 [1]:    The RSAref2.0 tookit is available on at least 3 ftp sites in Europe
3856         and one in South Africa.
3857
3858 [2]:    Since I always get questions when I post benchmark numbers :-),
3859         DES performace figures are in 1000's of bytes per second in cbc 
3860         mode using an 8192 byte buffer.  The pentium 100 was running Windows NT 
3861         3.51 DLLs and the 686/200 was running NextStep.
3862         I quote pentium 100 benchmarks because it is basically the
3863         'entry level' computer that most people buy for personal use.
3864         Windows 95 is the OS shipping on those boxes, so I'll give
3865         NT numbers (the same Win32 runtime environment).  The 686
3866         numbers are present as an indication of where we will be in a
3867         few years.
3868 --
3869 Eric Young                  | BOOL is tri-state according to Bill Gates.
3870 AARNet: eay@mincom.oz.au    | RTFM Win32 GetMessage().
3871
3872
3873
3874 ==== lhash.doc ========================================================
3875
3876 The LHASH library.
3877
3878 I wrote this library in 1991 and have since forgotten why I called it lhash.
3879 It implements a hash table from an article I read at the
3880 time from 'Communications of the ACM'.  What makes this hash
3881 table different is that as the table fills, the hash table is
3882 increased (or decreased) in size via realloc().
3883 When a 'resize' is done, instead of all hashes being redistributed over
3884 twice as many 'buckets', one bucket is split.  So when an 'expand' is done,
3885 there is only a minimal cost to redistribute some values.  Subsequent
3886 inserts will cause more single 'bucket' redistributions but there will
3887 never be a sudden large cost due to redistributing all the 'buckets'.
3888
3889 The state for a particular hash table is kept in the LHASH structure.
3890 The LHASH structure also records statistics about most aspects of accessing
3891 the hash table.  This is mostly a legacy of my writing this library for
3892 the reasons of implementing what looked like a nice algorithm rather than
3893 for a particular software product.
3894
3895 Internal stuff you probably don't want to know about.
3896 The decision to increase or decrease the hash table size is made depending
3897 on the 'load' of the hash table.  The load is the number of items in the
3898 hash table divided by the size of the hash table.  The default values are
3899 as follows.  If (hash->up_load < load) => expand.
3900 if (hash->down_load > load) =>  contract.  The 'up_load' has a default value of
3901 1 and 'down_load' has a default value of 2.  These numbers can be modified
3902 by the application by just playing with the 'up_load' and 'down_load'
3903 variables.  The 'load' is kept in a form which is multiplied by 256.  So
3904 hash->up_load=8*256; will cause a load of 8 to be set.
3905
3906 If you are interested in performance the field to watch is
3907 num_comp_calls.  The hash library keeps track of the 'hash' value for
3908 each item so when a lookup is done, the 'hashes' are compared, if
3909 there is a match, then a full compare is done, and
3910 hash->num_comp_calls is incremented.  If num_comp_calls is not equal
3911 to num_delete plus num_retrieve it means that your hash function is
3912 generating hashes that are the same for different values.  It is
3913 probably worth changing your hash function if this is the case because
3914 even if your hash table has 10 items in a 'bucked', it can be searched
3915 with 10 'unsigned long' compares and 10 linked list traverses.  This
3916 will be much less expensive that 10 calls to you compare function.
3917
3918 LHASH *lh_new(
3919 unsigned long (*hash)(),
3920 int (*cmp)());
3921         This function is used to create a new LHASH structure.  It is passed
3922         function pointers that are used to store and retrieve values passed
3923         into the hash table.  The 'hash'
3924         function is a hashing function that will return a hashed value of
3925         it's passed structure.  'cmp' is passed 2 parameters, it returns 0
3926         is they are equal, otherwise, non zero.
3927         If there are any problems (usually malloc failures), NULL is
3928         returned, otherwise a new LHASH structure is returned.  The
3929         hash value is normally truncated to a power of 2, so make sure
3930         that your hash function returns well mixed low order bits.
3931         
3932 void lh_free(
3933 LHASH *lh);
3934         This function free()s a LHASH structure.  If there is malloced
3935         data in the hash table, it will not be freed.  Consider using the
3936         lh_doall function to deallocate any remaining entries in the hash
3937         table.
3938         
3939 char *lh_insert(
3940 LHASH *lh,
3941 char *data);
3942         This function inserts the data pointed to by data into the lh hash
3943         table.  If there is already and entry in the hash table entry, the
3944         value being replaced is returned.  A NULL is returned if the new
3945         entry does not clash with an entry already in the table (the normal
3946         case) or on a malloc() failure (perhaps I should change this....).
3947         The 'char *data' is exactly what is passed to the hash and
3948         comparison functions specified in lh_new().
3949         
3950 char *lh_delete(
3951 LHASH *lh,
3952 char *data);
3953         This routine deletes an entry from the hash table.  The value being
3954         deleted is returned.  NULL is returned if there is no such value in
3955         the hash table.
3956
3957 char *lh_retrieve(
3958 LHASH *lh,
3959 char *data);
3960         If 'data' is in the hash table it is returned, else NULL is
3961         returned.  The way these routines would normally be uses is that a
3962         dummy structure would have key fields populated and then
3963         ret=lh_retrieve(hash,&dummy);.  Ret would now be a pointer to a fully
3964         populated structure.
3965
3966 void lh_doall(
3967 LHASH *lh,
3968 void (*func)(char *a));
3969         This function will, for every entry in the hash table, call function
3970         'func' with the data item as parameters.
3971         This function can be quite useful when used as follows.
3972         void cleanup(STUFF *a)
3973                 { STUFF_free(a); }
3974         lh_doall(hash,cleanup);
3975         lh_free(hash);
3976         This can be used to free all the entries, lh_free() then
3977         cleans up the 'buckets' that point to nothing.  Be careful
3978         when doing this.  If you delete entries from the hash table,
3979         in the call back function, the table may decrease in size,
3980         moving item that you are
3981         currently on down lower in the hash table.  This could cause
3982         some entries to be skipped.  The best solution to this problem
3983         is to set lh->down_load=0 before you start.  This will stop
3984         the hash table ever being decreased in size.
3985
3986 void lh_doall_arg(
3987 LHASH *lh;
3988 void(*func)(char *a,char *arg));
3989 char *arg;
3990         This function is the same as lh_doall except that the function
3991         called will be passed 'arg' as the second argument.
3992         
3993 unsigned long lh_strhash(
3994 char *c);
3995         This function is a demo string hashing function.  Since the LHASH
3996         routines would normally be passed structures, this routine would
3997         not normally be passed to lh_new(), rather it would be used in the
3998         function passed to lh_new().
3999
4000 The next three routines print out various statistics about the state of the
4001 passed hash table.  These numbers are all kept in the lhash structure.
4002
4003 void lh_stats(
4004 LHASH *lh,
4005 FILE *out);
4006         This function prints out statistics on the size of the hash table,
4007         how many entries are in it, and the number and result of calls to
4008         the routines in this library.
4009
4010 void lh_node_stats(
4011 LHASH *lh,
4012 FILE *out);
4013         For each 'bucket' in the hash table, the number of entries is
4014         printed.
4015         
4016 void lh_node_usage_stats(
4017 LHASH *lh,
4018 FILE *out);
4019         This function prints out a short summary of the state of the hash
4020         table.  It prints what I call the 'load' and the 'actual load'.
4021         The load is the average number of data items per 'bucket' in the
4022         hash table.  The 'actual load' is the average number of items per
4023         'bucket', but only for buckets which contain entries.  So the
4024         'actual load' is the average number of searches that will need to
4025         find an item in the hash table, while the 'load' is the average number
4026         that will be done to record a miss.
4027
4028 ==== md2.doc ========================================================
4029
4030 The MD2 library.
4031 MD2 is a message digest algorithm that can be used to condense an arbitrary
4032 length message down to a 16 byte hash.  The functions all need to be passed
4033 a MD2_CTX which is used to hold the MD2 context during multiple MD2_Update()
4034 function calls.  The normal method of use for this library is as follows
4035
4036 MD2_Init(...);
4037 MD2_Update(...);
4038 ...
4039 MD2_Update(...);
4040 MD2_Final(...);
4041
4042 This library requires the inclusion of 'md2.h'.
4043
4044 The main negative about MD2 is that it is slow, especially when compared
4045 to MD5.
4046
4047 The functions are as follows:
4048
4049 void MD2_Init(
4050 MD2_CTX *c);
4051         This function needs to be called to initiate a MD2_CTX structure for
4052         use.
4053         
4054 void MD2_Update(
4055 MD2_CTX *c;
4056 unsigned char *data;
4057 unsigned long len);
4058         This updates the message digest context being generated with 'len'
4059         bytes from the 'data' pointer.  The number of bytes can be any
4060         length.
4061
4062 void MD2_Final(
4063 unsigned char *md;
4064 MD2_CTX *c;
4065         This function is called when a message digest of the data digested
4066         with MD2_Update() is wanted.  The message digest is put in the 'md'
4067         array and is MD2_DIGEST_LENGTH (16) bytes long.
4068
4069 unsigned char *MD2(
4070 unsigned long n;
4071 unsigned char *d;
4072 unsigned char *md;
4073         This function performs a MD2_Init(), followed by a MD2_Update()
4074         followed by a MD2_Final() (using a local MD2_CTX).
4075         The resulting digest is put into 'md' if it is not NULL.
4076         Regardless of the value of 'md', the message
4077         digest is returned from the function.  If 'md' was NULL, the message
4078         digest returned is being stored in a static structure.
4079
4080 ==== md5.doc ========================================================
4081
4082 The MD5 library.
4083 MD5 is a message digest algorithm that can be used to condense an arbitrary
4084 length message down to a 16 byte hash.  The functions all need to be passed
4085 a MD5_CTX which is used to hold the MD5 context during multiple MD5_Update()
4086 function calls.  This library also contains random number routines that are
4087 based on MD5
4088
4089 The normal method of use for this library is as follows
4090
4091 MD5_Init(...);
4092 MD5_Update(...);
4093 ...
4094 MD5_Update(...);
4095 MD5_Final(...);
4096
4097 This library requires the inclusion of 'md5.h'.
4098
4099 The functions are as follows:
4100
4101 void MD5_Init(
4102 MD5_CTX *c);
4103         This function needs to be called to initiate a MD5_CTX structure for
4104         use.
4105         
4106 void MD5_Update(
4107 MD5_CTX *c;
4108 unsigned char *data;
4109 unsigned long len);
4110         This updates the message digest context being generated with 'len'
4111         bytes from the 'data' pointer.  The number of bytes can be any
4112         length.
4113
4114 void MD5_Final(
4115 unsigned char *md;
4116 MD5_CTX *c;
4117         This function is called when a message digest of the data digested
4118         with MD5_Update() is wanted.  The message digest is put in the 'md'
4119         array and is MD5_DIGEST_LENGTH (16) bytes long.
4120
4121 unsigned char *MD5(
4122 unsigned char *d;
4123 unsigned long n;
4124 unsigned char *md;
4125         This function performs a MD5_Init(), followed by a MD5_Update()
4126         followed by a MD5_Final() (using a local MD5_CTX).
4127         The resulting digest is put into 'md' if it is not NULL.
4128         Regardless of the value of 'md', the m