"Fossies" - the Fresh Open Source Software Archive

Member "openssl-1.0.2q/doc/ssleay.txt" (20 Nov 2018, 283130 Bytes) of package /linux/misc/openssl-1.0.2q.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    2 Bundle of old SSLeay documentation files [OBSOLETE!]
    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.
   14 People have done the mistake of trusting what's written here.  Please
   15 don't do that.
   20 ==== readme ========================================================
   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
   26 http://www.cryptsoft.com/ssleay/doc
   28 ==== API.doc ========================================================
   30 SSL - SSLv2/v3/v23 etc.
   32 BIO - methods and how they plug together
   34 MEM - memory allocation callback
   36 CRYPTO - locking for threads
   38 EVP - Ciphers/Digests/signatures
   40 RSA - methods
   42 X509 - certificate retrieval
   44 X509 - validation
   46 X509 - X509v3 extensions
   48 Objects - adding object identifiers
   50 ASN.1 - parsing
   52 PEM - parsing
   54 ==== ssl/readme =====================================================
   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 ===
   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.
   73 This file will probably be gibberish unless you have read
   74 rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM
   75 authentication.
   77 A Brief outline (and examples) how to use them to do so.
   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
   83 in a : separated list.
   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]
   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.
  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 :-).
  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.
  138 s_client
  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.
  152 s_client -verify 0
  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.
  162 s_client -verify 1
  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.
  174 s_client -verify 1 -CAfile eay1024.PEM
  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.
  184 s_client -verify 1 -CApath .
  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.
  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.
  200 export SSL_CIPHER
  201 s_client -verify 10 -CApath . -reconnect
  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.
  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.
  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
  244 	CIPHER is CBC-DES-MD5
  245 Everything up and running
  247 s_server -verify 0
  248 s_client  
  250 	CIPHER is CBC-DES-MD5
  251 Ok since no certificate was returned and we don't care.
  253 s_server -verify 0
  254 ./s_client -cert client.PEM
  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
  263 s_server -verify 4
  264 s_client -cert client.PEM
  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.
  274 s_server -verify 4 -CApath .
  275 s_client -cert client.PEM
  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 :-).
  284 s_server -Verify 0 -CApath .
  285 s_client
  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.
  292 s_server -Verify 4 -CApath .
  293 s_client -cert client.PEM
  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.
  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
  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
  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
  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.
  327 www.rsa.com was refusing to respond to connections on 443 when I was
  328 testing.
  330 have fun :-).
  332 eric
  334 ==== a_verify.doc ========================================================
  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: 
  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.)?
  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.
  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 :-(.
  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);
  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);
  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.
  401 To sign any of the above structures
  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);
  408 where md is the message digest to sign with.
  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.
  415 eric
  416 --
  417 Eric Young                  | BOOL is tri-state according to Bill Gates.
  418 AARNet: eay@mincom.oz.au    | RTFM Win32 GetMessage().
  420 ==== x509 =======================================================
  422 X509_verify()
  423 X509_sign()
  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()
  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()
  441 X509_get_extensions()
  442 X509_set_extensions()
  444 X509_EXTENSIONS_clear()
  445 X509_EXTENSIONS_retrieve()
  446 X509_EXTENSIONS_add()
  447 X509_EXTENSIONS_delete()
  449 ==== x509 attribute ================================================
  451 PKCS7
  453 		ASN1_OBJECT
  454 		STACK of ASN1_TYPE
  456 So it is
  458 p7.xa[].obj
  459 p7.xa[].data[]
  461 get_obj_by_nid(STACK , nid)
  462 get_num_by_nid(STACK , nid)
  463 get_data_by_nid(STACK , nid, index)
  465 X509_ATTRIBUTE *X509_ATTRIBUTE_new(void );
  466 void		X509_ATTRIBUTE_free(X509_ATTRIBUTE *a);
  468 X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **ex,
  469 			int nid, STACK *value);
  471 X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **ex,
  472 			int nid, STACK *value);
  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);
  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);
  482 ASN1_TYPE *	X509_ATTRIBUTE_get_data_by_NID(X509_ATTRIBUTE *ne,
  483 			ASN1_OBJECT *obj);
  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);
  488 ==== x509 v3 ========================================================
  490 The 'new' system.
  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.
  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);
  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.
  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 :-).
  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);
  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);
  514 ==== verify ========================================================
  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 */
  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,
  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,
  537 ==== apps.doc ========================================================
  539 The applications
  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.
  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.
  560 dgst	- message digests
  561 enc	- encryption and base64 encoding
  563 ans1parse - 'pulls' appart ASN.1 encoded objects like certificates.
  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.
  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.
  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
  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
  590 [ there a now a few more options, play with the program to see what they
  591   are ]
  593 ==== asn1.doc ========================================================
  595 The ASN.1 Routines.
  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.
  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 */
  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.
  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.
  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.
  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.
  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.
  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);
  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.
  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.
  682 TYPE			ASN.1
  687 ASN1_PRINTABLESTRING	PrintableString
  688 ASN1_T61STRING		T61String
  689 ASN1_IA5STRING		IA5String
  691 ASN1_TYPE		Any of the above mentioned types plus SEQUENCE and SET
  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
  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.
  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).
  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.
  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.
  773 X509_REQ		CertificateRequest
  774 X509_REQ_INFO		CertificateRequestInfo
  775 These are used to hold certificate requests.
  777 X509_CRL		CertificateRevocationList
  778 These are used to hold a certificate revocation list
  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.
  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.
  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).
  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. 
  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.
  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.
  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.
  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.
  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.
  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.
  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().
  851 int	PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,EVP_CIPHER *enc,
  852 		unsigned char *kstr,int klen,int (*callback)());
  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)());
  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);
  864 ASN1_BIT_STRING *ASN1_BIT_STRING_type_new(int type );
  866 int ASN1_UTCTIME_check(ASN1_UTCTIME *a);
  867 void ASN1_UTCTIME_print(BIO *fp,ASN1_UTCTIME *a);
  870 ASN1_BIT_STRING *d2i_asn1_print_type(ASN1_BIT_STRING **a,unsigned char **pp,
  871 		long length,int type);
  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);
  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);
  882 int ASN1_INTEGER_set(ASN1_INTEGER *a, long v);
  883 long ASN1_INTEGER_get(ASN1_INTEGER *a);
  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);
  892 void ASN1_parse(BIO *fp,unsigned char *pp,long len);
  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);
  898 /* PARSING */
  899 int asn1_Finish(ASN1_CTX *c);
  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);
  909 X509 *	X509_get_cert(CERTIFICATE_CTX *ctx,X509_NAME * name,X509 *tmp_x509);
  910 int  	X509_add_cert(CERTIFICATE_CTX *ctx,X509 *);
  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)()); 
  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);
  936 X509_INFO *	X509_INFO_new(void);
  937 void		X509_INFO_free(X509_INFO *a);
  939 char *		X509_NAME_oneline(X509_NAME *a);
  941 #define X509_verify(x,rsa)
  942 #define X509_REQ_verify(x,rsa)
  943 #define X509_CRL_verify(x,rsa)
  945 #define X509_sign(x,rsa,md)
  946 #define X509_REQ_sign(x,rsa,md)
  947 #define X509_CRL_sign(x,rsa,md)
  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)
  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)
  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)
  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)
  973 #define X509_NAME_dup(xn)
  974 #define X509_NAME_ENTRY_dup(ne)
  976 void X509_REQ_print_fp(FILE *fp,X509_REQ *req);
  977 void X509_REQ_print(BIO *fp,X509_REQ *req);
  979 RSA *X509_REQ_extract_key(X509_REQ *req);
  980 RSA *X509_extract_key(X509 *x509);
  982 int		X509_issuer_and_serial_cmp(X509 *a, X509 *b);
  983 unsigned long	X509_issuer_and_serial_hash(X509 *a);
  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);
  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);
  993 int		X509_NAME_cmp (X509_NAME *a, X509_NAME *b);
  994 unsigned long	X509_NAME_hash(X509_NAME *x);
  997 ==== bio.doc ========================================================
  999 BIO Routines
 1001 This documentation is rather sparse, you are probably best 
 1002 off looking at the code for specific details.
 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.
 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.
 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.
 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).
 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.
 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.
 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;
 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;
 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.
 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 
 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.
 1232 The following command is a special BIO_s_file() specific option.
 1233 -	BIO_CTRL_SET_FILENAME - specify a file to open for IO.
 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 		}
 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.
 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.
 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.
 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.
 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.
 1331 BIO_METHOD *BIO_s_null(void);
 1332 Read and write as much data as you like, it all disappears 
 1333 into this BIO.
 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.
 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.
 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.
 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.
 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.
 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()
 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.
 1420 The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c.
 1423 ==== blowfish.doc ========================================================
 1425 The Blowfish library.
 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.
 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.
 1435 For all calls that have an 'input' and 'output' variables, they can be the
 1436 same.
 1438 This library requires the inclusion of 'blowfish.h'.
 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.
 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.
 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 :-).
 1463 The functions are as follows:
 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.
 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. 
 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.
 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().
 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.
 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.
 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().
 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.
 1572 ==== bn.doc ========================================================
 1574 The Big Number library.
 1576 #include "bn.h" when using this library.
 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.
 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.
 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.
 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;
 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.
 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.
 1628 Get Size functions.
 1630 int BN_num_bits(BIGNUM *a);
 1631 	This function returns the size of 'a' in bits.
 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 :-).
 1643 Creation/Destruction routines.
 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.
 1649 void	BN_free(BIGNUM *a);
 1650 	Free()s a BIGNUM.
 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.
 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.
 1663 BN_CTX *BN_CTX_new(void);
 1664 	Returns a new BN_CTX.  NULL on error.
 1666 void	BN_CTX_free(BN_CTX *c);
 1667 	Free a BN_CTX structure.  The BIGNUMs in 'c' are BN_clear_free()ed.
 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.
 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.
 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.
 1683 Comparison and Test Functions.
 1685 int BN_is_zero(BIGNUM *a)
 1686 	Return 1 if 'a' is zero, else 0.
 1688 int BN_is_one(a)
 1689 	Return 1 is 'a' is one, else 0.
 1691 int BN_is_word(a,w)
 1692 	Return 1 if 'a' == w, else 0.  'w' is a BN_ULONG.
 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.
 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.
 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.
 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.
 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.
 1715 int BN_lshift(BIGNUM *r, BIGNUM *a, int n);
 1716 	Shift 'a' left by 'n' bits.  This is r=a*(2^n).
 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.
 1722 int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
 1723 	Shift 'a' right by 'n' bits.  This is r=int(a/(2^n)).
 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).
 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.
 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.
 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.
 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.
 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.
 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.
 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).
 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().
 1786 Assignment Operations
 1788 int BN_one(BIGNUM *a)
 1789 	Set 'a' to hold the value one.
 1790 	This is a=1.
 1792 int BN_zero(BIGNUM *a)
 1793 	Set 'a' to hold the value zero.
 1794 	This is a=0.
 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.
 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.
 1804 Word Operations
 1805 These functions are much more efficient that the normal bignum arithmetic
 1806 operations.
 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).
 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;
 1816 Bit operations.
 1818 int BN_is_bit_set(BIGNUM *a, int n);
 1819 	This function return 1 if bit 'n' is set in 'a' else 0.
 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);
 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);
 1829 int BN_mask_bits(BIGNUM *a, int n);
 1830 	Truncate 'a' to n bits long.  This is a&= ~((~0)<<n)
 1832 Format conversion routines.
 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
 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;
 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.
 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.
 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.
 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.
 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.
 1888 Miscellaneous Routines.
 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.
 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.
 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.
 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.
 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.
 1955 Hints
 1956 -----
 1958 DSA wants 64*32 to use word mont mul, but RSA wants to use full.
 1960 ==== callback.doc ========================================================
 1962 Callback functions used in SSLeay.
 1964 --------------------------
 1965 The BIO library.  
 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.
 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.
 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.
 1993 --------------------------
 1994 The PEM library.
 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.
 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.
 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.
 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.
 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)());
 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)());
 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.
 2066 --------------------------
 2067 The SSL library.
 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.
 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.
 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.
 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.
 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).
 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.
 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.
 2144 --------------------------
 2145 The X509 library.
 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);
 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
 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).
 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.
 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.
 2176 --------------------------
 2177 The BN and DH library.
 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),
 2183 Read doc/bn.doc for the description of these 2.
 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.
 2191 --------------------------
 2192 The CRYPTO library.
 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));
 2200 Read threads.doc for info on these ones.
 2203 ==== cipher.doc ========================================================
 2205 The Cipher subroutines.
 2207 These routines require "evp.h" to be included.
 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.
 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
 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;
 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).
 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).
 2250 The thirteen ciphers currently defined in this library are
 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 */
 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.
 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.
 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;
 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.
 2311 The following functions are to be used.
 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).
 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.
 2328 char *EVP_get_pw_prompt();
 2329 	This returns a pointer to the default prompt string.  NULL
 2330 	if it is not set.
 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
 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]);
 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 		}
 2371 	If the salt is NULL, it is not used.
 2372 	The digests are concatenated together.
 2373 	M = M[0] . M[1] . M[2] .......
 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].
 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.
 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.
 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.
 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.
 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.
 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)).
 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.
 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.
 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.
 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.  
 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.
 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'.
 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().
 2551 ==== cipher.m ========================================================
 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: 
 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 :-)
 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.
 2582 The documentation to read is in
 2583 doc/cipher.doc,
 2584 doc/encode.doc (very sparse :-).
 2585 and perhaps
 2586 doc/digest.doc,
 2588 The basic calls to encrypt with say triple DES are
 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;
 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);
 2602 /* Initalise the EVP_CIPHER_CTX */
 2603 EVP_EncryptInit(ctx,EVP_des_ede3_cbc,key,iv);
 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 	}
 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. */
 2617 EVP_EncryptFinal(ctx,out,&outl);
 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).
 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().
 2630 To do the base64 encoding,
 2631 EVP_EncodeInit()
 2632 EVP_EncodeUpdate()
 2633 EVP_EncodeFinal()
 2635 EVP_DecodeInit()
 2636 EVP_DecodeUpdate()
 2637 EVP_DecodeFinal()
 2639 where the encoding is quite simple, but the decoding can be a bit more 
 2640 fun (due to dud input).
 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.
 2645 EVP_DecodeFinal() returns -1 for an error or 1 if things are ok.
 2647 So the loop becomes
 2648 EVP_DecodeInit(....)
 2649 for (;;)
 2650 	{
 2651 	i=EVP_DecodeUpdate(....);
 2652 	if (i < 0) goto err;
 2654 	/* process the data */
 2656 	if (i == 0) break;
 2657 	}
 2658 EVP_DecodeFinal(....);
 2659 /* process the data */
 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.
 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().
 2672 ==== conf.doc ========================================================
 2674 The CONF library.
 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.
 2680 The library consists of 5 functions.
 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.
 2689 void CONF_free(LHASH *config);
 2690 This function free()s the data in config.
 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.
 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.
 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.
 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.
 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.
 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.
 2742 Examples
 2744 # This is a simple example
 2745 SSLEAY_HOME	= /usr/local/ssl
 2746 ENV::PATH	= $SSLEAY_HOME/bin:$PATH	# override my path
 2748 [X509]
 2749 cert_dir	= $SSLEAY_HOME/certs	# /usr/local/ssl/certs
 2751 [SSL]
 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
 2757 TEST		= 1234\
 2758 5678\
 2759 9ab					# TEST=123456789ab
 2760 TTT		= 1234\n\n		# TTT=1234<nl><nl>
 2764 ==== des.doc ========================================================
 2766 The DES library.
 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.
 2775 This library requires the inclusion of 'des.h'.
 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.
 2785 The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to
 2786 specify decryption.  The functions and global variable are as follows:
 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;
 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.
 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.
 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.
 2817 int des_key_sched(
 2818 des_cblock *key,
 2819 des_key_schedule schedule);
 2820 	An alternative name for des_set_key().
 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.
 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.
 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 :-).
 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).
 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.
 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.
 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();
 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.
 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.
 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.
 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().
 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.
 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 :-).
 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.
 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).
 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.
 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.
 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.
 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.
 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.
 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).
 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.
 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.
 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().
 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().
 3136 void des_random_seed(
 3137 des_cblock key);
 3138 	This routine sets a starting point for des_random_key().
 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.
 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
 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.
 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
 3188 There are several different modes in which DES can be used, they are
 3189 as follows.
 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.
 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.
 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.
 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.
 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.
 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.
 3272 ==== digest.doc ========================================================
 3275 The Message Digest subroutines.
 3277 These routines require "evp.h" to be included.
 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.
 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)();
 3297 	int required_pkey_type; /*EVP_PKEY_xxx */
 3298 	int (*sign)();
 3299 	int (*verify)();
 3300 	} EVP_MD;
 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.
 3318 The six message digests defined in this library are
 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 */
 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.
 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;
 3343 The Digest functions are as follows.
 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'.
 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'.
 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.
 3369 ==== encode.doc ========================================================
 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);
 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);
 3387 ==== envelope.doc ========================================================
 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.
 3397 To 'sign' a document involves generating a message digest and then encrypting
 3398 the digest with an private key.
 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.
 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.
 3420 Verify is used to check an signed message digest.
 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.
 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.
 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.
 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);
 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
 3451 #define EVP_OpenUpdate(a,b,c,d,e)	EVP_DecryptUpdate(a,b,c,d,e)
 3453 int	EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
 3454 Decrypt final return code
 3457 ==== error.doc ========================================================
 3459 The error routines.
 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.
 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.
 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'.
 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.
 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.
 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.
 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.
 3496 void ERR_clear_error(void );
 3497 	This function clears the error buffer, discarding all unread
 3498 errors.
 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.
 3505 typedef struct ERR_string_data_st
 3506 	{
 3507 	unsigned long error;
 3508 	char *string;
 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.
 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'.
 3519 void ERR_free_strings(void);
 3520 	This function free()s all the loaded error strings.
 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.
 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.
 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.
 3541 void ERR_load_ERR_strings(void );
 3542 	This function 'registers' the error strings for the 'ERR' module.
 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.
 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.
 3558 Late breaking news - the changes to support threads.
 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.
 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).
 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.
 3575 ==== idea.doc ========================================================
 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.
 3582 For all calls that have an 'input' and 'output' variables, they can be the
 3583 same.
 3585 This library requires the inclusion of 'idea.h'.
 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.
 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.
 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);
 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);
 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 :-).
 3622 The functions are as follows:
 3624 void idea_set_encrypt_key(
 3625 unsigned char *key;
 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.
 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.
 3649 void idea_encrypt(
 3650 unsigned long *data,
 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
 3662 void idea_ecb_encrypt(
 3663 unsigned char *input,
 3664 unsigned char *output,
 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.
 3673 void idea_cbc_encrypt(
 3674 unsigned char *input,
 3675 unsigned char *output,
 3676 long length,
 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().
 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 :-(.
 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.
 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().
 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.
 3754 ==== legal.doc ========================================================
 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: 
 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.
 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?
 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).
 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. 
 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.
 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.
 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]
 3822 > Is it possible to get a certificate for commercial use outside of the U.S.?
 3823 yes.
 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.
 3831 (The above mentioned companies just the ones that I know for sure are issuing
 3832  certificates outside the USA).
 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.
 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.
 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).
 3847 This could be completly hidden from the application, so this would not 
 3848 even require a re-linking.
 3850 This is the reverse of what people were talking about doing to get around 
 3851 USA export regulations :-)
 3853 eric
 3855 [1]:	The RSAref2.0 tookit is available on at least 3 ftp sites in Europe
 3856 	and one in South Africa.
 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().
 3874 ==== lhash.doc ========================================================
 3876 The LHASH library.
 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'.
 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.
 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.
 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.
 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.
 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.
 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().
 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.
 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.
 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.
 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.
 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().
 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.
 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.
 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.
 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.
 4028 ==== md2.doc ========================================================
 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
 4036 MD2_Init(...);
 4037 MD2_Update(...);
 4038 ...
 4039 MD2_Update(...);
 4040 MD2_Final(...);
 4042 This library requires the inclusion of 'md2.h'.
 4044 The main negative about MD2 is that it is slow, especially when compared
 4045 to MD5.
 4047 The functions are as follows:
 4049 void MD2_Init(
 4050 MD2_CTX *c);
 4051 	This function needs to be called to initiate a MD2_CTX structure for
 4052 	use.
 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.
 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.
 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.
 4080 ==== md5.doc ========================================================
 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
 4089 The normal method of use for this library is as follows
 4091 MD5_Init(...);
 4092 MD5_Update(...);
 4093 ...
 4094 MD5_Update(...);
 4095 MD5_Final(...);
 4097 This library requires the inclusion of 'md5.h'.
 4099 The functions are as follows:
 4101 void MD5_Init(
 4102 MD5_CTX *c);
 4103 	This function needs to be called to initiate a MD5_CTX structure for
 4104 	use.
 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.
 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.
 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 message
 4129 	digest is returned from the function.  If 'md' was NULL, the message
 4130 	digest returned is being stored in a static structure.
 4133 ==== memory.doc ========================================================
 4135 In the interests of debugging SSLeay, there is an option to compile
 4136 using some simple memory leak checking.
 4138 All malloc(), free() and realloc() calls in SSLeay now go via
 4139 Malloc(), Free() and Realloc() (except those in crypto/lhash).
 4141 If CRYPTO_MDEBUG is defined, these calls are #defined to
 4142 CRYPTO_malloc(), CRYPTO_free() and CRYPTO_realloc().
 4143 If it is not defined, they are #defined to malloc(), free() and realloc().
 4145 the CRYPTO_malloc() routines by default just call the underlying library
 4146 functons.
 4148 If CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON) is called, memory leak detection is
 4149 turned on.  CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_OFF) turns it off.
 4151 When turned on, each Malloc() or Realloc() call is recored along with the file
 4152 and line number from where the call was made.   (This is done using the
 4153 lhash library which always uses normal system malloc(3) routines).
 4155 void CRYPTO_mem_leaks(BIO *b);
 4156 void CRYPTO_mem_leaks_fp(FILE *fp);
 4157 These both print out the list of memory that has not been free()ed.
 4158 This will probably be rather hard to read, but if you look for the 'top level'
 4159 structure allocation, this will often give an idea as to what is not being
 4160 free()ed.  I don't expect people to use this stuff normally.
 4162 ==== ca.1 ========================================================
 4164 From eay@orb.mincom.oz.au Thu Dec 28 23:56:45 1995
 4165 Received: by orb.mincom.oz.au id AA07374
 4166   (5.65c/IDA-1.4.4 for eay); Thu, 28 Dec 1995 13:56:45 +1000
 4167 Date: Thu, 28 Dec 1995 13:56:45 +1000 (EST)
 4168 From: Eric Young <eay@mincom.oz.au>
 4169 X-Sender: eay@orb
 4170 To: sameer <sameer@c2.org>
 4171 Cc: ssleay@mincom.oz.au
 4172 Subject: Re: 'ca'
 4173 In-Reply-To: <199512230440.UAA23410@infinity.c2.org>
 4174 Message-Id: <Pine.SOL.3.91.951228133525.7269A-100000@orb>
 4175 Mime-Version: 1.0
 4176 Content-Type: TEXT/PLAIN; charset=US-ASCII
 4177 Status: RO
 4178 X-Status: 
 4180 On Fri, 22 Dec 1995, sameer wrote:
 4181 > 	I could use documentation on 'ca'. Thanks.
 4183 Very quickly.
 4184 The ca program uses the ssleay.conf file for most of its configuration
 4186 ./ca -help
 4188  -verbose        - Talk alot while doing things
 4189  -config file    - A config file. If you don't want to use the
 4190 		   default config file
 4191  -name arg       - The particular CA definition to use
 4192 	In the config file, the section to use for parameters.  This lets 
 4193 	multiple setups to be contained in the one file.  By default, the 
 4194 	default_ca variable is looked up in the [ ca ] section.  So in the 
 4195 	shipped ssleay.conf, the CA definition used is CA_default.  It could be 
 4196 	any other name.
 4197  -gencrl days    - Generate a new CRL, days is when the next CRL is due
 4198 	This will generate a new certificate revocion list.
 4199  -days arg       - number of days to certify the certificate for
 4200 	When certifiying certificates, this is the number of days to use.
 4201  -md arg         - md to use, one of md2, md5, sha or sha1
 4202  -policy arg     - The CA 'policy' to support
 4203 	I'll describe this later, but there are 2 policies definied in the 
 4204 	shipped ssleay.conf
 4205  -keyfile arg    - PEM RSA private key file
 4206  -key arg        - key to decode the RSA private key if it is encrypted
 4207 	since we need to keep the CA's RSA key encrypted
 4208  -cert           - The CA certificate
 4209  -in file        - The input PEM encoded certificate request(s)
 4210  -out file       - Where to put the output file(s)
 4211  -outdir dir     - Where to put output certificates
 4212 	The -out options concatinates all the output certificied
 4213 	certificates to one file, -outdir puts them in a directory,
 4214 	named by serial number.
 4215  -infiles ....   - The last argument, requests to process
 4216 	The certificate requests to process, -in is the same.
 4218 Just about all the above have default values defined in ssleay.conf.
 4220 The key variables in ssleay.conf are (for the pariticular '-name' being 
 4221 used, in the default, it is CA_default).
 4223 dir is where all the CA database stuff is kept.
 4224 certs is where all the previously issued certificates are kept.
 4225 The database is a simple text database containing the following tab separated 
 4226 fields.
 4227 status: a value of 'R' - revoked, 'E' -expired or 'V' valid.
 4228 issued date:  When the certificate was certified.
 4229 revoked date:  When it was revoked, blank if not revoked.
 4230 serial number:  The certificate serial number.
 4231 certificate:	Where the certificate is located.
 4232 CN:	The name of the certificate.
 4234 The demo file has quite a few made up values it it.  The last 2 were 
 4235 added by the ca program and are acurate.
 4236 The CA program does not update the 'certificate' file correctly right now.
 4237 The serial field should be unique as should the CN/status combination.
 4238 The ca program checks these at startup.  What still needs to be 
 4239 wrtten is a program to 'regenerate' the data base file from the issued 
 4240 certificate list (and a CRL list).
 4242 Back to the CA_default variables.
 4244 Most of the variables are commented.
 4246 policy is the default policy.
 4248 Ok for policies, they define the order and which fields must be present 
 4249 in the certificate request and what gets filled in.
 4251 So a value of
 4252 countryName             = match
 4253 means that the country name must match the CA certificate.
 4254 organizationalUnitName  = optional
 4255 The org.Unit,Name does not have to be present and
 4256 commonName              = supplied
 4257 commonName must be supplied in the certificate request.
 4259 For the 'policy_match' polocy, the order of the attributes in the 
 4260 generated certiticate would be
 4261 countryName
 4262 stateOrProvinceName
 4263 organizationName
 4264 organizationalUnitName
 4265 commonName
 4266 emailAddress
 4268 Have a play, it sort of makes sense.  If you think about how the persona 
 4269 requests operate, it is similar to the 'policy_match' policy and the
 4270 'policy_anything' is similar to what versign is doing.
 4272 I hope this helps a bit.  Some backend scripts are definitly needed to 
 4273 update the database and to make certificate revocion easy.  All 
 4274 certificates issued should also be kept forever (or until they expire?)
 4276 hope this helps
 4277 eric (who has to run off an buy some cheap knee pads for the caving in 4 
 4278 days time :-)
 4280 --
 4281 Eric Young                  | Signature removed since it was generating
 4282 AARNet: eay@mincom.oz.au    | more followups than the message contents :-)
 4285 ==== ms3-ca.doc ========================================================
 4287 Date: Mon, 9 Jun 97 08:00:33 +0200
 4288 From: Holger.Reif@PrakInf.TU-Ilmenau.DE (Holger Reif)
 4289 Subject: ms3-ca.doc
 4290 Organization: TU Ilmenau, Fak. IA, FG Telematik
 4291 Content-Length: 14575
 4292 Status: RO
 4293 X-Status: 
 4295 Loading client certs into MSIE 3.01
 4296 ===================================
 4298 This document contains all the information necessary to successfully set up 
 4299 some scripts to issue client certs to Microsoft Internet Explorer. It 
 4300 includes the required knowledge about the model MSIE uses for client 
 4301 certification and includes complete sample scripts ready to play with. The 
 4302 scripts were tested against a modified ca program of SSLeay 0.6.6 and should 
 4303 work with the regular ca program that comes with version 0.8.0. I haven't 
 4304 tested against MSIE 4.0
 4306 You can use the information contained in this document in either way you 
 4307 want. However if you feel it saved you a lot of time I ask you to be as fair 
 4308 as to mention my name: Holger Reif <reif@prakinf.tu-ilmenau.de>.
 4310 1.) The model used by MSIE
 4311 --------------------------
 4313 The Internet Explorer doesn't come with a embedded engine for installing 
 4314 client certs like Netscape's Navigator. It rather uses the CryptoAPI (CAPI) 
 4315 defined by Microsoft. CAPI comes with WindowsNT 4.0 or is installed together 
 4316 with Internet Explorer since 3.01. The advantage of this approach is a higher 
 4317 flexibility because the certificates in the (per user) system open 
 4318 certificate store may be used by other applications as well. The drawback 
 4319 however is that you need to do a bit more work to get a client cert issued.
 4321 CAPI defines functions which will handle basic cryptographic work, eg. 
 4322 generating keys, encrypting some data, signing text or building a certificate 
 4323 request. The procedure is as follows: A CAPI function generates you a key 
 4324 pair and saves it into the certificate store. After that one builds a 
 4325 Distinguished Name. Together with that key pair another CAPI function forms a 
 4326 PKCS#10 request which you somehow need to submit to a CA. Finally the issued 
 4327 cert is given to a yet another CAPI function which saves it into the 
 4328 certificate store.
 4330 The certificate store with the user's keys and certs is in the registry. You 
 4331 will find it under HKEY_CURRENT_USER/Software/Microsoft/Cryptography/ (I 
 4332 leave it to you as a little exercise to figure out what all the entries mean 
 4333 ;-). Note that the keys are protected only with the user's usual Windows 
 4334 login password.
 4336 2.) The practical usage
 4337 -----------------------
 4339 Unfortunatly since CAPI is a system API you can't access its functions from 
 4340 HTML code directly. For this purpose Microsoft provides a wrapper called 
 4341 certenr3.dll. This DLL accesses the CAPI functions and provides an interface 
 4342 usable from Visual Basic Script. One needs to install that library on the 
 4343 computer which wants to have client cert. The easiest way is to load it as an 
 4344 ActiveX control (certenr3.dll is properly authenticode signed by MS ;-). If 
 4345 you have ever enrolled e cert request at a CA you will have installed it.
 4347 At time of writing certenr3.dll is contained in 
 4348 http://www.microsoft.com/workshop/prog/security/csa/certenr3.exe. It comes 
 4349 with an README file which explains the available functions. It is labeled 
 4350 beta but every CA seems to use it anyway. The license.txt allows you the 
 4351 usage for your own purposes (as far as I understood) and a somehow limited 
 4352 distribution. 
 4354 The two functions of main interest are GenerateKeyPair and AcceptCredentials. 
 4355 For complete explanation of all possible parameters see the README file. Here 
 4356 are only minimal required parameters and their values.
 4358 GenerateKeyPair(sessionID, FASLE, szName, 0, "ClientAuth", TRUE, FALSE, 1)
 4359 - sessionID is a (locally to that computer) unique string to correlate the 
 4360 generated key pair with a cert installed later.
 4361 - szName is the DN of the form "C=DE; S=Thueringen; L=Ilmenau; CN=Holger 
 4362 Reif; 1.2.840.113549.1.9.1=reif@prakinf.tu-ilmenau.de". Note that S is the 
 4363 abreviation for StateOrProvince. The recognized abreviation include CN, O, C, 
 4364 OU, G, I, L, S, T. If the abreviation is unknown (eg. for PKCS#9 email addr) 
 4365 you need to use the full object identifier. The starting point for searching 
 4366 them could be crypto/objects.h since all OIDs know to SSLeay are listed 
 4367 there.
 4368 - note: the possible ninth parameter which should give a default name to the 
 4369 certificate storage location doesn't seem to work. Changes to the constant 
 4370 values in the call above doesn't seem to make sense. You can't generate 
 4371 PKCS#10 extensions with that function.
 4373 The result of GenerateKeyPair is the base64 encoded PKCS#10 request. However 
 4374 it has a little strange format that SSLeay doesn't accept. (BTW I feel the 
 4375 decision of rejecting that format as standard conforming.) It looks like 
 4376 follows:
 4377 	1st line with 76 chars
 4378 	2nd line with 76 chars
 4379 	...
 4380 	(n-2)th line with 76 chars
 4381 	(n-1)th line contains a multiple of 4 chars less then 76 (possible 
 4382 empty)
 4383 	(n)th line has zero or 4 chars (then with 1 or 2 equal signs - the 
 4384 		original text's lenght wasn'T a multiple of 3) 
 4385 	The line separator has two chars: 0x0d 0x0a
 4387 AcceptCredentials(sessionID, credentials, 0, FALSE)
 4388 - sessionID needs to be the same as while generating the key pair
 4389 - credentials is the base64 encoded PKCS#7 object containing the cert. 
 4391 CRL's and CA certs are not required simply just the client cert. (It seems to 
 4392 me that both are not even checked somehow.) The only format of the base64 
 4393 encoded object I succesfully used was all characters in a very long string 
 4394 without line feeds or carriage returns. (Hey, it doesn't matter, only a 
 4395 computer reads it!)
 4397 The result should be S_OK. For error handling see the example that comes with 
 4398 certenr3.dll.
 4400 A note about ASN.1 character encodings. certenr3.dll seems to know only about 
 4401 2 of them: UniversalString and PrintableString. First it is definitely wrong 
 4402 for an email address which is IA5STRING (checked by ssleay's ca). Second 
 4403 unfortunately MSIE (at least until version 3.02) can't handle UniversalString 
 4404 correctly - they just blow up you cert store! Therefore ssleay's ca (starting 
 4405 from version 0.8.0) tries to convert the encodings automatically to IA5STRING 
 4406 or TeletexString. The beef is it will work only for the latin-1 (western) 
 4407 charset. Microsoft still has to do abit of homework...
 4409 3.) An example
 4410 --------------
 4412 At least you need two steps: generating the key & request and then installing 
 4413 the certificate. A real world CA would have some more steps involved, eg. 
 4414 accepting some license. Note that both scripts shown below are just 
 4415 experimental state without any warrenty!
 4417 First how to generate a request. Note that we can't use a static page because 
 4418 of the sessionID. I generate it from system time plus pid and hope it is 
 4419 unique enough. Your are free to feed it through md5 to get more impressive 
 4420 ID's ;-) Then the intended text is read in with sed which inserts the 
 4421 sessionID. 
 4423 -----BEGIN ms-enroll.cgi-----
 4424 #!/bin/sh
 4425 SESSION_ID=`date '+%y%m%d%H%M%S'`$$
 4426 echo Content-type: text/html
 4427 echo
 4428 sed s/template_for_sessId/$SESSION_ID/ <<EOF
 4429 <HTML><HEAD>
 4430 <TITLE>Certificate Enrollment Test Page</TITLE>
 4431 </HEAD><BODY>
 4433 <OBJECT
 4434     classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43"
 4435     codebase=certenr3.dll
 4436     id=certHelper
 4437     >
 4438 </OBJECT>
 4440 <CENTER>
 4441 <H2>enrollment for a personal cert</H2>
 4442 <BR><HR WIDTH=50%><BR><P>
 4443 <FORM NAME="MSIE_Enrollment" ACTION="ms-gencert.cgi" ENCTYPE=x-www-form-
 4444 encoded METHOD=POST>
 4445 <TABLE>
 4446     <TR><TD>Country</TD><TD><INPUT NAME="Country" VALUE=""></TD></TR>
 4447     <TR><TD>State</TD><TD><INPUT NAME="StateOrProvince" VALUE=""></TD></TR>
 4448     <TR><TD>Location</TD><TD><INPUT NAME="Location" VALUE=""></TD></TR>
 4449     <TR><TD>Organization</TD><TD><INPUT NAME="Organization" 
 4450 VALUE=""></TD></TR>
 4451     <TR><TD>Organizational Unit</TD>
 4452         <TD><INPUT NAME="OrganizationalUnit" VALUE=""></TD></TR>
 4453     <TR><TD>Name</TD><TD><INPUT NAME="CommonName" VALUE=""></TD></TR>
 4454     <TR><TD>eMail Address</TD>
 4455         <TD><INPUT NAME="EmailAddress" VALUE=""></TD></TR>
 4456     <TR><TD></TD>
 4457         <TD><INPUT TYPE="BUTTON" NAME="submit" VALUE="Beantragen"></TD></TR>
 4458 </TABLE>
 4459 	<INPUT TYPE="hidden" NAME="SessionId" VALUE="template_for_sessId">
 4460 	<INPUT TYPE="hidden" NAME="Request" VALUE="">
 4461 </FORM>
 4462 <BR><HR WIDTH=50%><BR><P>
 4463 </CENTER>
 4466     Dim DN
 4468     Sub Submit_OnClick
 4469 	Dim TheForm
 4470 	Set TheForm = Document.MSIE_Enrollment
 4471 	sessionId	= TheForm.SessionId.value
 4472 	reqHardware     = FALSE
 4473 	C		= TheForm.Country.value
 4474 	SP		= TheForm.StateOrProvince.value
 4475 	L		= TheForm.Location.value
 4476 	O		= TheForm.Organization.value
 4477 	OU		= TheForm.OrganizationalUnit.value
 4478 	CN              = TheForm.CommonName.value
 4479 	Email		= TheForm.EmailAddress.value
 4480         szPurpose       = "ClientAuth"
 4481         doAcceptanceUINow   = FALSE
 4482         doOnline        = TRUE
 4484 	DN = ""
 4486 	Call Add_RDN("C", C)
 4487 	Call Add_RDN("S", SP)
 4488 	Call Add_RDN("L", L)
 4489 	Call Add_RDN("O", O)
 4490 	Call Add_RDN("OU", OU)
 4491 	Call Add_RDN("CN", CN)
 4492 	Call Add_RDN("1.2.840.113549.1.9.1", Email)
 4493 		      ' rsadsi
 4494 				     ' pkcs
 4495 				       ' pkcs9
 4496 					 ' eMailAddress
 4497         On Error Resume Next
 4498         sz10 = certHelper.GenerateKeyPair(sessionId, _
 4499                 FALSE, DN, 0, ClientAuth, FASLE, TRUE, 1)_
 4500         theError = Err.Number
 4501         On Error Goto 0
 4502         if (sz10 = Empty OR theError <> 0) Then
 4503             sz = "The error '" & Hex(theError) & "' occurred." & chr(13) & _
 4504                 chr(10) & "Your credentials could not be generated."
 4505             result = MsgBox(sz, 0, "Credentials Enrollment")
 4506             Exit Sub
 4507 	else 
 4508 	    TheForm.Request.value = sz10
 4509 	    TheForm.Submit
 4510         end if
 4511     End Sub
 4513     Sub Add_RDN(sn, value)
 4514 	if (value <> "") then
 4515 	    if (DN <> "") then
 4516 		DN = DN & "; "
 4517 	    end if
 4518 	    DN = DN & sn & "=" & value
 4519 	end if
 4520     End Sub
 4521 </SCRIPT>
 4522 </BODY>
 4523 </HTML>
 4524 EOF
 4525 -----END ms-enroll.cgi-----
 4527 Second, how to extract the request and feed the certificate back? We need to 
 4528 "normalize" the base64 encoding of the PKCS#10 format which means 
 4529 regenerating the lines and wrapping with BEGIN and END line. This is done by 
 4530 gawk. The request is taken by ca the normal way. Then the cert needs to be 
 4531 packed into a PKCS#7 structure (note: the use of a CRL is necessary for 
 4532 crl2pkcs7 as of version 0.6.6. Starting with 0.8.0 it it might probably be 
 4533 ommited). Finally we need to format the PKCS#7 object and generate the HTML 
 4534 text. I use two templates to have a clearer script.
 4536 1st note: postit2 is slightly modified from a program I found at ncsa's ftp 
 4537 site. Grab it from http://www.easterngraphics.com/certs/IX9704/postit2.c. You 
 4538 need utils.c from there too.
 4540 2nd note: I'm note quite sure wether the gawk script really handles all 
 4541 possible inputs for the request right! Today I don't use this construction 
 4542 anymore myself.
 4544 3d note: the cert must be of version 3! This could be done with the nsComment 
 4545 line in ssleay.cnf...
 4547 ------BEGIN ms-gencert.cgi-----
 4548 #!/bin/sh
 4549 FILE="/tmp/"`date '+%y%m%d%H%M%S'-`$$
 4550 rm -f "$FILE".*
 4552 HOME=`pwd`; export HOME  # as ssleay.cnf insists on having such an env var
 4553 cd /usr/local/ssl #where demoCA (as named in ssleay.conf) is located
 4555 postit2 -s " " -i 0x0d > "$FILE".inp  # process the FORM vars
 4557 SESSION_ID=`gawk '$1 == "SessionId" { print $2; exit }' "$FILE".inp`
 4559 gawk \
 4560 	'BEGIN { \
 4561 		OFS = ""; \
 4562 		print "-----BEGIN CERTIFICATE REQUEST-----"; \
 4563 		req_seen=0 \
 4564 	} \
 4565 	$1 == "Request" { \
 4566 		req_seen=1; \
 4567 		if (length($2) == 72) print($2); \
 4568 		lastline=$2; \
 4569 		next; \
 4570 	} \
 4571 	{ \
 4572 		if (req_seen == 1) { \
 4573 			if (length($1) >= 72) print($1); \
 4574 			else if (length(lastline) < 72) { \
 4575 				req_seen=0; \
 4576 				print (lastline,$1); \
 4577 			} \
 4578 		lastline=$1; \
 4579 		} \
 4580 	} \
 4581 	END { \
 4582 		print "-----END CERTIFICATE REQUEST-----"; \
 4583 	}' > "$FILE".pem < "$FILE".inp 
 4585 ssleay ca -batch -in "$FILE".pem -key passwd -out "$FILE".out
 4586 ssleay crl2pkcs7 -certfile "$FILE".out -out "$FILE".pkcs7 -in demoCA/crl.pem
 4588 sed s/template_for_sessId/$SESSION_ID/ <ms-enroll2a.html >"$FILE".cert
 4589 /usr/local/bin/gawk \
 4590 	'BEGIN	{ \
 4591 		OFS = ""; \
 4592 		dq = sprintf("%c",34); \
 4593 	} \
 4594 	$0 ~ "PKCS7" { next; } \
 4595 	{ \
 4596 		print dq$0dq" & _"; \
 4597 	}' <"$FILE".pkcs7 >> "$FILE".cert
 4598 cat  ms-enroll2b.html >>"$FILE".cert
 4600 echo Content-type: text/html
 4601 echo Content-length: `wc -c "$FILE".cert`
 4602 echo
 4603 cat "$FILE".cert
 4604 rm -f "$FILE".*
 4605 -----END ms-gencert.cgi-----
 4607 ----BEGIN ms-enroll2a.html----
 4608 <HTML><HEAD><TITLE>Certificate Acceptance Test Page</TITLE></HEAD><BODY>
 4610 <OBJECT
 4611     classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43"
 4612     codebase=certenr3.dll
 4613     id=certHelper
 4614     >
 4615 </OBJECT>
 4617 <CENTER>
 4618 <H2>Your personal certificate</H2>
 4619 <BR><HR WIDTH=50%><BR><P>
 4620 Press the button!
 4621 <P><INPUT TYPE=BUTTON VALUE="Nimm mich!" NAME="InstallCert">
 4622 </CENTER>
 4623 <BR><HR WIDTH=50%><BR>
 4626     Sub InstallCert_OnClick
 4628 	sessionId	= "template_for_sessId"
 4629 credentials = "" & _
 4630 ----END ms-enroll2a.html----
 4632 ----BEGIN ms-enroll2b.html----
 4633 ""
 4634         On Error Resume Next
 4635         result = certHelper.AcceptCredentials(sessionId, credentials, 0, 
 4636 FALSE)
 4637         if (IsEmpty(result)) Then
 4638            sz = "The error '" & Err.Number & "' occurred." & chr(13) & 
 4639 chr(10) & "This Digital ID could not be registered."
 4640            msgOut = MsgBox(sz, 0, "Credentials Registration Error")
 4641            navigate "error.html"
 4642         else
 4643            sz = "Digital ID successfully registered."
 4644            msgOut = MsgBox(sz, 0, "Credentials Registration")
 4645            navigate "success.html"
 4646         end if
 4647 	Exit Sub
 4648     End Sub
 4649 </SCRIPT>
 4650 </BODY>
 4651 </HTML>
 4652 ----END ms-enroll2b.html----
 4654 4.) What do do with the cert?
 4655 -----------------------------
 4657 The cert is visible (without restarting MSIE) under the following menu:
 4658 View->Options->Security->Personal certs. You can examine it's contents at 
 4659 least partially.
 4661 To use it for client authentication you need to use SSL3.0 (fortunately 
 4662 SSLeay supports it with 0.8.0). Furthermore MSIE is told to only supports a 
 4663 kind of automatic selection of certs (I personally wasn't able to test it 
 4664 myself). But there is a requirement that the issuer of the server cert and 
 4665 the issuer of the client cert needs to be the same (according to a developer 
 4666 from MS). Which means: you need may more then one cert to talk to all 
 4667 servers...
 4669 I'm sure we will get a bit more experience after ApacheSSL is available for 
 4670 SSLeay 0.8.8.
 4673 I hope you enjoyed reading and that in future questions on this topic will 
 4674 rarely appear on ssl-users@moncom.com ;-)
 4676 Ilmenau, 9th of June 1997
 4677 Holger Reif <reif@prakinf.tu-ilmenau.de>
 4678 -- 
 4679 read you later  -  Holger Reif
 4680 ----------------------------------------  Signaturprojekt Deutsche Einheit
 4681 TU Ilmenau - Informatik - Telematik                      (Verdamp lang her)
 4682 Holger.Reif@PrakInf.TU-Ilmenau.DE         Alt wie ein Baum werden, um ueber
 4683 http://Remus.PrakInf.TU-Ilmenau.DE/Reif/  alle 7 Bruecken gehen zu koennen
 4686 ==== ns-ca.doc ========================================================
 4688 The following documentation was supplied by Jeff Barber, who provided the
 4689 patch to the CA program to add this functionality.
 4691 eric
 4692 --
 4693 Jeff Barber                                Email: jeffb@issl.atl.hp.com
 4695 Hewlett Packard                            Phone: (404) 648-9503
 4696 Internet and System Security Lab           Fax:   (404) 648-9516
 4698                          oo
 4699 ---------------------cut /\ here for ns-ca.doc ------------------------------
 4701 This document briefly describes how to use SSLeay to implement a 
 4702 certificate authority capable of dynamically serving up client
 4703 certificates for version 3.0 beta 5 (and presumably later) versions of
 4704 the Netscape Navigator.  Before describing how this is done, it's
 4705 important to understand a little about how the browser implements its
 4706 client certificate support.  This is documented in some detail in the
 4707 URLs based at <URL:http://home.netscape.com/eng/security/certs.html>.
 4708 Here's a brief overview:
 4710 -	The Navigator supports a new HTML tag "KEYGEN" which will cause
 4711 	the browser to generate an RSA key pair when you submit a form
 4712 	containing the tag.  The public key, along with an optional
 4713 	challenge (supposedly provided for use in certificate revocation
 4714 	but I don't use it) is signed, DER-encoded, base-64 encoded
 4715 	and sent to the web server as the value of the variable
 4716 	whose NAME is provided in the KEYGEN tag.  The private key is
 4717 	stored by the browser in a local key database.
 4719 	This "Signed Public Key And Challenge" (SPKAC) arrives formatted
 4720 	into 64 character lines (which are of course URL-encoded when 
 4721 	sent via HTTP -- i.e. spaces, newlines and most punctuatation are
 4722 	encoded as "%HH" where HH is the hex equivalent of the ASCII code).
 4723 	Note that the SPKAC does not contain the other usual attributes
 4724 	of a certificate request, especially the subject name fields.
 4725 	These must be otherwise encoded in the form for submission along
 4726 	with the SPKAC.
 4728 -	Either immediately (in response to this form submission), or at
 4729 	some later date (a real CA will probably verify your identity in
 4730 	some way before issuing the certificate), a web server can send a
 4731 	certificate based on the public key and other attributes back to
 4732 	the browser by encoding it in DER (the binary form) and sending it
 4733 	to the browser as MIME type:
 4734 	"Content-type: application/x-x509-user-cert"
 4736 	The browser uses the public key encoded in the certificate to
 4737 	associate the certificate with the appropriate private key in
 4738 	its local key database.  Now, the certificate is "installed".
 4740 -	When a server wants to require authentication based on client
 4741 	certificates, it uses the right signals via the SSL protocol to
 4742 	trigger the Navigator to ask you which certificate you want to
 4743 	send.  Whether the certificate is accepted is dependent on CA
 4744 	certificates and so forth installed in the server and is beyond
 4745 	the scope of this document.
 4748 Now, here's how the SSLeay package can be used to provide client 
 4749 certficates:
 4751 -	You prepare a file for input to the SSLeay ca application.
 4752 	The file contains a number of "name = value" pairs that identify
 4753 	the subject.  The names here are the same subject name component
 4754 	identifiers used in the CA section of the lib/ssleay.conf file,
 4755 	such as "emailAddress", "commonName" "organizationName" and so
 4756 	forth.  Both the long version and the short version (e.g. "Email",
 4757 	"CN", "O") can be used.
 4759 	One more name is supported: this one is "SPKAC".  Its value
 4760 	is simply the value of the base-64 encoded SPKAC sent by the
 4761 	browser (with all the newlines and other space charaters
 4762 	removed -- and newline escapes are NOT supported).
 4764 	[ As of SSLeay 0.6.4, multiple lines are supported.
 4765 	  Put a \ at the end of each line and it will be joined with the
 4766 	  previous line with the '\n' removed - eay ]
 4768 	Here's a sample input file:
 4770 C = US
 4771 SP = Georgia
 4772 O = Some Organization, Inc.
 4773 OU = Netscape Compatibility Group
 4774 CN = John X. Doe
 4775 Email = jxdoe@someorg.com
 4778 -	You execute the ca command (either from a CGI program run out of
 4779 	the web server, or as a later manual task) giving it the above
 4780 	file as input.  For example, if the file were named /tmp/cert.req,
 4781 	you'd run:
 4782 	$SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert
 4784 	The output is in DER format (binary) if a -out argument is 
 4785 	provided, as above; otherwise, it's in the PEM format (base-64
 4786 	encoded DER).  Also, the "-batch" switch is implied by the
 4787 	"-spkac" so you don't get asked whether to complete the signing
 4788 	(probably it shouldn't work this way but I was only interested
 4789 	in hacking together an online CA that could be used for issuing
 4790 	test certificates).
 4792 	The "-spkac" capability doesn't support multiple files (I think).
 4794 	Any CHALLENGE provided in the SPKAC is simply ignored.
 4796 	The interactions between the identification fields you provide
 4797 	and those identified in your lib/ssleay.conf are the same as if
 4798 	you did an ordinary "ca -in infile -out outfile" -- that is, if
 4799 	something is marked as required in the ssleay.conf file and it
 4800 	isn't found in the -spkac file, the certificate won't be issued.
 4802 -	Now, you pick up the output from /tmp/cert and pass it back to
 4803 	the Navigator prepending the Content-type string described earlier.
 4805 -	In order to run the ca command out of a CGI program, you must
 4806 	provide a password to decrypt the CA's private key.  You can
 4807 	do this by using "echo MyKeyPassword | $SSLDIR/bin/ca ..."
 4808 	I think there's a way to not encrypt the key file in the first
 4809 	place, but I didn't see how to do that, so I made a small change
 4810 	to the library that allows the password to be accepted from a pipe.
 4811 	Either way is UTTERLY INSECURE and a real CA would never do that.
 4813 	[ You can use the 'ssleay rsa' command to remove the password
 4814 	  from the private key, or you can use the '-key' option to the
 4815 	  ca command to specify the decryption key on the command line
 4816 	  or use the -nodes option when generating the key.
 4817 	  ca will try to clear the command line version of the password
 4818 	  but for quite a few operating systems, this is not possible.
 4819 	  - eric ]
 4821 So, what do you have to do to make use of this stuff to create an online 
 4822 demo CA capability with SSLeay?
 4824 1	Create an HTML form for your users.  The form should contain
 4825 	fields for all of the required or optional fields in ssleay.conf.
 4826 	The form must contain a KEYGEN tag somewhere with at least a NAME
 4827 	attribute.
 4829 2	Create a CGI program to process the form input submitted by the
 4830 	browser.  The CGI program must URL-decode the variables and create
 4831 	the file described above, containing subject identification info
 4832 	as well as the SPKAC block.  It should then run the the ca program
 4833 	with the -spkac option.  If it works (check the exit status),
 4834 	return the new certificate with the appropriate MIME type.  If not,
 4835 	return the output of the ca command with MIME type "text/plain".
 4837 3	Set up your web server to accept connections signed by your demo
 4838 	CA.  This probably involves obtaining the PEM-encoded CA certificate
 4839 	(ordinarily in $SSLDIR/CA/cacert.pem) and installing it into a
 4840 	server database.  See your server manual for instructions.
 4843 ==== obj.doc ========================================================
 4845 The Object library.
 4847 As part of my Crypto library, I found I required a method of identifying various
 4848 objects.  These objects normally had 3 different values associated with
 4849 them, a short text name, a long (or lower case) text name, and an
 4850 ASN.1 Object Identifier (which is a sequence of numbers).
 4851 This library contains a static list of objects and functions to lookup
 4852 according to one type and to return the other types.
 4854 To use these routines, 'Object.h' needs to be included.
 4856 For each supported object, #define entries are defined as follows
 4857 #define SN_Algorithm			"Algorithm"
 4858 #define LN_algorithm			"algorithm"
 4859 #define NID_algorithm			38
 4860 #define OBJ_algorithm			1L,3L,14L,3L,2L
 4862 SN_  stands for short name.
 4863 LN_  stands for either long name or lowercase name.
 4864 NID_ stands for Numeric ID.  I each object has a unique NID and this
 4865      should be used internally to identify objects.
 4866 OBJ_ stands for ASN.1 Object Identifier or ASN1_OBJECT as defined in the
 4867      ASN1 routines.  These values are used in ASN1 encoding.
 4869 The following functions are to be used to return pointers into a static
 4870 definition of these types.  What this means is "don't try to free() any
 4871 pointers returned from these functions.
 4873 ASN1_OBJECT *OBJ_nid2obj(
 4874 int n);
 4875 	Return the ASN1_OBJECT that corresponds to a NID of n.
 4877 char *OBJ_nid2ln(
 4878 int n);
 4879 	Return the long/lower case name of the object represented by the
 4880 	NID of n.
 4882 char *OBJ_nid2sn(
 4883 int n);
 4884 	Return the short name for the object represented by the NID of n.
 4886 ASN1_OBJECT *OBJ_dup(
 4887 ASN1_OBJECT *o);
 4888 	Duplicate and return a new ASN1_OBJECT that is the same as the
 4889 	passed parameter.
 4891 int OBJ_obj2nid(
 4892 ASN1_OBJECT *o);
 4893 	Given ASN1_OBJECT o, return the NID that corresponds.
 4895 int OBJ_ln2nid(
 4896 char *s);
 4897 	Given the long/lower case name 's', return the NID of the object.
 4899 int OBJ_sn2nid(
 4900 char *s);
 4901 	Given the short name 's', return the NID of the object.
 4903 char *OBJ_bsearch(
 4904 char *key,
 4905 char *base,
 4906 int num,
 4907 int size,
 4908 int (*cmp)());
 4909 	Since I have come across a few platforms that do not have the
 4910 	bsearch() function, OBJ_bsearch is my version of that function.
 4911 	Feel free to use this function, but you may as well just use the
 4912 	normal system bsearch(3) if it is present.  This version also
 4913 	has tolerance of being passed NULL pointers.
 4915 ==== keys ===========================================================
 4925 valid DSA pkey types
 4926 	NID_dsa
 4927 	NID_dsaWithSHA
 4928 	NID_dsaWithSHA1
 4929 	NID_dsaWithSHA1_2
 4931 valid RSA pkey types
 4932 	NID_rsaEncryption
 4933 	NID_rsa
 4935 NID_dsaWithSHA	NID_dsaWithSHA			DSA		SHA
 4936 NID_dsa		NID_dsaWithSHA1			DSA		SHA1
 4937 NID_md2		NID_md2WithRSAEncryption	RSA-pkcs1	MD2
 4938 NID_md5		NID_md5WithRSAEncryption	RSA-pkcs1	MD5
 4939 NID_mdc2	NID_mdc2WithRSA			RSA-none	MDC2
 4940 NID_ripemd160	NID_ripemd160WithRSA		RSA-pkcs1	RIPEMD160
 4941 NID_sha		NID_shaWithRSAEncryption	RSA-pkcs1	SHA
 4942 NID_sha1	NID_sha1WithRSAEncryption	RSA-pkcs1	SHA1
 4944 ==== rand.doc ========================================================
 4946 My Random number library.
 4948 These routines can be used to generate pseudo random numbers and can be
 4949 used to 'seed' the pseudo random number generator (RNG).  The RNG make no
 4950 effort to reproduce the same random number stream with each execution.
 4951 Various other routines in the SSLeay library 'seed' the RNG when suitable
 4952 'random' input data is available.  Read the section at the end for details
 4953 on the design of the RNG.
 4955 void RAND_bytes(
 4956 unsigned char *buf,
 4957 int num);
 4958 	This routine puts 'num' random bytes into 'buf'.  One should make
 4959 	sure RAND_seed() has been called before using this routine.
 4961 void RAND_seed(
 4962 unsigned char *buf,
 4963 int num);
 4964 	This routine adds more 'seed' data the RNG state.  'num' bytes
 4965 	are added to the RNG state, they are taken from 'buf'.  This
 4966 	routine can be called with sensitive data such as user entered
 4967 	passwords.  This sensitive data is in no way recoverable from
 4968 	the RAND library routines or state.  Try to pass as much data
 4969 	from 'random' sources as possible into the RNG via this function.
 4970 	Also strongly consider using the RAND_load_file() and
 4971 	RAND_write_file() routines.
 4973 void RAND_cleanup();
 4974 	When a program has finished with the RAND library, if it so
 4975 	desires, it can 'zero' all RNG state.
 4977 The following 3 routines are convenience routines that can be used to
 4978 'save' and 'restore' data from/to the RNG and it's state.
 4979 Since the more 'random' data that is feed as seed data the better, why not
 4980 keep it around between executions of the program?  Of course the
 4981 application should pass more 'random' data in via RAND_seed() and 
 4982 make sure no-one can read the 'random' data file.
 4984 char *RAND_file_name(
 4985 char *buf,
 4986 int size);
 4987 	This routine returns a 'default' name for the location of a 'rand'
 4988 	file.  The 'rand' file should keep a sequence of random bytes used
 4989 	to initialise the RNG.  The filename is put in 'buf'.  Buf is 'size'
 4990 	bytes long.  Buf is returned if things go well, if they do not,
 4991 	NULL is returned.  The 'rand' file name is generated in the
 4992 	following way.  First, if there is a 'RANDFILE' environment
 4993 	variable, it is returned.  Second, if there is a 'HOME' environment
 4994 	variable, $HOME/.rand is returned.  Third, NULL is returned.  NULL
 4995 	is also returned if a buf would overflow.
 4997 int RAND_load_file(
 4998 char *file,
 4999 long number);
 5000 	This function 'adds' the 'file' into the RNG state.  It does this by
 5001 	doing a RAND_seed() on the value returned from a stat() system call
 5002 	on the file and if 'number' is non-zero, upto 'number' bytes read
 5003 	from the file.  The number of bytes passed to RAND_seed() is returned.
 5005 int RAND_write_file(
 5006 char *file),
 5007 	RAND_write_file() writes N random bytes to the file 'file', where
 5008 	N is the size of the internal RND state (currently 1k).
 5009 	This is a suitable method of saving RNG state for reloading via
 5010 	RAND_load_file().
 5012 What follows is a description of this RNG and a description of the rational
 5013 behind it's design.
 5015 It should be noted that this RNG is intended to be used to generate
 5016 'random' keys for various ciphers including generation of DH and RSA keys.  
 5018 It should also be noted that I have just created a system that I am happy with.
 5019 It may be overkill but that does not worry me.  I have not spent that much
 5020 time on this algorithm so if there are glaring errors, please let me know.
 5021 Speed has not been a consideration in the design of these routines.
 5023 First up I will state the things I believe I need for a good RNG.
 5024 1) A good hashing algorithm to mix things up and to convert the RNG 'state'
 5025    to random numbers.
 5026 2) An initial source of random 'state'.
 5027 3) The state should be very large.  If the RNG is being used to generate
 5028    4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum).
 5029    If your RNG state only has 128 bits, you are obviously limiting the
 5030    search space to 128 bits, not 2048.  I'm probably getting a little
 5031    carried away on this last point but it does indicate that it may not be
 5032    a bad idea to keep quite a lot of RNG state.  It should be easier to
 5033    break a cipher than guess the RNG seed data.
 5034 4) Any RNG seed data should influence all subsequent random numbers
 5035    generated.  This implies that any random seed data entered will have
 5036    an influence on all subsequent random numbers generated.
 5037 5) When using data to seed the RNG state, the data used should not be
 5038    extractable from the RNG state.  I believe this should be a
 5039    requirement because one possible source of 'secret' semi random
 5040    data would be a private key or a password.  This data must
 5041    not be disclosed by either subsequent random numbers or a
 5042    'core' dump left by a program crash.
 5043 6) Given the same initial 'state', 2 systems should deviate in their RNG state
 5044    (and hence the random numbers generated) over time if at all possible.
 5045 7) Given the random number output stream, it should not be possible to determine
 5046    the RNG state or the next random number.
 5049 The algorithm is as follows.
 5051 There is global state made up of a 1023 byte buffer (the 'state'), a
 5052 working message digest ('md') and a counter ('count').
 5054 Whenever seed data is added, it is inserted into the 'state' as
 5055 follows.
 5056 	The input is chopped up into units of 16 bytes (or less for
 5057 	the last block).  Each of these blocks is run through the MD5
 5058 	message digest.  The data passed to the MD5 digest is the
 5059 	current 'md', the same number of bytes from the 'state'
 5060 	(the location determined by in incremented looping index) as
 5061 	the current 'block' and the new key data 'block'.  The result
 5062 	of this is kept in 'md' and also xored into the 'state' at the
 5063 	same locations that were used as input into the MD5.
 5064 	I believe this system addresses points 1 (MD5), 3 (the 'state'),
 5065 	4 (via the 'md'), 5 (by the use of MD5 and xor).
 5067 When bytes are extracted from the RNG, the following process is used.
 5068 For each group of 8 bytes (or less), we do the following,
 5069 	Input into MD5, the top 8 bytes from 'md', the byte that are
 5070 	to be overwritten by the random bytes and bytes from the
 5071 	'state' (incrementing looping index).  From this digest output
 5072 	(which is kept in 'md'), the top (upto) 8 bytes are
 5073 	returned to the caller and the bottom (upto) 8 bytes are xored
 5074 	into the 'state'.
 5075 	Finally, after we have finished 'generation' random bytes for the
 5076 	called, 'count' (which is incremented) and 'md' are fed into MD5 and
 5077 	the results are kept in 'md'.
 5078 	I believe the above addressed points 1 (use of MD5), 6 (by
 5079 	hashing into the 'state' the 'old' data from the caller that
 5080 	is about to be overwritten) and 7 (by not using the 8 bytes
 5081 	given to the caller to update the 'state', but they are used
 5082 	to update 'md').
 5084 So of the points raised, only 2 is not addressed, but sources of
 5085 random data will always be a problem.
 5088 ==== rc2.doc ========================================================
 5090 The RC2 library.
 5092 RC2 is a block cipher that operates on 64bit (8 byte) quantities.  It
 5093 uses variable size key, but 128bit (16 byte) key would normally be considered
 5094 good.  It can be used in all the modes that DES can be used.  This
 5095 library implements the ecb, cbc, cfb64, ofb64 modes.
 5097 I have implemented this library from an article posted to sci.crypt on
 5098 11-Feb-1996.  I personally don't know how far to trust the RC2 cipher.
 5099 While it is capable of having a key of any size, not much reseach has
 5100 publically been done on it at this point in time (Apr-1996)
 5101 since the cipher has only been public for a few months :-)
 5102 It is of a similar speed to DES and IDEA, so unless it is required for
 5103 meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable
 5104 to stick to IDEA, or for the paranoid, Tripple DES.
 5106 Mind you, having said all that, I should mention that I just read alot and
 5107 implement ciphers, I'm a 'babe in the woods' when it comes to evaluating
 5108 ciphers :-).
 5110 For all calls that have an 'input' and 'output' variables, they can be the
 5111 same.
 5113 This library requires the inclusion of 'rc2.h'.
 5115 All of the encryption functions take what is called an RC2_KEY as an 
 5116 argument.  An RC2_KEY is an expanded form of the RC2 key.
 5117 For all modes of the RC2 algorithm, the RC2_KEY used for
 5118 decryption is the same one that was used for encryption.
 5120 The define RC2_ENCRYPT is passed to specify encryption for the functions
 5121 that require an encryption/decryption flag. RC2_DECRYPT is passed to
 5122 specify decryption.
 5124 Please note that any of the encryption modes specified in my DES library
 5125 could be used with RC2.  I have only implemented ecb, cbc, cfb64 and
 5126 ofb64 for the following reasons.
 5127 - ecb is the basic RC2 encryption.
 5128 - cbc is the normal 'chaining' form for block ciphers.
 5129 - cfb64 can be used to encrypt single characters, therefore input and output
 5130   do not need to be a multiple of 8.
 5131 - ofb64 is similar to cfb64 but is more like a stream cipher, not as
 5132   secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
 5133 - If you want triple RC2, thats 384 bits of key and you must be totally
 5134   obsessed with security.  Still, if you want it, it is simple enough to
 5135   copy the function from the DES library and change the des_encrypt to
 5136   RC2_encrypt; an exercise left for the paranoid reader :-).
 5138 The functions are as follows:
 5140 void RC2_set_key(
 5141 RC2_KEY *ks;
 5142 int len;
 5143 unsigned char *key;
 5144 int bits;
 5145         RC2_set_key converts an 'len' byte key into a RC2_KEY.
 5146         A 'ks' is an expanded form of the 'key' which is used to
 5147         perform actual encryption.  It can be regenerated from the RC2 key
 5148         so it only needs to be kept when encryption or decryption is about
 5149         to occur.  Don't save or pass around RC2_KEY's since they
 5150         are CPU architecture dependent, 'key's are not.  RC2 is an
 5151 	interesting cipher in that it can be used with a variable length
 5152 	key.  'len' is the length of 'key' to be used as the key.
 5153 	A 'len' of 16 is recomended.  The 'bits' argument is an
 5154 	interesting addition which I only found out about in Aug 96.
 5155 	BSAFE uses this parameter to 'limit' the number of bits used
 5156 	for the key.  To use the 'key' unmodified, set bits to 1024.
 5157 	This is what old versions of my RC2 library did (SSLeay 0.6.3).
 5158 	RSAs BSAFE library sets this parameter to be 128 if 128 bit
 5159 	keys are being used.  So to be compatable with BSAFE, set it
 5160 	to 128, if you don't want to reduce RC2's key length, leave it
 5161 	at 1024.
 5163 void RC2_encrypt(
 5164 unsigned long *data,
 5165 RC2_KEY *key,
 5166 int encrypt);
 5167 	This is the RC2 encryption function that gets called by just about
 5168 	every other RC2 routine in the library.  You should not use this
 5169 	function except to implement 'modes' of RC2.  I say this because the
 5170 	functions that call this routine do the conversion from 'char *' to
 5171 	long, and this needs to be done to make sure 'non-aligned' memory
 5172 	access do not occur.
 5173 	Data is a pointer to 2 unsigned long's and key is the
 5174 	RC2_KEY to use.  Encryption or decryption is indicated by 'encrypt'.
 5175 	which can have the values RC2_ENCRYPT or RC2_DECRYPT.
 5177 void RC2_ecb_encrypt(
 5178 unsigned char *in,
 5179 unsigned char *out,
 5180 RC2_KEY *key,
 5181 int encrypt);
 5182 	This is the basic Electronic Code Book form of RC2 (in DES this
 5183 	mode is called Electronic Code Book so I'm going to use the term
 5184 	for rc2 as well.
 5185 	Input is encrypted into output using the key represented by
 5186 	key.  Depending on the encrypt, encryption or
 5187 	decryption occurs.  Input is 8 bytes long and output is 8 bytes.
 5189 void RC2_cbc_encrypt(
 5190 unsigned char *in,
 5191 unsigned char *out,
 5192 long length,
 5193 RC2_KEY *ks,
 5194 unsigned char *ivec,
 5195 int encrypt);
 5196 	This routine implements RC2 in Cipher Block Chaining mode.
 5197 	Input, which should be a multiple of 8 bytes is encrypted
 5198 	(or decrypted) to output which will also be a multiple of 8 bytes.
 5199 	The number of bytes is in length (and from what I've said above,
 5200 	should be a multiple of 8).  If length is not a multiple of 8, bad 
 5201 	things will probably happen.  ivec is the initialisation vector.
 5202 	This function updates iv after each call so that it can be passed to
 5203 	the next call to RC2_cbc_encrypt().
 5205 void RC2_cfb64_encrypt(
 5206 unsigned char *in,
 5207 unsigned char *out,
 5208 long length,
 5209 RC2_KEY *schedule,
 5210 unsigned char *ivec,
 5211 int *num,
 5212 int encrypt);
 5213 	This is one of the more useful functions in this RC2 library, it
 5214 	implements CFB mode of RC2 with 64bit feedback.
 5215 	This allows you to encrypt an arbitrary number of bytes,
 5216 	you do not require 8 byte padding.  Each call to this
 5217 	routine will encrypt the input bytes to output and then update ivec
 5218 	and num.  Num contains 'how far' we are though ivec.
 5219 	'Encrypt' is used to indicate encryption or decryption.
 5220 	CFB64 mode operates by using the cipher to generate a stream
 5221 	of bytes which is used to encrypt the plain text.
 5222 	The cipher text is then encrypted to generate the next 64 bits to
 5223 	be xored (incrementally) with the next 64 bits of plain
 5224 	text.  As can be seen from this, to encrypt or decrypt,
 5225 	the same 'cipher stream' needs to be generated but the way the next
 5226 	block of data is gathered for encryption is different for
 5227 	encryption and decryption.
 5229 void RC2_ofb64_encrypt(
 5230 unsigned char *in,
 5231 unsigned char *out,
 5232 long length,
 5233 RC2_KEY *schedule,
 5234 unsigned char *ivec,
 5235 int *num);
 5236 	This functions implements OFB mode of RC2 with 64bit feedback.
 5237 	This allows you to encrypt an arbitrary number of bytes,
 5238 	you do not require 8 byte padding.  Each call to this
 5239 	routine will encrypt the input bytes to output and then update ivec
 5240 	and num.  Num contains 'how far' we are though ivec.
 5241 	This is in effect a stream cipher, there is no encryption or
 5242 	decryption mode.
 5244 For reading passwords, I suggest using des_read_pw_string() from my DES library.
 5245 To generate a password from a text string, I suggest using MD5 (or MD2) to
 5246 produce a 16 byte message digest that can then be passed directly to
 5247 RC2_set_key().
 5249 =====
 5250 For more information about the specific RC2 modes in this library
 5251 (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
 5252 documentation on my DES library.  What is said about DES is directly
 5253 applicable for RC2.
 5256 ==== rc4.doc ========================================================
 5258 The RC4 library.
 5259 RC4 is a stream cipher that operates on a byte stream.  It can be used with
 5260 any length key but I would recommend normally using 16 bytes.
 5262 This library requires the inclusion of 'rc4.h'.
 5264 The RC4 encryption function takes what is called an RC4_KEY as an argument.
 5265 The RC4_KEY is generated by the RC4_set_key function from the key bytes.
 5267 RC4, being a stream cipher, does not have an encryption or decryption mode.
 5268 It produces a stream of bytes that the input stream is xor'ed against and
 5269 so decryption is just a case of 'encrypting' again with the same key.
 5271 I have only put in one 'mode' for RC4 which is the normal one.  This means
 5272 there is no initialisation vector and there is no feedback of the cipher
 5273 text into the cipher.  This implies that you should not ever use the
 5274 same key twice if you can help it.  If you do, you leave yourself open to
 5275 known plain text attacks; if you know the plain text and
 5276 corresponding cipher text in one message, all messages that used the same
 5277 key can have the cipher text decoded for the corresponding positions in the
 5278 cipher stream.
 5280 The main positive feature of RC4 is that it is a very fast cipher; about 4
 5281 times faster that DES.  This makes it ideally suited to protocols where the
 5282 key is randomly chosen, like SSL.
 5284 The functions are as follows:
 5286 void RC4_set_key(
 5287 RC4_KEY *key;
 5288 int len;
 5289 unsigned char *data);
 5290 	This function initialises the RC4_KEY structure with the key passed
 5291 	in 'data', which is 'len' bytes long.  The key data can be any
 5292 	length but 16 bytes seems to be a good number.
 5294 void RC4(
 5295 RC4_KEY *key;
 5296 unsigned long len;
 5297 unsigned char *in;
 5298 unsigned char *out);
 5299 	Do the actual RC4 encryption/decryption.  Using the 'key', 'len'
 5300 	bytes are transformed from 'in' to 'out'.  As mentioned above,
 5301 	decryption is the operation as encryption.
 5303 ==== ref.doc ========================================================
 5305 I have lots more references etc, and will update this list in the future,
 5306 30 Aug 1996 - eay
 5309 SSL	The SSL Protocol - from Netscapes.
 5311 RC4	Newsgroups: sci.crypt
 5312 	From: sterndark@netcom.com (David Sterndark)
 5313 	Subject: RC4 Algorithm revealed.
 5314 	Message-ID: <sternCvKL4B.Hyy@netcom.com>
 5316 RC2	Newsgroups: sci.crypt
 5317 	From: pgut01@cs.auckland.ac.nz (Peter Gutmann)
 5318 	Subject: Specification for Ron Rivests Cipher No.2
 5319 	Message-ID: <4fk39f$f70@net.auckland.ac.nz>
 5321 MD2	RFC1319 The MD2 Message-Digest Algorithm
 5322 MD5	RFC1321 The MD5 Message-Digest Algorithm
 5324 X509 Certificates
 5325 	RFC1421 Privacy Enhancement for Internet Electronic Mail: Part I
 5326 	RFC1422 Privacy Enhancement for Internet Electronic Mail: Part II
 5327 	RFC1423 Privacy Enhancement for Internet Electronic Mail: Part III
 5328 	RFC1424 Privacy Enhancement for Internet Electronic Mail: Part IV
 5330 RSA and various standard encoding
 5331 	PKCS#1 RSA Encryption Standard
 5332 	PKCS#5 Password-Based Encryption Standard
 5333 	PKCS#7 Cryptographic Message Syntax Standard
 5334 	A Layman's Guide to a Subset of ASN.1, BER, and DER
 5335 	An Overview of the PKCS Standards
 5336 	Some Examples of the PKCS Standards
 5338 IDEA	Chapter 3 The Block Cipher IDEA
 5340 RSA, prime number generation and bignum algorithms
 5341 	Introduction To Algorithms,
 5342 	Thomas Cormen, Charles Leiserson, Ronald Rivest,
 5343 	Section 29 Arithmetic Circuits
 5344 	Section 33 Number-Theoretic Algorithms
 5346 Fast Private Key algorithm
 5347 	Fast Decipherment Algorithm for RSA Public-Key Cryptosystem
 5348 	J.-J. Quisquater and C. Couvreur, Electronics Letters,
 5349 	14th October 1982, Vol. 18 No. 21
 5351 Prime number generation and bignum algorithms.
 5352 	PGP-2.3a
 5354 ==== rsa.doc ========================================================
 5356 The RSA encryption and utility routines.
 5358 The RSA routines are built on top of a big number library (the BN library).
 5359 There are support routines in the X509 library for loading and manipulating
 5360 the various objects in the RSA library.  When errors are returned, read
 5361 about the ERR library for how to access the error codes.
 5363 All RSA encryption is done according to the PKCS-1 standard which is
 5364 compatible with PEM and RSAref.  This means that any values being encrypted
 5365 must be less than the size of the modulus in bytes, minus 10, bytes long.
 5367 This library uses RAND_bytes()() for it's random data, make sure to feed
 5368 RAND_seed() with lots of interesting and varied data before using these
 5369 routines.
 5371 The RSA library has one specific data type, the RSA structure.
 5372 It is composed of 8 BIGNUM variables (see the BN library for details) and
 5373 can hold either a private RSA key or a public RSA key.
 5374 Some RSA libraries have different structures for public and private keys, I
 5375 don't.  For my libraries, a public key is determined by the fact that the
 5376 RSA->d value is NULL.  These routines will operate on any size RSA keys.
 5377 While I'm sure 4096 bit keys are very very secure, they take a lot longer
 5378 to process that 1024 bit keys :-).
 5380 The function in the RSA library are as follows.
 5382 RSA *RSA_new();
 5383 	This function creates a new RSA object.  The sub-fields of the RSA
 5384 	type are also malloced so you should always use this routine to
 5385 	create RSA variables.
 5387 void RSA_free(
 5388 RSA *rsa);
 5389 	This function 'frees' an RSA structure.  This routine should always
 5390 	be used to free the RSA structure since it will also 'free' any
 5391 	sub-fields of the RSA type that need freeing.
 5393 int RSA_size(
 5394 RSA *rsa);	
 5395 	This function returns the size of the RSA modulus in bytes.  Why do
 5396 	I need this you may ask, well the reason is that when you encrypt
 5397 	with RSA, the output string will be the size of the RSA modulus.
 5398 	So the output for the RSA_encrypt and the input for the RSA_decrypt
 5399 	routines need to be RSA_size() bytes long, because this is how many
 5400 	bytes are expected.
 5402 For the following 4 RSA encryption routines, it should be noted that
 5403 RSA_private_decrypt() should be used on the output from 
 5404 RSA_public_encrypt() and RSA_public_decrypt() should be used on
 5405 the output from RSA_private_encrypt().
 5407 int RSA_public_encrypt(
 5408 int from_len;
 5409 unsigned char *from	
 5410 unsigned char *to	
 5411 RSA *rsa);
 5412 	This function implements RSA public encryption, the rsa variable
 5413 	should be a public key (but can be a private key).  'from_len'
 5414 	bytes taken from 'from' and encrypted and put into 'to'.  'to' needs
 5415 	to be at least RSA_size(rsa) bytes long.  The number of bytes
 5416 	written into 'to' is returned.  -1 is returned on an error.  The
 5417 	operation performed is
 5418 	to = from^rsa->e mod rsa->n.
 5420 int RSA_private_encrypt(
 5421 int from_len;
 5422 unsigned char *from	
 5423 unsigned char *to	
 5424 RSA *rsa);
 5425 	This function implements RSA private encryption, the rsa variable
 5426 	should be a private key.  'from_len' bytes taken from
 5427 	'from' and encrypted and put into 'to'.  'to' needs
 5428 	to be at least RSA_size(rsa) bytes long.  The number of bytes
 5429 	written into 'to' is returned.  -1 is returned on an error.  The
 5430 	operation performed is
 5431 	to = from^rsa->d mod rsa->n.
 5433 int RSA_public_decrypt(
 5434 int from_len;
 5435 unsigned char *from	
 5436 unsigned char *to	
 5437 RSA *rsa);
 5438 	This function implements RSA public decryption, the rsa variable
 5439 	should be a public key (but can be a private key).  'from_len'
 5440 	bytes are taken from 'from' and decrypted.  The decrypted data is
 5441 	put into 'to'.  The number of bytes encrypted is returned.  -1 is
 5442 	returned to indicate an error. The operation performed is
 5443 	to = from^rsa->e mod rsa->n.
 5445 int RSA_private_decrypt(
 5446 int from_len;
 5447 unsigned char *from	
 5448 unsigned char *to	
 5449 RSA *rsa);
 5450 	This function implements RSA private decryption, the rsa variable
 5451 	should be a private key.  'from_len' bytes are taken
 5452 	from 'from' and decrypted.  The decrypted data is
 5453 	put into 'to'.  The number of bytes encrypted is returned.  -1 is
 5454 	returned to indicate an error. The operation performed is
 5455 	to = from^rsa->d mod rsa->n.
 5457 int RSA_mod_exp(
 5458 BIGNUM *n;
 5459 BIGNUM *p;
 5460 RSA *rsa);
 5461 	Normally you will never use this routine.
 5462 	This is really an internal function which is called by
 5463 	RSA_private_encrypt() and RSA_private_decrypt().  It performs
 5464 	n=n^p mod rsa->n except that it uses the 5 extra variables in the
 5465 	RSA structure to make this more efficient.
 5467 RSA *RSA_generate_key(
 5468 int bits;
 5469 unsigned long e;
 5470 void (*callback)();
 5471 char *cb_arg;
 5472 	This routine is used to generate RSA private keys.  It takes
 5473 	quite a period of time to run and should only be used to
 5474 	generate initial private keys that should then be stored
 5475 	for later use.  The passed callback function 
 5476 	will be called periodically so that feedback can be given
 5477 	as to how this function is progressing.
 5478 	'bits' is the length desired for the modulus, so it would be 1024
 5479 	to generate a 1024 bit private key.
 5480 	'e' is the value to use for the public exponent 'e'.  Traditionally
 5481 	it is set to either 3 or 0x10001.
 5482 	The callback function (if not NULL) is called in the following
 5483 	situations.
 5484 	when we have generated a suspected prime number to test,
 5485 	callback(0,num1++,cb_arg).  When it passes a prime number test,
 5486 	callback(1,num2++,cb_arg).  When it is rejected as one of
 5487 	the 2 primes required due to gcd(prime,e value) != 0,
 5488 	callback(2,num3++,cb_arg).  When finally accepted as one
 5489 	of the 2 primes, callback(3,num4++,cb_arg).
 5492 ==== rsaref.doc ========================================================
 5494 This package can be compiled to use the RSAref library.
 5495 This library is not allowed outside of the USA but inside the USA it is
 5496 claimed by RSA to be the only RSA public key library that can be used
 5497 besides BSAFE..
 5499 There are 2 files, rsaref/rsaref.c and rsaref/rsaref.h that contain the glue
 5500 code to use RSAref.  These files were written by looking at the PGP
 5501 source code and seeing which routines it used to access RSAref.
 5502 I have also been sent by some-one a copy of the RSAref header file that
 5503 contains the library error codes.
 5505 [ Jun 1996 update - I have recently gotten hold of RSAref 2.0 from
 5506   South Africa and have been doing some performace tests. ]
 5508 They have now been tested against the recently announced RSAEURO
 5509 library.
 5511 There are 2 ways to use SSLeay and RSAref.  First, to build so that
 5512 the programs must be linked with RSAref, add '-DRSAref' to CFLAG in the top
 5513 level makefile and -lrsaref (or where ever you are keeping RSAref) to
 5514 EX_LIBS.
 5516 To build a makefile via util/mk1mf.pl to do this, use the 'rsaref' option.
 5518 The second method is to build as per normal and link applications with
 5519 the RSAglue library.  The correct library order would be
 5520 cc -o cmd cmd.o -lssl -lRSAglue -lcrypto -lrsaref -ldes
 5521 The RSAglue library is built in the rsa directory and is NOT
 5522 automatically installed.
 5524 Be warned that the RSAEURO library, that is claimed to be compatible
 5525 with RSAref contains a different value for the maximum number of bits
 5526 supported.  This changes structure sizes and so if you are using
 5527 RSAEURO, change the value of RSAref_MAX_BITS in rsa/rsaref.h
 5530 ==== s_mult.doc ========================================================
 5532 s_mult is a test program I hacked up on a Sunday for testing non-blocking
 5533 IO.  It has a select loop at it's centre that handles multiple readers
 5534 and writers.
 5536 Try the following command
 5537 ssleay s_mult -echo -nbio -ssl -v
 5538 echo - sends any sent text back to the sender
 5539 nbio - turns on non-blocking IO
 5540 ssl  - accept SSL connections, default is normal text
 5541 v    - print lots
 5542 	type Q<cr> to quit
 5544 In another window, run the following
 5545 ssleay s_client -pause </etc/termcap
 5547 The pause option puts in a 1 second pause in each read(2)/write(2) call
 5548 so the other end will have read()s fail.
 5550 ==== session.doc ========================================================
 5552 I have just checked over and re-worked the session stuff.
 5553 The following brief example will ignore all setup information to do with
 5554 authentication.
 5556 Things operate as follows.
 5558 The SSL environment has a 'context', a SSL_CTX structure.  This holds the
 5559 cached SSL_SESSIONS (which can be reused) and the certificate lookup
 5560 information.  Each SSL structure needs to be associated with a SSL_CTX.
 5561 Normally only one SSL_CTX structure is needed per program.
 5563 SSL_CTX *SSL_CTX_new(void ); 
 5564 void    SSL_CTX_free(SSL_CTX *);
 5565 These 2 functions create and destroy SSL_CTX structures
 5567 The SSL_CTX has a session_cache_mode which is by default,
 5568 in SSL_SESS_CACHE_SERVER mode.  What this means is that the library
 5569 will automatically add new session-id's to the cache upon successful
 5570 SSL_accept() calls.
 5571 If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added
 5572 to the cache.
 5573 SSL_set_session_cache_mode(ctx,mode)  will set the 'mode' and
 5574 SSL_get_session_cache_mode(ctx) will get the cache 'mode'.
 5575 The modes can be
 5576 SSL_SESS_CACHE_OFF	- no caching
 5577 SSL_SESS_CACHE_CLIENT	- only SSL_connect()
 5578 SSL_SESS_CACHE_SERVER	- only SSL_accept()
 5579 SSL_SESS_NO_CACHE_BOTH	- Either SSL_accept() or SSL_connect().
 5580 If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are
 5581 not automatically removed each 255, SSL_connect()s or SSL_accept()s.
 5583 By default, upon every 255 successful SSL_connect() or SSL_accept()s,
 5584 the cache is flush.  Please note that this could be expensive on
 5585 a heavily loaded SSL server, in which case, turn this off and
 5586 clear the cache of old entries 'manually' (with one of the functions
 5587 listed below) every few hours.  Perhaps I should up this number, it is hard
 5588 to say.  Remember, the '255' new calls is just a mechanism to get called
 5589 every now and then, in theory at most 255 new session-id's will have been
 5590 added but if 100 are added every minute, you would still have
 5591 500 in the cache before any would start being flushed (assuming a 3 minute
 5592 timeout)..
 5594 int SSL_CTX_sess_hits(SSL_CTX *ctx);
 5595 int SSL_CTX_sess_misses(SSL_CTX *ctx);
 5596 int SSL_CTX_sess_timeouts(SSL_CTX *ctx);
 5597 These 3 functions return statistics about the SSL_CTX.  These 3 are the
 5598 number of session id reuses.  hits is the number of reuses, misses are the
 5599 number of lookups that failed, and timeouts is the number of cached
 5600 entries ignored because they had timeouted.
 5602 ctx->new_session_cb is a function pointer to a function of type
 5603 int new_session_callback(SSL *ssl,SSL_SESSION *new);
 5604 This function, if set in the SSL_CTX structure is called whenever a new
 5605 SSL_SESSION is added to the cache.  If the callback returns non-zero, it
 5606 means that the application will have to do a SSL_SESSION_free()
 5607 on the structure (this is
 5608 to do with the cache keeping the reference counts correct, without the
 5609 application needing to know about it.
 5610 The 'active' parameter is the current SSL session for which this connection
 5611 was created.
 5613 void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,int (*cb)());
 5614 to set the callback,
 5615 int (*cb)() SSL_CTX_sess_get_new_cb(SSL_CTX *ctx)
 5616 to get the callback.
 5618 If the 'get session' callback is set, when a session id is looked up and
 5619 it is not in the session-id cache, this callback is called.  The callback is
 5620 of the form
 5621 SSL_SESSION *get_session_callback(unsigned char *sess_id,int sess_id_len,
 5622 	int *copy);
 5624 The get_session_callback is intended to return null if no session id is found.
 5625 The reference count on the SSL_SESSION in incremented by the SSL library,
 5626 if copy is 1.  Otherwise, the reference count is not modified.
 5628 void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and
 5629 int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback.
 5631 These callbacks are basically intended to be used by processes to
 5632 send their session-id's to other processes.  I currently have not implemented
 5633 non-blocking semantics for these callbacks, it is upto the application
 5634 to make the callbacks efficient if they require blocking (perhaps
 5635 by 'saving' them and then 'posting them' when control returns from
 5636 the SSL_accept().
 5638 LHASH *SSL_CTX_sessions(SSL_CTX *ctx)
 5639 This returns the session cache.  The lhash strucutre can be accessed for
 5640 statistics about the cache.
 5642 void lh_stats(LHASH *lh, FILE *out);
 5643 void lh_node_stats(LHASH *lh, FILE *out);
 5644 void lh_node_usage_stats(LHASH *lh, FILE *out);
 5646 can be used to print details about it's activity and current state.
 5647 You can also delve directly into the lhash structure for 14 different
 5648 counters that are kept against the structure.  When I wrote the lhash library,
 5649 I was interested in gathering statistics :-).
 5650 Have a read of doc/lhash.doc in the SSLeay distribution area for more details
 5651 on the lhash library.
 5653 Now as mentioned ealier, when a SSL is created, it needs a SSL_CTX.
 5654 SSL *   SSL_new(SSL_CTX *);
 5656 This stores a session.  A session is secret information shared between 2
 5657 SSL contexts.  It will only be created if both ends of the connection have
 5658 authenticated their peer to their satisfaction.  It basically contains
 5659 the information required to use a particular secret key cipher.
 5661 To retrieve the SSL_CTX being used by a SSL,
 5662 SSL_CTX *SSL_get_SSL_CTX(SSL *s);
 5664 Now when a SSL session is established between to programs, the 'session'
 5665 information that is cached in the SSL_CTX can me manipulated by the
 5666 following functions.
 5667 int SSL_set_session(SSL *s, SSL_SESSION *session);
 5668 This will set the SSL_SESSION to use for the next SSL_connect().  If you use
 5669 this function on an already 'open' established SSL connection, 'bad things
 5670 will happen'.  This function is meaning-less when used on a ssl strucutre
 5671 that is just about to be used in a SSL_accept() call since the
 5672 SSL_accept() will either create a new session or retrieve one from the
 5673 cache.
 5675 SSL_SESSION *SSL_get_session(SSL *s);
 5676 This will return the SSL_SESSION for the current SSL, NULL if there is
 5677 no session associated with the SSL structure.
 5679 The SSL sessions are kept in the SSL_CTX in a hash table, to remove a
 5680 session
 5681 void    SSL_CTX_remove_session(SSL_CTX *,SSL_SESSION *c);
 5682 and to add one
 5683 int    SSL_CTX_add_session(SSL_CTX *s, SSL_SESSION *c);
 5684 SSL_CTX_add_session() returns 1 if the session was already in the cache (so it
 5685 was not added).
 5686 Whenever a new session is created via SSL_connect()/SSL_accept(),
 5687 they are automatically added to the cache, depending on the session_cache_mode
 5688 settings.  SSL_set_session()
 5689 does not add it to the cache.  Just call SSL_CTX_add_session() if you do want the
 5690 session added.  For a 'client' this would not normally be the case.
 5691 SSL_CTX_add_session() is not normally ever used, except for doing 'evil' things
 5692 which the next 2 funtions help you do.
 5694 int     i2d_SSL_SESSION(SSL_SESSION *in,unsigned char **pp);
 5695 SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a,unsigned char **pp,long length);
 5696 These 2 functions are in the standard ASN1 library form and can be used to
 5697 load and save to a byte format, the SSL_SESSION structure.
 5698 With these functions, you can save and read these structures to a files or
 5699 arbitary byte string.
 5700 The PEM_write_SSL_SESSION(fp,x) and PEM_read_SSL_SESSION(fp,x,cb) will
 5701 write to a file pointer in base64 encoding.
 5703 What you can do with this, is pass session information between separate
 5704 processes.  Please note, that you will probably also need to modify the
 5705 timeout information on the SSL_SESSIONs.
 5707 long SSL_get_time(SSL_SESSION *s)
 5708 will return the 'time' that the session
 5709 was loaded.  The timeout is relative to this time.  This information is
 5710 saved when the SSL_SESSION is converted to binarary but it is stored
 5711 in as a unix long, which is rather OS dependant, but easy to convert back.
 5713 long SSL_set_time(SSL_SESSION *s,long t) will set the above mentioned time.
 5714 The time value is just the value returned from time(3), and should really
 5715 be defined by be to be time_t.
 5717 long SSL_get_timeout(SSL_SESSION *s);
 5718 long SSL_set_timeout(SSL_SESSION *s,long t);
 5719 These 2 retrieve and set the timeout which is just a number of secconds
 5720 from the 'SSL_get_time()' value.  When this time period has elapesed,
 5721 the session will no longer be in the cache (well it will actually be removed
 5722 the next time it is attempted to be retrieved, so you could 'bump'
 5723 the timeout so it remains valid).
 5724 The 'time' and 'timeout' are set on a session when it is created, not reset
 5725 each time it is reused.  If you did wish to 'bump it', just after establishing
 5726 a connection, do a
 5727 SSL_set_time(ssl,time(NULL));
 5729 You can also use
 5730 SSL_CTX_set_timeout(SSL_CTX *ctx,unsigned long t) and
 5731 SSL_CTX_get_timeout(SSL_CTX *ctx) to manipulate the default timeouts for
 5732 all SSL connections created against a SSL_CTX.  If you set a timeout in
 5733 an SSL_CTX, all new SSL's created will inherit the timeout.  It can be over
 5734 written by the SSL_set_timeout(SSL *s,unsigned long t) function call.
 5735 If you 'set' the timeout back to 0, the system default will be used.
 5738 void SSL_SESSION_free(SSL_SESSION *ses);
 5739 These 2 functions are used to create and dispose of SSL_SESSION functions.
 5740 You should not ever normally need to use them unless you are using 
 5741 i2d_SSL_SESSION() and/or d2i_SSL_SESSION().  If you 'load' a SSL_SESSION
 5742 via d2i_SSL_SESSION(), you will need to SSL_SESSION_free() it.
 5743 Both SSL_set_session() and SSL_CTX_add_session() will 'take copies' of the
 5744 structure (via reference counts) when it is passed to them.
 5746 SSL_CTX_flush_sessions(ctx,time);
 5747 The first function will clear all sessions from the cache, which have expired
 5748 relative to 'time' (which could just be time(NULL)).
 5750 SSL_CTX_flush_sessions(ctx,0);
 5751 This is a special case that clears everything.
 5753 As a final comment, a 'session' is not enough to establish a new
 5754 connection.  If a session has timed out, a certificate and private key
 5755 need to have been associated with the SSL structure.
 5756 SSL_copy_session_id(SSL *to,SSL *from); will copy not only the session
 5757 strucutre but also the private key and certificate associated with
 5758 'from'.
 5762 So lets play at being a weird SSL server.
 5764 /* setup a context */
 5765 ctx=SSL_CTX_new();
 5767 /* Lets load some session from binary into the cache, why one would do
 5768  * this is not toally clear, but passing between programs does make sense
 5769  * Perhaps you are using 4096 bit keys and are happy to keep them
 5770  * valid for a week, to avoid the RSA overhead of 15 seconds, I'm not toally
 5771  * sure, perhaps this is a process called from an SSL inetd and this is being 
 5772  * passed to the application. */
 5773 session=d2i_SSL_SESSION(....)
 5774 SSL_CTX_add_session(ctx,session);
 5776 /* Lets even add a session from a file */
 5777 session=PEM_read_SSL_SESSION(....)
 5778 SSL_CTX_add_session(ctx,session);
 5780 /* create a new SSL structure */
 5781 ssl=SSL_new(ctx);
 5783 /* At this point we want to be able to 'create' new session if
 5784  * required, so we need a certificate and RSAkey. */
 5785 SSL_use_RSAPrivateKey_file(ssl,...)
 5786 SSL_use_certificate_file(ssl,...)
 5788 /* Now since we are a server, it make little sence to load a session against
 5789  * the ssl strucutre since a SSL_accept() will either create a new session or
 5790  * grab an existing one from the cache. */
 5792 /* grab a socket descriptor */
 5793 fd=accept(...);
 5795 /* associated it with the ssl strucutre */
 5796 SSL_set_fd(ssl,fd);
 5798 SSL_accept(ssl); /* 'do' SSL using out cert and RSA key */
 5800 /* Lets print out the session details or lets save it to a file,
 5801  * perhaps with a secret key cipher, so that we can pass it to the FBI
 5802  * when they want to decode the session :-).  While we have RSA
 5803  * this does not matter much but when I do SSLv3, this will allow a mechanism
 5804  * for the server/client to record the information needed to decode
 5805  * the traffic that went over the wire, even when using Diffie-Hellman */
 5806 PEM_write_SSL_SESSION(SSL_get_session(ssl),stdout,....)
 5808 Lets 'connect' back to the caller using the same session id.
 5810 ssl2=SSL_new(ctx);
 5811 fd2=connect(them);
 5812 SSL_set_fd(ssl2,fd2);
 5813 SSL_set_session(ssl2,SSL_get_session(ssl));
 5814 SSL_connect(ssl2);
 5816 /* what the hell, lets accept no more connections using this session */
 5817 SSL_CTX_remove_session(SSL_get_SSL_CTX(ssl),SSL_get_session(ssl));
 5819 /* we could have just as easily used ssl2 since they both are using the
 5820  * same session.
 5821  * You will note that both ssl and ssl2 are still using the session, and
 5822  * the SSL_SESSION structure will be free()ed when both ssl and ssl2
 5823  * finish using the session.  Also note that you could continue to initiate
 5824  * connections using this session by doing SSL_get_session(ssl) to get the
 5825  * existing session, but SSL_accept() will not be able to find it to
 5826  * use for incoming connections.
 5827  * Of corse, the session will timeout at the far end and it will no
 5828  * longer be accepted after a while.  The time and timeout are ignored except
 5829  * by SSL_accept(). */
 5831 /* Since we have had our server running for 10 weeks, and memory is getting
 5832  * short, perhaps we should clear the session cache to remove those
 5833  * 100000 session entries that have expired.  Some may consider this
 5834  * a memory leak :-) */
 5836 SSL_CTX_flush_sessions(ctx,time(NULL));
 5838 /* Ok, after a bit more time we wish to flush all sessions from the cache
 5839  * so that all new connections will be authenticated and incure the
 5840  * public key operation overhead */
 5842 SSL_CTX_flush_sessions(ctx,0);
 5844 /* As a final note, to copy everything to do with a SSL, use */
 5845 SSL_copy_session_id(SSL *to,SSL *from);
 5846 /* as this also copies the certificate and RSA key so new session can
 5847  * be established using the same details */
 5850 ==== sha.doc ========================================================
 5852 The SHA (Secure Hash Algorithm) library.
 5853 SHA is a message digest algorithm that can be used to condense an arbitrary
 5854 length message down to a 20 byte hash.  The functions all need to be passed
 5855 a SHA_CTX which is used to hold the SHA context during multiple SHA_Update()
 5856 function calls.  The normal method of use for this library is as follows
 5857 This library contains both SHA and SHA-1 digest algorithms.  SHA-1 is
 5858 an update to SHA (which should really be called SHA-0 now) which
 5859 tweaks the algorithm slightly.  The SHA-1 algorithm is used by simply
 5860 using SHA1_Init(), SHA1_Update(), SHA1_Final() and SHA1() instead of the
 5861 SHA*() calls
 5863 SHA_Init(...);
 5864 SHA_Update(...);
 5865 ...
 5866 SHA_Update(...);
 5867 SHA_Final(...);
 5869 This library requires the inclusion of 'sha.h'.
 5871 The functions are as follows:
 5873 void SHA_Init(
 5874 SHA_CTX *c);
 5875 	This function needs to be called to initiate a SHA_CTX structure for
 5876 	use.
 5878 void SHA_Update(
 5879 SHA_CTX *c;
 5880 unsigned char *data;
 5881 unsigned long len);
 5882 	This updates the message digest context being generated with 'len'
 5883 	bytes from the 'data' pointer.  The number of bytes can be any
 5884 	length.
 5886 void SHA_Final(
 5887 unsigned char *md;
 5888 SHA_CTX *c;
 5889 	This function is called when a message digest of the data digested
 5890 	with SHA_Update() is wanted.  The message digest is put in the 'md'
 5891 	array and is SHA_DIGEST_LENGTH (20) bytes long.
 5893 unsigned char *SHA(
 5894 unsigned char *d;
 5895 unsigned long n;
 5896 unsigned char *md;
 5897 	This function performs a SHA_Init(), followed by a SHA_Update()
 5898 	followed by a SHA_Final() (using a local SHA_CTX).
 5899 	The resulting digest is put into 'md' if it is not NULL.
 5900 	Regardless of the value of 'md', the message
 5901 	digest is returned from the function.  If 'md' was NULL, the message
 5902 	digest returned is being stored in a static structure.
 5905 ==== speed.doc ========================================================
 5907 To get an idea of the performance of this library, use
 5908 ssleay speed
 5910 perl util/sp-diff.pl file1 file2
 5912 will print out the relative differences between the 2 files which are
 5913 expected to be the output from the speed program.
 5915 The performace of the library is very dependant on the Compiler
 5916 quality and various flags used to build.
 5918 ---
 5920 These are some numbers I did comparing RSAref and SSLeay on a Pentium 100.
 5921 [ These numbers are all out of date, as of SSL - 0.6.1 the RSA
 5922 operations are about 2 times faster, so check the version number ]
 5924 RSA performance.
 5926 SSLeay 0.6.0
 5927 Pentium 100, 32meg, Windows NT Workstation 3.51
 5928 linux - gcc v 2.7.0 -O3 -fomit-frame-pointer -m486
 5929 and
 5930 Windows NT  - Windows NT 3.51 - Visual C++ 4.1   - 586 code + 32bit assember
 5931 Windows 3.1 - Windows NT 3.51 - Visual C++ 1.52c - 286 code + 32bit assember
 5932 NT Dos Shell- Windows NT 3.51 - Visual C++ 1.52c - 286 code + 16bit assember
 5934 Times are how long it takes to do an RSA private key operation.
 5936 	       512bits 1024bits
 5937 -------------------------------
 5938 SSLeay NT dll	0.042s   0.202s see above
 5939 SSLeay linux	0.046s   0.218s	Assember inner loops (normal build) 
 5940 SSLeay linux	0.067s   0.380s Pure C code with BN_LLONG defined
 5941 SSLeay W3.1 dll	0.108s 	 0.478s see above
 5942 SSLeay linux	0.109s   0.713s C without BN_LLONG.
 5943 RSAref2.0 linux	0.149s   0.936s
 5944 SSLeay MS-DOS	0.197s   1.049s see above
 5946 486DX66, 32meg, Windows NT Server 3.51
 5947 	       512bits 1024bits
 5948 -------------------------------
 5949 SSLeay NT dll   0.084s	 0.495s	<- SSLeay 0.6.3
 5950 SSLeay NT dll   0.154s   0.882s
 5951 SSLeay W3.1 dll 0.335s   1.538s
 5952 SSLeay MS-DOS	0.490s   2.790s
 5954 What I find cute is that I'm still faster than RSAref when using standard C,
 5955 without using the 'long long' data type :-), %35 faster for 512bit and we
 5956 scale up to 3.2 times faster for the 'default linux' build.  I should mention
 5957 that people should 'try' to use either x86-lnx.s (elf), x86-lnxa.s or
 5958 x86-sol.s for any x86 based unix they are building on.  The only problems
 5959 with be with syntax but the performance gain is quite large, especially for
 5960 servers.  The code is very simple, you just need to modify the 'header'.
 5962 The message is, if you are stuck using RSAref, the RSA performance will be
 5963 bad. Considering the code was compiled for a pentium, the 486DX66 number
 5964 would indicate 'Use RSAref and turn you Pentium 100 into a 486DX66' :-). 
 5965 [ As of verson 0.6.1, it would be correct to say 'turn you pentium 100
 5966  into a 486DX33' :-) ]
 5968 I won't tell people if the DLL's are using RSAref or my stuff if no-one
 5969 asks :-).
 5971 eric
 5973 PS while I know I could speed things up further, I will probably not do
 5974    so due to the effort involved.  I did do some timings on the
 5975    SSLeay bignum format -> RSAref number format conversion that occurs
 5976    each time RSAref is used by SSLeay, and the numbers are trivial.
 5977    0.00012s a call for 512bit vs 0.149s for the time spent in the function.
 5978    0.00018s for 1024bit vs 0.938s.  Insignificant.
 5979    So the 'way to go', to support faster RSA libraries, if people are keen,
 5980    is to write 'glue' code in a similar way that I do for RSAref and send it
 5981    to me :-).
 5982    My base library still has the advantage of being able to operate on 
 5983    any size numbers, and is not that far from the performance from the
 5984    leaders in the field. (-%30?)
 5985    [ Well as of 0.6.1 I am now the leader in the filed on x86 (we at
 5986      least very close :-) ]
 5988    I suppose I should also mention some other numbers RSAref numbers, again
 5989    on my Pentium.
 5990 		DES CBC		EDE-DES		MD5
 5991    RSAref linux	 830k/s		 302k/s		4390k/s
 5992    SSLeay linux  855k/s          319k/s        10025k/s
 5993    SSLeay NT	1158k/s		 410k/s	       10470k/s
 5994    SSLeay w31	 378k/s		 143k/s         2383k/s (fully 16bit)
 5996    Got to admit that Visual C++ 4.[01] is a damn fine compiler :-)
 5997 --
 5998 Eric Young                  | BOOL is tri-state according to Bill Gates.
 5999 AARNet: eay@cryptsoft.com   | RTFM Win32 GetMessage().
 6004 ==== ssl-ciph.doc ========================================================
 6006 This is a quick high level summery of how things work now.
 6008 Each SSLv2 and SSLv3 cipher is composed of 4 major attributes plus a few extra
 6009 minor ones.
 6011 They are 'The key exchange algorithm', which is RSA for SSLv2 but can also
 6012 be Diffle-Hellman for SSLv3.
 6014 An 'Authenticion algorithm', which can be RSA, Diffle-Helman, DSS or
 6015 none.
 6017 The cipher
 6019 The MAC digest.
 6021 A cipher can also be an export cipher and is either an SSLv2 or a
 6022 SSLv3 ciphers.
 6024 To specify which ciphers to use, one can either specify all the ciphers,
 6025 one at a time, or use 'aliases' to specify the preference and order for
 6026 the ciphers.
 6028 There are a large number of aliases, but the most importaint are
 6029 kRSA, kDHr, kDHd and kDHE for key exchange types.
 6031 aRSA, aDSS, aNULL and aDH for authentication
 6032 DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers
 6033 MD5, SHA0 and SHA1 digests
 6035 Now where this becomes interesting is that these can be put together to
 6036 specify the order and ciphers you wish to use.
 6038 To speed this up there are also aliases for certian groups of ciphers.
 6039 The main ones are
 6040 SSLv2	- all SSLv2 ciphers
 6041 SSLv3	- all SSLv3 ciphers
 6042 EXP	- all export ciphers
 6043 LOW	- all low strngth ciphers (no export ciphers, normally single DES)
 6044 MEDIUM	- 128 bit encryption
 6045 HIGH	- Triple DES
 6047 These aliases can be joined in a : separated list which specifies to
 6048 add ciphers, move them to the current location and delete them.
 6050 A simpler way to look at all of this is to use the 'ssleay ciphers -v' command.
 6051 The default library cipher spec is
 6053 which means, first, remove from consideration any ciphers that do not
 6054 authenticate.  Next up, use ciphers using RC4 and RSA.  Next include the HIGH,
 6055 MEDIUM and the LOW security ciphers.  Finish up by adding all the export
 6056 ciphers on the end, then 'pull' all the SSLv2 and export ciphers to
 6057 the end of the list.
 6059 The results are
 6060 $ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP'
 6062 RC4-SHA                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=SHA1
 6063 RC4-MD5                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5 
 6064 EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
 6065 EDH-DSS-DES-CBC3-SHA    SSLv3 Kx=DH       Au=DSS  Enc=3DES(168) Mac=SHA1
 6066 DES-CBC3-SHA            SSLv3 Kx=RSA      Au=RSA  Enc=3DES(168) Mac=SHA1
 6067 IDEA-CBC-MD5            SSLv3 Kx=RSA      Au=RSA  Enc=IDEA(128) Mac=SHA1
 6068 EDH-RSA-DES-CBC-SHA     SSLv3 Kx=DH       Au=RSA  Enc=DES(56)   Mac=SHA1
 6069 EDH-DSS-DES-CBC-SHA     SSLv3 Kx=DH       Au=DSS  Enc=DES(56)   Mac=SHA1
 6070 DES-CBC-SHA             SSLv3 Kx=RSA      Au=RSA  Enc=DES(56)   Mac=SHA1
 6071 DES-CBC3-MD5            SSLv2 Kx=RSA      Au=RSA  Enc=3DES(168) Mac=MD5 
 6072 DES-CBC-MD5             SSLv2 Kx=RSA      Au=RSA  Enc=DES(56)   Mac=MD5 
 6073 IDEA-CBC-MD5            SSLv2 Kx=RSA      Au=RSA  Enc=IDEA(128) Mac=MD5 
 6074 RC2-CBC-MD5             SSLv2 Kx=RSA      Au=RSA  Enc=RC2(128)  Mac=MD5 
 6075 RC4-MD5                 SSLv2 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5 
 6076 EXP-EDH-RSA-DES-CBC     SSLv3 Kx=DH(512)  Au=RSA  Enc=DES(40)   Mac=SHA1 export
 6077 EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512)  Au=DSS  Enc=DES(40)   Mac=SHA1 export
 6078 EXP-DES-CBC-SHA         SSLv3 Kx=RSA(512) Au=RSA  Enc=DES(40)   Mac=SHA1 export
 6079 EXP-RC2-CBC-MD5         SSLv3 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
 6080 EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
 6081 EXP-RC2-CBC-MD5         SSLv2 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
 6082 EXP-RC4-MD5             SSLv2 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
 6084 I would recoment people use the 'ssleay ciphers -v "text"'
 6085 command to check what they are going to use.
 6087 Anyway, I'm falling asleep here so I'll do some more tomorrow.
 6089 eric
 6091 ==== ssl.doc ========================================================
 6093 SSL_CTX_sessions(SSL_CTX *ctx) - the session-id hash table.
 6095 /* Session-id cache stats */
 6096 SSL_CTX_sess_number
 6097 SSL_CTX_sess_connect
 6098 SSL_CTX_sess_connect_good
 6099 SSL_CTX_sess_accept
 6100 SSL_CTX_sess_accept_good
 6101 SSL_CTX_sess_hits
 6102 SSL_CTX_sess_cb_hits
 6103 SSL_CTX_sess_misses
 6104 SSL_CTX_sess_timeouts
 6106 /* Session-id application notification callbacks */
 6107 SSL_CTX_sess_set_new_cb
 6108 SSL_CTX_sess_get_new_cb
 6109 SSL_CTX_sess_set_get_cb
 6110 SSL_CTX_sess_get_get_cb
 6112 /* Session-id cache operation mode */
 6113 SSL_CTX_set_session_cache_mode
 6114 SSL_CTX_get_session_cache_mode
 6116 /* Set default timeout values to use. */
 6117 SSL_CTX_set_timeout
 6118 SSL_CTX_get_timeout
 6120 /* Global  SSL initalisation informational callback */
 6121 SSL_CTX_set_info_callback
 6122 SSL_CTX_get_info_callback
 6123 SSL_set_info_callback
 6124 SSL_get_info_callback
 6126 /* If the SSL_accept/SSL_connect returned with -1, these indicate when
 6127  * we should re-call *.
 6128 SSL_want
 6129 SSL_want_nothing
 6130 SSL_want_read
 6131 SSL_want_write
 6132 SSL_want_x509_lookup
 6134 /* Where we are in SSL initalisation, used in non-blocking, perhaps
 6135  * have a look at ssl/bio_ssl.c */
 6136 SSL_state
 6137 SSL_is_init_finished
 6138 SSL_in_init
 6139 SSL_in_connect_init
 6140 SSL_in_accept_init
 6142 /* Used to set the 'inital' state so SSL_in_connect_init and SSL_in_accept_init
 6143  * can be used to work out which function to call. */
 6144 SSL_set_connect_state
 6145 SSL_set_accept_state
 6147 /* Where to look for certificates for authentication */
 6148 SSL_set_default_verify_paths /* calles SSL_load_verify_locations */
 6149 SSL_load_verify_locations
 6151 /* get info from an established connection */
 6152 SSL_get_session
 6153 SSL_get_certificate
 6154 SSL_get_SSL_CTX
 6156 SSL_CTX_new
 6157 SSL_CTX_free
 6158 SSL_new
 6159 SSL_clear
 6160 SSL_free
 6162 SSL_CTX_set_cipher_list
 6163 SSL_get_cipher
 6164 SSL_set_cipher_list
 6165 SSL_get_cipher_list
 6166 SSL_get_shared_ciphers
 6168 SSL_accept
 6169 SSL_connect
 6170 SSL_read
 6171 SSL_write
 6173 SSL_debug
 6175 SSL_get_read_ahead
 6176 SSL_set_read_ahead
 6177 SSL_set_verify
 6179 SSL_pending
 6181 SSL_set_fd
 6182 SSL_set_rfd
 6183 SSL_set_wfd
 6184 SSL_set_bio
 6185 SSL_get_fd
 6186 SSL_get_rbio
 6187 SSL_get_wbio
 6189 SSL_use_RSAPrivateKey
 6190 SSL_use_RSAPrivateKey_ASN1
 6191 SSL_use_RSAPrivateKey_file
 6192 SSL_use_PrivateKey
 6193 SSL_use_PrivateKey_ASN1
 6194 SSL_use_PrivateKey_file
 6195 SSL_use_certificate
 6196 SSL_use_certificate_ASN1
 6197 SSL_use_certificate_file
 6199 ERR_load_SSL_strings
 6200 SSL_load_error_strings
 6202 /* human readable version of the 'state' of the SSL connection. */
 6203 SSL_state_string
 6204 SSL_state_string_long
 6205 /* These 2 report what kind of IO operation the library was trying to
 6206  * perform last.  Probably not very usefull. */
 6207 SSL_rstate_string
 6208 SSL_rstate_string_long
 6210 SSL_get_peer_certificate
 6212 SSL_SESSION_new
 6213 SSL_SESSION_print_fp
 6214 SSL_SESSION_print
 6215 SSL_SESSION_free
 6216 i2d_SSL_SESSION
 6217 d2i_SSL_SESSION
 6219 SSL_get_time
 6220 SSL_set_time
 6221 SSL_get_timeout
 6222 SSL_set_timeout
 6223 SSL_copy_session_id
 6224 SSL_set_session
 6225 SSL_CTX_add_session
 6226 SSL_CTX_remove_session
 6227 SSL_CTX_flush_sessions
 6229 BIO_f_ssl
 6231 /* used to hold information as to why a certificate verification failed */
 6232 SSL_set_verify_result
 6233 SSL_get_verify_result
 6235 /* can be used by the application to associate data with an SSL structure.
 6236  * It needs to be 'free()ed' by the application */
 6237 SSL_set_app_data
 6238 SSL_get_app_data
 6240 /* The following all set values that are kept in the SSL_CTX but
 6241  * are used as the default values when an SSL session is created.
 6242  * They are over writen by the relevent SSL_xxxx functions */
 6244 /* SSL_set_verify */
 6245 void SSL_CTX_set_default_verify
 6247 /* This callback, if set, totaly overrides the normal SSLeay verification
 6248  * functions and should return 1 on success and 0 on failure */
 6249 void SSL_CTX_set_cert_verify_callback
 6251 /* The following are the same as the equivilent SSL_xxx functions.
 6252  * Only one copy of this information is kept and if a particular
 6253  * SSL structure has a local override, it is totally separate structure.
 6254  */
 6255 int SSL_CTX_use_RSAPrivateKey
 6256 int SSL_CTX_use_RSAPrivateKey_ASN1
 6257 int SSL_CTX_use_RSAPrivateKey_file
 6258 int SSL_CTX_use_PrivateKey
 6259 int SSL_CTX_use_PrivateKey_ASN1
 6260 int SSL_CTX_use_PrivateKey_file
 6261 int SSL_CTX_use_certificate
 6262 int SSL_CTX_use_certificate_ASN1
 6263 int SSL_CTX_use_certificate_file
 6266 ==== ssl_ctx.doc ========================================================
 6268 This is now a bit dated, quite a few of the SSL_ functions could be
 6269 SSL_CTX_ functions.  I will update this in the future. 30 Aug 1996
 6271 From eay@orb.mincom.oz.au Mon Dec 11 21:37:08 1995
 6272 Received: by orb.mincom.oz.au id AA00696
 6273   (5.65c/IDA-1.4.4 for eay); Mon, 11 Dec 1995 11:37:08 +1000
 6274 Date: Mon, 11 Dec 1995 11:37:08 +1000 (EST)
 6275 From: Eric Young <eay@mincom.oz.au>
 6276 X-Sender: eay@orb
 6277 To: sameer <sameer@c2.org>
 6278 Cc: Eric Young <eay@mincom.oz.au>
 6279 Subject: Re: PEM_readX509 oesn't seem to be working
 6280 In-Reply-To: <199512110102.RAA12521@infinity.c2.org>
 6281 Message-Id: <Pine.SOL.3.91.951211112115.28608D-100000@orb>
 6282 Mime-Version: 1.0
 6283 Content-Type: TEXT/PLAIN; charset=US-ASCII
 6284 Status: RO
 6285 X-Status: 
 6287 On Sun, 10 Dec 1995, sameer wrote:
 6288 > 	OK, that's solved. I've found out that it is saying "no
 6289 > certificate set" in SSL_accept because s->conn == NULL
 6290 > so there is some place I need to initialize s->conn that I am
 6291 > not initializing it.
 6293 The full order of things for a server should be.
 6295 ctx=SSL_CTX_new();
 6297 /* The next line should not really be using ctx->cert but I'll leave it 
 6298  * this way right now... I don't want a X509_ routine to know about an SSL
 6299  * structure, there should be an SSL_load_verify_locations... hmm, I may 
 6300  * add it tonight.
 6301  */
 6302 X509_load_verify_locations(ctx->cert,CAfile,CApath);
 6304 /* Ok now for each new connection we do the following */
 6305 con=SSL_new(ctx);
 6306 SSL_set_fd(con,s);
 6307 SSL_set_verify(con,verify,verify_callback);
 6309 /* set the certificate and private key to use. */
 6310 SSL_use_certificate_ASN1(con,X509_certificate);
 6311 SSL_use_RSAPrivateKey_ASN1(con,RSA_private_key);
 6313 SSL_accept(con);
 6315 SSL_read(con)/SSL_write(con);
 6317 There is a bit more than that but that is basically the structure.
 6319 Create a context and specify where to lookup certificates.
 6321 foreach connection
 6322 	{
 6323 	create a SSL structure
 6324 	set the certificate and private key
 6325 	do a SSL_accept
 6327 	we should now be ok
 6328 	}
 6330 eric
 6331 --
 6332 Eric Young                  | Signature removed since it was generating
 6333 AARNet: eay@mincom.oz.au    | more followups than the message contents :-)
 6337 ==== ssleay.doc ========================================================
 6339 SSLeay: a cryptographic kitchen sink.
 6341 1st December 1995
 6342 Way back at the start of April 1995, I was looking for a mindless
 6343 programming project.  A friend of mine (Tim Hudson) said "why don't you do SSL,
 6344 it has DES encryption in it and I would not mind using it in a SSL telnet".
 6345 While it was true I had written a DES library in previous years, litle
 6346 did I know what an expansive task SSL would turn into.
 6348 First of all, the SSL protocol contains DES encryption.  Well and good.  My
 6349 DES library was fast and portable.  It also contained the RSA's RC4 stream
 6350 cipher.  Again, not a problem, some-one had just posted to sci.crypt
 6351 something that was claimed to be RC4.  It also contained IDEA, I had the
 6352 specifications, not a problem to implement.  MD5, an RFC, trivial, at most
 6353 I could spend a week or so trying to see if I could speed up the
 6354 implementation.  All in all a nice set of ciphers.
 6355 Then the first 'expantion of the scope', RSA public key
 6356 encryption.  Since I did not knowing a thing about public key encryption
 6357 or number theory, this appeared quite a daunting task.  Just writing a
 6358 big number library would be problomatic in itself, let alone making it fast.
 6359 At this point the scope of 'implementing SSL' expands eponentialy.
 6360 First of all, the RSA private keys  were being kept in ASN.1 format.
 6361 Thankfully the RSA PKCS series of documents explains this format.  So I now
 6362 needed to be able to encode and decode arbitary ASN.1 objects.  The Public
 6363 keys were embeded in X509 certificates.  Hmm... these are not only
 6364 ASN.1 objects but they make up a heirachy of authentication.  To
 6365 authenticate a X509 certificate one needs to retrieve it's issuers
 6366 certificate etc etc.  Hmm..., so I also need to implement some kind
 6367 of certificate management software.  I would also have to implement
 6368 software to authenticate certificates.  At this point the support code made
 6369 the SSL part of my library look quite small.
 6370 Around this time, the first version of SSLeay was released.
 6372 Ah, but here was the problem, I was not happy with the code so far.  As may
 6373 have become obvious, I had been treating all of this as a learning
 6374 exersize, so I have completely written the library myself.  As such, due
 6375 to the way it had grown like a fungus, much of the library was not
 6376 'elagent' or neat.  There were global and static variables all over the
 6377 place, the SSL part did not even handle non-blocking IO.
 6378 The Great rewrite began.
 6380 As of this point in time, the 'Great rewrite' has almost finished.  So what
 6381 follows is an approximate list of what is actually SSLeay 0.5.0
 6383 /********* This needs to be updated for 0.6.0+ *************/
 6385 ---
 6386 The library contains the following routines.  Please note that most of these
 6387 functions are not specfic for SSL or any other particular cipher
 6388 implementation.  I have tried to make all the routines as general purpose
 6389 as possible.  So you should not think of this library as an SSL
 6390 implemtation, but rather as a library of cryptographic functions
 6391 that also contains SSL.  I refer to each of these function groupings as
 6392 libraries since they are often capable of functioning as independant
 6393 libraries
 6395 First up, the general ciphers and message digests supported by the library.
 6397 MD2	rfc???, a standard 'by parts' interface to this algorithm.
 6398 MD5	rfc???, the same type of interface as for the MD2 library except a
 6399 	different algorithm.
 6400 SHA	THe Secure Hash Algorithm.  Again the same type of interface as
 6401 	MD2/MD5 except the digest is 20 bytes.
 6402 SHA1	The 'revised' version of SHA.  Just about identical to SHA except
 6403 	for one tweak of an inner loop.
 6404 DES	This is my libdes library that has been floating around for the last
 6405 	few years.  It has been enhanced for no other reason than completeness.
 6406 	It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and
 6407 	triple DES modes of ecb, cbc, cfb64 and ofb64.  cfb64 and ofb64 are
 6408 	functional interfaces to the 64 bit modes of cfb and ofb used in
 6409 	such a way thay they function as single character interfaces.
 6410 RC4	The RSA Inc. stream cipher.
 6411 RC2	The RSA Inc. block cipher.
 6412 IDEA	An implmentation of the IDEA cipher, the library supports ecb, cbc,
 6413 	cfb64 and ofb64 modes of operation.
 6415 Now all the above mentioned ciphers and digests libraries support high
 6416 speed, minimal 'crap in the way' type interfaces.  For fastest and
 6417 lowest level access, these routines should be used directly.
 6419 Now there was also the matter of public key crypto systems.  These are
 6420 based on large integer arithmatic.
 6422 BN	This is my large integer library.  It supports all the normal
 6423 	arithmentic operations.  It uses malloc extensivly and as such has
 6424 	no limits of the size of the numbers being manipulated.  If you
 6425 	wish to use 4000 bit RSA moduli, these routines will handle it.
 6426 	This library also contains routines to 'generate' prime numbers and
 6427 	to test for primality.  The RSA and DH libraries sit on top of this
 6428 	library.  As of this point in time, I don't support SHA, but
 6429 	when I do add it, it will just sit on top of the routines contained
 6430 	in this library.
 6431 RSA	This implements the RSA public key algorithm.  It also contains
 6432 	routines that will generate a new private/public key pair.
 6433 	All the RSA functions conform to the PKCS#1 standard.
 6434 DH	This is an implementation of the
 6435 	Diffie-Hellman protocol.  There are all the require routines for
 6436 	the protocol, plus extra routines that can be used to generate a
 6437 	strong prime for use with a specified generator.  While this last
 6438 	routine is not generally required by applications implementing DH,
 6439 	It is present for completeness and because I thing it is much
 6440 	better to be able to 'generate' your own 'magic' numbers as oposed
 6441 	to using numbers suplied by others.  I conform to the PKCS#3
 6442 	standard where required.
 6444 You may have noticed the preceeding section mentions the 'generation' of
 6445 prime numbers.  Now this requries the use of 'random numbers'. 
 6447 RAND	This psuedo-random number library is based on MD5 at it's core
 6448 	and a large internal state (2k bytes).  Once you have entered enough
 6449 	seed data into this random number algorithm I don't feel
 6450 	you will ever need to worry about it generating predictable output.
 6451 	Due to the way I am writing a portable library, I have left the
 6452 	issue of how to get good initial random seed data upto the
 6453 	application but I do have support routines for saving and loading a
 6454 	persistant random number state for use between program runs.
 6456 Now to make all these ciphers easier to use, a higher level
 6457 interface was required.  In this form, the same function would be used to
 6458 encrypt 'by parts', via any one of the above mentioned ciphers.
 6460 EVP	The Digital EnVeloPe library is quite large.  At it's core are
 6461 	function to perform encryption and decryption by parts while using
 6462 	an initial parameter to specify which of the 17 different ciphers
 6463 	or 4 different message digests to use.  On top of these are implmented
 6464 	the digital signature functions, sign, verify, seal and open.
 6465 	Base64 encoding of binary data is also done in this library.
 6467 PEM	rfc???? describe the format for Privacy Enhanced eMail.
 6468 	As part of this standard, methods of encoding digital enveloped
 6469 	data is an ascii format are defined.  As such, I use a form of these
 6470 	to encode enveloped data.  While at this point in time full support
 6471 	for PEM has not been built into the library, a minimal subset of
 6472 	the secret key and Base64 encoding is present.  These reoutines are
 6473 	mostly used to Ascii encode binary data with a 'type' associated
 6474 	with it and perhaps details of private key encryption used to
 6475 	encrypt the data.
 6477 PKCS7	This is another Digital Envelope encoding standard which uses ASN.1
 6478 	to encode the data.  At this point in time, while there are some
 6479 	routines to encode and decode this binary format, full support is
 6480 	not present.
 6482 As Mentioned, above, there are several different ways to encode
 6483 data structures.
 6485 ASN1	This library is more a set of primatives used to encode the packing
 6486 	and unpacking of data structures.  It is used by the X509
 6487 	certificate standard and by the PKCS standards which are used by
 6488 	this library.  It also contains routines for duplicating and signing
 6489 	the structures asocisated with X509.
 6491 X509	The X509 library contains routines for packing and unpacking,
 6492 	verifying and just about every thing else you would want to do with
 6493 	X509 certificates.
 6495 PKCS7	PKCS-7 is a standard for encoding digital envelope data
 6496 	structures.  At this point in time the routines will load and save
 6497 	DER forms of these structees.  They need to be re-worked to support
 6498 	the BER form which is the normal way PKCS-7 is encoded.  If the
 6499 	previous 2 sentances don't make much sense, don't worry, this
 6500 	library is not used by this version of SSLeay anyway.
 6502 OBJ	ASN.1 uses 'object identifiers' to identify objects.  A set of
 6503 	functions were requred to translate from ASN.1 to an intenger, to a
 6504 	character string.  This library provieds these translations
 6506 Now I mentioned an X509 library.  X509 specified a hieachy of certificates
 6507 which needs to be traversed to authenticate particular certificates.
 6509 METH	This library is used to push 'methods' of retrieving certificates
 6510 	into the library.  There are some supplied 'methods' with SSLeay
 6511 	but applications can add new methods if they so desire.
 6512 	This library has not been finished and is not being used in this
 6513 	version.
 6515 Now all the above are required for use in the initial point of this project.
 6517 SSL	The SSL protocol.  This is a full implmentation of SSL v 2.  It
 6518 	support both server and client authentication.  SSL v 3 support
 6519 	will be added when the SSL v 3 specification is released in it's
 6520 	final form.
 6522 Now quite a few of the above mentioned libraries rely on a few 'complex'
 6523 data structures.  For each of these I have a library.
 6525 Lhash	This is a hash table library which is used extensivly.
 6527 STACK	An implemetation of a Stack data structure.
 6529 BUF	A simple character array structure that also support a function to
 6530 	check that the array is greater that a certain size, if it is not,
 6531 	it is realloced so that is it.
 6533 TXT_DB	A simple memory based text file data base.  The application can specify
 6534 	unique indexes that will be enforced at update time.
 6536 CONF	Most of the programs written for this library require a configuration
 6537 	file.  Instead of letting programs constantly re-implment this
 6538 	subsystem, the CONF library provides a consistant and flexable
 6539 	interface to not only configuration files but also environment
 6540 	variables.
 6542 But what about when something goes wrong?
 6543 The one advantage (and perhaps disadvantage) of all of these
 6544 functions being in one library was the ability to implement a
 6545 single error reporting system.
 6547 ERR	This library is used to report errors.  The error system records
 6548 	library number, function number (in the library) and reason
 6549 	number.  Multiple errors can be reported so that an 'error' trace
 6550 	is created.  The errors can be printed in numeric or textual form.
 6553 ==== ssluse.doc ========================================================
 6555 We have an SSL_CTX which contains global information for lots of
 6556 SSL connections.  The session-id cache and the certificate verificate cache.
 6557 It also contains default values for use when certificates are used.
 6559 SSL_CTX
 6560 	default cipher list
 6561 	session-id cache
 6562 	certificate cache
 6563 	default session-id timeout period
 6564 	New session-id callback
 6565 	Required session-id callback
 6566 	session-id stats
 6567 	Informational callback
 6568 	Callback that is set, overrides the SSLeay X509 certificate
 6569 	  verification
 6570 	The default Certificate/Private Key pair
 6571 	Default read ahead mode.
 6572 	Default verify mode and verify callback.  These are not used
 6573 	  if the over ride callback mentioned above is used.
 6575 Each SSL can have the following defined for it before a connection is made.
 6577 Certificate
 6578 Private key
 6579 Ciphers to use
 6580 Certificate verify mode and callback
 6581 IO object to use in the comunication.
 6582 Some 'read-ahead' mode information.
 6583 A previous session-id to re-use.
 6585 A connection is made by using SSL_connect or SSL_accept.
 6586 When non-blocking IO is being used, there are functions that can be used
 6587 to determin where and why the SSL_connect or SSL_accept did not complete.
 6588 This information can be used to recall the functions when the 'error'
 6589 condition has dissapeared.
 6591 After the connection has been made, information can be retrived about the
 6592 SSL session and the session-id values that have been decided upon.
 6593 The 'peer' certificate can be retrieved.
 6595 The session-id values include
 6596 'start time'
 6597 'timeout length'
 6601 ==== stack.doc ========================================================
 6603 The stack data structure is used to store an ordered list of objects.
 6604 It is basically misnamed to call it a stack but it can function that way
 6605 and that is what I originally used it for.  Due to the way element
 6606 pointers are kept in a malloc()ed array, the most efficient way to use this
 6607 structure is to add and delete elements from the end via sk_pop() and
 6608 sk_push().  If you wish to do 'lookups' sk_find() is quite efficient since
 6609 it will sort the stack (if required) and then do a binary search to lookup 
 6610 the requested item.  This sorting occurs automatically so just sk_push()
 6611 elements on the stack and don't worry about the order.  Do remember that if
 6612 you do a sk_find(), the order of the elements will change.
 6614 You should never need to 'touch' this structure directly.
 6615 typedef struct stack_st
 6616 	{
 6617 	unsigned int num;
 6618 	char **data;
 6619 	int sorted;
 6621 	unsigned int num_alloc;
 6622 	int (*comp)();
 6623 	} STACK;
 6625 'num' holds the number of elements in the stack, 'data' is the array of
 6626 elements.  'sorted' is 1 is the list has been sorted, 0 if not.
 6628 num_alloc is the number of 'nodes' allocated in 'data'.  When num becomes
 6629 larger than num_alloc, data is realloced to a larger size.
 6630 If 'comp' is set, it is a function that is used to compare 2 of the items
 6631 in the stack.  The function should return -1, 0 or 1, depending on the
 6632 ordering.
 6634 #define sk_num(sk)	((sk)->num)
 6635 #define sk_value(sk,n)	((sk)->data[n])
 6637 These 2 macros should be used to access the number of elements in the
 6638 'stack' and to access a pointer to one of the values.
 6640 STACK *sk_new(int (*c)());
 6641 	This creates a new stack.  If 'c', the comparison function, is not
 6642 specified, the various functions that operate on a sorted 'stack' will not
 6643 work (sk_find()).  NULL is returned on failure.
 6645 void sk_free(STACK *);
 6646 	This function free()'s a stack structure.  The elements in the
 6647 stack will not be freed so one should 'pop' and free all elements from the
 6648 stack before calling this function or call sk_pop_free() instead.
 6650 void sk_pop_free(STACK *st; void (*func)());
 6651 	This function calls 'func' for each element on the stack, passing
 6652 the element as the argument.  sk_free() is then called to free the 'stack'
 6653 structure.
 6655 int sk_insert(STACK *sk,char *data,int where);
 6656 	This function inserts 'data' into stack 'sk' at location 'where'.
 6657 If 'where' is larger that the number of elements in the stack, the element
 6658 is put at the end.  This function tends to be used by other 'stack'
 6659 functions.  Returns 0 on failure, otherwise the number of elements in the
 6660 new stack.
 6662 char *sk_delete(STACK *st,int loc);
 6663 	Remove the item a location 'loc' from the stack and returns it.
 6664 Returns NULL if the 'loc' is out of range.
 6666 char *sk_delete_ptr(STACK *st, char *p);
 6667 	If the data item pointed to by 'p' is in the stack, it is deleted
 6668 from the stack and returned.  NULL is returned if the element is not in the
 6669 stack.
 6671 int sk_find(STACK *st,char *data);
 6672 	Returns the location that contains a value that is equal to 
 6673 the 'data' item.  If the comparison function was not set, this function
 6674 does a linear search.  This function actually qsort()s the stack if it is not
 6675 in order and then uses bsearch() to do the initial search.  If the
 6676 search fails,, -1 is returned.  For mutliple items with the same
 6677 value, the index of the first in the array is returned.
 6679 int sk_push(STACK *st,char *data);
 6680 	Append 'data' to the stack.  0 is returned if there is a failure
 6681 (due to a malloc failure), else 1.  This is 
 6682 sk_insert(st,data,sk_num(st));
 6684 int sk_unshift(STACK *st,char *data);
 6685 	Prepend 'data' to the front (location 0) of the stack.  This is
 6686 sk_insert(st,data,0);
 6688 char *sk_shift(STACK *st);
 6689 	Return and delete from the stack the first element in the stack.
 6690 This is sk_delete(st,0);
 6692 char *sk_pop(STACK *st);
 6693 	Return and delete the last element on the stack.  This is
 6694 sk_delete(st,sk_num(sk)-1);
 6696 void sk_zero(STACK *st);
 6697 	Removes all items from the stack.  It does not 'free'
 6698 pointers but is a quick way to clear a 'stack of references'.
 6700 ==== threads.doc ========================================================
 6702 How to compile SSLeay for multi-threading.
 6704 Well basically it is quite simple, set the compiler flags and build.
 6705 I have only really done much testing under Solaris and Windows NT.
 6706 If you library supports localtime_r() and gmtime_r() add,
 6707 -DTHREADS to the makefile parameters.  You can probably survive with out
 6708 this define unless you are going to have multiple threads generating
 6709 certificates at once.  It will not affect the SSL side of things.
 6711 The approach I have taken to doing locking is to make the application provide
 6712 callbacks to perform locking and so that the SSLeay library can distinguish
 6713 between threads (for the error state).
 6715 To have a look at an example program, 'cd mt; vi mttest.c'.
 6716 To build under solaris, sh solaris.sh, for Windows NT or Windows 95,
 6717 win32.bat
 6719 This will build mttest which will fire up 10 threads that talk SSL
 6720 to each other 10 times.
 6721 To enable everything to work, the application needs to call
 6723 CRYPTO_set_id_callback(id_function);
 6724 CRYPTO_set_locking_callback(locking_function);
 6726 before any multithreading is started.
 6727 id_function does not need to be defined under Windows NT or 95, the
 6728 correct function will be called if it is not.  Under unix, getpid()
 6729 is call if the id_callback is not defined, for Solaris this is wrong
 6730 (since threads id's are not pid's) but under Linux it is correct
 6731 (threads are just processes sharing the data segement).
 6733 The locking_callback is used to perform locking by the SSLeay library.
 6734 eg.
 6736 void solaris_locking_callback(mode,type,file,line)
 6737 int mode;
 6738 int type;
 6739 char *file;
 6740 int line;
 6741 	{
 6742 	if (mode & CRYPTO_LOCK)
 6743 		mutex_lock(&(lock_cs[type]));
 6744 	else
 6745 		mutex_unlock(&(lock_cs[type]));
 6746 	}
 6748 Now in this case I have used mutexes instead of read/write locks, since they
 6749 are faster and there are not many read locks in SSLeay, you may as well
 6750 always use write locks.  file and line are __FILE__ and __LINE__ from
 6751 the compile and can be usefull when debugging.
 6753 Now as you can see, 'type' can be one of a range of values, these values are
 6754 defined in crypto/crypto.h
 6755 CRYPTO_get_lock_name(type) will return a text version of what the lock is.
 6756 There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup
 6757 for multi-threading can be
 6759 static mutex_t lock_cs[CRYPTO_NUM_LOCKS];
 6761 void thread_setup()
 6762 	{
 6763 	int i;
 6765 	for (i=0; i<CRYPTO_NUM_LOCKS; i++)
 6766 		mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL);
 6767 	CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id);
 6768 	CRYPTO_set_locking_callback((void (*)())solaris_locking_callback);
 6769 	}
 6771 As a final note, under Windows NT or Windows 95, you have to be careful
 6772 not to mix the various threaded, unthreaded and debug libraries.
 6773 Normally if they are mixed incorrectly, mttest will crash just after printing
 6774 out some usage statistics at the end.  This is because the
 6775 different system libraries use different malloc routines and if
 6776 data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a
 6777 different library malloc, things get very confused.
 6779 The default SSLeay DLL builds use /MD, so if you use this on your
 6780 application, things will work as expected.  If you use /MDd,
 6781 you will probably have to rebuild SSLeay using this flag.
 6782 I should modify util/mk1mf.pl so it does all this correctly, but 
 6783 this has not been done yet.
 6785 One last warning.  Because locking overheads are actually quite large, the
 6786 statistics collected against the SSL_CTX for successfull connections etc
 6787 are not locked when updated.  This does make it possible for these
 6788 values to be slightly lower than they should be, if you are
 6789 running multithreaded on a multi-processor box, but this does not really
 6790 matter much.
 6793 ==== txt_db.doc ========================================================
 6795 TXT_DB, a simple text based in memory database.
 6797 It holds rows of ascii data, for which the only special character is '\0'.
 6798 The rows can be of an unlimited length.
 6800 ==== why.doc ========================================================
 6802 This file is more of a note for other people who wish to understand why
 6803 the build environment is the way it is :-).
 6805 The include files 'depend' as follows.
 6806 Each of 
 6807 crypto/*/*.c includes crypto/cryptlib.h
 6808 ssl/*.c include ssl/ssl_locl.h
 6809 apps/*.c include apps/apps.h
 6810 crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h
 6811 all include e_os.h which contains OS/environment specific information.
 6812 If you need to add something todo with a particular environment,
 6813 add it to this file.  It is worth remembering that quite a few libraries,
 6814 like lhash, des, md, sha etc etc do not include crypto/cryptlib.h.  This
 6815 is because these libraries should be 'independantly compilable' and so I
 6816 try to keep them this way.
 6817 e_os.h is not so much a part of SSLeay, as the placing in one spot all the
 6818 evil OS dependant muck.
 6820 I wanted to automate as many things as possible.  This includes
 6821 error number generation.  A
 6822 make errors
 6823 will scan the source files for error codes, append them to the correct
 6824 header files, and generate the functions to print the text version
 6825 of the error numbers.  So don't even think about adding error numbers by
 6826 hand, put them in the form
 6828 on line and it will be automatically picked up my a make errors.
 6830 In a similar vein, programs to be added into ssleay in the apps directory
 6831 just need to have an entry added to E_EXE in makefile.ssl and
 6832 everthing will work as expected.  Don't edit progs.h by hand.
 6834 make links re-generates the symbolic links that are used.  The reason why
 6835 I keep everything in its own directory, and don't put all the
 6836 test programs and header files in 'test' and 'include' is because I want
 6837 to keep the 'sub-libraries' independant.  I still 'pull' out
 6838 indervidual libraries for use in specific projects where the code is
 6839 required.  I have used the 'lhash' library in just about every software
 6840 project I have worked on :-).
 6842 make depend generates dependancies and
 6843 make dclean removes them.
 6845 You will notice that I use perl quite a bit when I could be using 'sed'.
 6846 The reason I decided to do this was to just stick to one 'extra' program.
 6847 For Windows NT, I have perl and no sed.
 6849 The util/mk1mf.pl program can be used to generate a single makefile.
 6850 I use this because makefiles under Microsoft are horrific.
 6851 Each C compiler seems to have different linker formats, which have
 6852 to be used because the retarted C compilers explode when you do
 6853 cl -o file *.o.
 6855 Now some would argue that I should just use the single makefile.  I don't
 6856 like it during develoment for 2 reasons.  First, the actuall make
 6857 command takes a long time.  For my current setup, if I'm in
 6858 crypto/bn and I type make, only the crypto/bn directory gets rebuilt,
 6859 which is nice when you are modifying prototypes in bn.h which
 6860 half the SSLeay depends on.  The second is that to add a new souce file
 6861 I just plonk it in at the required spot in the local makefile.  This
 6862 then alows me to keep things local, I don't need to modify a 'global'
 6863 tables (the make for unix, the make for NT, the make for w31...).
 6864 When I am ripping apart a library structure, it is nice to only
 6865 have to worry about one directory :-).
 6867 Having said all this, for the hell of it I put together 2 files that
 6868 #include all the souce code (generated by doing a ls */*.o after a build).
 6869 crypto.c takes only 30 seconds to build under NT and 2 minutes under linux
 6870 for my pentium100.  Much faster that the normal build :-).
 6871 Again, the problem is that when using libraries, every program linked
 6872 to libcrypto.a would suddenly get 330k of library when it may only need
 6873 1k.  This technique does look like a nice way to do shared libraries though.
 6875 Oh yes, as a final note, to 'build' a distribution, I just type
 6876 make dist.
 6877 This cleans and packages everything.  The directory needs to be called
 6878 SSLeay since the make does a 'cd ..' and renames and tars things up.
 6880 ==== req.1 ========================================================
 6882 The 'req' command is used to manipulate and deal with pkcs#10
 6883 certificate requests.
 6885 It's default mode of operation is to load a certificate and then
 6886 write it out again.
 6888 By default the 'req' is read from stdin in 'PEM' format.
 6889 The -inform option can be used to specify 'pem' format or 'der'
 6890 format.  PEM format is the base64 encoding of the DER format.
 6892 By default 'req' then writes the request back out. -outform can be used
 6893 to indicate the desired output format, be it 'pem' or 'der'.
 6895 To specify an input file, use the '-in' option and the '-out' option
 6896 can be used to specify the output file.
 6898 If you wish to perform a command and not output the certificate
 6899 request afterwards, use the '-noout' option.
 6901 When a certificate is loaded, it can be printed in a human readable
 6902 ascii format via the '-text' option.
 6904 To check that the signature on a certificate request is correct, use
 6905 the '-verify' option to make sure that the private key contained in the
 6906 certificate request corresponds to the signature.
 6908 Besides the default mode, there is also the 'generate a certificate
 6909 request' mode.  There are several flags that trigger this mode.
 6911 -new will generate a new RSA key (if required) and then prompts
 6912 the user for details for the certificate request.
 6913 -newkey has an argument that is the number of bits to make the new
 6914 key.  This function also triggers '-new'.
 6916 The '-new' option can have a key to use specified instead of having to
 6917 load one, '-key' is used to specify the file containg the key.
 6918 -keyform can be used to specify the format of the key.  Only
 6919 'pem' and 'der' formats are supported, later, 'netscape' format may be added.
 6921 Finally there is the '-x509' options which makes req output a self
 6922 signed x509 certificate instead of a certificate request.
 6924 Now as you may have noticed, there are lots of default options that
 6925 cannot be specified via the command line.  They are held in a 'template'
 6926 or 'configuration file'.  The -config option specifies which configuration
 6927 file to use.  See conf.doc for details on the syntax of this file.
 6929 The req command uses the 'req' section of the config file.
 6931 ---
 6932 # The following variables are defined.  For this example I will populate
 6933 # the various values
 6934 [ req ]
 6935 default_bits	= 512		# default number of bits to use.
 6936 default_keyfile	= testkey.pem	# Where to write the generated keyfile
 6937 				# if not specified.
 6938 distinguished_name= req_dn	# The section that contains the
 6939 				# information about which 'object' we
 6940 				# want to put in the DN.
 6941 attributes	= req_attr	# The objects we want for the
 6942 				# attributes field.
 6943 encrypt_rsa_key	= no		# Should we encrypt newly generated
 6944 				# keys.  I strongly recommend 'yes'.
 6946 # The distinguished name section.  For the following entries, the
 6947 # object names must exist in the SSLeay header file objects.h.  If they
 6948 # do not, they will be silently ignored.  The entries have the following
 6949 # format.
 6950 # <object_name>		=> string to prompt with
 6951 # <object_name>_default	=> default value for people
 6952 # <object_name>_value	=> Automatically use this value for this field.
 6953 # <object_name>_min	=> minimum number of characters for data (def. 0)
 6954 # <object_name>_max	=> maximum number of characters for data (def. inf.)
 6955 # All of these entries are optional except for the first one.
 6956 [ req_dn ]
 6957 countryName			= Country Name (2 letter code)
 6958 countryName_default		= AU
 6960 stateOrProvinceName		= State or Province Name (full name)
 6961 stateOrProvinceName_default	= Queensland
 6963 localityName			= Locality Name (eg, city)
 6965 organizationName		= Organization Name (eg, company)
 6966 organizationName_default	= Mincom Pty Ltd
 6968 organizationalUnitName		= Organizational Unit Name (eg, section)
 6969 organizationalUnitName_default	= MTR
 6971 commonName			= Common Name (eg, YOUR name)
 6972 commonName_max			= 64
 6974 emailAddress			= Email Address
 6975 emailAddress_max		= 40
 6977 # The next section is the attributes section.  This is exactly the
 6978 # same as for the previous section except that the resulting objects are
 6979 # put in the attributes field. 
 6980 [ req_attr ]
 6981 challengePassword		= A challenge password
 6982 challengePassword_min		= 4
 6983 challengePassword_max		= 20
 6985 unstructuredName		= An optional company name
 6987 ----
 6988 Also note that the order that attributes appear in this file is the
 6989 order they will be put into the distinguished name.
 6991 Once this request has been generated, it can be sent to a CA for
 6992 certifying.
 6994 ----
 6995 A few quick examples....
 6997 To generate a new request and a new key
 6998 req -new
 7000 To generate a new request and a 1058 bit key
 7001 req -newkey 1058
 7003 To generate a new request using a pre-existing key
 7004 req -new -key key.pem
 7006 To generate a self signed x509 certificate from a certificate
 7007 request using a supplied key, and we want to see the text form of the
 7008 output certificate (which we will put in the file selfSign.pem
 7009 req -x509 -in req.pem -key key.pem -text -out selfSign.pem
 7011 Verify that the signature is correct on a certificate request.
 7012 req -verify -in req.pem
 7014 Verify that the signature was made using a specified public key.
 7015 req -verify -in req.pem -key key.pem
 7017 Print the contents of a certificate request
 7018 req -text -in req.pem
 7020 ==== danger ========================================================
 7022 If you specify a SSLv2 cipher, and the mode is SSLv23 and the server
 7023 can talk SSLv3, it will claim there is no cipher since you should be
 7024 using SSLv3.
 7026 When tracing debug stuff, remember BIO_s_socket() is different to
 7027 BIO_s_connect().
 7029 BSD/OS assember is not working