ssleay.txt revision 55714
1226031Sstas 2Bundle of old SSLeay documentation files [OBSOLETE!] 3 4==== readme ======================================================== 5 6This is the old 0.6.6 docuementation. Most of the cipher stuff is still 7relevent but I'm working (very slowly) on new docuemtation. 8The current version can be found online at 9 10http://www.cryptsoft.com/ssleay/doc 11 12==== API.doc ======================================================== 13 14SSL - SSLv2/v3/v23 etc. 15 16BIO - methods and how they plug together 17 18MEM - memory allocation callback 19 20CRYPTO - locking for threads 21 22EVP - Ciphers/Digests/signatures 23 24RSA - methods 25 26X509 - certificate retrieval 27 28X509 - validation 29 30X509 - X509v3 extensions 31 32Objects - adding object identifiers 33 34ASN.1 - parsing 35 36PEM - parsing 37 38==== ssl/readme ===================================================== 39 4022 Jun 1996 41This file belongs in ../apps, but I'll leave it here because it deals 42with SSL :-) It is rather dated but it gives you an idea of how 43things work. 44=== 45 4617 Jul 1995 47I have been changing things quite a bit and have not fully updated 48this file, so take what you read with a grain of salt 49eric 50=== 51The s_client and s_server programs can be used to test SSL capable 52IP/port addresses and the verification of the X509 certificates in use 53by these services. I strongly advise having a look at the code to get 54an idea of how to use the authentication under SSLeay. Any feedback 55on changes and improvements would be greatly accepted. 56 57This file will probably be gibberish unless you have read 58rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM 59authentication. 60 61A Brief outline (and examples) how to use them to do so. 62 63NOTE: 64The environment variable SSL_CIPER is used to specify the prefered 65cipher to use, play around with setting it's value to combinations of 66RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL 67in a : separated list. 68 69This directory contains 3 X509 certificates which can be used by these programs. 70client.pem: a file containing a certificate and private key to be used 71 by s_client. 72server.pem :a file containing a certificate and private key to be used 73 by s_server. 74eay1024.pem:the certificate used to sign client.pem and server.pem. 75 This would be your CA's certificate. There is also a link 76 from the file a8556381.0 to eay1024.PEM. The value a8556381 77 is returned by 'x509 -hash -noout <eay1024.pem' and is the 78 value used by X509 verification routines to 'find' this 79 certificte when search a directory for it. 80 [the above is not true any more, the CA cert is 81 ../certs/testca.pem which is signed by ../certs/mincomca.pem] 82 83When testing the s_server, you may get 84bind: Address already in use 85errors. These indicate the port is still being held by the unix 86kernel and you are going to have to wait for it to let go of it. If 87this is the case, remember to use the port commands on the s_server and 88s_client to talk on an alternative port. 89 90===== 91s_client. 92This program can be used to connect to any IP/hostname:port that is 93talking SSL. Once connected, it will attempt to authenticate the 94certificate it was passed and if everything works as expected, a 2 95directional channel will be open. Any text typed will be sent to the 96other end. type Q<cr> to exit. Flags are as follows. 97-host arg : Arg is the host or IP address to connect to. 98-port arg : Arg is the port to connect to (https is 443). 99-verify arg : Turn on authentication of the server certificate. 100 : Arg specifies the 'depth', this will covered below. 101-cert arg : The optional certificate to use. This certificate 102 : will be returned to the server if the server 103 : requests it for client authentication. 104-key arg : The private key that matches the certificate 105 : specified by the -cert option. If this is not 106 : specified (but -cert is), the -cert file will be 107 : searched for the Private key. Both files are 108 : assumed to be in PEM format. 109-CApath arg : When to look for certificates when 'verifying' the 110 : certificate from the server. 111-CAfile arg : A file containing certificates to be used for 112 : 'verifying' the server certificate. 113-reconnect : Once a connection has been made, drop it and 114 : reconnect with same session-id. This is for testing :-). 115 116The '-verify n' parameter specifies not only to verify the servers 117certificate but to also only take notice of 'n' levels. The best way 118to explain is to show via examples. 119Given 120s_server -cert server.PEM is running. 121 122s_client 123 CONNECTED 124 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server 125 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 126 verify error:num=1:unable to get issuer certificate 127 verify return:1 128 CIPHER is CBC-DES-MD5 129What has happened is that the 'SSLeay demo server' certificate's 130issuer ('CA') could not be found but because verify is not on, we 131don't care and the connection has been made anyway. It is now 'up' 132using CBC-DES-MD5 mode. This is an unauthenticate secure channel. 133You may not be talking to the right person but the data going to them 134is encrypted. 135 136s_client -verify 0 137 CONNECTED 138 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server 139 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 140 verify error:num=1:unable to get issuer certificate 141 verify return:1 142 CIPHER is CBC-DES-MD5 143We are 'verifying' but only to depth 0, so since the 'SSLeay demo server' 144certificate passed the date and checksum, we are happy to proceed. 145 146s_client -verify 1 147 CONNECTED 148 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server 149 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 150 verify error:num=1:unable to get issuer certificate 151 verify return:0 152 ERROR 153 verify error:unable to get issuer certificate 154In this case we failed to make the connection because we could not 155authenticate the certificate because we could not find the 156'CA' certificate. 157 158s_client -verify 1 -CAfile eay1024.PEM 159 CONNECTED 160 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server 161 verify return:1 162 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 163 verify return:1 164 CIPHER is CBC-DES-MD5 165We loaded the certificates from the file eay1024.PEM. Everything 166checked out and so we made the connection. 167 168s_client -verify 1 -CApath . 169 CONNECTED 170 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server 171 verify return:1 172 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 173 verify return:1 174 CIPHER is CBC-DES-MD5 175We looked in out local directory for issuer certificates and 'found' 176a8556381.0 and so everything is ok. 177 178It is worth noting that 'CA' is a self certified certificate. If you 179are passed one of these, it will fail to 'verify' at depth 0 because 180we need to lookup the certifier of a certificate from some information 181that we trust and keep locally. 182 183SSL_CIPHER=CBC3-DES-MD5:RC4-MD5 184export SSL_CIPHER 185s_client -verify 10 -CApath . -reconnect 186 CONNECTED 187 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server 188 verify return:1 189 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 190 verify return:1 191 drop the connection and reconnect with the same session id 192 CIPHER is CBC3-DES-MD5 193This has done a full connection and then re-estabished it with the 194same session id but a new socket. No RSA stuff occures on the second 195connection. Note that we said we would prefer to use CBC3-DES-MD5 196encryption and so, since the server supports it, we are. 197 198===== 199s_server 200This program accepts SSL connections on a specified port 201Once connected, it will estabish an SSL connection and optionaly 202attempt to authenticate the client. A 2 directional channel will be 203open. Any text typed will be sent to the other end. Type Q<cr> to exit. 204Flags are as follows. 205-port arg : Arg is the port to listen on. 206-verify arg : Turn on authentication of the client if they have a 207 : certificate. Arg specifies the 'depth'. 208-Verify arg : Turn on authentication of the client. If they don't 209 : have a valid certificate, drop the connection. 210-cert arg : The certificate to use. This certificate 211 : will be passed to the client. If it is not 212 : specified, it will default to server.PEM 213-key arg : The private key that matches the certificate 214 : specified by the -cert option. If this is not 215 : specified (but -cert is), the -cert file will be 216 : searched for the Private key. Both files are 217 : assumed to be in PEM format. Default is server.PEM 218-CApath arg : When to look for certificates when 'verifying' the 219 : certificate from the client. 220-CAfile arg : A file containing certificates to be used for 221 : 'verifying' the client certificate. 222 223For the following 'demo' I will specify the s_server command and 224the s_client command and then list the output from the s_server. 225s_server 226s_client 227 CONNECTED 228 CIPHER is CBC-DES-MD5 229Everything up and running 230 231s_server -verify 0 232s_client 233 CONNECTED 234 CIPHER is CBC-DES-MD5 235Ok since no certificate was returned and we don't care. 236 237s_server -verify 0 238./s_client -cert client.PEM 239 CONNECTED 240 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client 241 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 242 verify error:num=1:unable to get issuer certificate 243 verify return:1 244 CIPHER is CBC-DES-MD5 245Ok since we were only verifying to level 0 246 247s_server -verify 4 248s_client -cert client.PEM 249 CONNECTED 250 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client 251 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 252 verify error:num=1:unable to get issuer certificate 253 verify return:0 254 ERROR 255 verify error:unable to get issuer certificate 256Bad because we could not authenticate the returned certificate. 257 258s_server -verify 4 -CApath . 259s_client -cert client.PEM 260 CONNECTED 261 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client 262 verify return:1 263 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 264 verify return:1 265 CIPHER is CBC-DES-MD5 266Ok because we could authenticate the returned certificate :-). 267 268s_server -Verify 0 -CApath . 269s_client 270 CONNECTED 271 ERROR 272 SSL error:function is:REQUEST_CERTIFICATE 273 :error is :client end did not return a certificate 274Error because no certificate returned. 275 276s_server -Verify 4 -CApath . 277s_client -cert client.PEM 278 CONNECTED 279 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client 280 verify return:1 281 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 282 verify return:1 283 CIPHER is CBC-DES-MD5 284Full authentication of the client. 285 286So in summary to do full authentication of both ends 287s_server -Verify 9 -CApath . 288s_client -cert client.PEM -CApath . -verify 9 289From the server side 290 CONNECTED 291 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client 292 verify return:1 293 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 294 verify return:1 295 CIPHER is CBC-DES-MD5 296From the client side 297 CONNECTED 298 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server 299 verify return:1 300 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA 301 verify return:1 302 CIPHER is CBC-DES-MD5 303 304For general probing of the 'internet https' servers for the 305distribution area, run 306s_client -host www.netscape.com -port 443 -verify 4 -CApath ../rsa/hash 307Then enter 308GET / 309and you should be talking to the https server on that host. 310 311www.rsa.com was refusing to respond to connections on 443 when I was 312testing. 313 314have fun :-). 315 316eric 317 318==== a_verify.doc ======================================================== 319 320From eay@mincom.com Fri Oct 4 18:29:06 1996 321Received: by orb.mincom.oz.au id AA29080 322 (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000 323Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST) 324From: Eric Young <eay@mincom.oz.au> 325X-Sender: eay@orb 326To: wplatzer <wplatzer@iaik.tu-graz.ac.at> 327Cc: Eric Young <eay@mincom.oz.au>, SSL Mailing List <ssl-users@mincom.com> 328Subject: Re: Netscape's Public Key 329In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at> 330Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb> 331Mime-Version: 1.0 332Content-Type: TEXT/PLAIN; charset=US-ASCII 333Status: RO 334X-Status: 335 336On Thu, 3 Oct 1996, wplatzer wrote: 337> I get Public Key from Netscape (Gold 3.0b4), but cannot do anything 338> with it... It looks like (asn1parse): 339> 340> 0:d=0 hl=3 l=180 cons: SEQUENCE 341> 3:d=1 hl=2 l= 96 cons: SEQUENCE 342> 5:d=2 hl=2 l= 92 cons: SEQUENCE 343> 7:d=3 hl=2 l= 13 cons: SEQUENCE 344> 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption 345> 20:d=4 hl=2 l= 0 prim: NULL 346> 22:d=3 hl=2 l= 75 prim: BIT STRING 347> 99:d=2 hl=2 l= 0 prim: IA5STRING : 348> 101:d=1 hl=2 l= 13 cons: SEQUENCE 349> 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption 350> 114:d=2 hl=2 l= 0 prim: NULL 351> 116:d=1 hl=2 l= 65 prim: BIT STRING 352> 353> The first BIT STRING is the public key and the second BIT STRING is 354> the signature. 355> But a public key consists of the public exponent and the modulus. Are 356> both numbers in the first BIT STRING? 357> Is there a document simply describing this coding stuff (checking 358> signature, get the public key, etc.)? 359 360Minimal in SSLeay. If you want to see what the modulus and exponent are, 361try asn1parse -offset 25 -length 75 <key.pem 362asn1parse will currently stuff up on the 'length 75' part (fixed in next 363release) but it will print the stuff. If you are after more 364documentation on ASN.1, have a look at www.rsa.com and get their PKCS 365documents, most of my initial work on SSLeay was done using them. 366 367As for SSLeay, 368util/crypto.num and util/ssl.num are lists of all exported functions in 369the library (but not macros :-(. 370 371The ones for extracting public keys from certificates and certificate 372requests are EVP_PKEY * X509_REQ_extract_key(X509_REQ *req); 373EVP_PKEY * X509_extract_key(X509 *x509); 374 375To verify a signature on a signed ASN.1 object 376int X509_verify(X509 *a,EVP_PKEY *key); 377int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key); 378int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key); 379int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key); 380 381I should mention that EVP_PKEY can be used to hold a public or a private key, 382since for things like RSA and DSS, a public key is just a subset of what 383is stored for the private key. 384 385To sign any of the above structures 386 387int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md); 388int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md); 389int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md); 390int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md); 391 392where md is the message digest to sign with. 393 394There are all defined in x509.h and all the _sign and _verify functions are 395actually macros to the ASN1_sign() and ASN1_verify() functions. 396These functions will put the correct algorithm identifiers in the correct 397places in the structures. 398 399eric 400-- 401Eric Young | BOOL is tri-state according to Bill Gates. 402AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). 403 404==== x509 ======================================================= 405 406X509_verify() 407X509_sign() 408 409X509_get_version() 410X509_get_serialNumber() 411X509_get_issuer() 412X509_get_subject() 413X509_get_notBefore() 414X509_get_notAfter() 415X509_get_pubkey() 416 417X509_set_version() 418X509_set_serialNumber() 419X509_set_issuer() 420X509_set_subject() 421X509_set_notBefore() 422X509_set_notAfter() 423X509_set_pubkey() 424 425X509_get_extensions() 426X509_set_extensions() 427 428X509_EXTENSIONS_clear() 429X509_EXTENSIONS_retrieve() 430X509_EXTENSIONS_add() 431X509_EXTENSIONS_delete() 432 433==== x509 attribute ================================================ 434 435PKCS7 436 STACK of X509_ATTRIBUTES 437 ASN1_OBJECT 438 STACK of ASN1_TYPE 439 440So it is 441 442p7.xa[].obj 443p7.xa[].data[] 444 445get_obj_by_nid(STACK , nid) 446get_num_by_nid(STACK , nid) 447get_data_by_nid(STACK , nid, index) 448 449X509_ATTRIBUTE *X509_ATTRIBUTE_new(void ); 450void X509_ATTRIBUTE_free(X509_ATTRIBUTE *a); 451 452X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **ex, 453 int nid, STACK *value); 454 455X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **ex, 456 int nid, STACK *value); 457 458int X509_ATTRIBUTE_set_object(X509_ATTRIBUTE *ex,ASN1_OBJECT *obj); 459int X509_ATTRIBUTE_add_data(X509_ATTRIBUTE *ex, int index, 460 ASN1_TYPE *value); 461 462ASN1_OBJECT * X509_ATTRIBUTE_get_object(X509_ATTRIBUTE *ex); 463int X509_ATTRIBUTE_get_num(X509_ATTRIBUTE *ne); 464ASN1_TYPE * X509_ATTRIBUTE_get_data(X509_ATTRIBUTE *ne,int index); 465 466ASN1_TYPE * X509_ATTRIBUTE_get_data_by_NID(X509_ATTRIBUTE *ne, 467 ASN1_OBJECT *obj); 468 469X509_ATTRIBUTE *PKCS7_get_s_att_by_NID(PKCS7 *p7,int nid); 470X509_ATTRIBUTE *PKCS7_get_u_att_by_NID(PKCS7 *p7,int nid); 471 472==== x509 v3 ======================================================== 473 474The 'new' system. 475 476The X509_EXTENSION_METHOD includes extensions and attributes and/or names. 477Basically everthing that can be added to an X509 with an OID identifying it. 478 479It operates via 2 methods per object id. 480int a2i_XXX(X509 *x,char *str,int len); 481int i2a_XXX(BIO *bp,X509 *x); 482 483The a2i_XXX function will add the object with a value converted from the 484string into the X509. Len can be -1 in which case the length is calculated 485via strlen(str). Applications can always use direct knowledge to load and 486unload the relevent objects themselves. 487 488i2a_XXX will print to the passed BIO, a text representation of the 489relevet object. Use a memory BIO if you want it printed to a buffer :-). 490 491X509_add_by_NID(X509 *x,int nid,char *str,int len); 492X509_add_by_OBJ(X509 *x,ASN1_OBJECT *obj,char *str,int len); 493 494X509_print_by_name(BIO *bp,X509 *x); 495X509_print_by_NID(BIO *bp,X509 *x); 496X509_print_by_OBJ(BIO *bp,X509 *x); 497 498==== verify ======================================================== 499 500X509_verify_cert_chain( 501 CERT_STORE *cert_store, 502 STACK /* X509 */ *certs, 503 int *verify_result, 504 int (*verify_error_callback)() 505 char *argument_to_callback, /* SSL */ 506 507app_verify_callback( 508 char *app_verify_arg, /* from SSL_CTX */ 509 STACK /* X509 */ *certs, 510 int *verify_result, 511 int (*verify_error_callback)() 512 SSL *s, 513 514int X509_verify_cert( 515 CERT_STORE *cert_store, 516 X509 *x509, 517 int *verify_result, 518 int (*verify_error_callback)(), 519 char *arg, 520 521==== apps.doc ======================================================== 522 523The applications 524 525Ok, where to begin.... 526In the begining, when SSLeay was small (April 1995), there 527were but few applications, they did happily cohabit in 528the one bin directory. Then over time, they did multiply and grow, 529and they started to look like microsoft software; 500k to print 'hello world'. 530A new approach was needed. They were coalessed into one 'Monolithic' 531application, ssleay. This one program is composed of many programs that 532can all be compiled independantly. 533 534ssleay has 3 modes of operation. 5351) If the ssleay binaray has the name of one of its component programs, it 536executes that program and then exits. This can be achieve by using hard or 537symbolic links, or failing that, just renaming the binary. 5382) If the first argument to ssleay is the name of one of the component 539programs, that program runs that program and then exits. 5403) If there are no arguments, ssleay enters a 'command' mode. Each line is 541interpreted as a program name plus arguments. After each 'program' is run, 542ssleay returns to the comand line. 543 544dgst - message digests 545enc - encryption and base64 encoding 546 547ans1parse - 'pulls' appart ASN.1 encoded objects like certificates. 548 549dh - Diffle-Hellman parameter manipulation. 550rsa - RSA manipulations. 551crl - Certificate revokion list manipulations 552x509 - X509 cert fiddles, including signing. 553pkcs7 - pkcs7 manipulation, only DER versions right now. 554 555genrsa - generate an RSA private key. 556gendh - Generate a set of Diffle-Hellman parameters. 557req - Generate a PKCS#10 object, a certificate request. 558 559s_client - SSL client program 560s_server - SSL server program 561s_time - A SSL protocol timing program 562s_mult - Another SSL server, but it multiplexes 563 connections. 564s_filter - under development 565 566errstr - Convert SSLeay error numbers to strings. 567ca - Sign certificate requests, and generate 568 certificate revokion lists 569crl2pkcs7 - put a crl and certifcates into a pkcs7 object. 570speed - Benchmark the ciphers. 571verify - Check certificates 572hashdir - under development 573 574[ there a now a few more options, play with the program to see what they 575 are ] 576 577==== asn1.doc ======================================================== 578 579The ASN.1 Routines. 580 581ASN.1 is a specification for how to encode structured 'data' in binary form. 582The approach I have take to the manipulation of structures and their encoding 583into ASN.1 is as follows. 584 585For each distinct structure there are 4 function of the following form 586TYPE *TYPE_new(void); 587void TYPE_free(TYPE *); 588TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length); 589long i2d_TYPE(TYPE *a,unsigned char **pp); /* CHECK RETURN VALUE */ 590 591where TYPE is the type of the 'object'. The TYPE that have these functions 592can be in one of 2 forms, either the internal C malloc()ed data structure 593or in the DER (a variant of ASN.1 encoding) binary encoding which is just 594an array of unsigned bytes. The 'i2d' functions converts from the internal 595form to the DER form and the 'd2i' functions convert from the DER form to 596the internal form. 597 598The 'new' function returns a malloc()ed version of the structure with all 599substructures either created or left as NULL pointers. For 'optional' 600fields, they are normally left as NULL to indicate no value. For variable 601size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the 602STACK data type is used to hold the values. Have a read of stack.doc 603and have a look at the relevant header files to see what I mean. If there 604is an error while malloc()ing the structure, NULL is returned. 605 606The 'free' function will free() all the sub components of a particular 607structure. If any of those sub components have been 'removed', replace 608them with NULL pointers, the 'free' functions are tolerant of NULL fields. 609 610The 'd2i' function copies a binary representation into a C structure. It 611operates as follows. 'a' is a pointer to a pointer to 612the structure to populate, 'pp' is a pointer to a pointer to where the DER 613byte string is located and 'length' is the length of the '*pp' data. 614If there are no errors, a pointer to the populated structure is returned. 615If there is an error, NULL is returned. Errors can occur because of 616malloc() failures but normally they will be due to syntax errors in the DER 617encoded data being parsed. It is also an error if there was an 618attempt to read more that 'length' bytes from '*p'. If 619everything works correctly, the value in '*p' is updated 620to point at the location just beyond where the DER 621structure was read from. In this way, chained calls to 'd2i' type 622functions can be made, with the pointer into the 'data' array being 623'walked' along the input byte array. 624Depending on the value passed for 'a', different things will be done. If 625'a' is NULL, a new structure will be malloc()ed and returned. If '*a' is 626NULL, a new structure will be malloc()ed and put into '*a' and returned. 627If '*a' is not NULL, the structure in '*a' will be populated, or in the 628case of an error, free()ed and then returned. 629Having these semantics means that a structure 630can call a 'd2i' function to populate a field and if the field is currently 631NULL, the structure will be created. 632 633The 'i2d' function type is used to copy a C structure to a byte array. 634The parameter 'a' is the structure to convert and '*p' is where to put it. 635As for the 'd2i' type structure, 'p' is updated to point after the last 636byte written. If p is NULL, no data is written. The function also returns 637the number of bytes written. Where this becomes useful is that if the 638function is called with a NULL 'p' value, the length is returned. This can 639then be used to malloc() an array of bytes and then the same function can 640be recalled passing the malloced array to be written to. e.g. 641 642int len; 643unsigned char *bytes,*p; 644len=i2d_X509(x,NULL); /* get the size of the ASN1 encoding of 'x' */ 645if ((bytes=(unsigned char *)malloc(len)) == NULL) 646 goto err; 647p=bytes; 648i2d_X509(x,&p); 649 650Please note that a new variable, 'p' was passed to i2d_X509. After the 651call to i2d_X509 p has been incremented by len bytes. 652 653Now the reason for this functional organisation is that it allows nested 654structures to be built up by calling these functions as required. There 655are various macros used to help write the general 'i2d', 'd2i', 'new' and 656'free' functions. They are discussed in another file and would only be 657used by some-one wanting to add new structures to the library. As you 658might be able to guess, the process of writing ASN.1 files can be a bit CPU 659expensive for complex structures. I'm willing to live with this since the 660simpler library code make my life easier and hopefully most programs using 661these routines will have their execution profiles dominated by cipher or 662message digest routines. 663What follows is a list of 'TYPE' values and the corresponding ASN.1 664structure and where it is used. 665 666TYPE ASN.1 667ASN1_INTEGER INTEGER 668ASN1_BIT_STRING BIT STRING 669ASN1_OCTET_STRING OCTET STRING 670ASN1_OBJECT OBJECT IDENTIFIER 671ASN1_PRINTABLESTRING PrintableString 672ASN1_T61STRING T61String 673ASN1_IA5STRING IA5String 674ASN1_UTCTIME UTCTime 675ASN1_TYPE Any of the above mentioned types plus SEQUENCE and SET 676 677Most of the above mentioned types are actualled stored in the 678ASN1_BIT_STRING type and macros are used to differentiate between them. 679The 3 types used are 680 681typedef struct asn1_object_st 682 { 683 /* both null if a dynamic ASN1_OBJECT, one is 684 * defined if a 'static' ASN1_OBJECT */ 685 char *sn,*ln; 686 int nid; 687 int length; 688 unsigned char *data; 689 } ASN1_OBJECT; 690This is used to store ASN1 OBJECTS. Read 'objects.doc' for details ono 691routines to manipulate this structure. 'sn' and 'ln' are used to hold text 692strings that represent the object (short name and long or lower case name). 693These are used by the 'OBJ' library. 'nid' is a number used by the OBJ 694library to uniquely identify objects. The ASN1 routines will populate the 695'length' and 'data' fields which will contain the bit string representing 696the object. 697 698typedef struct asn1_bit_string_st 699 { 700 int length; 701 int type; 702 unsigned char *data; 703 } ASN1_BIT_STRING; 704This structure is used to hold all the other base ASN1 types except for 705ASN1_UTCTIME (which is really just a 'char *'). Length is the number of 706bytes held in data and type is the ASN1 type of the object (there is a list 707in asn1.h). 708 709typedef struct asn1_type_st 710 { 711 int type; 712 union { 713 char *ptr; 714 ASN1_INTEGER * integer; 715 ASN1_BIT_STRING * bit_string; 716 ASN1_OCTET_STRING * octet_string; 717 ASN1_OBJECT * object; 718 ASN1_PRINTABLESTRING * printablestring; 719 ASN1_T61STRING * t61string; 720 ASN1_IA5STRING * ia5string; 721 ASN1_UTCTIME * utctime; 722 ASN1_BIT_STRING * set; 723 ASN1_BIT_STRING * sequence; 724 } value; 725 } ASN1_TYPE; 726This structure is used in a few places when 'any' type of object can be 727expected. 728 729X509 Certificate 730X509_CINF CertificateInfo 731X509_ALGOR AlgorithmIdentifier 732X509_NAME Name 733X509_NAME_ENTRY A single sub component of the name. 734X509_VAL Validity 735X509_PUBKEY SubjectPublicKeyInfo 736The above mentioned types are declared in x509.h. They are all quite 737straight forward except for the X509_NAME/X509_NAME_ENTRY pair. 738A X509_NAME is a STACK (see stack.doc) of X509_NAME_ENTRY's. 739typedef struct X509_name_entry_st 740 { 741 ASN1_OBJECT *object; 742 ASN1_BIT_STRING *value; 743 int set; 744 int size; /* temp variable */ 745 } X509_NAME_ENTRY; 746The size is a temporary variable used by i2d_NAME and set is the set number 747for the particular NAME_ENTRY. A X509_NAME is encoded as a sequence of 748sequence of sets. Normally each set contains only a single item. 749Sometimes it contains more. Normally throughout this library there will be 750only one item per set. The set field contains the 'set' that this entry is 751a member of. So if you have just created a X509_NAME structure and 752populated it with X509_NAME_ENTRYs, you should then traverse the X509_NAME 753(which is just a STACK) and set the 'set/' field to incrementing numbers. 754For more details on why this is done, read the ASN.1 spec for Distinguished 755Names. 756 757X509_REQ CertificateRequest 758X509_REQ_INFO CertificateRequestInfo 759These are used to hold certificate requests. 760 761X509_CRL CertificateRevocationList 762These are used to hold a certificate revocation list 763 764RSAPrivateKey PrivateKeyInfo 765RSAPublicKey PublicKeyInfo 766Both these 'function groups' operate on 'RSA' structures (see rsa.doc). 767The difference is that the RSAPublicKey operations only manipulate the m 768and e fields in the RSA structure. 769 770DSAPrivateKey DSS private key 771DSAPublicKey DSS public key 772Both these 'function groups' operate on 'DSS' structures (see dsa.doc). 773The difference is that the RSAPublicKey operations only manipulate the 774XXX fields in the DSA structure. 775 776DHparams DHParameter 777This is used to hold the p and g value for The Diffie-Hellman operation. 778The function deal with the 'DH' strucure (see dh.doc). 779 780Now all of these function types can be used with several other functions to give 781quite useful set of general manipulation routines. Normally one would 782not uses these functions directly but use them via macros. 783 784char *ASN1_dup(int (*i2d)(),char *(*d2i)(),char *x); 785'x' is the input structure case to a 'char *', 'i2d' is the 'i2d_TYPE' 786function for the type that 'x' is and d2i is the 'd2i_TYPE' function for the 787type that 'x' is. As is obvious from the parameters, this function 788duplicates the strucutre by transforming it into the DER form and then 789re-loading it into a new strucutre and returning the new strucutre. This 790is obviously a bit cpu intensive but when faced with a complex dynamic 791structure this is the simplest programming approach. There are macros for 792duplicating the major data types but is simple to add extras. 793 794char *ASN1_d2i_fp(char *(*new)(),char *(*d2i)(),FILE *fp,unsigned char **x); 795'x' is a pointer to a pointer of the 'desired type'. new and d2i are the 796corresponding 'TYPE_new' and 'd2i_TYPE' functions for the type and 'fp' is 797an open file pointer to read from. This function reads from 'fp' as much 798data as it can and then uses 'd2i' to parse the bytes to load and return 799the parsed strucutre in 'x' (if it was non-NULL) and to actually return the 800strucutre. The behavior of 'x' is as per all the other d2i functions. 801 802char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x); 803The 'BIO' is the new IO type being used in SSLeay (see bio.doc). This 804function is the same as ASN1_d2i_fp() except for the BIO argument. 805ASN1_d2i_fp() actually calls this function. 806 807int ASN1_i2d_fp(int (*i2d)(),FILE *out,unsigned char *x); 808'x' is converted to bytes by 'i2d' and then written to 'out'. ASN1_i2d_fp 809and ASN1_d2i_fp are not really symetric since ASN1_i2d_fp will read all 810available data from the file pointer before parsing a single item while 811ASN1_i2d_fp can be used to write a sequence of data objects. To read a 812series of objects from a file I would sugest loading the file into a buffer 813and calling the relevent 'd2i' functions. 814 815char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x); 816This function is the same as ASN1_i2d_fp() except for the BIO argument. 817ASN1_i2d_fp() actually calls this function. 818 819char * PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)()); 820This function will read the next PEM encoded (base64) object of the same 821type as 'x' (loaded by the d2i function). 'name' is the name that is in 822the '-----BEGIN name-----' that designates the start of that object type. 823If the data is encrypted, 'cb' will be called to prompt for a password. If 824it is NULL a default function will be used to prompt from the password. 825'x' is delt with as per the standard 'd2i' function interface. This 826function can be used to read a series of objects from a file. While any 827data type can be encrypted (see PEM_ASN1_write) only RSA private keys tend 828to be encrypted. 829 830char * PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *fp, 831 char **x,int (*cb)()); 832Same as PEM_ASN1_read() except using a BIO. This is called by 833PEM_ASN1_read(). 834 835int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,EVP_CIPHER *enc, 836 unsigned char *kstr,int klen,int (*callback)()); 837 838int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *fp, 839 char *x,EVP_CIPHER *enc,unsigned char *kstr,int klen, 840 int (*callback)()); 841 842int ASN1_sign(int (*i2d)(), X509_ALGOR *algor1, X509_ALGOR *algor2, 843 ASN1_BIT_STRING *signature, char *data, RSA *rsa, EVP_MD *type); 844int ASN1_verify(int (*i2d)(), X509_ALGOR *algor1, 845 ASN1_BIT_STRING *signature,char *data, RSA *rsa); 846 847int ASN1_BIT_STRING_cmp(ASN1_BIT_STRING *a, ASN1_BIT_STRING *b); 848ASN1_BIT_STRING *ASN1_BIT_STRING_type_new(int type ); 849 850int ASN1_UTCTIME_check(ASN1_UTCTIME *a); 851void ASN1_UTCTIME_print(BIO *fp,ASN1_UTCTIME *a); 852ASN1_UTCTIME *ASN1_UTCTIME_dup(ASN1_UTCTIME *a); 853 854ASN1_BIT_STRING *d2i_asn1_print_type(ASN1_BIT_STRING **a,unsigned char **pp, 855 long length,int type); 856 857int i2d_ASN1_SET(STACK *a, unsigned char **pp, 858 int (*func)(), int ex_tag, int ex_class); 859STACK * d2i_ASN1_SET(STACK **a, unsigned char **pp, long length, 860 char *(*func)(), int ex_tag, int ex_class); 861 862int i2a_ASN1_OBJECT(BIO *bp,ASN1_OBJECT *object); 863int i2a_ASN1_INTEGER(BIO *bp, ASN1_INTEGER *a); 864int a2i_ASN1_INTEGER(BIO *bp,ASN1_INTEGER *bs,char *buf,int size); 865 866int ASN1_INTEGER_set(ASN1_INTEGER *a, long v); 867long ASN1_INTEGER_get(ASN1_INTEGER *a); 868ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai); 869BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn); 870 871/* given a string, return the correct type. Max is the maximum number 872 * of bytes to parse. It stops parsing when 'max' bytes have been 873 * processed or a '\0' is hit */ 874int ASN1_PRINTABLE_type(unsigned char *s,int max); 875 876void ASN1_parse(BIO *fp,unsigned char *pp,long len); 877 878int i2d_ASN1_bytes(ASN1_BIT_STRING *a, unsigned char **pp, int tag, int class); 879ASN1_BIT_STRING *d2i_ASN1_bytes(ASN1_OCTET_STRING **a, unsigned char **pp, 880 long length, int Ptag, int Pclass); 881 882/* PARSING */ 883int asn1_Finish(ASN1_CTX *c); 884 885/* SPECIALS */ 886int ASN1_get_object(unsigned char **pp, long *plength, int *ptag, 887 int *pclass, long omax); 888int ASN1_check_infinite_end(unsigned char **p,long len); 889void ASN1_put_object(unsigned char **pp, int constructed, int length, 890 int tag, int class); 891int ASN1_object_size(int constructed, int length, int tag); 892 893X509 * X509_get_cert(CERTIFICATE_CTX *ctx,X509_NAME * name,X509 *tmp_x509); 894int X509_add_cert(CERTIFICATE_CTX *ctx,X509 *); 895 896char * X509_cert_verify_error_string(int n); 897int X509_add_cert_file(CERTIFICATE_CTX *c,char *file, int type); 898char * X509_gmtime (char *s, long adj); 899int X509_add_cert_dir (CERTIFICATE_CTX *c,char *dir, int type); 900int X509_load_verify_locations (CERTIFICATE_CTX *ctx, 901 char *file_env, char *dir_env); 902int X509_set_default_verify_paths(CERTIFICATE_CTX *cts); 903X509 * X509_new_D2i_X509(int len, unsigned char *p); 904char * X509_get_default_cert_area(void ); 905char * X509_get_default_cert_dir(void ); 906char * X509_get_default_cert_file(void ); 907char * X509_get_default_cert_dir_env(void ); 908char * X509_get_default_cert_file_env(void ); 909char * X509_get_default_private_dir(void ); 910X509_REQ *X509_X509_TO_req(X509 *x, RSA *rsa); 911int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)()); 912 913CERTIFICATE_CTX *CERTIFICATE_CTX_new(); 914void CERTIFICATE_CTX_free(CERTIFICATE_CTX *c); 915 916void X509_NAME_print(BIO *fp, X509_NAME *name, int obase); 917int X509_print_fp(FILE *fp,X509 *x); 918int X509_print(BIO *fp,X509 *x); 919 920X509_INFO * X509_INFO_new(void); 921void X509_INFO_free(X509_INFO *a); 922 923char * X509_NAME_oneline(X509_NAME *a); 924 925#define X509_verify(x,rsa) 926#define X509_REQ_verify(x,rsa) 927#define X509_CRL_verify(x,rsa) 928 929#define X509_sign(x,rsa,md) 930#define X509_REQ_sign(x,rsa,md) 931#define X509_CRL_sign(x,rsa,md) 932 933#define X509_dup(x509) 934#define d2i_X509_fp(fp,x509) 935#define i2d_X509_fp(fp,x509) 936#define d2i_X509_bio(bp,x509) 937#define i2d_X509_bio(bp,x509) 938 939#define X509_CRL_dup(crl) 940#define d2i_X509_CRL_fp(fp,crl) 941#define i2d_X509_CRL_fp(fp,crl) 942#define d2i_X509_CRL_bio(bp,crl) 943#define i2d_X509_CRL_bio(bp,crl) 944 945#define X509_REQ_dup(req) 946#define d2i_X509_REQ_fp(fp,req) 947#define i2d_X509_REQ_fp(fp,req) 948#define d2i_X509_REQ_bio(bp,req) 949#define i2d_X509_REQ_bio(bp,req) 950 951#define RSAPrivateKey_dup(rsa) 952#define d2i_RSAPrivateKey_fp(fp,rsa) 953#define i2d_RSAPrivateKey_fp(fp,rsa) 954#define d2i_RSAPrivateKey_bio(bp,rsa) 955#define i2d_RSAPrivateKey_bio(bp,rsa) 956 957#define X509_NAME_dup(xn) 958#define X509_NAME_ENTRY_dup(ne) 959 960void X509_REQ_print_fp(FILE *fp,X509_REQ *req); 961void X509_REQ_print(BIO *fp,X509_REQ *req); 962 963RSA *X509_REQ_extract_key(X509_REQ *req); 964RSA *X509_extract_key(X509 *x509); 965 966int X509_issuer_and_serial_cmp(X509 *a, X509 *b); 967unsigned long X509_issuer_and_serial_hash(X509 *a); 968 969X509_NAME * X509_get_issuer_name(X509 *a); 970int X509_issuer_name_cmp(X509 *a, X509 *b); 971unsigned long X509_issuer_name_hash(X509 *a); 972 973X509_NAME * X509_get_subject_name(X509 *a); 974int X509_subject_name_cmp(X509 *a,X509 *b); 975unsigned long X509_subject_name_hash(X509 *x); 976 977int X509_NAME_cmp (X509_NAME *a, X509_NAME *b); 978unsigned long X509_NAME_hash(X509_NAME *x); 979 980 981==== bio.doc ======================================================== 982 983BIO Routines 984 985This documentation is rather sparse, you are probably best 986off looking at the code for specific details. 987 988The BIO library is a IO abstraction that was originally 989inspired by the need to have callbacks to perform IO to FILE 990pointers when using Windows 3.1 DLLs. There are two types 991of BIO; a source/sink type and a filter type. 992The source/sink methods are as follows: 993- BIO_s_mem() memory buffer - a read/write byte array that 994 grows until memory runs out :-). 995- BIO_s_file() FILE pointer - A wrapper around the normal 996 'FILE *' commands, good for use with stdin/stdout. 997- BIO_s_fd() File descriptor - A wrapper around file 998 descriptors, often used with pipes. 999- BIO_s_socket() Socket - Used around sockets. It is 1000 mostly in the Microsoft world that sockets are different 1001 from file descriptors and there are all those ugly winsock 1002 commands. 1003- BIO_s_null() Null - read nothing and write nothing.; a 1004 useful endpoint for filter type BIO's specifically things 1005 like the message digest BIO. 1006 1007The filter types are 1008- BIO_f_buffer() IO buffering - does output buffering into 1009 larger chunks and performs input buffering to allow gets() 1010 type functions. 1011- BIO_f_md() Message digest - a transparent filter that can 1012 be asked to return a message digest for the data that has 1013 passed through it. 1014- BIO_f_cipher() Encrypt or decrypt all data passing 1015 through the filter. 1016- BIO_f_base64() Base64 decode on read and encode on write. 1017- BIO_f_ssl() A filter that performs SSL encryption on the 1018 data sent through it. 1019 1020Base BIO functions. 1021The BIO library has a set of base functions that are 1022implemented for each particular type. Filter BIOs will 1023normally call the equivalent function on the source/sink BIO 1024that they are layered on top of after they have performed 1025some modification to the data stream. Multiple filter BIOs 1026can be 'push' into a stack of modifers, so to read from a 1027file, unbase64 it, then decrypt it, a BIO_f_cipher, 1028BIO_f_base64 and a BIO_s_file would probably be used. If a 1029sha-1 and md5 message digest needed to be generated, a stack 1030two BIO_f_md() BIOs and a BIO_s_null() BIO could be used. 1031The base functions are 1032- BIO *BIO_new(BIO_METHOD *type); Create a new BIO of type 'type'. 1033- int BIO_free(BIO *a); Free a BIO structure. Depending on 1034 the configuration, this will free the underlying data 1035 object for a source/sink BIO. 1036- int BIO_read(BIO *b, char *data, int len); Read upto 'len' 1037 bytes into 'data'. 1038- int BIO_gets(BIO *bp,char *buf, int size); Depending on 1039 the BIO, this can either be a 'get special' or a get one 1040 line of data, as per fgets(); 1041- int BIO_write(BIO *b, char *data, int len); Write 'len' 1042 bytes from 'data' to the 'b' BIO. 1043- int BIO_puts(BIO *bp,char *buf); Either a 'put special' or 1044 a write null terminated string as per fputs(). 1045- long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg); A 1046 control function which is used to manipulate the BIO 1047 structure and modify it's state and or report on it. This 1048 function is just about never used directly, rather it 1049 should be used in conjunction with BIO_METHOD specific 1050 macros. 1051- BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the 1052 top of the 'old' BIO list. new_top should be a filter BIO. 1053 All writes will go through 'new_top' first and last on read. 1054 'old' is returned. 1055- BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if 1056 there are no more. 1057 1058If a particular low level BIO method is not supported 1059(normally BIO_gets()), -2 will be returned if that method is 1060called. Otherwise the IO methods (read, write, gets, puts) 1061will return the number of bytes read or written, and 0 or -1 1062for error (or end of input). For the -1 case, 1063BIO_should_retry(bio) can be called to determine if it was a 1064genuine error or a temporary problem. -2 will also be 1065returned if the BIO has not been initalised yet, in all 1066cases, the correct error codes are set (accessible via the 1067ERR library). 1068 1069 1070The following functions are convenience functions: 1071- int BIO_printf(BIO *bio, char * format, ..); printf but 1072 to a BIO handle. 1073- long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a 1074 convenience function to allow a different argument types 1075 to be passed to BIO_ctrl(). 1076- int BIO_dump(BIO *b,char *bytes,int len); output 'len' 1077 bytes from 'bytes' in a hex dump debug format. 1078- long BIO_debug_callback(BIO *bio, int cmd, char *argp, int 1079 argi, long argl, long ret) - a default debug BIO callback, 1080 this is mentioned below. To use this one normally has to 1081 use the BIO_set_callback_arg() function to assign an 1082 output BIO for the callback to use. 1083- BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack' 1084 of BIOs, this function scan the list and returns the first 1085 that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX. 1086- void BIO_free_all(BIO *bio); Free the bio and all other BIOs 1087 in the list. It walks the bio->next_bio list. 1088 1089 1090 1091Extra commands are normally implemented as macros calling BIO_ctrl(). 1092- BIO_number_read(BIO *bio) - the number of bytes processed 1093 by BIO_read(bio,.). 1094- BIO_number_written(BIO *bio) - the number of bytes written 1095 by BIO_write(bio,.). 1096- BIO_reset(BIO *bio) - 'reset' the BIO. 1097- BIO_eof(BIO *bio) - non zero if we are at the current end 1098 of input. 1099- BIO_set_close(BIO *bio, int close_flag) - set the close flag. 1100- BIO_get_close(BIO *bio) - return the close flag. 1101 BIO_pending(BIO *bio) - return the number of bytes waiting 1102 to be read (normally buffered internally). 1103- BIO_flush(BIO *bio) - output any data waiting to be output. 1104- BIO_should_retry(BIO *io) - after a BIO_read/BIO_write 1105 operation returns 0 or -1, a call to this function will 1106 return non zero if you should retry the call later (this 1107 is for non-blocking IO). 1108- BIO_should_read(BIO *io) - we should retry when data can 1109 be read. 1110- BIO_should_write(BIO *io) - we should retry when data can 1111 be written. 1112- BIO_method_name(BIO *io) - return a string for the method name. 1113- BIO_method_type(BIO *io) - return the unique ID of the BIO method. 1114- BIO_set_callback(BIO *io, long (*callback)(BIO *io, int 1115 cmd, char *argp, int argi, long argl, long ret); - sets 1116 the debug callback. 1117- BIO_get_callback(BIO *io) - return the assigned function 1118 as mentioned above. 1119- BIO_set_callback_arg(BIO *io, char *arg) - assign some 1120 data against the BIO. This is normally used by the debug 1121 callback but could in reality be used for anything. To 1122 get an idea of how all this works, have a look at the code 1123 in the default debug callback mentioned above. The 1124 callback can modify the return values. 1125 1126Details of the BIO_METHOD structure. 1127typedef struct bio_method_st 1128 { 1129 int type; 1130 char *name; 1131 int (*bwrite)(); 1132 int (*bread)(); 1133 int (*bputs)(); 1134 int (*bgets)(); 1135 long (*ctrl)(); 1136 int (*create)(); 1137 int (*destroy)(); 1138 } BIO_METHOD; 1139 1140The 'type' is the numeric type of the BIO, these are listed in buffer.h; 1141'Name' is a textual representation of the BIO 'type'. 1142The 7 function pointers point to the respective function 1143methods, some of which can be NULL if not implemented. 1144The BIO structure 1145typedef struct bio_st 1146 { 1147 BIO_METHOD *method; 1148 long (*callback)(BIO * bio, int mode, char *argp, int 1149 argi, long argl, long ret); 1150 char *cb_arg; /* first argument for the callback */ 1151 int init; 1152 int shutdown; 1153 int flags; /* extra storage */ 1154 int num; 1155 char *ptr; 1156 struct bio_st *next_bio; /* used by filter BIOs */ 1157 int references; 1158 unsigned long num_read; 1159 unsigned long num_write; 1160 } BIO; 1161 1162- 'Method' is the BIO method. 1163- 'callback', when configured, is called before and after 1164 each BIO method is called for that particular BIO. This 1165 is intended primarily for debugging and of informational feedback. 1166- 'init' is 0 when the BIO can be used for operation. 1167 Often, after a BIO is created, a number of operations may 1168 need to be performed before it is available for use. An 1169 example is for BIO_s_sock(). A socket needs to be 1170 assigned to the BIO before it can be used. 1171- 'shutdown', this flag indicates if the underlying 1172 comunication primative being used should be closed/freed 1173 when the BIO is closed. 1174- 'flags' is used to hold extra state. It is primarily used 1175 to hold information about why a non-blocking operation 1176 failed and to record startup protocol information for the 1177 SSL BIO. 1178- 'num' and 'ptr' are used to hold instance specific state 1179 like file descriptors or local data structures. 1180- 'next_bio' is used by filter BIOs to hold the pointer of the 1181 next BIO in the chain. written data is sent to this BIO and 1182 data read is taken from it. 1183- 'references' is used to indicate the number of pointers to 1184 this structure. This needs to be '1' before a call to 1185 BIO_free() is made if the BIO_free() function is to 1186 actually free() the structure, otherwise the reference 1187 count is just decreased. The actual BIO subsystem does 1188 not really use this functionality but it is useful when 1189 used in more advanced applicaion. 1190- num_read and num_write are the total number of bytes 1191 read/written via the 'read()' and 'write()' methods. 1192 1193BIO_ctrl operations. 1194The following is the list of standard commands passed as the 1195second parameter to BIO_ctrl() and should be supported by 1196all BIO as best as possible. Some are optional, some are 1197manditory, in any case, where is makes sense, a filter BIO 1198should pass such requests to underlying BIO's. 1199- BIO_CTRL_RESET - Reset the BIO back to an initial state. 1200- BIO_CTRL_EOF - return 0 if we are not at the end of input, 1201 non 0 if we are. 1202- BIO_CTRL_INFO - BIO specific special command, normal 1203 information return. 1204- BIO_CTRL_SET - set IO specific parameter. 1205- BIO_CTRL_GET - get IO specific parameter. 1206- BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one 1207 of BIO_CLOSE or BIO_NOCLOSE. 1208- BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag. 1209- BIO_CTRL_PENDING - Return the number of bytes available 1210 for instant reading 1211- BIO_CTRL_FLUSH - Output pending data, return number of bytes output. 1212- BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned) 1213 should we 'retry' when IO is possible on the underlying IO object. 1214- BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on. 1215 1216The following command is a special BIO_s_file() specific option. 1217- BIO_CTRL_SET_FILENAME - specify a file to open for IO. 1218 1219The BIO_CTRL_RETRY_TYPE needs a little more explanation. 1220When performing non-blocking IO, or say reading on a memory 1221BIO, when no data is present (or cannot be written), 1222BIO_read() and/or BIO_write() will return -1. 1223BIO_should_retry(bio) will return true if this is due to an 1224IO condition rather than an actual error. In the case of 1225BIO_s_mem(), a read when there is no data will return -1 and 1226a should retry when there is more 'read' data. 1227The retry type is deduced from 2 macros 1228BIO_should_read(bio) and BIO_should_write(bio). 1229Now while it may appear obvious that a BIO_read() failure 1230should indicate that a retry should be performed when more 1231read data is available, this is often not true when using 1232things like an SSL BIO. During the SSL protocol startup 1233multiple reads and writes are performed, triggered by any 1234SSL_read or SSL_write. 1235So to write code that will transparently handle either a 1236socket or SSL BIO, 1237 i=BIO_read(bio,..) 1238 if (I == -1) 1239 { 1240 if (BIO_should_retry(bio)) 1241 { 1242 if (BIO_should_read(bio)) 1243 { 1244 /* call us again when BIO can be read */ 1245 } 1246 if (BIO_should_write(bio)) 1247 { 1248 /* call us again when BIO can be written */ 1249 } 1250 } 1251 } 1252 1253At this point in time only read and write conditions can be 1254used but in the future I can see the situation for other 1255conditions, specifically with SSL there could be a condition 1256of a X509 certificate lookup taking place and so the non- 1257blocking BIO_read would require a retry when the certificate 1258lookup subsystem has finished it's lookup. This is all 1259makes more sense and is easy to use in a event loop type 1260setup. 1261When using the SSL BIO, either SSL_read() or SSL_write()s 1262can be called during the protocol startup and things will 1263still work correctly. 1264The nice aspect of the use of the BIO_should_retry() macro 1265is that all the errno codes that indicate a non-fatal error 1266are encapsulated in one place. The Windows specific error 1267codes and WSAGetLastError() calls are also hidden from the 1268application. 1269 1270Notes on each BIO method. 1271Normally buffer.h is just required but depending on the 1272BIO_METHOD, ssl.h or evp.h will also be required. 1273 1274BIO_METHOD *BIO_s_mem(void); 1275- BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) - 1276 set the underlying BUF_MEM structure for the BIO to use. 1277- BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL, 1278 set it to point to the memory array and return the number 1279 of bytes available. 1280A read/write BIO. Any data written is appended to the 1281memory array and any read is read from the front. This BIO 1282can be used for read/write at the same time. BIO_gets() is 1283supported in the fgets() sense. 1284BIO_CTRL_INFO can be used to retrieve pointers to the memory 1285buffer and it's length. 1286 1287BIO_METHOD *BIO_s_file(void); 1288- BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use. 1289- BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use. 1290- BIO_read_filename(BIO *bio, char *name) - read from file. 1291- BIO_write_filename(BIO *bio, char *name) - write to file. 1292- BIO_append_filename(BIO *bio, char *name) - append to file. 1293This BIO sits over the normal system fread()/fgets() type 1294functions. Gets() is supported. This BIO in theory could be 1295used for read and write but it is best to think of each BIO 1296of this type as either a read or a write BIO, not both. 1297 1298BIO_METHOD *BIO_s_socket(void); 1299BIO_METHOD *BIO_s_fd(void); 1300- BIO_sock_should_retry(int i) - the underlying function 1301 used to determine if a call should be retried; the 1302 argument is the '0' or '-1' returned by the previous BIO 1303 operation. 1304- BIO_fd_should_retry(int i) - same as the 1305- BIO_sock_should_retry() except that it is different internally. 1306- BIO_set_fd(BIO *bio, int fd, int close_flag) - set the 1307 file descriptor to use 1308- BIO_get_fd(BIO *bio, int *fd) - get the file descriptor. 1309These two methods are very similar. Gets() is not 1310supported, if you want this functionality, put a 1311BIO_f_buffer() onto it. This BIO is bi-directional if the 1312underlying file descriptor is. This is normally the case 1313for sockets but not the case for stdio descriptors. 1314 1315BIO_METHOD *BIO_s_null(void); 1316Read and write as much data as you like, it all disappears 1317into this BIO. 1318 1319BIO_METHOD *BIO_f_buffer(void); 1320- BIO_get_buffer_num_lines(BIO *bio) - return the number of 1321 complete lines in the buffer. 1322- BIO_set_buffer_size(BIO *bio, long size) - set the size of 1323 the buffers. 1324This type performs input and output buffering. It performs 1325both at the same time. The size of the buffer can be set 1326via the set buffer size option. Data buffered for output is 1327only written when the buffer fills. 1328 1329BIO_METHOD *BIO_f_ssl(void); 1330- BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL 1331 structure to use. 1332- BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure 1333 in use. 1334The SSL bio is a little different from normal BIOs because 1335the underlying SSL structure is a little different. A SSL 1336structure performs IO via a read and write BIO. These can 1337be different and are normally set via the 1338SSL_set_rbio()/SSL_set_wbio() calls. The SSL_set_fd() calls 1339are just wrappers that create socket BIOs and then call 1340SSL_set_bio() where the read and write BIOs are the same. 1341The BIO_push() operation makes the SSLs IO BIOs the same, so 1342make sure the BIO pushed is capable of two directional 1343traffic. If it is not, you will have to install the BIOs 1344via the more conventional SSL_set_bio() call. BIO_pop() will retrieve 1345the 'SSL read' BIO. 1346 1347BIO_METHOD *BIO_f_md(void); 1348- BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest 1349 to use. 1350- BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest 1351 method in use in mdp, return 0 if not set yet. 1352- BIO_reset() reinitializes the digest (EVP_DigestInit()) 1353 and passes the reset to the underlying BIOs. 1354All data read or written via BIO_read() or BIO_write() to 1355this BIO will be added to the calculated digest. This 1356implies that this BIO is only one directional. If read and 1357write operations are performed, two separate BIO_f_md() BIOs 1358are reuqired to generate digests on both the input and the 1359output. BIO_gets(BIO *bio, char *md, int size) will place the 1360generated digest into 'md' and return the number of bytes. 1361The EVP_MAX_MD_SIZE should probably be used to size the 'md' 1362array. Reading the digest will also reset it. 1363 1364BIO_METHOD *BIO_f_cipher(void); 1365- BIO_reset() reinitializes the cipher. 1366- BIO_flush() should be called when the last bytes have been 1367 output to flush the final block of block ciphers. 1368- BIO_get_cipher_status(BIO *b), when called after the last 1369 read from a cipher BIO, returns non-zero if the data 1370 decrypted correctly, otherwise, 0. 1371- BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key, 1372 unsigned char *iv, int encrypt) This function is used to 1373 setup a cipher BIO. The length of key and iv are 1374 specified by the choice of EVP_CIPHER. Encrypt is 1 to 1375 encrypt and 0 to decrypt. 1376 1377BIO_METHOD *BIO_f_base64(void); 1378- BIO_flush() should be called when the last bytes have been output. 1379This BIO base64 encodes when writing and base64 decodes when 1380reading. It will scan the input until a suitable begin line 1381is found. After reading data, BIO_reset() will reset the 1382BIO to start scanning again. Do not mix reading and writing 1383on the same base64 BIO. It is meant as a single stream BIO. 1384 1385Directions type 1386both BIO_s_mem() 1387one/both BIO_s_file() 1388both BIO_s_fd() 1389both BIO_s_socket() 1390both BIO_s_null() 1391both BIO_f_buffer() 1392one BIO_f_md() 1393one BIO_f_cipher() 1394one BIO_f_base64() 1395both BIO_f_ssl() 1396 1397It is easy to mix one and two directional BIOs, all one has 1398to do is to keep two separate BIO pointers for reading and 1399writing and be careful about usage of underlying BIOs. The 1400SSL bio by it's very nature has to be two directional but 1401the BIO_push() command will push the one BIO into the SSL 1402BIO for both reading and writing. 1403 1404The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c. 1405 1406 1407==== blowfish.doc ======================================================== 1408 1409The Blowfish library. 1410 1411Blowfish is a block cipher that operates on 64bit (8 byte) quantities. It 1412uses variable size key, but 128bit (16 byte) key would normally be considered 1413good. It can be used in all the modes that DES can be used. This 1414library implements the ecb, cbc, cfb64, ofb64 modes. 1415 1416Blowfish is quite a bit faster that DES, and much faster than IDEA or 1417RC2. It is one of the faster block ciphers. 1418 1419For all calls that have an 'input' and 'output' variables, they can be the 1420same. 1421 1422This library requires the inclusion of 'blowfish.h'. 1423 1424All of the encryption functions take what is called an BF_KEY as an 1425argument. An BF_KEY is an expanded form of the Blowfish key. 1426For all modes of the Blowfish algorithm, the BF_KEY used for 1427decryption is the same one that was used for encryption. 1428 1429The define BF_ENCRYPT is passed to specify encryption for the functions 1430that require an encryption/decryption flag. BF_DECRYPT is passed to 1431specify decryption. 1432 1433Please note that any of the encryption modes specified in my DES library 1434could be used with Blowfish. I have only implemented ecb, cbc, cfb64 and 1435ofb64 for the following reasons. 1436- ecb is the basic Blowfish encryption. 1437- cbc is the normal 'chaining' form for block ciphers. 1438- cfb64 can be used to encrypt single characters, therefore input and output 1439 do not need to be a multiple of 8. 1440- ofb64 is similar to cfb64 but is more like a stream cipher, not as 1441 secure (not cipher feedback) but it does not have an encrypt/decrypt mode. 1442- If you want triple Blowfish, thats 384 bits of key and you must be totally 1443 obsessed with security. Still, if you want it, it is simple enough to 1444 copy the function from the DES library and change the des_encrypt to 1445 BF_encrypt; an exercise left for the paranoid reader :-). 1446 1447The functions are as follows: 1448 1449void BF_set_key( 1450BF_KEY *ks; 1451int len; 1452unsigned char *key; 1453 BF_set_key converts an 'len' byte key into a BF_KEY. 1454 A 'ks' is an expanded form of the 'key' which is used to 1455 perform actual encryption. It can be regenerated from the Blowfish key 1456 so it only needs to be kept when encryption or decryption is about 1457 to occur. Don't save or pass around BF_KEY's since they 1458 are CPU architecture dependent, 'key's are not. Blowfish is an 1459 interesting cipher in that it can be used with a variable length 1460 key. 'len' is the length of 'key' to be used as the key. 1461 A 'len' of 16 is recomended by me, but blowfish can use upto 1462 72 bytes. As a warning, blowfish has a very very slow set_key 1463 function, it actually runs BF_encrypt 521 times. 1464 1465void BF_encrypt(unsigned long *data, BF_KEY *key); 1466void BF_decrypt(unsigned long *data, BF_KEY *key); 1467 These are the Blowfish encryption function that gets called by just 1468 about every other Blowfish routine in the library. You should not 1469 use this function except to implement 'modes' of Blowfish. 1470 I say this because the 1471 functions that call this routine do the conversion from 'char *' to 1472 long, and this needs to be done to make sure 'non-aligned' memory 1473 access do not occur. 1474 Data is a pointer to 2 unsigned long's and key is the 1475 BF_KEY to use. 1476 1477void BF_ecb_encrypt( 1478unsigned char *in, 1479unsigned char *out, 1480BF_KEY *key, 1481int encrypt); 1482 This is the basic Electronic Code Book form of Blowfish (in DES this 1483 mode is called Electronic Code Book so I'm going to use the term 1484 for blowfish as well. 1485 Input is encrypted into output using the key represented by 1486 key. Depending on the encrypt, encryption or 1487 decryption occurs. Input is 8 bytes long and output is 8 bytes. 1488 1489void BF_cbc_encrypt( 1490unsigned char *in, 1491unsigned char *out, 1492long length, 1493BF_KEY *ks, 1494unsigned char *ivec, 1495int encrypt); 1496 This routine implements Blowfish in Cipher Block Chaining mode. 1497 Input, which should be a multiple of 8 bytes is encrypted 1498 (or decrypted) to output which will also be a multiple of 8 bytes. 1499 The number of bytes is in length (and from what I've said above, 1500 should be a multiple of 8). If length is not a multiple of 8, bad 1501 things will probably happen. ivec is the initialisation vector. 1502 This function updates iv after each call so that it can be passed to 1503 the next call to BF_cbc_encrypt(). 1504 1505void BF_cfb64_encrypt( 1506unsigned char *in, 1507unsigned char *out, 1508long length, 1509BF_KEY *schedule, 1510unsigned char *ivec, 1511int *num, 1512int encrypt); 1513 This is one of the more useful functions in this Blowfish library, it 1514 implements CFB mode of Blowfish with 64bit feedback. 1515 This allows you to encrypt an arbitrary number of bytes, 1516 you do not require 8 byte padding. Each call to this 1517 routine will encrypt the input bytes to output and then update ivec 1518 and num. Num contains 'how far' we are though ivec. 1519 'Encrypt' is used to indicate encryption or decryption. 1520 CFB64 mode operates by using the cipher to generate a stream 1521 of bytes which is used to encrypt the plain text. 1522 The cipher text is then encrypted to generate the next 64 bits to 1523 be xored (incrementally) with the next 64 bits of plain 1524 text. As can be seen from this, to encrypt or decrypt, 1525 the same 'cipher stream' needs to be generated but the way the next 1526 block of data is gathered for encryption is different for 1527 encryption and decryption. 1528 1529void BF_ofb64_encrypt( 1530unsigned char *in, 1531unsigned char *out, 1532long length, 1533BF_KEY *schedule, 1534unsigned char *ivec, 1535int *num); 1536 This functions implements OFB mode of Blowfish with 64bit feedback. 1537 This allows you to encrypt an arbitrary number of bytes, 1538 you do not require 8 byte padding. Each call to this 1539 routine will encrypt the input bytes to output and then update ivec 1540 and num. Num contains 'how far' we are though ivec. 1541 This is in effect a stream cipher, there is no encryption or 1542 decryption mode. 1543 1544For reading passwords, I suggest using des_read_pw_string() from my DES library. 1545To generate a password from a text string, I suggest using MD5 (or MD2) to 1546produce a 16 byte message digest that can then be passed directly to 1547BF_set_key(). 1548 1549===== 1550For more information about the specific Blowfish modes in this library 1551(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the 1552documentation on my DES library. What is said about DES is directly 1553applicable for Blowfish. 1554 1555 1556==== bn.doc ======================================================== 1557 1558The Big Number library. 1559 1560#include "bn.h" when using this library. 1561 1562This big number library was written for use in implementing the RSA and DH 1563public key encryption algorithms. As such, features such as negative 1564numbers have not been extensively tested but they should work as expected. 1565This library uses dynamic memory allocation for storing its data structures 1566and so there are no limit on the size of the numbers manipulated by these 1567routines but there is always the requirement to check return codes from 1568functions just in case a memory allocation error has occurred. 1569 1570The basic object in this library is a BIGNUM. It is used to hold a single 1571large integer. This type should be considered opaque and fields should not 1572be modified or accessed directly. 1573typedef struct bignum_st 1574 { 1575 int top; /* Index of last used d. */ 1576 BN_ULONG *d; /* Pointer to an array of 'BITS2' bit chunks. */ 1577 int max; /* Size of the d array. */ 1578 int neg; 1579 } BIGNUM; 1580The big number is stored in a malloced array of BN_ULONG's. A BN_ULONG can 1581be either 16, 32 or 64 bits in size, depending on the 'number of bits' 1582specified in bn.h. 1583The 'd' field is this array. 'max' is the size of the 'd' array that has 1584been allocated. 'top' is the 'last' entry being used, so for a value of 4, 1585bn.d[0]=4 and bn.top=1. 'neg' is 1 if the number is negative. 1586When a BIGNUM is '0', the 'd' field can be NULL and top == 0. 1587 1588Various routines in this library require the use of 'temporary' BIGNUM 1589variables during their execution. Due to the use of dynamic memory 1590allocation to create BIGNUMs being rather expensive when used in 1591conjunction with repeated subroutine calls, the BN_CTX structure is 1592used. This structure contains BN_CTX BIGNUMs. BN_CTX 1593is the maximum number of temporary BIGNUMs any publicly exported 1594function will use. 1595 1596#define BN_CTX 12 1597typedef struct bignum_ctx 1598 { 1599 int tos; /* top of stack */ 1600 BIGNUM *bn[BN_CTX]; /* The variables */ 1601 } BN_CTX; 1602 1603The functions that follow have been grouped according to function. Most 1604arithmetic functions return a result in the first argument, sometimes this 1605first argument can also be an input parameter, sometimes it cannot. These 1606restrictions are documented. 1607 1608extern BIGNUM *BN_value_one; 1609There is one variable defined by this library, a BIGNUM which contains the 1610number 1. This variable is useful for use in comparisons and assignment. 1611 1612Get Size functions. 1613 1614int BN_num_bits(BIGNUM *a); 1615 This function returns the size of 'a' in bits. 1616 1617int BN_num_bytes(BIGNUM *a); 1618 This function (macro) returns the size of 'a' in bytes. 1619 For conversion of BIGNUMs to byte streams, this is the number of 1620 bytes the output string will occupy. If the output byte 1621 format specifies that the 'top' bit indicates if the number is 1622 signed, so an extra '0' byte is required if the top bit on a 1623 positive number is being written, it is upto the application to 1624 make this adjustment. Like I said at the start, I don't 1625 really support negative numbers :-). 1626 1627Creation/Destruction routines. 1628 1629BIGNUM *BN_new(); 1630 Return a new BIGNUM object. The number initially has a value of 0. If 1631 there is an error, NULL is returned. 1632 1633void BN_free(BIGNUM *a); 1634 Free()s a BIGNUM. 1635 1636void BN_clear(BIGNUM *a); 1637 Sets 'a' to a value of 0 and also zeros all unused allocated 1638 memory. This function is used to clear a variable of 'sensitive' 1639 data that was held in it. 1640 1641void BN_clear_free(BIGNUM *a); 1642 This function zeros the memory used by 'a' and then free()'s it. 1643 This function should be used to BN_free() BIGNUMS that have held 1644 sensitive numeric values like RSA private key values. Both this 1645 function and BN_clear tend to only be used by RSA and DH routines. 1646 1647BN_CTX *BN_CTX_new(void); 1648 Returns a new BN_CTX. NULL on error. 1649 1650void BN_CTX_free(BN_CTX *c); 1651 Free a BN_CTX structure. The BIGNUMs in 'c' are BN_clear_free()ed. 1652 1653BIGNUM *bn_expand(BIGNUM *b, int bits); 1654 This is an internal function that should not normally be used. It 1655 ensures that 'b' has enough room for a 'bits' bit number. It is 1656 mostly used by the various BIGNUM routines. If there is an error, 1657 NULL is returned. if not, 'b' is returned. 1658 1659BIGNUM *BN_copy(BIGNUM *to, BIGNUM *from); 1660 The 'from' is copied into 'to'. NULL is returned if there is an 1661 error, otherwise 'to' is returned. 1662 1663BIGNUM *BN_dup(BIGNUM *a); 1664 A new BIGNUM is created and returned containing the value of 'a'. 1665 NULL is returned on error. 1666 1667Comparison and Test Functions. 1668 1669int BN_is_zero(BIGNUM *a) 1670 Return 1 if 'a' is zero, else 0. 1671 1672int BN_is_one(a) 1673 Return 1 is 'a' is one, else 0. 1674 1675int BN_is_word(a,w) 1676 Return 1 if 'a' == w, else 0. 'w' is a BN_ULONG. 1677 1678int BN_cmp(BIGNUM *a, BIGNUM *b); 1679 Return -1 if 'a' is less than 'b', 0 if 'a' and 'b' are the same 1680 and 1 is 'a' is greater than 'b'. This is a signed comparison. 1681 1682int BN_ucmp(BIGNUM *a, BIGNUM *b); 1683 This function is the same as BN_cmp except that the comparison 1684 ignores the sign of the numbers. 1685 1686Arithmetic Functions 1687For all of these functions, 0 is returned if there is an error and 1 is 1688returned for success. The return value should always be checked. eg. 1689if (!BN_add(r,a,b)) goto err; 1690Unless explicitly mentioned, the 'return' value can be one of the 1691'parameters' to the function. 1692 1693int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b); 1694 Add 'a' and 'b' and return the result in 'r'. This is r=a+b. 1695 1696int BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b); 1697 Subtract 'a' from 'b' and put the result in 'r'. This is r=a-b. 1698 1699int BN_lshift(BIGNUM *r, BIGNUM *a, int n); 1700 Shift 'a' left by 'n' bits. This is r=a*(2^n). 1701 1702int BN_lshift1(BIGNUM *r, BIGNUM *a); 1703 Shift 'a' left by 1 bit. This form is more efficient than 1704 BN_lshift(r,a,1). This is r=a*2. 1705 1706int BN_rshift(BIGNUM *r, BIGNUM *a, int n); 1707 Shift 'a' right by 'n' bits. This is r=int(a/(2^n)). 1708 1709int BN_rshift1(BIGNUM *r, BIGNUM *a); 1710 Shift 'a' right by 1 bit. This form is more efficient than 1711 BN_rshift(r,a,1). This is r=int(a/2). 1712 1713int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b); 1714 Multiply a by b and return the result in 'r'. 'r' must not be 1715 either 'a' or 'b'. It has to be a different BIGNUM. 1716 This is r=a*b. 1717 1718int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); 1719 Multiply a by a and return the result in 'r'. 'r' must not be 1720 'a'. This function is alot faster than BN_mul(r,a,a). This is r=a*a. 1721 1722int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); 1723 Divide 'm' by 'd' and return the result in 'dv' and the remainder 1724 in 'rem'. Either of 'dv' or 'rem' can be NULL in which case that 1725 value is not returned. 'ctx' needs to be passed as a source of 1726 temporary BIGNUM variables. 1727 This is dv=int(m/d), rem=m%d. 1728 1729int BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); 1730 Find the remainder of 'm' divided by 'd' and return it in 'rem'. 1731 'ctx' holds the temporary BIGNUMs required by this function. 1732 This function is more efficient than BN_div(NULL,rem,m,d,ctx); 1733 This is rem=m%d. 1734 1735int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BIGNUM *m,BN_CTX *ctx); 1736 Multiply 'a' by 'b' and return the remainder when divided by 'm'. 1737 'ctx' holds the temporary BIGNUMs required by this function. 1738 This is r=(a*b)%m. 1739 1740int BN_mod_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx); 1741 Raise 'a' to the 'p' power and return the remainder when divided by 1742 'm'. 'ctx' holds the temporary BIGNUMs required by this function. 1743 This is r=(a^p)%m. 1744 1745int BN_reciprocal(BIGNUM *r, BIGNUM *m, BN_CTX *ctx); 1746 Return the reciprocal of 'm'. 'ctx' holds the temporary variables 1747 required. This function returns -1 on error, otherwise it returns 1748 the number of bits 'r' is shifted left to make 'r' into an integer. 1749 This number of bits shifted is required in BN_mod_mul_reciprocal(). 1750 This is r=(1/m)<<(BN_num_bits(m)+1). 1751 1752int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y, BIGNUM *m, 1753 BIGNUM *i, int nb, BN_CTX *ctx); 1754 This function is used to perform an efficient BN_mod_mul() 1755 operation. If one is going to repeatedly perform BN_mod_mul() with 1756 the same modulus is worth calculating the reciprocal of the modulus 1757 and then using this function. This operation uses the fact that 1758 a/b == a*r where r is the reciprocal of b. On modern computers 1759 multiplication is very fast and big number division is very slow. 1760 'x' is multiplied by 'y' and then divided by 'm' and the remainder 1761 is returned. 'i' is the reciprocal of 'm' and 'nb' is the number 1762 of bits as returned from BN_reciprocal(). Normal usage is as follows. 1763 bn=BN_reciprocal(i,m); 1764 for (...) 1765 { BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); } 1766 This is r=(x*y)%m. Internally it is approximately 1767 r=(x*y)-m*(x*y/m) or r=(x*y)-m*((x*y*i) >> bn) 1768 This function is used in BN_mod_exp() and BN_is_prime(). 1769 1770Assignment Operations 1771 1772int BN_one(BIGNUM *a) 1773 Set 'a' to hold the value one. 1774 This is a=1. 1775 1776int BN_zero(BIGNUM *a) 1777 Set 'a' to hold the value zero. 1778 This is a=0. 1779 1780int BN_set_word(BIGNUM *a, unsigned long w); 1781 Set 'a' to hold the value of 'w'. 'w' is an unsigned long. 1782 This is a=w. 1783 1784unsigned long BN_get_word(BIGNUM *a); 1785 Returns 'a' in an unsigned long. Not remarkably, often 'a' will 1786 be biger than a word, in which case 0xffffffffL is returned. 1787 1788Word Operations 1789These functions are much more efficient that the normal bignum arithmetic 1790operations. 1791 1792BN_ULONG BN_mod_word(BIGNUM *a, unsigned long w); 1793 Return the remainder of 'a' divided by 'w'. 1794 This is return(a%w). 1795 1796int BN_add_word(BIGNUM *a, unsigned long w); 1797 Add 'w' to 'a'. This function does not take the sign of 'a' into 1798 account. This is a+=w; 1799 1800Bit operations. 1801 1802int BN_is_bit_set(BIGNUM *a, int n); 1803 This function return 1 if bit 'n' is set in 'a' else 0. 1804 1805int BN_set_bit(BIGNUM *a, int n); 1806 This function sets bit 'n' to 1 in 'a'. 1807 This is a&= ~(1<<n); 1808 1809int BN_clear_bit(BIGNUM *a, int n); 1810 This function sets bit 'n' to zero in 'a'. Return 0 if less 1811 than 'n' bits in 'a' else 1. This is a&= ~(1<<n); 1812 1813int BN_mask_bits(BIGNUM *a, int n); 1814 Truncate 'a' to n bits long. This is a&= ~((~0)<<n) 1815 1816Format conversion routines. 1817 1818BIGNUM *BN_bin2bn(unsigned char *s, int len,BIGNUM *ret); 1819 This function converts 'len' bytes in 's' into a BIGNUM which 1820 is put in 'ret'. If ret is NULL, a new BIGNUM is created. 1821 Either this new BIGNUM or ret is returned. The number is 1822 assumed to be in bigendian form in 's'. By this I mean that 1823 to 'ret' is created as follows for 'len' == 5. 1824 ret = s[0]*2^32 + s[1]*2^24 + s[2]*2^16 + s[3]*2^8 + s[4]; 1825 This function cannot be used to convert negative numbers. It 1826 is always assumed the number is positive. The application 1827 needs to diddle the 'neg' field of th BIGNUM its self. 1828 The better solution would be to save the numbers in ASN.1 format 1829 since this is a defined standard for storing big numbers. 1830 Look at the functions 1831 1832 ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai); 1833 BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn); 1834 int i2d_ASN1_INTEGER(ASN1_INTEGER *a,unsigned char **pp); 1835 ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **a,unsigned char **pp, 1836 long length; 1837 1838int BN_bn2bin(BIGNUM *a, unsigned char *to); 1839 This function converts 'a' to a byte string which is put into 1840 'to'. The representation is big-endian in that the most 1841 significant byte of 'a' is put into to[0]. This function 1842 returns the number of bytes used to hold 'a'. BN_num_bytes(a) 1843 would return the same value and can be used to determine how 1844 large 'to' needs to be. If the number is negative, this 1845 information is lost. Since this library was written to 1846 manipulate large positive integers, the inability to save and 1847 restore them is not considered to be a problem by me :-). 1848 As for BN_bin2bn(), look at the ASN.1 integer encoding funtions 1849 for SSLeay. They use BN_bin2bn() and BN_bn2bin() internally. 1850 1851char *BN_bn2ascii(BIGNUM *a); 1852 This function returns a malloc()ed string that contains the 1853 ascii hexadecimal encoding of 'a'. The number is in bigendian 1854 format with a '-' in front if the number is negative. 1855 1856int BN_ascii2bn(BIGNUM **bn, char *a); 1857 The inverse of BN_bn2ascii. The function returns the number of 1858 characters from 'a' were processed in generating a the bignum. 1859 error is inticated by 0 being returned. The number is a 1860 hex digit string, optionally with a leading '-'. If *bn 1861 is null, a BIGNUM is created and returned via that variable. 1862 1863int BN_print_fp(FILE *fp, BIGNUM *a); 1864 'a' is printed to file pointer 'fp'. It is in the same format 1865 that is output from BN_bn2ascii(). 0 is returned on error, 1866 1 if things are ok. 1867 1868int BN_print(BIO *bp, BIGNUM *a); 1869 Same as BN_print except that the output is done to the SSLeay libraries 1870 BIO routines. BN_print_fp() actually calls this function. 1871 1872Miscellaneous Routines. 1873 1874int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); 1875 This function returns in 'rnd' a random BIGNUM that is bits 1876 long. If bottom is 1, the number returned is odd. If top is set, 1877 the top 2 bits of the number are set. This is useful because if 1878 this is set, 2 'n; bit numbers multiplied together will return a 2n 1879 bit number. If top was not set, they could produce a 2n-1 bit 1880 number. 1881 1882BIGNUM *BN_mod_inverse(BIGNUM *a, BIGNUM *n,BN_CTX *ctx); 1883 This function create a new BIGNUM and returns it. This number 1884 is the inverse mod 'n' of 'a'. By this it is meant that the 1885 returned value 'r' satisfies (a*r)%n == 1. This function is 1886 used in the generation of RSA keys. 'ctx', as per usual, 1887 is used to hold temporary variables that are required by the 1888 function. NULL is returned on error. 1889 1890int BN_gcd(BIGNUM *r,BIGNUM *a,BIGNUM *b,BN_CTX *ctx); 1891 'r' has the greatest common divisor of 'a' and 'b'. 'ctx' is 1892 used for temporary variables and 0 is returned on error. 1893 1894int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(),BN_CTX *ctx, 1895 char *cb_arg); 1896 This function is used to check if a BIGNUM ('p') is prime. 1897 It performs this test by using the Miller-Rabin randomised 1898 primality test. This is a probalistic test that requires a 1899 number of rounds to ensure the number is prime to a high 1900 degree of probability. Since this can take quite some time, a 1901 callback function can be passed and it will be called each 1902 time 'p' passes a round of the prime testing. 'callback' will 1903 be called as follows, callback(1,n,cb_arg) where n is the number of 1904 the round, just passed. As per usual 'ctx' contains temporary 1905 variables used. If ctx is NULL, it does not matter, a local version 1906 will be malloced. This parameter is present to save some mallocing 1907 inside the function but probably could be removed. 1908 0 is returned on error. 1909 'ncheck' is the number of Miller-Rabin tests to run. It is 1910 suggested to use the value 'BN_prime_checks' by default. 1911 1912BIGNUM *BN_generate_prime( 1913int bits, 1914int strong, 1915BIGNUM *a, 1916BIGNUM *rems, 1917void (*callback)()); 1918char *cb_arg 1919 This function is used to generate prime numbers. It returns a 1920 new BIGNUM that has a high probability of being a prime. 1921 'bits' is the number of bits that 1922 are to be in the prime. If 'strong' is true, the returned prime 1923 will also be a strong prime ((p-1)/2 is also prime). 1924 While searching for the prime ('p'), we 1925 can add the requirement that the prime fill the following 1926 condition p%a == rem. This can be used to help search for 1927 primes with specific features, which is required when looking 1928 for primes suitable for use with certain 'g' values in the 1929 Diffie-Hellman key exchange algorithm. If 'a' is NULL, 1930 this condition is not checked. If rem is NULL, rem is assumed 1931 to be 1. Since this search for a prime 1932 can take quite some time, if callback is not NULL, it is called 1933 in the following situations. 1934 We have a suspected prime (from a quick sieve), 1935 callback(0,sus_prime++,cb_arg). Each item to be passed to BN_is_prime(). 1936 callback(1,round++,cb_arg). Each successful 'round' in BN_is_prime(). 1937 callback(2,round,cb_arg). For each successful BN_is_prime() test. 1938 1939Hints 1940----- 1941 1942DSA wants 64*32 to use word mont mul, but RSA wants to use full. 1943 1944==== callback.doc ======================================================== 1945 1946Callback functions used in SSLeay. 1947 1948-------------------------- 1949The BIO library. 1950 1951Each BIO structure can have a callback defined against it. This callback is 1952called 2 times for each BIO 'function'. It is passed 6 parameters. 1953BIO_debug_callback() is an example callback which is defined in 1954crypto/buffer/bio_cb.c and is used in apps/dgst.c This is intended mostly 1955for debuging or to notify the application of IO. 1956 1957long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl, 1958 long ret); 1959bio is the BIO being called, cmd is the type of BIO function being called. 1960Look at the BIO_CB_* defines in buffer.h. Argp and argi are the arguments 1961passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts(). In the case of 1962BIO_ctrl(), argl is also defined. The first time the callback is called, 1963before the underlying function has been executed, 0 is passed as 'ret', and 1964if the return code from the callback is not > 0, the call is aborted 1965and the returned <= 0 value is returned. 1966The second time the callback is called, the 'cmd' value also has 1967BIO_CB_RETURN logically 'or'ed with it. The 'ret' value is the value returned 1968from the actuall function call and whatever the callback returns is returned 1969from the BIO function. 1970 1971BIO_set_callback(b,cb) can be used to set the callback function 1972(b is a BIO), and BIO_set_callback_arg(b,arg) can be used to 1973set the cb_arg argument in the BIO strucutre. This field is only intended 1974to be used by application, primarily in the callback function since it is 1975accessable since the BIO is passed. 1976 1977-------------------------- 1978The PEM library. 1979 1980The pem library only really uses one type of callback, 1981static int def_callback(char *buf, int num, int verify); 1982which is used to return a password string if required. 1983'buf' is the buffer to put the string in. 'num' is the size of 'buf' 1984and 'verify' is used to indicate that the password should be checked. 1985This last flag is mostly used when reading a password for encryption. 1986 1987For all of these functions, a NULL callback will call the above mentioned 1988default callback. This default function does not work under Windows 3.1. 1989For other machines, it will use an application defined prompt string 1990(EVP_set_pw_prompt(), which defines a library wide prompt string) 1991if defined, otherwise it will use it's own PEM password prompt. 1992It will then call EVP_read_pw_string() to get a password from the console. 1993If your application wishes to use nice fancy windows to retrieve passwords, 1994replace this function. The callback should return the number of bytes read 1995into 'buf'. If the number of bytes <= 0, it is considered an error. 1996 1997Functions that take this callback are listed below. For the 'read' type 1998functions, the callback will only be required if the PEM data is encrypted. 1999 2000For the Write functions, normally a password can be passed in 'kstr', of 2001'klen' bytes which will be used if the 'enc' cipher is not NULL. If 2002'kstr' is NULL, the callback will be used to retrieve a password. 2003 2004int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len, 2005 int (*callback)()); 2006char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)()); 2007char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)()); 2008int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x, 2009 EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)()); 2010int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x, 2011 EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)()); 2012STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)()); 2013STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)()); 2014 2015#define PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb) 2016#define PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb) 2017#define PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb) 2018#define PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb) 2019#define PEM_read_SSL_SESSION(fp,x,cb) 2020#define PEM_read_X509(fp,x,cb) 2021#define PEM_read_X509_REQ(fp,x,cb) 2022#define PEM_read_X509_CRL(fp,x,cb) 2023#define PEM_read_RSAPrivateKey(fp,x,cb) 2024#define PEM_read_DSAPrivateKey(fp,x,cb) 2025#define PEM_read_PrivateKey(fp,x,cb) 2026#define PEM_read_PKCS7(fp,x,cb) 2027#define PEM_read_DHparams(fp,x,cb) 2028#define PEM_read_bio_SSL_SESSION(bp,x,cb) 2029#define PEM_read_bio_X509(bp,x,cb) 2030#define PEM_read_bio_X509_REQ(bp,x,cb) 2031#define PEM_read_bio_X509_CRL(bp,x,cb) 2032#define PEM_read_bio_RSAPrivateKey(bp,x,cb) 2033#define PEM_read_bio_DSAPrivateKey(bp,x,cb) 2034#define PEM_read_bio_PrivateKey(bp,x,cb) 2035#define PEM_read_bio_PKCS7(bp,x,cb) 2036#define PEM_read_bio_DHparams(bp,x,cb) 2037int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); 2038RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)()); 2039 2040Now you will notice that macros like 2041#define PEM_write_X509(fp,x) \ 2042 PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \ 2043 (char *)x, NULL,NULL,0,NULL) 2044Don't do encryption normally. If you want to PEM encrypt your X509 structure, 2045either just call PEM_ASN1_write directly or just define you own 2046macro variant. As you can see, this macro just sets all encryption related 2047parameters to NULL. 2048 2049 2050-------------------------- 2051The SSL library. 2052 2053#define SSL_set_info_callback(ssl,cb) 2054#define SSL_CTX_set_info_callback(ctx,cb) 2055void callback(SSL *ssl,int location,int ret) 2056This callback is called each time around the SSL_connect()/SSL_accept() 2057state machine. So it will be called each time the SSL protocol progresses. 2058It is mostly present for use when debugging. When SSL_connect() or 2059SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or 2060SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned. 2061Have a look at the SSL_CB_* defines in ssl.h. If an info callback is defined 2062against the SSL_CTX, it is called unless there is one set against the SSL. 2063Have a look at 2064void client_info_callback() in apps/s_client() for an example. 2065 2066Certificate verification. 2067void SSL_set_verify(SSL *s, int mode, int (*callback) ()); 2068void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)()); 2069This callback is used to help verify client and server X509 certificates. 2070It is actually passed to X509_cert_verify(), along with the SSL structure 2071so you have to read about X509_cert_verify() :-). The SSL_CTX version is used 2072if the SSL version is not defined. X509_cert_verify() is the function used 2073by the SSL part of the library to verify certificates. This function is 2074nearly always defined by the application. 2075 2076void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg); 2077int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain); 2078This call is used to replace the SSLeay certificate verification code. 2079The 'arg' is kept in the SSL_CTX and is passed to the callback. 2080If the callback returns 0, the certificate is rejected, otherwise it 2081is accepted. The callback is replacing the X509_cert_verify() call. 2082This feature is not often used, but if you wished to implement 2083some totally different certificate authentication system, this 'hook' is 2084vital. 2085 2086SSLeay keeps a cache of session-ids against each SSL_CTX. These callbacks can 2087be used to notify the application when a SSL_SESSION is added to the cache 2088or to retrieve a SSL_SESSION that is not in the cache from the application. 2089#define SSL_CTX_sess_set_get_cb(ctx,cb) 2090SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy); 2091If defined, this callback is called to return the SESSION_ID for the 2092session-id in 'session_id', of 'session_id_len' bytes. 'copy' is set to 1 2093if the server is to 'take a copy' of the SSL_SESSION structure. It is 0 2094if the SSL_SESSION is being 'passed in' so the SSLeay library is now 2095responsible for 'free()ing' the structure. Basically it is used to indicate 2096if the reference count on the SSL_SESSION structure needs to be incremented. 2097 2098#define SSL_CTX_sess_set_new_cb(ctx,cb) 2099int callback(SSL *s, SSL_SESSION *sess); 2100When a new connection is established, if the SSL_SESSION is going to be added 2101to the cache, this callback is called. Return 1 if a 'copy' is required, 2102otherwise, return 0. This return value just causes the reference count 2103to be incremented (on return of a 1), this means the application does 2104not need to worry about incrementing the refernece count (and the 2105locking that implies in a multi-threaded application). 2106 2107void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)()); 2108This sets the SSL password reading function. 2109It is mostly used for windowing applications 2110and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey() 2111calls inside the SSL library. The only reason this is present is because the 2112calls to PEM_* functions is hidden in the SSLeay library so you have to 2113pass in the callback some how. 2114 2115#define SSL_CTX_set_client_cert_cb(ctx,cb) 2116int callback(SSL *s,X509 **x509, EVP_PKEY **pkey); 2117Called when a client certificate is requested but there is not one set 2118against the SSL_CTX or the SSL. If the callback returns 1, x509 and 2119pkey need to point to valid data. The library will free these when 2120required so if the application wants to keep these around, increment 2121their reference counts. If 0 is returned, no client cert is 2122available. If -1 is returned, it is assumed that the callback needs 2123to be called again at a later point in time. SSL_connect will return 2124-1 and SSL_want_x509_lookup(ssl) returns true. Remember that 2125application data can be attached to an SSL structure via the 2126SSL_set_app_data(SSL *ssl,char *data) call. 2127 2128-------------------------- 2129The X509 library. 2130 2131int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(), 2132 int *error,char *arg,STACK *cert_chain); 2133int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg, 2134 STACK *cert_chain); 2135 2136X509_cert_verify() is used to authenticate X509 certificates. The 'ctx' holds 2137the details of the various caches and files used to locate certificates. 2138'xs' is the certificate to verify and 'cb' is the application callback (more 2139detail later). 'error' will be set to the error code and 'arg' is passed 2140to the 'cb' callback. Look at the VERIFY_* defines in crypto/x509/x509.h 2141 2142When ever X509_cert_verify() makes a 'negative' decision about a 2143certitificate, the callback is called. If everything checks out, the 2144callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self 2145signed cert that is not the passed certificate). 2146 2147The callback is passed the X509_cert_verify opinion of the certificate 2148in 'ok', the certificate in 'xs', the issuer certificate in 'xi', 2149the 'depth' of the certificate in the verification 'chain', the 2150VERIFY_* code in 'error' and the argument passed to X509_cert_verify() 2151in 'arg'. cert_chain is a list of extra certs to use if they are not 2152in the cache. 2153 2154The callback can be used to look at the error reason, and then return 0 2155for an 'error' or '1' for ok. This will override the X509_cert_verify() 2156opinion of the certificates validity. Processing will continue depending on 2157the return value. If one just wishes to use the callback for informational 2158reason, just return the 'ok' parameter. 2159 2160-------------------------- 2161The BN and DH library. 2162 2163BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add, 2164 BIGNUM *rem,void (*callback)(int,int)); 2165int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int), 2166 2167Read doc/bn.doc for the description of these 2. 2168 2169DH *DH_generate_parameters(int prime_len,int generator, 2170 void (*callback)(int,int)); 2171Read doc/bn.doc for the description of the callback, since it is just passed 2172to BN_generate_prime(), except that it is also called as 2173callback(3,0) by this function. 2174 2175-------------------------- 2176The CRYPTO library. 2177 2178void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file, 2179 int line)); 2180void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount, 2181 int type,char *file, int line)); 2182void CRYPTO_set_id_callback(unsigned long (*func)(void)); 2183 2184Read threads.doc for info on these ones. 2185 2186 2187==== cipher.doc ======================================================== 2188 2189The Cipher subroutines. 2190 2191These routines require "evp.h" to be included. 2192 2193These functions are a higher level interface to the various cipher 2194routines found in this library. As such, they allow the same code to be 2195used to encrypt and decrypt via different ciphers with only a change 2196in an initial parameter. These routines also provide buffering for block 2197ciphers. 2198 2199These routines all take a pointer to the following structure to specify 2200which cipher to use. If you wish to use a new cipher with these routines, 2201you would probably be best off looking an how an existing cipher is 2202implemented and copying it. At this point in time, I'm not going to go 2203into many details. This structure should be considered opaque 2204 2205typedef struct pem_cipher_st 2206 { 2207 int type; 2208 int block_size; 2209 int key_len; 2210 int iv_len; 2211 void (*enc_init)(); /* init for encryption */ 2212 void (*dec_init)(); /* init for decryption */ 2213 void (*do_cipher)(); /* encrypt data */ 2214 } EVP_CIPHER; 2215 2216The type field is the object NID of the cipher type 2217(read the section on Objects for an explanation of what a NID is). 2218The cipher block_size is how many bytes need to be passed 2219to the cipher at a time. Key_len is the 2220length of the key the cipher requires and iv_len is the length of the 2221initialisation vector required. enc_init is the function 2222called to initialise the ciphers context for encryption and dec_init is the 2223function to initialise for decryption (they need to be different, especially 2224for the IDEA cipher). 2225 2226One reason for specifying the Cipher via a pointer to a structure 2227is that if you only use des-cbc, only the des-cbc routines will 2228be included when you link the program. If you passed an integer 2229that specified which cipher to use, the routine that mapped that 2230integer to a set of cipher functions would cause all the ciphers 2231to be link into the code. This setup also allows new ciphers 2232to be added by the application (with some restrictions). 2233 2234The thirteen ciphers currently defined in this library are 2235 2236EVP_CIPHER *EVP_des_ecb(); /* DES in ecb mode, iv=0, block=8, key= 8 */ 2237EVP_CIPHER *EVP_des_ede(); /* DES in ecb ede mode, iv=0, block=8, key=16 */ 2238EVP_CIPHER *EVP_des_ede3(); /* DES in ecb ede mode, iv=0, block=8, key=24 */ 2239EVP_CIPHER *EVP_des_cfb(); /* DES in cfb mode, iv=8, block=1, key= 8 */ 2240EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */ 2241EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */ 2242EVP_CIPHER *EVP_des_ofb(); /* DES in ofb mode, iv=8, block=1, key= 8 */ 2243EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */ 2244EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */ 2245EVP_CIPHER *EVP_des_cbc(); /* DES in cbc mode, iv=8, block=8, key= 8 */ 2246EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */ 2247EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */ 2248EVP_CIPHER *EVP_desx_cbc(); /* DES in desx cbc mode,iv=8, block=8, key=24 */ 2249EVP_CIPHER *EVP_rc4(); /* RC4, iv=0, block=1, key=16 */ 2250EVP_CIPHER *EVP_idea_ecb(); /* IDEA in ecb mode, iv=0, block=8, key=16 */ 2251EVP_CIPHER *EVP_idea_cfb(); /* IDEA in cfb mode, iv=8, block=1, key=16 */ 2252EVP_CIPHER *EVP_idea_ofb(); /* IDEA in ofb mode, iv=8, block=1, key=16 */ 2253EVP_CIPHER *EVP_idea_cbc(); /* IDEA in cbc mode, iv=8, block=8, key=16 */ 2254EVP_CIPHER *EVP_rc2_ecb(); /* RC2 in ecb mode, iv=0, block=8, key=16 */ 2255EVP_CIPHER *EVP_rc2_cfb(); /* RC2 in cfb mode, iv=8, block=1, key=16 */ 2256EVP_CIPHER *EVP_rc2_ofb(); /* RC2 in ofb mode, iv=8, block=1, key=16 */ 2257EVP_CIPHER *EVP_rc2_cbc(); /* RC2 in cbc mode, iv=8, block=8, key=16 */ 2258EVP_CIPHER *EVP_bf_ecb(); /* Blowfish in ecb mode,iv=0, block=8, key=16 */ 2259EVP_CIPHER *EVP_bf_cfb(); /* Blowfish in cfb mode,iv=8, block=1, key=16 */ 2260EVP_CIPHER *EVP_bf_ofb(); /* Blowfish in ofb mode,iv=8, block=1, key=16 */ 2261EVP_CIPHER *EVP_bf_cbc(); /* Blowfish in cbc mode,iv=8, block=8, key=16 */ 2262 2263The meaning of the compound names is as follows. 2264des The base cipher is DES. 2265idea The base cipher is IDEA 2266rc4 The base cipher is RC4-128 2267rc2 The base cipher is RC2-128 2268ecb Electronic Code Book form of the cipher. 2269cbc Cipher Block Chaining form of the cipher. 2270cfb 64 bit Cipher Feedback form of the cipher. 2271ofb 64 bit Output Feedback form of the cipher. 2272ede The cipher is used in Encrypt, Decrypt, Encrypt mode. The first 2273 and last keys are the same. 2274ede3 The cipher is used in Encrypt, Decrypt, Encrypt mode. 2275 2276All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument. 2277The state of the cipher is kept in this structure. 2278 2279typedef struct EVP_CIPHER_Ctx_st 2280 { 2281 EVP_CIPHER *cipher; 2282 int encrypt; /* encrypt or decrypt */ 2283 int buf_len; /* number we have left */ 2284 unsigned char buf[8]; 2285 union { 2286 .... /* cipher specific stuff */ 2287 } c; 2288 } EVP_CIPHER_CTX; 2289 2290Cipher is a pointer the the EVP_CIPHER for the current context. The encrypt 2291flag indicates encryption or decryption. buf_len is the number of bytes 2292currently being held in buf. 2293The 'c' union holds the cipher specify context. 2294 2295The following functions are to be used. 2296 2297int EVP_read_pw_string( 2298char *buf, 2299int len, 2300char *prompt, 2301int verify, 2302 This function is the same as des_read_pw_string() (des.doc). 2303 2304void EVP_set_pw_prompt(char *prompt); 2305 This function sets the 'default' prompt to use to use in 2306 EVP_read_pw_string when the prompt parameter is NULL. If the 2307 prompt parameter is NULL, this 'default prompt' feature is turned 2308 off. Be warned, this is a global variable so weird things 2309 will happen if it is used under Win16 and care must be taken 2310 with a multi-threaded version of the library. 2311 2312char *EVP_get_pw_prompt(); 2313 This returns a pointer to the default prompt string. NULL 2314 if it is not set. 2315 2316int EVP_BytesToKey( 2317EVP_CIPHER *type, 2318EVP_MD *md, 2319unsigned char *salt, 2320unsigned char *data, 2321int datal, 2322int count, 2323unsigned char *key, 2324unsigned char *iv); 2325 This function is used to generate a key and an initialisation vector 2326 for a specified cipher from a key string and a salt. Type 2327 specifies the cipher the 'key' is being generated for. Md is the 2328 message digest algorithm to use to generate the key and iv. The salt 2329 is an optional 8 byte object that is used to help seed the key 2330 generator. 2331 If the salt value is NULL, it is just not used. Datal is the 2332 number of bytes to use from 'data' in the key generation. 2333 This function returns the key size for the specified cipher, if 2334 data is NULL, this value is returns and no other 2335 computation is performed. Count is 2336 the number of times to loop around the key generator. I would 2337 suggest leaving it's value as 1. Key and iv are the structures to 2338 place the returning iv and key in. If they are NULL, no value is 2339 generated for that particular value. 2340 The algorithm used is as follows 2341 2342 /* M[] is an array of message digests 2343 * MD() is the message digest function */ 2344 M[0]=MD(data . salt); 2345 for (i=1; i<count; i++) M[0]=MD(M[0]); 2346 2347 i=1 2348 while (data still needed for key and iv) 2349 { 2350 M[i]=MD(M[i-1] . data . salt); 2351 for (i=1; i<count; i++) M[i]=MD(M[i]); 2352 i++; 2353 } 2354 2355 If the salt is NULL, it is not used. 2356 The digests are concatenated together. 2357 M = M[0] . M[1] . M[2] ....... 2358 2359 For key= 8, iv=8 => key=M[0.. 8], iv=M[ 9 .. 16]. 2360 For key=16, iv=0 => key=M[0..16]. 2361 For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24]. 2362 For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32]. 2363 2364 This routine will produce DES-CBC keys and iv that are compatible 2365 with the PKCS-5 standard when md2 or md5 are used. If md5 is 2366 used, the salt is NULL and count is 1, this routine will produce 2367 the password to key mapping normally used with RC4. 2368 I have attempted to logically extend the PKCS-5 standard to 2369 generate keys and iv for ciphers that require more than 16 bytes, 2370 if anyone knows what the correct standard is, please inform me. 2371 When using sha or sha1, things are a bit different under this scheme, 2372 since sha produces a 20 byte digest. So for ciphers requiring 2373 24 bits of data, 20 will come from the first MD and 4 will 2374 come from the second. 2375 2376 I have considered having a separate function so this 'routine' 2377 can be used without the requirement of passing a EVP_CIPHER *, 2378 but I have decided to not bother. If you wish to use the 2379 function without official EVP_CIPHER structures, just declare 2380 a local one and set the key_len and iv_len fields to the 2381 length you desire. 2382 2383The following routines perform encryption and decryption 'by parts'. By 2384this I mean that there are groups of 3 routines. An Init function that is 2385used to specify a cipher and initialise data structures. An Update routine 2386that does encryption/decryption, one 'chunk' at a time. And finally a 2387'Final' function that finishes the encryption/decryption process. 2388All these functions take a EVP_CIPHER pointer to specify which cipher to 2389encrypt/decrypt with. They also take a EVP_CIPHER_CTX object as an 2390argument. This structure is used to hold the state information associated 2391with the operation in progress. 2392 2393void EVP_EncryptInit( 2394EVP_CIPHER_CTX *ctx, 2395EVP_CIPHER *type, 2396unsigned char *key, 2397unsigned char *iv); 2398 This function initialise a EVP_CIPHER_CTX for encryption using the 2399 cipher passed in the 'type' field. The cipher is initialised to use 2400 'key' as the key and 'iv' for the initialisation vector (if one is 2401 required). If the type, key or iv is NULL, the value currently in the 2402 EVP_CIPHER_CTX is reused. So to perform several decrypt 2403 using the same cipher, key and iv, initialise with the cipher, 2404 key and iv the first time and then for subsequent calls, 2405 reuse 'ctx' but pass NULL for type, key and iv. You must make sure 2406 to pass a key that is large enough for a particular cipher. I 2407 would suggest using the EVP_BytesToKey() function. 2408 2409void EVP_EncryptUpdate( 2410EVP_CIPHER_CTX *ctx, 2411unsigned char *out, 2412int *outl, 2413unsigned char *in, 2414int inl); 2415 This function takes 'inl' bytes from 'in' and outputs bytes 2416 encrypted by the cipher 'ctx' was initialised with into 'out'. The 2417 number of bytes written to 'out' is put into outl. If a particular 2418 cipher encrypts in blocks, less or more bytes than input may be 2419 output. Currently the largest block size used by supported ciphers 2420 is 8 bytes, so 'out' should have room for 'inl+7' bytes. Normally 2421 EVP_EncryptInit() is called once, followed by lots and lots of 2422 calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal 2423 call. 2424 2425void EVP_EncryptFinal( 2426EVP_CIPHER_CTX *ctx, 2427unsigned char *out, 2428int *outl); 2429 Because quite a large number of ciphers are block ciphers, there is 2430 often an incomplete block to write out at the end of the 2431 encryption. EVP_EncryptFinal() performs processing on this last 2432 block. The last block in encoded in such a way that it is possible 2433 to determine how many bytes in the last block are valid. For 8 byte 2434 block size ciphers, if only 5 bytes in the last block are valid, the 2435 last three bytes will be filled with the value 3. If only 2 were 2436 valid, the other 6 would be filled with sixes. If all 8 bytes are 2437 valid, a extra 8 bytes are appended to the cipher stream containing 2438 nothing but 8 eights. These last bytes are output into 'out' and 2439 the number of bytes written is put into 'outl' These last bytes 2440 are output into 'out' and the number of bytes written is put into 2441 'outl'. This form of block cipher finalisation is compatible with 2442 PKCS-5. Please remember that even if you are using ciphers like 2443 RC4 that has no blocking and so the function will not write 2444 anything into 'out', it would still be a good idea to pass a 2445 variable for 'out' that can hold 8 bytes just in case the cipher is 2446 changed some time in the future. It should also be remembered 2447 that the EVP_CIPHER_CTX contains the password and so when one has 2448 finished encryption with a particular EVP_CIPHER_CTX, it is good 2449 practice to zero the structure 2450 (ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)). 2451 2452void EVP_DecryptInit( 2453EVP_CIPHER_CTX *ctx, 2454EVP_CIPHER *type, 2455unsigned char *key, 2456unsigned char *iv); 2457 This function is basically the same as EVP_EncryptInit() accept that 2458 is prepares the EVP_CIPHER_CTX for decryption. 2459 2460void EVP_DecryptUpdate( 2461EVP_CIPHER_CTX *ctx, 2462unsigned char *out, 2463int *outl, 2464unsigned char *in, 2465int inl); 2466 This function is basically the same as EVP_EncryptUpdate() 2467 except that it performs decryption. There is one 2468 fundamental difference though. 'out' can not be the same as 2469 'in' for any ciphers with a block size greater than 1 if more 2470 than one call to EVP_DecryptUpdate() will be made. This 2471 is because this routine can hold a 'partial' block between 2472 calls. When a partial block is decrypted (due to more bytes 2473 being passed via this function, they will be written to 'out' 2474 overwriting the input bytes in 'in' that have not been read 2475 yet. From this it should also be noted that 'out' should 2476 be at least one 'block size' larger than 'inl'. This problem 2477 only occurs on the second and subsequent call to 2478 EVP_DecryptUpdate() when using a block cipher. 2479 2480int EVP_DecryptFinal( 2481EVP_CIPHER_CTX *ctx, 2482unsigned char *out, 2483int *outl); 2484 This function is different to EVP_EncryptFinal in that it 'removes' 2485 any padding bytes appended when the data was encrypted. Due to the 2486 way in which 1 to 8 bytes may have been appended when encryption 2487 using a block cipher, 'out' can end up with 0 to 7 bytes being put 2488 into it. When decoding the padding bytes, it is possible to detect 2489 an incorrect decryption. If the decryption appears to be wrong, 0 2490 is returned. If everything seems ok, 1 is returned. For ciphers 2491 with a block size of 1 (RC4), this function would normally not 2492 return any bytes and would always return 1. Just because this 2493 function returns 1 does not mean the decryption was correct. It 2494 would normally be wrong due to either the wrong key/iv or 2495 corruption of the cipher data fed to EVP_DecryptUpdate(). 2496 As for EVP_EncryptFinal, it is a good idea to zero the 2497 EVP_CIPHER_CTX after use since the structure contains the key used 2498 to decrypt the data. 2499 2500The following Cipher routines are convenience routines that call either 2501EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX 2502was setup to encrypt or decrypt. 2503 2504void EVP_CipherInit( 2505EVP_CIPHER_CTX *ctx, 2506EVP_CIPHER *type, 2507unsigned char *key, 2508unsigned char *iv, 2509int enc); 2510 This function take arguments that are the same as EVP_EncryptInit() 2511 and EVP_DecryptInit() except for the extra 'enc' flag. If 1, the 2512 EVP_CIPHER_CTX is setup for encryption, if 0, decryption. 2513 2514void EVP_CipherUpdate( 2515EVP_CIPHER_CTX *ctx, 2516unsigned char *out, 2517int *outl, 2518unsigned char *in, 2519int inl); 2520 Again this function calls either EVP_EncryptUpdate() or 2521 EVP_DecryptUpdate() depending on state in the 'ctx' structure. 2522 As noted for EVP_DecryptUpdate(), when this routine is used 2523 for decryption with block ciphers, 'out' should not be the 2524 same as 'in'. 2525 2526int EVP_CipherFinal( 2527EVP_CIPHER_CTX *ctx, 2528unsigned char *outm, 2529int *outl); 2530 This routine call EVP_EncryptFinal() or EVP_DecryptFinal() 2531 depending on the state information in 'ctx'. 1 is always returned 2532 if the mode is encryption, otherwise the return value is the return 2533 value of EVP_DecryptFinal(). 2534 2535==== cipher.m ======================================================== 2536 2537Date: Tue, 15 Oct 1996 08:16:14 +1000 (EST) 2538From: Eric Young <eay@mincom.com> 2539X-Sender: eay@orb 2540To: Roland Haring <rharing@tandem.cl> 2541Cc: ssl-users@mincom.com 2542Subject: Re: Symmetric encryption with ssleay 2543In-Reply-To: <m0vBpyq-00001aC@tandemnet.tandem.cl> 2544Message-Id: <Pine.SOL.3.91.961015075623.11394A-100000@orb> 2545Mime-Version: 1.0 2546Content-Type: TEXT/PLAIN; charset=US-ASCII 2547Sender: ssl-lists-owner@mincom.com 2548Precedence: bulk 2549Status: RO 2550X-Status: 2551 2552On Fri, 11 Oct 1996, Roland Haring wrote: 2553> THE_POINT: 2554> Would somebody be so kind to give me the minimum basic 2555> calls I need to do to libcrypto.a to get some text encrypted 2556> and decrypted again? ...hopefully with code included to do 2557> base64 encryption and decryption ... e.g. that sign-it.c code 2558> posted some while ago was a big help :-) (please, do not point 2559> me to apps/enc.c where I suspect my Heissenbug to be hidden :-) 2560 2561Ok, the base64 encoding stuff in 'enc.c' does the wrong thing sometimes 2562when the data is less than a line long (this is for decoding). I'll dig 2563up the exact fix today and post it. I am taking longer on 0.6.5 than I 2564intended so I'll just post this patch. 2565 2566The documentation to read is in 2567doc/cipher.doc, 2568doc/encode.doc (very sparse :-). 2569and perhaps 2570doc/digest.doc, 2571 2572The basic calls to encrypt with say triple DES are 2573 2574Given 2575char key[EVP_MAX_KEY_LENGTH]; 2576char iv[EVP_MAX_IV_LENGTH]; 2577EVP_CIPHER_CTX ctx; 2578unsigned char out[512+8]; 2579int outl; 2580 2581/* optional generation of key/iv data from text password using md5 2582 * via an upward compatable verson of PKCS#5. */ 2583EVP_BytesToKey(EVP_des_ede3_cbc,EVP_md5,NULL,passwd,strlen(passwd), 2584 key,iv); 2585 2586/* Initalise the EVP_CIPHER_CTX */ 2587EVP_EncryptInit(ctx,EVP_des_ede3_cbc,key,iv); 2588 2589while (....) 2590 { 2591 /* This is processing 512 bytes at a time, the bytes are being 2592 * copied into 'out', outl bytes are output. 'out' should not be the 2593 * same as 'in' for reasons mentioned in the documentation. */ 2594 EVP_EncryptUpdate(ctx,out,&outl,in,512); 2595 } 2596 2597/* Output the last 'block'. If the cipher is a block cipher, the last 2598 * block is encoded in such a way so that a wrong decryption will normally be 2599 * detected - again, one of the PKCS standards. */ 2600 2601EVP_EncryptFinal(ctx,out,&outl); 2602 2603To decrypt, use the EVP_DecryptXXXXX functions except that EVP_DecryptFinal() 2604will return 0 if the decryption fails (only detectable on block ciphers). 2605 2606You can also use 2607EVP_CipherInit() 2608EVP_CipherUpdate() 2609EVP_CipherFinal() 2610which does either encryption or decryption depending on an extra 2611parameter to EVP_CipherInit(). 2612 2613 2614To do the base64 encoding, 2615EVP_EncodeInit() 2616EVP_EncodeUpdate() 2617EVP_EncodeFinal() 2618 2619EVP_DecodeInit() 2620EVP_DecodeUpdate() 2621EVP_DecodeFinal() 2622 2623where the encoding is quite simple, but the decoding can be a bit more 2624fun (due to dud input). 2625 2626EVP_DecodeUpdate() returns -1 for an error on an input line, 0 if the 2627'last line' was just processed, and 1 if more lines should be submitted. 2628 2629EVP_DecodeFinal() returns -1 for an error or 1 if things are ok. 2630 2631So the loop becomes 2632EVP_DecodeInit(....) 2633for (;;) 2634 { 2635 i=EVP_DecodeUpdate(....); 2636 if (i < 0) goto err; 2637 2638 /* process the data */ 2639 2640 if (i == 0) break; 2641 } 2642EVP_DecodeFinal(....); 2643/* process the data */ 2644 2645The problem in 'enc.c' is that I was stuff the processing up after the 2646EVP_DecodeFinal(...) when the for(..) loop was not being run (one line of 2647base64 data) and this was because 'enc.c' tries to scan over a file until 2648it hits the first valid base64 encoded line. 2649 2650hope this helps a bit. 2651eric 2652-- 2653Eric Young | BOOL is tri-state according to Bill Gates. 2654AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). 2655 2656==== conf.doc ======================================================== 2657 2658The CONF library. 2659 2660The CONF library is a simple set of routines that can be used to configure 2661programs. It is a superset of the genenv() function with some extra 2662structure. 2663 2664The library consists of 5 functions. 2665 2666LHASH *CONF_load(LHASH *config,char *file); 2667This function is called to load in a configuration file. Multiple 2668configuration files can be loaded, with each subsequent 'load' overwriting 2669any already defined 'variables'. If there is an error, NULL is returned. 2670If config is NULL, a new LHASH structure is created and returned, otherwise 2671the new data in the 'file' is loaded into the 'config' structure. 2672 2673void CONF_free(LHASH *config); 2674This function free()s the data in config. 2675 2676char *CONF_get_string(LHASH *config,char *section,char *name); 2677This function returns the string found in 'config' that corresponds to the 2678'section' and 'name' specified. Classes and the naming system used will be 2679discussed later in this document. If the variable is not defined, an NULL 2680is returned. 2681 2682long CONF_get_long(LHASH *config,char *section, char *name); 2683This function is the same as CONF_get_string() except that it converts the 2684string to an long and returns it. If variable is not a number or the 2685variable does not exist, 0 is returned. This is a little problematic but I 2686don't know of a simple way around it. 2687 2688STACK *CONF_get_section(LHASH *config, char *section); 2689This function returns a 'stack' of CONF_VALUE items that are all the 2690items defined in a particular section. DO NOT free() any of the 2691variable returned. They will disappear when CONF_free() is called. 2692 2693The 'lookup' model. 2694The configuration file is divided into 'sections'. Each section is started by 2695a line of the form '[ section ]'. All subsequent variable definitions are 2696of this section. A variable definition is a simple alpha-numeric name 2697followed by an '=' and then the data. A section or variable name can be 2698described by a regular expression of the following form '[A-Za-z0-9_]+'. 2699The value of the variable is the text after the '=' until the end of the 2700line, stripped of leading and trailing white space. 2701At this point I should mention that a '#' is a comment character, \ is the 2702escape character, and all three types of quote can be used to stop any 2703special interpretation of the data. 2704Now when the data is being loaded, variable expansion can occur. This is 2705done by expanding any $NAME sequences into the value represented by the 2706variable NAME. If the variable is not in the current section, the different 2707section can be specified by using the $SECTION::NAME form. The ${NAME} form 2708also works and is very useful for expanding variables inside strings. 2709 2710When a variable is looked up, there are 2 special section. 'default', which 2711is the initial section, and 'ENV' which is the processes environment 2712variables (accessed via getenv()). When a variable is looked up, it is 2713first 'matched' with it's section (if one was specified), if this fails, the 2714'default' section is matched. 2715If the 'lhash' variable passed was NULL, the environment is searched. 2716 2717Now why do we bother with sections? So we can have multiple programs using 2718the same configuration file, or multiple instances of the same program 2719using different variables. It also provides a nice mechanism to override 2720the processes environment variables (eg ENV::HOME=/tmp). If there is a 2721program specific variable missing, we can have default values. 2722Multiple configuration files can be loaded, with each new value clearing 2723any predefined values. A system config file can provide 'default' values, 2724and application/usr specific files can provide overriding values. 2725 2726Examples 2727 2728# This is a simple example 2729SSLEAY_HOME = /usr/local/ssl 2730ENV::PATH = $SSLEAY_HOME/bin:$PATH # override my path 2731 2732[X509] 2733cert_dir = $SSLEAY_HOME/certs # /usr/local/ssl/certs 2734 2735[SSL] 2736CIPHER = DES-EDE-MD5:RC4-MD5 2737USER_CERT = $HOME/${USER}di'r 5' # /home/eay/eaydir 5 2738USER_CERT = $HOME/\${USER}di\'r # /home/eay/${USER}di'r 2739USER_CERT = "$HOME/${US"ER}di\'r # $HOME/${USER}di'r 2740 2741TEST = 1234\ 27425678\ 27439ab # TEST=123456789ab 2744TTT = 1234\n\n # TTT=1234<nl><nl> 2745 2746 2747 2748==== des.doc ======================================================== 2749 2750The DES library. 2751 2752Please note that this library was originally written to operate with 2753eBones, a version of Kerberos that had had encryption removed when it left 2754the USA and then put back in. As such there are some routines that I will 2755advise not using but they are still in the library for historical reasons. 2756For all calls that have an 'input' and 'output' variables, they can be the 2757same. 2758 2759This library requires the inclusion of 'des.h'. 2760 2761All of the encryption functions take what is called a des_key_schedule as an 2762argument. A des_key_schedule is an expanded form of the des key. 2763A des_key is 8 bytes of odd parity, the type used to hold the key is a 2764des_cblock. A des_cblock is an array of 8 bytes, often in this library 2765description I will refer to input bytes when the function specifies 2766des_cblock's as input or output, this just means that the variable should 2767be a multiple of 8 bytes. 2768 2769The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to 2770specify decryption. The functions and global variable are as follows: 2771 2772int des_check_key; 2773 DES keys are supposed to be odd parity. If this variable is set to 2774 a non-zero value, des_set_key() will check that the key has odd 2775 parity and is not one of the known weak DES keys. By default this 2776 variable is turned off; 2777 2778void des_set_odd_parity( 2779des_cblock *key ); 2780 This function takes a DES key (8 bytes) and sets the parity to odd. 2781 2782int des_is_weak_key( 2783des_cblock *key ); 2784 This function returns a non-zero value if the DES key passed is a 2785 weak, DES key. If it is a weak key, don't use it, try a different 2786 one. If you are using 'random' keys, the chances of hitting a weak 2787 key are 1/2^52 so it is probably not worth checking for them. 2788 2789int des_set_key( 2790des_cblock *key, 2791des_key_schedule schedule); 2792 Des_set_key converts an 8 byte DES key into a des_key_schedule. 2793 A des_key_schedule is an expanded form of the key which is used to 2794 perform actual encryption. It can be regenerated from the DES key 2795 so it only needs to be kept when encryption or decryption is about 2796 to occur. Don't save or pass around des_key_schedule's since they 2797 are CPU architecture dependent, DES keys are not. If des_check_key 2798 is non zero, zero is returned if the key has the wrong parity or 2799 the key is a weak key, else 1 is returned. 2800 2801int des_key_sched( 2802des_cblock *key, 2803des_key_schedule schedule); 2804 An alternative name for des_set_key(). 2805 2806int des_rw_mode; /* defaults to DES_PCBC_MODE */ 2807 This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default). 2808 This specifies the function to use in the enc_read() and enc_write() 2809 functions. 2810 2811void des_encrypt( 2812unsigned long *data, 2813des_key_schedule ks, 2814int enc); 2815 This is the DES encryption function that gets called by just about 2816 every other DES routine in the library. You should not use this 2817 function except to implement 'modes' of DES. I say this because the 2818 functions that call this routine do the conversion from 'char *' to 2819 long, and this needs to be done to make sure 'non-aligned' memory 2820 access do not occur. The characters are loaded 'little endian', 2821 have a look at my source code for more details on how I use this 2822 function. 2823 Data is a pointer to 2 unsigned long's and ks is the 2824 des_key_schedule to use. enc, is non zero specifies encryption, 2825 zero if decryption. 2826 2827void des_encrypt2( 2828unsigned long *data, 2829des_key_schedule ks, 2830int enc); 2831 This functions is the same as des_encrypt() except that the DES 2832 initial permutation (IP) and final permutation (FP) have been left 2833 out. As for des_encrypt(), you should not use this function. 2834 It is used by the routines in my library that implement triple DES. 2835 IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same 2836 as des_encrypt() des_encrypt() des_encrypt() except faster :-). 2837 2838void des_ecb_encrypt( 2839des_cblock *input, 2840des_cblock *output, 2841des_key_schedule ks, 2842int enc); 2843 This is the basic Electronic Code Book form of DES, the most basic 2844 form. Input is encrypted into output using the key represented by 2845 ks. If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise 2846 decryption occurs. Input is 8 bytes long and output is 8 bytes. 2847 (the des_cblock structure is 8 chars). 2848 2849void des_ecb3_encrypt( 2850des_cblock *input, 2851des_cblock *output, 2852des_key_schedule ks1, 2853des_key_schedule ks2, 2854des_key_schedule ks3, 2855int enc); 2856 This is the 3 key EDE mode of ECB DES. What this means is that 2857 the 8 bytes of input is encrypted with ks1, decrypted with ks2 and 2858 then encrypted again with ks3, before being put into output; 2859 C=E(ks3,D(ks2,E(ks1,M))). There is a macro, des_ecb2_encrypt() 2860 that only takes 2 des_key_schedules that implements, 2861 C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1. 2862 2863void des_cbc_encrypt( 2864des_cblock *input, 2865des_cblock *output, 2866long length, 2867des_key_schedule ks, 2868des_cblock *ivec, 2869int enc); 2870 This routine implements DES in Cipher Block Chaining mode. 2871 Input, which should be a multiple of 8 bytes is encrypted 2872 (or decrypted) to output which will also be a multiple of 8 bytes. 2873 The number of bytes is in length (and from what I've said above, 2874 should be a multiple of 8). If length is not a multiple of 8, I'm 2875 not being held responsible :-). ivec is the initialisation vector. 2876 This function does not modify this variable. To correctly implement 2877 cbc mode, you need to do one of 2 things; copy the last 8 bytes of 2878 cipher text for use as the next ivec in your application, 2879 or use des_ncbc_encrypt(). 2880 Only this routine has this problem with updating the ivec, all 2881 other routines that are implementing cbc mode update ivec. 2882 2883void des_ncbc_encrypt( 2884des_cblock *input, 2885des_cblock *output, 2886long length, 2887des_key_schedule sk, 2888des_cblock *ivec, 2889int enc); 2890 For historical reasons, des_cbc_encrypt() did not update the 2891 ivec with the value requires so that subsequent calls to 2892 des_cbc_encrypt() would 'chain'. This was needed so that the same 2893 'length' values would not need to be used when decrypting. 2894 des_ncbc_encrypt() does the right thing. It is the same as 2895 des_cbc_encrypt accept that ivec is updates with the correct value 2896 to pass in subsequent calls to des_ncbc_encrypt(). I advise using 2897 des_ncbc_encrypt() instead of des_cbc_encrypt(); 2898 2899void des_xcbc_encrypt( 2900des_cblock *input, 2901des_cblock *output, 2902long length, 2903des_key_schedule sk, 2904des_cblock *ivec, 2905des_cblock *inw, 2906des_cblock *outw, 2907int enc); 2908 This is RSA's DESX mode of DES. It uses inw and outw to 2909 'whiten' the encryption. inw and outw are secret (unlike the iv) 2910 and are as such, part of the key. So the key is sort of 24 bytes. 2911 This is much better than cbc des. 2912 2913void des_3cbc_encrypt( 2914des_cblock *input, 2915des_cblock *output, 2916long length, 2917des_key_schedule sk1, 2918des_key_schedule sk2, 2919des_cblock *ivec1, 2920des_cblock *ivec2, 2921int enc); 2922 This function is flawed, do not use it. I have left it in the 2923 library because it is used in my des(1) program and will function 2924 correctly when used by des(1). If I removed the function, people 2925 could end up unable to decrypt files. 2926 This routine implements outer triple cbc encryption using 2 ks and 2927 2 ivec's. Use des_ede2_cbc_encrypt() instead. 2928 2929void des_ede3_cbc_encrypt( 2930des_cblock *input, 2931des_cblock *output, 2932long length, 2933des_key_schedule ks1, 2934des_key_schedule ks2, 2935des_key_schedule ks3, 2936des_cblock *ivec, 2937int enc); 2938 This function implements outer triple CBC DES encryption with 3 2939 keys. What this means is that each 'DES' operation 2940 inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))). 2941 Again, this is cbc mode so an ivec is requires. 2942 This mode is used by SSL. 2943 There is also a des_ede2_cbc_encrypt() that only uses 2 2944 des_key_schedule's, the first being reused for the final 2945 encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of triple DES 2946 is used by the RSAref library. 2947 2948void des_pcbc_encrypt( 2949des_cblock *input, 2950des_cblock *output, 2951long length, 2952des_key_schedule ks, 2953des_cblock *ivec, 2954int enc); 2955 This is Propagating Cipher Block Chaining mode of DES. It is used 2956 by Kerberos v4. It's parameters are the same as des_ncbc_encrypt(). 2957 2958void des_cfb_encrypt( 2959unsigned char *in, 2960unsigned char *out, 2961int numbits, 2962long length, 2963des_key_schedule ks, 2964des_cblock *ivec, 2965int enc); 2966 Cipher Feedback Back mode of DES. This implementation 'feeds back' 2967 in numbit blocks. The input (and output) is in multiples of numbits 2968 bits. numbits should to be a multiple of 8 bits. Length is the 2969 number of bytes input. If numbits is not a multiple of 8 bits, 2970 the extra bits in the bytes will be considered padding. So if 2971 numbits is 12, for each 2 input bytes, the 4 high bits of the 2972 second byte will be ignored. So to encode 72 bits when using 2973 a numbits of 12 take 12 bytes. To encode 72 bits when using 2974 numbits of 9 will take 16 bytes. To encode 80 bits when using 2975 numbits of 16 will take 10 bytes. etc, etc. This padding will 2976 apply to both input and output. 2977 2978 2979void des_cfb64_encrypt( 2980unsigned char *in, 2981unsigned char *out, 2982long length, 2983des_key_schedule ks, 2984des_cblock *ivec, 2985int *num, 2986int enc); 2987 This is one of the more useful functions in this DES library, it 2988 implements CFB mode of DES with 64bit feedback. Why is this 2989 useful you ask? Because this routine will allow you to encrypt an 2990 arbitrary number of bytes, no 8 byte padding. Each call to this 2991 routine will encrypt the input bytes to output and then update ivec 2992 and num. num contains 'how far' we are though ivec. If this does 2993 not make much sense, read more about cfb mode of DES :-). 2994 2995void des_ede3_cfb64_encrypt( 2996unsigned char *in, 2997unsigned char *out, 2998long length, 2999des_key_schedule ks1, 3000des_key_schedule ks2, 3001des_key_schedule ks3, 3002des_cblock *ivec, 3003int *num, 3004int enc); 3005 Same as des_cfb64_encrypt() accept that the DES operation is 3006 triple DES. As usual, there is a macro for 3007 des_ede2_cfb64_encrypt() which reuses ks1. 3008 3009void des_ofb_encrypt( 3010unsigned char *in, 3011unsigned char *out, 3012int numbits, 3013long length, 3014des_key_schedule ks, 3015des_cblock *ivec); 3016 This is a implementation of Output Feed Back mode of DES. It is 3017 the same as des_cfb_encrypt() in that numbits is the size of the 3018 units dealt with during input and output (in bits). 3019 3020void des_ofb64_encrypt( 3021unsigned char *in, 3022unsigned char *out, 3023long length, 3024des_key_schedule ks, 3025des_cblock *ivec, 3026int *num); 3027 The same as des_cfb64_encrypt() except that it is Output Feed Back 3028 mode. 3029 3030void des_ede3_ofb64_encrypt( 3031unsigned char *in, 3032unsigned char *out, 3033long length, 3034des_key_schedule ks1, 3035des_key_schedule ks2, 3036des_key_schedule ks3, 3037des_cblock *ivec, 3038int *num); 3039 Same as des_ofb64_encrypt() accept that the DES operation is 3040 triple DES. As usual, there is a macro for 3041 des_ede2_ofb64_encrypt() which reuses ks1. 3042 3043int des_read_pw_string( 3044char *buf, 3045int length, 3046char *prompt, 3047int verify); 3048 This routine is used to get a password from the terminal with echo 3049 turned off. Buf is where the string will end up and length is the 3050 size of buf. Prompt is a string presented to the 'user' and if 3051 verify is set, the key is asked for twice and unless the 2 copies 3052 match, an error is returned. A return code of -1 indicates a 3053 system error, 1 failure due to use interaction, and 0 is success. 3054 3055unsigned long des_cbc_cksum( 3056des_cblock *input, 3057des_cblock *output, 3058long length, 3059des_key_schedule ks, 3060des_cblock *ivec); 3061 This function produces an 8 byte checksum from input that it puts in 3062 output and returns the last 4 bytes as a long. The checksum is 3063 generated via cbc mode of DES in which only the last 8 byes are 3064 kept. I would recommend not using this function but instead using 3065 the EVP_Digest routines, or at least using MD5 or SHA. This 3066 function is used by Kerberos v4 so that is why it stays in the 3067 library. 3068 3069char *des_fcrypt( 3070const char *buf, 3071const char *salt 3072char *ret); 3073 This is my fast version of the unix crypt(3) function. This version 3074 takes only a small amount of space relative to other fast 3075 crypt() implementations. This is different to the normal crypt 3076 in that the third parameter is the buffer that the return value 3077 is written into. It needs to be at least 14 bytes long. This 3078 function is thread safe, unlike the normal crypt. 3079 3080char *crypt( 3081const char *buf, 3082const char *salt); 3083 This function calls des_fcrypt() with a static array passed as the 3084 third parameter. This emulates the normal non-thread safe semantics 3085 of crypt(3). 3086 3087void des_string_to_key( 3088char *str, 3089des_cblock *key); 3090 This function takes str and converts it into a DES key. I would 3091 recommend using MD5 instead and use the first 8 bytes of output. 3092 When I wrote the first version of these routines back in 1990, MD5 3093 did not exist but I feel these routines are still sound. This 3094 routines is compatible with the one in MIT's libdes. 3095 3096void des_string_to_2keys( 3097char *str, 3098des_cblock *key1, 3099des_cblock *key2); 3100 This function takes str and converts it into 2 DES keys. 3101 I would recommend using MD5 and using the 16 bytes as the 2 keys. 3102 I have nothing against these 2 'string_to_key' routines, it's just 3103 that if you say that your encryption key is generated by using the 3104 16 bytes of an MD5 hash, every-one knows how you generated your 3105 keys. 3106 3107int des_read_password( 3108des_cblock *key, 3109char *prompt, 3110int verify); 3111 This routine combines des_read_pw_string() with des_string_to_key(). 3112 3113int des_read_2passwords( 3114des_cblock *key1, 3115des_cblock *key2, 3116char *prompt, 3117int verify); 3118 This routine combines des_read_pw_string() with des_string_to_2key(). 3119 3120void des_random_seed( 3121des_cblock key); 3122 This routine sets a starting point for des_random_key(). 3123 3124void des_random_key( 3125des_cblock ret); 3126 This function return a random key. Make sure to 'seed' the random 3127 number generator (with des_random_seed()) before using this function. 3128 I personally now use a MD5 based random number system. 3129 3130int des_enc_read( 3131int fd, 3132char *buf, 3133int len, 3134des_key_schedule ks, 3135des_cblock *iv); 3136 This function will write to a file descriptor the encrypted data 3137 from buf. This data will be preceded by a 4 byte 'byte count' and 3138 will be padded out to 8 bytes. The encryption is either CBC of 3139 PCBC depending on the value of des_rw_mode. If it is DES_PCBC_MODE, 3140 pcbc is used, if DES_CBC_MODE, cbc is used. The default is to use 3141 DES_PCBC_MODE. 3142 3143int des_enc_write( 3144int fd, 3145char *buf, 3146int len, 3147des_key_schedule ks, 3148des_cblock *iv); 3149 This routines read stuff written by des_enc_read() and decrypts it. 3150 I have used these routines quite a lot but I don't believe they are 3151 suitable for non-blocking io. If you are after a full 3152 authentication/encryption over networks, have a look at SSL instead. 3153 3154unsigned long des_quad_cksum( 3155des_cblock *input, 3156des_cblock *output, 3157long length, 3158int out_count, 3159des_cblock *seed); 3160 This is a function from Kerberos v4 that is not anything to do with 3161 DES but was needed. It is a cksum that is quicker to generate than 3162 des_cbc_cksum(); I personally would use MD5 routines now. 3163===== 3164Modes of DES 3165Quite a bit of the following information has been taken from 3166 AS 2805.5.2 3167 Australian Standard 3168 Electronic funds transfer - Requirements for interfaces, 3169 Part 5.2: Modes of operation for an n-bit block cipher algorithm 3170 Appendix A 3171 3172There are several different modes in which DES can be used, they are 3173as follows. 3174 3175Electronic Codebook Mode (ECB) (des_ecb_encrypt()) 3176- 64 bits are enciphered at a time. 3177- The order of the blocks can be rearranged without detection. 3178- The same plaintext block always produces the same ciphertext block 3179 (for the same key) making it vulnerable to a 'dictionary attack'. 3180- An error will only affect one ciphertext block. 3181 3182Cipher Block Chaining Mode (CBC) (des_cbc_encrypt()) 3183- a multiple of 64 bits are enciphered at a time. 3184- The CBC mode produces the same ciphertext whenever the same 3185 plaintext is encrypted using the same key and starting variable. 3186- The chaining operation makes the ciphertext blocks dependent on the 3187 current and all preceding plaintext blocks and therefore blocks can not 3188 be rearranged. 3189- The use of different starting variables prevents the same plaintext 3190 enciphering to the same ciphertext. 3191- An error will affect the current and the following ciphertext blocks. 3192 3193Cipher Feedback Mode (CFB) (des_cfb_encrypt()) 3194- a number of bits (j) <= 64 are enciphered at a time. 3195- The CFB mode produces the same ciphertext whenever the same 3196 plaintext is encrypted using the same key and starting variable. 3197- The chaining operation makes the ciphertext variables dependent on the 3198 current and all preceding variables and therefore j-bit variables are 3199 chained together and can not be rearranged. 3200- The use of different starting variables prevents the same plaintext 3201 enciphering to the same ciphertext. 3202- The strength of the CFB mode depends on the size of k (maximal if 3203 j == k). In my implementation this is always the case. 3204- Selection of a small value for j will require more cycles through 3205 the encipherment algorithm per unit of plaintext and thus cause 3206 greater processing overheads. 3207- Only multiples of j bits can be enciphered. 3208- An error will affect the current and the following ciphertext variables. 3209 3210Output Feedback Mode (OFB) (des_ofb_encrypt()) 3211- a number of bits (j) <= 64 are enciphered at a time. 3212- The OFB mode produces the same ciphertext whenever the same 3213 plaintext enciphered using the same key and starting variable. More 3214 over, in the OFB mode the same key stream is produced when the same 3215 key and start variable are used. Consequently, for security reasons 3216 a specific start variable should be used only once for a given key. 3217- The absence of chaining makes the OFB more vulnerable to specific attacks. 3218- The use of different start variables values prevents the same 3219 plaintext enciphering to the same ciphertext, by producing different 3220 key streams. 3221- Selection of a small value for j will require more cycles through 3222 the encipherment algorithm per unit of plaintext and thus cause 3223 greater processing overheads. 3224- Only multiples of j bits can be enciphered. 3225- OFB mode of operation does not extend ciphertext errors in the 3226 resultant plaintext output. Every bit error in the ciphertext causes 3227 only one bit to be in error in the deciphered plaintext. 3228- OFB mode is not self-synchronising. If the two operation of 3229 encipherment and decipherment get out of synchronism, the system needs 3230 to be re-initialised. 3231- Each re-initialisation should use a value of the start variable 3232 different from the start variable values used before with the same 3233 key. The reason for this is that an identical bit stream would be 3234 produced each time from the same parameters. This would be 3235 susceptible to a ' known plaintext' attack. 3236 3237Triple ECB Mode (des_ecb3_encrypt()) 3238- Encrypt with key1, decrypt with key2 and encrypt with key3 again. 3239- As for ECB encryption but increases the key length to 168 bits. 3240 There are theoretic attacks that can be used that make the effective 3241 key length 112 bits, but this attack also requires 2^56 blocks of 3242 memory, not very likely, even for the NSA. 3243- If both keys are the same it is equivalent to encrypting once with 3244 just one key. 3245- If the first and last key are the same, the key length is 112 bits. 3246 There are attacks that could reduce the key space to 55 bit's but it 3247 requires 2^56 blocks of memory. 3248- If all 3 keys are the same, this is effectively the same as normal 3249 ecb mode. 3250 3251Triple CBC Mode (des_ede3_cbc_encrypt()) 3252- Encrypt with key1, decrypt with key2 and then encrypt with key3. 3253- As for CBC encryption but increases the key length to 168 bits with 3254 the same restrictions as for triple ecb mode. 3255 3256==== digest.doc ======================================================== 3257 3258 3259The Message Digest subroutines. 3260 3261These routines require "evp.h" to be included. 3262 3263These functions are a higher level interface to the various message digest 3264routines found in this library. As such, they allow the same code to be 3265used to digest via different algorithms with only a change in an initial 3266parameter. They are basically just a front-end to the MD2, MD5, SHA 3267and SHA1 3268routines. 3269 3270These routines all take a pointer to the following structure to specify 3271which message digest algorithm to use. 3272typedef struct evp_md_st 3273 { 3274 int type; 3275 int pkey_type; 3276 int md_size; 3277 void (*init)(); 3278 void (*update)(); 3279 void (*final)(); 3280 3281 int required_pkey_type; /*EVP_PKEY_xxx */ 3282 int (*sign)(); 3283 int (*verify)(); 3284 } EVP_MD; 3285 3286If additional message digest algorithms are to be supported, a structure of 3287this type needs to be declared and populated and then the Digest routines 3288can be used with that algorithm. The type field is the object NID of the 3289digest type (read the section on Objects for an explanation). The pkey_type 3290is the Object type to use when the a message digest is generated by there 3291routines and then is to be signed with the pkey algorithm. Md_size is 3292the size of the message digest returned. Init, update 3293and final are the relevant functions to perform the message digest function 3294by parts. One reason for specifying the message digest to use via this 3295mechanism is that if you only use md5, only the md5 routines will 3296be included in you linked program. If you passed an integer 3297that specified which message digest to use, the routine that mapped that 3298integer to a set of message digest functions would cause all the message 3299digests functions to be link into the code. This setup also allows new 3300message digest functions to be added by the application. 3301 3302The six message digests defined in this library are 3303 3304EVP_MD *EVP_md2(void); /* RSA sign/verify */ 3305EVP_MD *EVP_md5(void); /* RSA sign/verify */ 3306EVP_MD *EVP_sha(void); /* RSA sign/verify */ 3307EVP_MD *EVP_sha1(void); /* RSA sign/verify */ 3308EVP_MD *EVP_dss(void); /* DSA sign/verify */ 3309EVP_MD *EVP_dss1(void); /* DSA sign/verify */ 3310 3311All the message digest routines take a EVP_MD_CTX pointer as an argument. 3312The state of the message digest is kept in this structure. 3313 3314typedef struct pem_md_ctx_st 3315 { 3316 EVP_MD *digest; 3317 union { 3318 unsigned char base[4]; /* this is used in my library as a 3319 * 'pointer' to all union elements 3320 * structures. */ 3321 MD2_CTX md2; 3322 MD5_CTX md5; 3323 SHA_CTX sha; 3324 } md; 3325 } EVP_MD_CTX; 3326 3327The Digest functions are as follows. 3328 3329void EVP_DigestInit( 3330EVP_MD_CTX *ctx, 3331EVP_MD *type); 3332 This function is used to initialise the EVP_MD_CTX. The message 3333 digest that will associated with 'ctx' is specified by 'type'. 3334 3335void EVP_DigestUpdate( 3336EVP_MD_CTX *ctx, 3337unsigned char *data, 3338unsigned int cnt); 3339 This function is used to pass more data to the message digest 3340 function. 'cnt' bytes are digested from 'data'. 3341 3342void EVP_DigestFinal( 3343EVP_MD_CTX *ctx, 3344unsigned char *md, 3345unsigned int *len); 3346 This function finishes the digestion and puts the message digest 3347 into 'md'. The length of the message digest is put into len; 3348 EVP_MAX_MD_SIZE is the size of the largest message digest that 3349 can be returned from this function. Len can be NULL if the 3350 size of the digest is not required. 3351 3352 3353==== encode.doc ======================================================== 3354 3355 3356void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); 3357void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out, 3358 int *outl,unsigned char *in,int inl); 3359void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl); 3360int EVP_EncodeBlock(unsigned char *t, unsigned char *f, int n); 3361 3362void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); 3363int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl, 3364 unsigned char *in, int inl); 3365int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned 3366 char *out, int *outl); 3367int EVP_DecodeBlock(unsigned char *t, unsigned 3368 char *f, int n); 3369 3370 3371==== envelope.doc ======================================================== 3372 3373The following routines are use to create 'digital' envelopes. 3374By this I mean that they perform various 'higher' level cryptographic 3375functions. Have a read of 'cipher.doc' and 'digest.doc' since those 3376routines are used by these functions. 3377cipher.doc contains documentation about the cipher part of the 3378envelope library and digest.doc contatins the description of the 3379message digests supported. 3380 3381To 'sign' a document involves generating a message digest and then encrypting 3382the digest with an private key. 3383 3384#define EVP_SignInit(a,b) EVP_DigestInit(a,b) 3385#define EVP_SignUpdate(a,b,c) EVP_DigestUpdate(a,b,c) 3386Due to the fact this operation is basically just an extended message 3387digest, the first 2 functions are macro calls to Digest generating 3388functions. 3389 3390int EVP_SignFinal( 3391EVP_MD_CTX *ctx, 3392unsigned char *md, 3393unsigned int *s, 3394EVP_PKEY *pkey); 3395 This finalisation function finishes the generation of the message 3396digest and then encrypts the digest (with the correct message digest 3397object identifier) with the EVP_PKEY private key. 'ctx' is the message digest 3398context. 'md' will end up containing the encrypted message digest. This 3399array needs to be EVP_PKEY_size(pkey) bytes long. 's' will actually 3400contain the exact length. 'pkey' of course is the private key. It is 3401one of EVP_PKEY_RSA or EVP_PKEY_DSA type. 3402If there is an error, 0 is returned, otherwise 1. 3403 3404Verify is used to check an signed message digest. 3405 3406#define EVP_VerifyInit(a,b) EVP_DigestInit(a,b) 3407#define EVP_VerifyUpdate(a,b,c) EVP_DigestUpdate(a,b,c) 3408Since the first step is to generate a message digest, the first 2 functions 3409are macros. 3410 3411int EVP_VerifyFinal( 3412EVP_MD_CTX *ctx, 3413unsigned char *md, 3414unsigned int s, 3415EVP_PKEY *pkey); 3416 This function finishes the generation of the message digest and then 3417compares it with the supplied encrypted message digest. 'md' contains the 3418's' bytes of encrypted message digest. 'pkey' is used to public key decrypt 3419the digest. It is then compared with the message digest just generated. 3420If they match, 1 is returned else 0. 3421 3422int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek, 3423 int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk); 3424Must have at least one public key, error is 0. I should also mention that 3425the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size. 3426 3427#define EVP_SealUpdate(a,b,c,d,e) EVP_EncryptUpdate(a,b,c,d,e) 3428void EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl); 3429 3430 3431int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek, 3432 int ekl,unsigned char *iv,EVP_PKEY *priv); 34330 on failure 3434 3435#define EVP_OpenUpdate(a,b,c,d,e) EVP_DecryptUpdate(a,b,c,d,e) 3436 3437int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); 3438Decrypt final return code 3439 3440 3441==== error.doc ======================================================== 3442 3443The error routines. 3444 3445The 'error' system I've implemented is intended to server 2 purpose, to 3446record the reason why a command failed and to record where in the libraries 3447the failure occurred. It is more or less setup to record a 'trace' of which 3448library components were being traversed when the error occurred. 3449 3450When an error is recorded, it is done so a as single unsigned long which is 3451composed of three parts. The top byte is the 'library' number, the middle 345212 bytes is the function code, and the bottom 12 bits is the 'reason' code. 3453 3454Each 'library', or should a say, 'section' of the SSLeay library has a 3455different unique 'library' error number. Each function in the library has 3456a number that is unique for that library. Each 'library' also has a number 3457for each 'error reason' that is only unique for that 'library'. 3458 3459Due to the way these error routines record a 'error trace', there is an 3460array per thread that is used to store the error codes. 3461The various functions in this library are used to access 3462and manipulate this array. 3463 3464void ERR_put_error(int lib, int func,int reason); 3465 This routine records an error in library 'lib', function 'func' 3466and reason 'reason'. As errors get 'put' into the buffer, they wrap 3467around and overwrite old errors if too many are written. It is assumed 3468that the last errors are the most important. 3469 3470unsigned long ERR_get_error(void ); 3471 This function returns the last error added to the error buffer. 3472In effect it is popping the value off the buffer so repeated calls will 3473continue to return values until there are no more errors to return in which 3474case 0 is returned. 3475 3476unsigned long ERR_peek_error(void ); 3477 This function returns the value of the last error added to the 3478error buffer but does not 'pop' it from the buffer. 3479 3480void ERR_clear_error(void ); 3481 This function clears the error buffer, discarding all unread 3482errors. 3483 3484While the above described error system obviously produces lots of different 3485error number, a method for 'reporting' these errors in a human readable 3486form is required. To achieve this, each library has the option of 3487'registering' error strings. 3488 3489typedef struct ERR_string_data_st 3490 { 3491 unsigned long error; 3492 char *string; 3493 } ERR_STRING_DATA; 3494 3495The 'ERR_STRING_DATA' contains an error code and the corresponding text 3496string. To add new function error strings for a library, the 3497ERR_STRING_DATA needs to be 'registered' with the library. 3498 3499void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err); 3500 This function 'registers' the array of ERR_STRING_DATA pointed to by 3501'err' as error text strings for the error library 'lib'. 3502 3503void ERR_free_strings(void); 3504 This function free()s all the loaded error strings. 3505 3506char *ERR_error_string(unsigned long error,char *buf); 3507 This function returns a text string that is a human readable 3508version of the error represented by 'error'. Buff should be at least 120 3509bytes long and if it is NULL, the return value is a pointer to a static 3510variable that will contain the error string, otherwise 'buf' is returned. 3511If there is not a text string registered for a particular error, a text 3512string containing the error number is returned instead. 3513 3514void ERR_print_errors(BIO *bp); 3515void ERR_print_errors_fp(FILE *fp); 3516 This function is a convenience routine that prints the error string 3517for each error until all errors have been accounted for. 3518 3519char *ERR_lib_error_string(unsigned long e); 3520char *ERR_func_error_string(unsigned long e); 3521char *ERR_reason_error_string(unsigned long e); 3522The above three functions return the 3 different components strings for the 3523error 'e'. ERR_error_string() uses these functions. 3524 3525void ERR_load_ERR_strings(void ); 3526 This function 'registers' the error strings for the 'ERR' module. 3527 3528void ERR_load_crypto_strings(void ); 3529 This function 'register' the error strings for just about every 3530library in the SSLeay package except for the SSL routines. There is no 3531need to ever register any error text strings and you will probably save in 3532program size. If on the other hand you do 'register' all errors, it is 3533quite easy to determine why a particular routine failed. 3534 3535As a final footnote as to why the error system is designed as it is. 35361) I did not want a single 'global' error code. 35372) I wanted to know which subroutine a failure occurred in. 35383) For Windows NT etc, it should be simple to replace the 'key' routines 3539 with code to pass error codes back to the application. 35404) I wanted the option of meaningful error text strings. 3541 3542Late breaking news - the changes to support threads. 3543 3544Each 'thread' has an 'ERR_STATE' state associated with it. 3545ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling 3546thread/process. 3547 3548ERR_remove_state(unsigned long pid); will 'free()' this state. If pid == 0 3549the current 'thread/process' will have it's error state removed. 3550If you do not remove the error state of a thread, this could be considered a 3551form of memory leak, so just after 'reaping' a thread that has died, 3552call ERR_remove_state(pid). 3553 3554Have a read of thread.doc for more details for what is required for 3555multi-threading support. All the other error routines will 3556work correctly when using threads. 3557 3558 3559==== idea.doc ======================================================== 3560 3561The IDEA library. 3562IDEA is a block cipher that operates on 64bit (8 byte) quantities. It 3563uses a 128bit (16 byte) key. It can be used in all the modes that DES can 3564be used. This library implements the ecb, cbc, cfb64 and ofb64 modes. 3565 3566For all calls that have an 'input' and 'output' variables, they can be the 3567same. 3568 3569This library requires the inclusion of 'idea.h'. 3570 3571All of the encryption functions take what is called an IDEA_KEY_SCHEDULE as an 3572argument. An IDEA_KEY_SCHEDULE is an expanded form of the idea key. 3573For all modes of the IDEA algorithm, the IDEA_KEY_SCHEDULE used for 3574decryption is different to the one used for encryption. 3575 3576The define IDEA_ENCRYPT is passed to specify encryption for the functions 3577that require an encryption/decryption flag. IDEA_DECRYPT is passed to 3578specify decryption. For some mode there is no encryption/decryption 3579flag since this is determined by the IDEA_KEY_SCHEDULE. 3580 3581So to encrypt you would do the following 3582idea_set_encrypt_key(key,encrypt_ks); 3583idea_ecb_encrypt(...,encrypt_ks); 3584idea_cbc_encrypt(....,encrypt_ks,...,IDEA_ENCRYPT); 3585 3586To Decrypt 3587idea_set_encrypt_key(key,encrypt_ks); 3588idea_set_decrypt_key(encrypt_ks,decrypt_ks); 3589idea_ecb_encrypt(...,decrypt_ks); 3590idea_cbc_encrypt(....,decrypt_ks,...,IDEA_DECRYPT); 3591 3592Please note that any of the encryption modes specified in my DES library 3593could be used with IDEA. I have only implemented ecb, cbc, cfb64 and 3594ofb64 for the following reasons. 3595- ecb is the basic IDEA encryption. 3596- cbc is the normal 'chaining' form for block ciphers. 3597- cfb64 can be used to encrypt single characters, therefore input and output 3598 do not need to be a multiple of 8. 3599- ofb64 is similar to cfb64 but is more like a stream cipher, not as 3600 secure (not cipher feedback) but it does not have an encrypt/decrypt mode. 3601- If you want triple IDEA, thats 384 bits of key and you must be totally 3602 obsessed with security. Still, if you want it, it is simple enough to 3603 copy the function from the DES library and change the des_encrypt to 3604 idea_encrypt; an exercise left for the paranoid reader :-). 3605 3606The functions are as follows: 3607 3608void idea_set_encrypt_key( 3609unsigned char *key; 3610IDEA_KEY_SCHEDULE *ks); 3611 idea_set_encrypt_key converts a 16 byte IDEA key into an 3612 IDEA_KEY_SCHEDULE. The IDEA_KEY_SCHEDULE is an expanded form of 3613 the key which can be used to perform IDEA encryption. 3614 An IDEA_KEY_SCHEDULE is an expanded form of the key which is used to 3615 perform actual encryption. It can be regenerated from the IDEA key 3616 so it only needs to be kept when encryption is about 3617 to occur. Don't save or pass around IDEA_KEY_SCHEDULE's since they 3618 are CPU architecture dependent, IDEA keys are not. 3619 3620void idea_set_decrypt_key( 3621IDEA_KEY_SCHEDULE *encrypt_ks, 3622IDEA_KEY_SCHEDULE *decrypt_ks); 3623 This functions converts an encryption IDEA_KEY_SCHEDULE into a 3624 decryption IDEA_KEY_SCHEDULE. For all decryption, this conversion 3625 of the key must be done. In some modes of IDEA, an 3626 encryption/decryption flag is also required, this is because these 3627 functions involve block chaining and the way this is done changes 3628 depending on which of encryption of decryption is being done. 3629 Please note that there is no quick way to generate the decryption 3630 key schedule other than generating the encryption key schedule and 3631 then converting it. 3632 3633void idea_encrypt( 3634unsigned long *data, 3635IDEA_KEY_SCHEDULE *ks); 3636 This is the IDEA encryption function that gets called by just about 3637 every other IDEA routine in the library. You should not use this 3638 function except to implement 'modes' of IDEA. I say this because the 3639 functions that call this routine do the conversion from 'char *' to 3640 long, and this needs to be done to make sure 'non-aligned' memory 3641 access do not occur. 3642 Data is a pointer to 2 unsigned long's and ks is the 3643 IDEA_KEY_SCHEDULE to use. Encryption or decryption depends on the 3644 IDEA_KEY_SCHEDULE. 3645 3646void idea_ecb_encrypt( 3647unsigned char *input, 3648unsigned char *output, 3649IDEA_KEY_SCHEDULE *ks); 3650 This is the basic Electronic Code Book form of IDEA (in DES this 3651 mode is called Electronic Code Book so I'm going to use the term 3652 for idea as well :-). 3653 Input is encrypted into output using the key represented by 3654 ks. Depending on the IDEA_KEY_SCHEDULE, encryption or 3655 decryption occurs. Input is 8 bytes long and output is 8 bytes. 3656 3657void idea_cbc_encrypt( 3658unsigned char *input, 3659unsigned char *output, 3660long length, 3661IDEA_KEY_SCHEDULE *ks, 3662unsigned char *ivec, 3663int enc); 3664 This routine implements IDEA in Cipher Block Chaining mode. 3665 Input, which should be a multiple of 8 bytes is encrypted 3666 (or decrypted) to output which will also be a multiple of 8 bytes. 3667 The number of bytes is in length (and from what I've said above, 3668 should be a multiple of 8). If length is not a multiple of 8, bad 3669 things will probably happen. ivec is the initialisation vector. 3670 This function updates iv after each call so that it can be passed to 3671 the next call to idea_cbc_encrypt(). 3672 3673void idea_cfb64_encrypt( 3674unsigned char *in, 3675unsigned char *out, 3676long length, 3677des_key_schedule ks, 3678des_cblock *ivec, 3679int *num, 3680int enc); 3681 This is one of the more useful functions in this IDEA library, it 3682 implements CFB mode of IDEA with 64bit feedback. 3683 This allows you to encrypt an arbitrary number of bytes, 3684 you do not require 8 byte padding. Each call to this 3685 routine will encrypt the input bytes to output and then update ivec 3686 and num. Num contains 'how far' we are though ivec. 3687 Enc is used to indicate encryption or decryption. 3688 One very important thing to remember is that when decrypting, use 3689 the encryption form of the key. 3690 CFB64 mode operates by using the cipher to 3691 generate a stream of bytes which is used to encrypt the plain text. 3692 The cipher text is then encrypted to generate the next 64 bits to 3693 be xored (incrementally) with the next 64 bits of plain 3694 text. As can be seen from this, to encrypt or decrypt, 3695 the same 'cipher stream' needs to be generated but the way the next 3696 block of data is gathered for encryption is different for 3697 encryption and decryption. What this means is that to encrypt 3698 idea_set_encrypt_key(key,ks); 3699 idea_cfb64_encrypt(...,ks,..,IDEA_ENCRYPT) 3700 do decrypt 3701 idea_set_encrypt_key(key,ks) 3702 idea_cfb64_encrypt(...,ks,...,IDEA_DECRYPT) 3703 Note: The same IDEA_KEY_SCHEDULE but different encryption flags. 3704 For idea_cbc or idea_ecb, idea_set_decrypt_key() would need to be 3705 used to generate the IDEA_KEY_SCHEDULE for decryption. 3706 The reason I'm stressing this point is that I just wasted 3 hours 3707 today trying to decrypt using this mode and the decryption form of 3708 the key :-(. 3709 3710void idea_ofb64_encrypt( 3711unsigned char *in, 3712unsigned char *out, 3713long length, 3714des_key_schedule ks, 3715des_cblock *ivec, 3716int *num); 3717 This functions implements OFB mode of IDEA with 64bit feedback. 3718 This allows you to encrypt an arbitrary number of bytes, 3719 you do not require 8 byte padding. Each call to this 3720 routine will encrypt the input bytes to output and then update ivec 3721 and num. Num contains 'how far' we are though ivec. 3722 This is in effect a stream cipher, there is no encryption or 3723 decryption mode. The same key and iv should be used to 3724 encrypt and decrypt. 3725 3726For reading passwords, I suggest using des_read_pw_string() from my DES library. 3727To generate a password from a text string, I suggest using MD5 (or MD2) to 3728produce a 16 byte message digest that can then be passed directly to 3729idea_set_encrypt_key(). 3730 3731===== 3732For more information about the specific IDEA modes in this library 3733(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the 3734documentation on my DES library. What is said about DES is directly 3735applicable for IDEA. 3736 3737 3738==== legal.doc ======================================================== 3739 3740From eay@mincom.com Thu Jun 27 00:25:45 1996 3741Received: by orb.mincom.oz.au id AA15821 3742 (5.65c/IDA-1.4.4 for eay); Wed, 26 Jun 1996 14:25:45 +1000 3743Date: Wed, 26 Jun 1996 14:25:45 +1000 (EST) 3744From: Eric Young <eay@mincom.oz.au> 3745X-Sender: eay@orb 3746To: Ken Toll <ktoll@ren.digitalage.com> 3747Cc: Eric Young <eay@mincom.oz.au>, ssl-talk@netscape.com 3748Subject: Re: Unidentified subject! 3749In-Reply-To: <9606261950.ZM28943@ren.digitalage.com> 3750Message-Id: <Pine.SOL.3.91.960626131156.28573K-100000@orb> 3751Mime-Version: 1.0 3752Content-Type: TEXT/PLAIN; charset=US-ASCII 3753Status: O 3754X-Status: 3755 3756 3757This is a little off topic but since SSLeay is a free implementation of 3758the SSLv2 protocol, I feel it is worth responding on the topic of if it 3759is actually legal for Americans to use free cryptographic software. 3760 3761On Wed, 26 Jun 1996, Ken Toll wrote: 3762> Is the U.S the only country that SSLeay cannot be used commercially 3763> (because of RSAref) or is that going to be an issue with every country 3764> that a client/server application (non-web browser/server) is deployed 3765> and sold? 3766 3767>From what I understand, the software patents that apply to algorithms 3768like RSA and DH only apply in the USA. The IDEA algorithm I believe is 3769patened in europe (USA?), but considing how little it is used by other SSL 3770implementations, it quite easily be left out of the SSLeay build 3771(this can be done with a compile flag). 3772 3773Actually if the RSA patent did apply outside the USA, it could be rather 3774interesting since RSA is not alowed to let RSA toolkits outside of the USA 3775[1], and since these are the only forms that they will alow the algorithm 3776to be used in, it would mean that non-one outside of the USA could produce 3777public key software which would be a very strong statment for 3778international patent law to make :-). This logic is a little flawed but 3779it still points out some of the more interesting permutations of USA 3780patent law and ITAR restrictions. 3781 3782Inside the USA there is also the unresolved issue of RC4/RC2 which were 3783made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2). I have 3784copies of the origional postings if people are interested. RSA I believe 3785claim that they were 'trade-secrets' and that some-one broke an NDA in 3786revealing them. Other claim they reverse engineered the algorithms from 3787compiled binaries. If the algorithms were reverse engineered, I belive 3788RSA had no legal leg to stand on. If an NDA was broken, I don't know. 3789Regardless, RSA, I belive, is willing to go to court over the issue so 3790licencing is probably the best idea, or at least talk to them. 3791If there are people who actually know more about this, pease let me know, I 3792don't want to vilify or spread miss-information if I can help it. 3793 3794If you are not producing a web browser, it is easy to build SSLeay with 3795RC2/RC4 removed. Since RC4 is the defacto standard cipher in 3796all web software (and it is damn fast) it is more or less required for 3797www use. For non www use of SSL, especially for an application where 3798interoperability with other vendors is not critical just leave it out. 3799 3800Removing IDEA, RC2 and RC4 would only leave DES and Triple DES but 3801they should be ok. Considing that Triple DES can encrypt at rates of 3802410k/sec on a pentium 100, and 940k/sec on a P6/200, this is quite 3803reasonable performance. Single DES clocks in at 1160k/s and 2467k/s 3804respectivly is actually quite fast for those not so paranoid (56 bit key).[1] 3805 3806> Is it possible to get a certificate for commercial use outside of the U.S.? 3807yes. 3808 3809Thawte Consulting issues certificates (they are the people who sell the 3810 Sioux httpd server and are based in South Africa) 3811Verisign will issue certificates for Sioux (sold from South Africa), so this 3812 proves that they will issue certificate for OS use if they are 3813 happy with the quality of the software. 3814 3815(The above mentioned companies just the ones that I know for sure are issuing 3816 certificates outside the USA). 3817 3818There is always the point that if you are using SSL for an intra net, 3819SSLeay provides programs that can be used so you can issue your own 3820certificates. They need polishing but at least it is a good starting point. 3821 3822I am not doing anything outside Australian law by implementing these 3823algorithms (to the best of my knowedge). It is another example of how 3824the world legal system does not cope with the internet very well. 3825 3826I may start making shared libraries available (I have now got DLL's for 3827Windows). This will mean that distributions into the usa could be 3828shipped with a version with a reduced cipher set and the versions outside 3829could use the DLL/shared library with all the ciphers (and without RSAref). 3830 3831This could be completly hidden from the application, so this would not 3832even require a re-linking. 3833 3834This is the reverse of what people were talking about doing to get around 3835USA export regulations :-) 3836 3837eric 3838 3839[1]: The RSAref2.0 tookit is available on at least 3 ftp sites in Europe 3840 and one in South Africa. 3841 3842[2]: Since I always get questions when I post benchmark numbers :-), 3843 DES performace figures are in 1000's of bytes per second in cbc 3844 mode using an 8192 byte buffer. The pentium 100 was running Windows NT 3845 3.51 DLLs and the 686/200 was running NextStep. 3846 I quote pentium 100 benchmarks because it is basically the 3847 'entry level' computer that most people buy for personal use. 3848 Windows 95 is the OS shipping on those boxes, so I'll give 3849 NT numbers (the same Win32 runtime environment). The 686 3850 numbers are present as an indication of where we will be in a 3851 few years. 3852-- 3853Eric Young | BOOL is tri-state according to Bill Gates. 3854AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). 3855 3856 3857 3858==== lhash.doc ======================================================== 3859 3860The LHASH library. 3861 3862I wrote this library in 1991 and have since forgotten why I called it lhash. 3863It implements a hash table from an article I read at the 3864time from 'Communications of the ACM'. What makes this hash 3865table different is that as the table fills, the hash table is 3866increased (or decreased) in size via realloc(). 3867When a 'resize' is done, instead of all hashes being redistributed over 3868twice as many 'buckets', one bucket is split. So when an 'expand' is done, 3869there is only a minimal cost to redistribute some values. Subsequent 3870inserts will cause more single 'bucket' redistributions but there will 3871never be a sudden large cost due to redistributing all the 'buckets'. 3872 3873The state for a particular hash table is kept in the LHASH structure. 3874The LHASH structure also records statistics about most aspects of accessing 3875the hash table. This is mostly a legacy of my writing this library for 3876the reasons of implementing what looked like a nice algorithm rather than 3877for a particular software product. 3878 3879Internal stuff you probably don't want to know about. 3880The decision to increase or decrease the hash table size is made depending 3881on the 'load' of the hash table. The load is the number of items in the 3882hash table divided by the size of the hash table. The default values are 3883as follows. If (hash->up_load < load) => expand. 3884if (hash->down_load > load) => contract. The 'up_load' has a default value of 38851 and 'down_load' has a default value of 2. These numbers can be modified 3886by the application by just playing with the 'up_load' and 'down_load' 3887variables. The 'load' is kept in a form which is multiplied by 256. So 3888hash->up_load=8*256; will cause a load of 8 to be set. 3889 3890If you are interested in performance the field to watch is 3891num_comp_calls. The hash library keeps track of the 'hash' value for 3892each item so when a lookup is done, the 'hashes' are compared, if 3893there is a match, then a full compare is done, and 3894hash->num_comp_calls is incremented. If num_comp_calls is not equal 3895to num_delete plus num_retrieve it means that your hash function is 3896generating hashes that are the same for different values. It is 3897probably worth changing your hash function if this is the case because 3898even if your hash table has 10 items in a 'bucked', it can be searched 3899with 10 'unsigned long' compares and 10 linked list traverses. This 3900will be much less expensive that 10 calls to you compare function. 3901 3902LHASH *lh_new( 3903unsigned long (*hash)(), 3904int (*cmp)()); 3905 This function is used to create a new LHASH structure. It is passed 3906 function pointers that are used to store and retrieve values passed 3907 into the hash table. The 'hash' 3908 function is a hashing function that will return a hashed value of 3909 it's passed structure. 'cmp' is passed 2 parameters, it returns 0 3910 is they are equal, otherwise, non zero. 3911 If there are any problems (usually malloc failures), NULL is 3912 returned, otherwise a new LHASH structure is returned. The 3913 hash value is normally truncated to a power of 2, so make sure 3914 that your hash function returns well mixed low order bits. 3915 3916void lh_free( 3917LHASH *lh); 3918 This function free()s a LHASH structure. If there is malloced 3919 data in the hash table, it will not be freed. Consider using the 3920 lh_doall function to deallocate any remaining entries in the hash 3921 table. 3922 3923char *lh_insert( 3924LHASH *lh, 3925char *data); 3926 This function inserts the data pointed to by data into the lh hash 3927 table. If there is already and entry in the hash table entry, the 3928 value being replaced is returned. A NULL is returned if the new 3929 entry does not clash with an entry already in the table (the normal 3930 case) or on a malloc() failure (perhaps I should change this....). 3931 The 'char *data' is exactly what is passed to the hash and 3932 comparison functions specified in lh_new(). 3933 3934char *lh_delete( 3935LHASH *lh, 3936char *data); 3937 This routine deletes an entry from the hash table. The value being 3938 deleted is returned. NULL is returned if there is no such value in 3939 the hash table. 3940 3941char *lh_retrieve( 3942LHASH *lh, 3943char *data); 3944 If 'data' is in the hash table it is returned, else NULL is 3945 returned. The way these routines would normally be uses is that a 3946 dummy structure would have key fields populated and then 3947 ret=lh_retrieve(hash,&dummy);. Ret would now be a pointer to a fully 3948 populated structure. 3949 3950void lh_doall( 3951LHASH *lh, 3952void (*func)(char *a)); 3953 This function will, for every entry in the hash table, call function 3954 'func' with the data item as parameters. 3955 This function can be quite useful when used as follows. 3956 void cleanup(STUFF *a) 3957 { STUFF_free(a); } 3958 lh_doall(hash,cleanup); 3959 lh_free(hash); 3960 This can be used to free all the entries, lh_free() then 3961 cleans up the 'buckets' that point to nothing. Be careful 3962 when doing this. If you delete entries from the hash table, 3963 in the call back function, the table may decrease in size, 3964 moving item that you are 3965 currently on down lower in the hash table. This could cause 3966 some entries to be skipped. The best solution to this problem 3967 is to set lh->down_load=0 before you start. This will stop 3968 the hash table ever being decreased in size. 3969 3970void lh_doall_arg( 3971LHASH *lh; 3972void(*func)(char *a,char *arg)); 3973char *arg; 3974 This function is the same as lh_doall except that the function 3975 called will be passed 'arg' as the second argument. 3976 3977unsigned long lh_strhash( 3978char *c); 3979 This function is a demo string hashing function. Since the LHASH 3980 routines would normally be passed structures, this routine would 3981 not normally be passed to lh_new(), rather it would be used in the 3982 function passed to lh_new(). 3983 3984The next three routines print out various statistics about the state of the 3985passed hash table. These numbers are all kept in the lhash structure. 3986 3987void lh_stats( 3988LHASH *lh, 3989FILE *out); 3990 This function prints out statistics on the size of the hash table, 3991 how many entries are in it, and the number and result of calls to 3992 the routines in this library. 3993 3994void lh_node_stats( 3995LHASH *lh, 3996FILE *out); 3997 For each 'bucket' in the hash table, the number of entries is 3998 printed. 3999 4000void lh_node_usage_stats( 4001LHASH *lh, 4002FILE *out); 4003 This function prints out a short summary of the state of the hash 4004 table. It prints what I call the 'load' and the 'actual load'. 4005 The load is the average number of data items per 'bucket' in the 4006 hash table. The 'actual load' is the average number of items per 4007 'bucket', but only for buckets which contain entries. So the 4008 'actual load' is the average number of searches that will need to 4009 find an item in the hash table, while the 'load' is the average number 4010 that will be done to record a miss. 4011 4012==== md2.doc ======================================================== 4013 4014The MD2 library. 4015MD2 is a message digest algorithm that can be used to condense an arbitrary 4016length message down to a 16 byte hash. The functions all need to be passed 4017a MD2_CTX which is used to hold the MD2 context during multiple MD2_Update() 4018function calls. The normal method of use for this library is as follows 4019 4020MD2_Init(...); 4021MD2_Update(...); 4022... 4023MD2_Update(...); 4024MD2_Final(...); 4025 4026This library requires the inclusion of 'md2.h'. 4027 4028The main negative about MD2 is that it is slow, especially when compared 4029to MD5. 4030 4031The functions are as follows: 4032 4033void MD2_Init( 4034MD2_CTX *c); 4035 This function needs to be called to initiate a MD2_CTX structure for 4036 use. 4037 4038void MD2_Update( 4039MD2_CTX *c; 4040unsigned char *data; 4041unsigned long len); 4042 This updates the message digest context being generated with 'len' 4043 bytes from the 'data' pointer. The number of bytes can be any 4044 length. 4045 4046void MD2_Final( 4047unsigned char *md; 4048MD2_CTX *c; 4049 This function is called when a message digest of the data digested 4050 with MD2_Update() is wanted. The message digest is put in the 'md' 4051 array and is MD2_DIGEST_LENGTH (16) bytes long. 4052 4053unsigned char *MD2( 4054unsigned long n; 4055unsigned char *d; 4056unsigned char *md; 4057 This function performs a MD2_Init(), followed by a MD2_Update() 4058 followed by a MD2_Final() (using a local MD2_CTX). 4059 The resulting digest is put into 'md' if it is not NULL. 4060 Regardless of the value of 'md', the message 4061 digest is returned from the function. If 'md' was NULL, the message 4062 digest returned is being stored in a static structure. 4063 4064==== md5.doc ======================================================== 4065 4066The MD5 library. 4067MD5 is a message digest algorithm that can be used to condense an arbitrary 4068length message down to a 16 byte hash. The functions all need to be passed 4069a MD5_CTX which is used to hold the MD5 context during multiple MD5_Update() 4070function calls. This library also contains random number routines that are 4071based on MD5 4072 4073The normal method of use for this library is as follows 4074 4075MD5_Init(...); 4076MD5_Update(...); 4077... 4078MD5_Update(...); 4079MD5_Final(...); 4080 4081This library requires the inclusion of 'md5.h'. 4082 4083The functions are as follows: 4084 4085void MD5_Init( 4086MD5_CTX *c); 4087 This function needs to be called to initiate a MD5_CTX structure for 4088 use. 4089 4090void MD5_Update( 4091MD5_CTX *c; 4092unsigned char *data; 4093unsigned long len); 4094 This updates the message digest context being generated with 'len' 4095 bytes from the 'data' pointer. The number of bytes can be any 4096 length. 4097 4098void MD5_Final( 4099unsigned char *md; 4100MD5_CTX *c; 4101 This function is called when a message digest of the data digested 4102 with MD5_Update() is wanted. The message digest is put in the 'md' 4103 array and is MD5_DIGEST_LENGTH (16) bytes long. 4104 4105unsigned char *MD5( 4106unsigned char *d; 4107unsigned long n; 4108unsigned char *md; 4109 This function performs a MD5_Init(), followed by a MD5_Update() 4110 followed by a MD5_Final() (using a local MD5_CTX). 4111 The resulting digest is put into 'md' if it is not NULL. 4112 Regardless of the value of 'md', the message 4113 digest is returned from the function. If 'md' was NULL, the message 4114 digest returned is being stored in a static structure. 4115 4116 4117==== memory.doc ======================================================== 4118 4119In the interests of debugging SSLeay, there is an option to compile 4120using some simple memory leak checking. 4121 4122All malloc(), free() and realloc() calls in SSLeay now go via 4123Malloc(), Free() and Realloc() (except those in crypto/lhash). 4124 4125If CRYPTO_MDEBUG is defined, these calls are #defined to 4126CRYPTO_malloc(), CRYPTO_free() and CRYPTO_realloc(). 4127If it is not defined, they are #defined to malloc(), free() and realloc(). 4128 4129the CRYPTO_malloc() routines by default just call the underlying library 4130functons. 4131 4132If CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON) is called, memory leak detection is 4133turned on. CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_OFF) turns it off. 4134 4135When turned on, each Malloc() or Realloc() call is recored along with the file 4136and line number from where the call was made. (This is done using the 4137lhash library which always uses normal system malloc(3) routines). 4138 4139void CRYPTO_mem_leaks(BIO *b); 4140void CRYPTO_mem_leaks_fp(FILE *fp); 4141These both print out the list of memory that has not been free()ed. 4142This will probably be rather hard to read, but if you look for the 'top level' 4143structure allocation, this will often give an idea as to what is not being 4144free()ed. I don't expect people to use this stuff normally. 4145 4146==== ca.1 ======================================================== 4147 4148From eay@orb.mincom.oz.au Thu Dec 28 23:56:45 1995 4149Received: by orb.mincom.oz.au id AA07374 4150 (5.65c/IDA-1.4.4 for eay); Thu, 28 Dec 1995 13:56:45 +1000 4151Date: Thu, 28 Dec 1995 13:56:45 +1000 (EST) 4152From: Eric Young <eay@mincom.oz.au> 4153X-Sender: eay@orb 4154To: sameer <sameer@c2.org> 4155Cc: ssleay@mincom.oz.au 4156Subject: Re: 'ca' 4157In-Reply-To: <199512230440.UAA23410@infinity.c2.org> 4158Message-Id: <Pine.SOL.3.91.951228133525.7269A-100000@orb> 4159Mime-Version: 1.0 4160Content-Type: TEXT/PLAIN; charset=US-ASCII 4161Status: RO 4162X-Status: 4163 4164On Fri, 22 Dec 1995, sameer wrote: 4165> I could use documentation on 'ca'. Thanks. 4166 4167Very quickly. 4168The ca program uses the ssleay.conf file for most of its configuration 4169 4170./ca -help 4171 4172 -verbose - Talk alot while doing things 4173 -config file - A config file. If you don't want to use the 4174 default config file 4175 -name arg - The particular CA definition to use 4176 In the config file, the section to use for parameters. This lets 4177 multiple setups to be contained in the one file. By default, the 4178 default_ca variable is looked up in the [ ca ] section. So in the 4179 shipped ssleay.conf, the CA definition used is CA_default. It could be 4180 any other name. 4181 -gencrl days - Generate a new CRL, days is when the next CRL is due 4182 This will generate a new certificate revocion list. 4183 -days arg - number of days to certify the certificate for 4184 When certifiying certificates, this is the number of days to use. 4185 -md arg - md to use, one of md2, md5, sha or sha1 4186 -policy arg - The CA 'policy' to support 4187 I'll describe this later, but there are 2 policies definied in the 4188 shipped ssleay.conf 4189 -keyfile arg - PEM RSA private key file 4190 -key arg - key to decode the RSA private key if it is encrypted 4191 since we need to keep the CA's RSA key encrypted 4192 -cert - The CA certificate 4193 -in file - The input PEM encoded certificate request(s) 4194 -out file - Where to put the output file(s) 4195 -outdir dir - Where to put output certificates 4196 The -out options concatinates all the output certificied 4197 certificates to one file, -outdir puts them in a directory, 4198 named by serial number. 4199 -infiles .... - The last argument, requests to process 4200 The certificate requests to process, -in is the same. 4201 4202Just about all the above have default values defined in ssleay.conf. 4203 4204The key variables in ssleay.conf are (for the pariticular '-name' being 4205used, in the default, it is CA_default). 4206 4207dir is where all the CA database stuff is kept. 4208certs is where all the previously issued certificates are kept. 4209The database is a simple text database containing the following tab separated 4210fields. 4211status: a value of 'R' - revoked, 'E' -expired or 'V' valid. 4212issued date: When the certificate was certified. 4213revoked date: When it was revoked, blank if not revoked. 4214serial number: The certificate serial number. 4215certificate: Where the certificate is located. 4216CN: The name of the certificate. 4217 4218The demo file has quite a few made up values it it. The last 2 were 4219added by the ca program and are acurate. 4220The CA program does not update the 'certificate' file correctly right now. 4221The serial field should be unique as should the CN/status combination. 4222The ca program checks these at startup. What still needs to be 4223wrtten is a program to 'regenerate' the data base file from the issued 4224certificate list (and a CRL list). 4225 4226Back to the CA_default variables. 4227 4228Most of the variables are commented. 4229 4230policy is the default policy. 4231 4232Ok for policies, they define the order and which fields must be present 4233in the certificate request and what gets filled in. 4234 4235So a value of 4236countryName = match 4237means that the country name must match the CA certificate. 4238organizationalUnitName = optional 4239The org.Unit,Name does not have to be present and 4240commonName = supplied 4241commonName must be supplied in the certificate request. 4242 4243For the 'policy_match' polocy, the order of the attributes in the 4244generated certiticate would be 4245countryName 4246stateOrProvinceName 4247organizationName 4248organizationalUnitName 4249commonName 4250emailAddress 4251 4252Have a play, it sort of makes sense. If you think about how the persona 4253requests operate, it is similar to the 'policy_match' policy and the 4254'policy_anything' is similar to what versign is doing. 4255 4256I hope this helps a bit. Some backend scripts are definitly needed to 4257update the database and to make certificate revocion easy. All 4258certificates issued should also be kept forever (or until they expire?) 4259 4260hope this helps 4261eric (who has to run off an buy some cheap knee pads for the caving in 4 4262days time :-) 4263 4264-- 4265Eric Young | Signature removed since it was generating 4266AARNet: eay@mincom.oz.au | more followups than the message contents :-) 4267 4268 4269==== ms3-ca.doc ======================================================== 4270 4271Date: Mon, 9 Jun 97 08:00:33 +0200 4272From: Holger.Reif@PrakInf.TU-Ilmenau.DE (Holger Reif) 4273Subject: ms3-ca.doc 4274Organization: TU Ilmenau, Fak. IA, FG Telematik 4275Content-Length: 14575 4276Status: RO 4277X-Status: 4278 4279Loading client certs into MSIE 3.01 4280=================================== 4281 4282This document conatains all the information necessary to succesfully set up 4283some scripts to issue client certs to Microsoft Internet Explorer. It 4284includes the required knowledge about the model MSIE uses for client 4285certification and includes complete sample scripts ready to play with. The 4286scripts were tested against a modified ca program of SSLeay 0.6.6 and should 4287work with the regular ca program that comes with version 0.8.0. I haven't 4288tested against MSIE 4.0 4289 4290You can use the information contained in this document in either way you 4291want. However if you feel it saved you a lot of time I ask you to be as fair 4292as to mention my name: Holger Reif <reif@prakinf.tu-ilmenau.de>. 4293 42941.) The model used by MSIE 4295-------------------------- 4296 4297The Internet Explorer doesn't come with a embedded engine for installing 4298client certs like Netscape's Navigator. It rather uses the CryptoAPI (CAPI) 4299defined by Microsoft. CAPI comes with WindowsNT 4.0 or is installed together 4300with Internet Explorer since 3.01. The advantage of this approach is a higher 4301flexibility because the certificates in the (per user) system open 4302certificate store may be used by other applications as well. The drawback 4303however is that you need to do a bit more work to get a client cert issued. 4304 4305CAPI defines functions which will handle basic cryptographic work, eg. 4306generating keys, encrypting some data, signing text or building a certificate 4307request. The procedure is as follows: A CAPI function generates you a key 4308pair and saves it into the certificate store. After that one builds a 4309Distinguished Name. Together with that key pair another CAPI function forms a 4310PKCS#10 request which you somehow need to submit to a CA. Finally the issued 4311cert is given to a yet another CAPI function which saves it into the 4312certificate store. 4313 4314The certificate store with the user's keys and certs is in the registry. You 4315will find it under HKEY_CURRENT_USER/Software/Microsoft/Cryptography/ (I 4316leave it to you as a little exercise to figure out what all the entries mean 4317;-). Note that the keys are protected only with the user's usual Windows 4318login password. 4319 43202.) The practical usage 4321----------------------- 4322 4323Unfortunatly since CAPI is a system API you can't access its functions from 4324HTML code directly. For this purpose Microsoft provides a wrapper called 4325certenr3.dll. This DLL accesses the CAPI functions and provides an interface 4326usable from Visual Basic Script. One needs to install that library on the 4327computer which wants to have client cert. The easiest way is to load it as an 4328ActiveX control (certenr3.dll is properly authenticode signed by MS ;-). If 4329you have ever enrolled e cert request at a CA you will have installed it. 4330 4331At time of writing certenr3.dll is contained in 4332http://www.microsoft.com/workshop/prog/security/csa/certenr3.exe. It comes 4333with an README file which explains the available functions. It is labeled 4334beta but every CA seems to use it anyway. The license.txt allows you the 4335usage for your own purposes (as far as I understood) and a somehow limited 4336distribution. 4337 4338The two functions of main interest are GenerateKeyPair and AcceptCredentials. 4339For complete explanation of all possible parameters see the README file. Here 4340are only minimal required parameters and their values. 4341 4342GenerateKeyPair(sessionID, FASLE, szName, 0, "ClientAuth", TRUE, FALSE, 1) 4343- sessionID is a (locally to that computer) unique string to correlate the 4344generated key pair with a cert installed later. 4345- szName is the DN of the form "C=DE; S=Thueringen; L=Ilmenau; CN=Holger 4346Reif; 1.2.840.113549.1.9.1=reif@prakinf.tu-ilmenau.de". Note that S is the 4347abreviation for StateOrProvince. The recognized abreviation include CN, O, C, 4348OU, G, I, L, S, T. If the abreviation is unknown (eg. for PKCS#9 email addr) 4349you need to use the full object identifier. The starting point for searching 4350them could be crypto/objects.h since all OIDs know to SSLeay are listed 4351there. 4352- note: the possible ninth parameter which should give a default name to the 4353certificate storage location doesn't seem to work. Changes to the constant 4354values in the call above doesn't seem to make sense. You can't generate 4355PKCS#10 extensions with that function. 4356 4357The result of GenerateKeyPair is the base64 encoded PKCS#10 request. However 4358it has a little strange format that SSLeay doesn't accept. (BTW I feel the 4359decision of rejecting that format as standard conforming.) It looks like 4360follows: 4361 1st line with 76 chars 4362 2nd line with 76 chars 4363 ... 4364 (n-2)th line with 76 chars 4365 (n-1)th line contains a multiple of 4 chars less then 76 (possible 4366empty) 4367 (n)th line has zero or 4 chars (then with 1 or 2 equal signs - the 4368 original text's lenght wasn'T a multiple of 3) 4369 The line separator has two chars: 0x0d 0x0a 4370 4371AcceptCredentials(sessionID, credentials, 0, FALSE) 4372- sessionID needs to be the same as while generating the key pair 4373- credentials is the base64 encoded PKCS#7 object containing the cert. 4374 4375CRL's and CA certs are not required simply just the client cert. (It seems to 4376me that both are not even checked somehow.) The only format of the base64 4377encoded object I succesfully used was all characters in a very long string 4378without line feeds or carriage returns. (Hey, it doesn't matter, only a 4379computer reads it!) 4380 4381The result should be S_OK. For error handling see the example that comes with 4382certenr3.dll. 4383 4384A note about ASN.1 character encodings. certenr3.dll seems to know only about 43852 of them: UniversalString and PrintableString. First it is definitely wrong 4386for an email address which is IA5STRING (checked by ssleay's ca). Second 4387unfortunately MSIE (at least until version 3.02) can't handle UniversalString 4388correctly - they just blow up you cert store! Therefore ssleay's ca (starting 4389from version 0.8.0) tries to convert the encodings automatically to IA5STRING 4390or TeletexString. The beef is it will work only for the latin-1 (western) 4391charset. Microsoft still has to do abit of homework... 4392 43933.) An example 4394-------------- 4395 4396At least you need two steps: generating the key & request and then installing 4397the certificate. A real world CA would have some more steps involved, eg. 4398accepting some license. Note that both scripts shown below are just 4399experimental state without any warrenty! 4400 4401First how to generate a request. Note that we can't use a static page because 4402of the sessionID. I generate it from system time plus pid and hope it is 4403unique enough. Your are free to feed it through md5 to get more impressive 4404ID's ;-) Then the intended text is read in with sed which inserts the 4405sessionID. 4406 4407-----BEGIN ms-enroll.cgi----- 4408#!/bin/sh 4409SESSION_ID=`date '+%y%m%d%H%M%S'`$$ 4410echo Content-type: text/html 4411echo 4412sed s/template_for_sessId/$SESSION_ID/ <<EOF 4413<HTML><HEAD> 4414<TITLE>Certificate Enrollment Test Page</TITLE> 4415</HEAD><BODY> 4416 4417<OBJECT 4418 classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43" 4419 codebase=certenr3.dll 4420 id=certHelper 4421 > 4422</OBJECT> 4423 4424<CENTER> 4425<H2>enrollment for a personal cert</H2> 4426<BR><HR WIDTH=50%><BR><P> 4427<FORM NAME="MSIE_Enrollment" ACTION="ms-gencert.cgi" ENCTYPE=x-www-form- 4428encoded METHOD=POST> 4429<TABLE> 4430 <TR><TD>Country</TD><TD><INPUT NAME="Country" VALUE=""></TD></TR> 4431 <TR><TD>State</TD><TD><INPUT NAME="StateOrProvince" VALUE=""></TD></TR> 4432 <TR><TD>Location</TD><TD><INPUT NAME="Location" VALUE=""></TD></TR> 4433 <TR><TD>Organization</TD><TD><INPUT NAME="Organization" 4434VALUE=""></TD></TR> 4435 <TR><TD>Organizational Unit</TD> 4436 <TD><INPUT NAME="OrganizationalUnit" VALUE=""></TD></TR> 4437 <TR><TD>Name</TD><TD><INPUT NAME="CommonName" VALUE=""></TD></TR> 4438 <TR><TD>eMail Address</TD> 4439 <TD><INPUT NAME="EmailAddress" VALUE=""></TD></TR> 4440 <TR><TD></TD> 4441 <TD><INPUT TYPE="BUTTON" NAME="submit" VALUE="Beantragen"></TD></TR> 4442</TABLE> 4443 <INPUT TYPE="hidden" NAME="SessionId" VALUE="template_for_sessId"> 4444 <INPUT TYPE="hidden" NAME="Request" VALUE=""> 4445</FORM> 4446<BR><HR WIDTH=50%><BR><P> 4447</CENTER> 4448 4449<SCRIPT LANGUAGE=VBS> 4450 Dim DN 4451 4452 Sub Submit_OnClick 4453 Dim TheForm 4454 Set TheForm = Document.MSIE_Enrollment 4455 sessionId = TheForm.SessionId.value 4456 reqHardware = FALSE 4457 C = TheForm.Country.value 4458 SP = TheForm.StateOrProvince.value 4459 L = TheForm.Location.value 4460 O = TheForm.Organization.value 4461 OU = TheForm.OrganizationalUnit.value 4462 CN = TheForm.CommonName.value 4463 Email = TheForm.EmailAddress.value 4464 szPurpose = "ClientAuth" 4465 doAcceptanceUINow = FALSE 4466 doOnline = TRUE 4467 4468 DN = "" 4469 4470 Call Add_RDN("C", C) 4471 Call Add_RDN("S", SP) 4472 Call Add_RDN("L", L) 4473 Call Add_RDN("O", O) 4474 Call Add_RDN("OU", OU) 4475 Call Add_RDN("CN", CN) 4476 Call Add_RDN("1.2.840.113549.1.9.1", Email) 4477 ' rsadsi 4478 ' pkcs 4479 ' pkcs9 4480 ' eMailAddress 4481 On Error Resume Next 4482 sz10 = certHelper.GenerateKeyPair(sessionId, _ 4483 FALSE, DN, 0, ClientAuth, FASLE, TRUE, 1)_ 4484 theError = Err.Number 4485 On Error Goto 0 4486 if (sz10 = Empty OR theError <> 0) Then 4487 sz = "The error '" & Hex(theError) & "' occurred." & chr(13) & _ 4488 chr(10) & "Your credentials could not be generated." 4489 result = MsgBox(sz, 0, "Credentials Enrollment") 4490 Exit Sub 4491 else 4492 TheForm.Request.value = sz10 4493 TheForm.Submit 4494 end if 4495 End Sub 4496 4497 Sub Add_RDN(sn, value) 4498 if (value <> "") then 4499 if (DN <> "") then 4500 DN = DN & "; " 4501 end if 4502 DN = DN & sn & "=" & value 4503 end if 4504 End Sub 4505</SCRIPT> 4506</BODY> 4507</HTML> 4508EOF 4509-----END ms-enroll.cgi----- 4510 4511Second, how to extract the request and feed the certificate back? We need to 4512"normalize" the base64 encoding of the PKCS#10 format which means 4513regenerating the lines and wrapping with BEGIN and END line. This is done by 4514gawk. The request is taken by ca the normal way. Then the cert needs to be 4515packed into a PKCS#7 structure (note: the use of a CRL is necessary for 4516crl2pkcs7 as of version 0.6.6. Starting with 0.8.0 it it might probably be 4517ommited). Finally we need to format the PKCS#7 object and generate the HTML 4518text. I use two templates to have a clearer script. 4519 45201st note: postit2 is slightly modified from a program I found at ncsa's ftp 4521site. Grab it from http://www.easterngraphics.com/certs/IX9704/postit2.c. You 4522need utils.c from there too. 4523 45242nd note: I'm note quite sure wether the gawk script really handles all 4525possible inputs for the request right! Today I don't use this construction 4526anymore myself. 4527 45283d note: the cert must be of version 3! This could be done with the nsComment 4529line in ssleay.cnf... 4530 4531------BEGIN ms-gencert.cgi----- 4532#!/bin/sh 4533FILE="/tmp/"`date '+%y%m%d%H%M%S'-`$$ 4534rm -f "$FILE".* 4535 4536HOME=`pwd`; export HOME # as ssleay.cnf insists on having such an env var 4537cd /usr/local/ssl #where demoCA (as named in ssleay.conf) is located 4538 4539postit2 -s " " -i 0x0d > "$FILE".inp # process the FORM vars 4540 4541SESSION_ID=`gawk '$1 == "SessionId" { print $2; exit }' "$FILE".inp` 4542 4543gawk \ 4544 'BEGIN { \ 4545 OFS = ""; \ 4546 print "-----BEGIN CERTIFICATE REQUEST-----"; \ 4547 req_seen=0 \ 4548 } \ 4549 $1 == "Request" { \ 4550 req_seen=1; \ 4551 if (length($2) == 72) print($2); \ 4552 lastline=$2; \ 4553 next; \ 4554 } \ 4555 { \ 4556 if (req_seen == 1) { \ 4557 if (length($1) >= 72) print($1); \ 4558 else if (length(lastline) < 72) { \ 4559 req_seen=0; \ 4560 print (lastline,$1); \ 4561 } \ 4562 lastline=$1; \ 4563 } \ 4564 } \ 4565 END { \ 4566 print "-----END CERTIFICATE REQUEST-----"; \ 4567 }' > "$FILE".pem < "$FILE".inp 4568 4569ssleay ca -batch -in "$FILE".pem -key passwd -out "$FILE".out 4570ssleay crl2pkcs7 -certfile "$FILE".out -out "$FILE".pkcs7 -in demoCA/crl.pem 4571 4572sed s/template_for_sessId/$SESSION_ID/ <ms-enroll2a.html >"$FILE".cert 4573/usr/local/bin/gawk \ 4574 'BEGIN { \ 4575 OFS = ""; \ 4576 dq = sprintf("%c",34); \ 4577 } \ 4578 $0 ~ "PKCS7" { next; } \ 4579 { \ 4580 print dq$0dq" & _"; \ 4581 }' <"$FILE".pkcs7 >> "$FILE".cert 4582cat ms-enroll2b.html >>"$FILE".cert 4583 4584echo Content-type: text/html 4585echo Content-length: `wc -c "$FILE".cert` 4586echo 4587cat "$FILE".cert 4588rm -f "$FILE".* 4589-----END ms-gencert.cgi----- 4590 4591----BEGIN ms-enroll2a.html---- 4592<HTML><HEAD><TITLE>Certificate Acceptance Test Page</TITLE></HEAD><BODY> 4593 4594<OBJECT 4595 classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43" 4596 codebase=certenr3.dll 4597 id=certHelper 4598 > 4599</OBJECT> 4600 4601<CENTER> 4602<H2>Your personal certificate</H2> 4603<BR><HR WIDTH=50%><BR><P> 4604Press the button! 4605<P><INPUT TYPE=BUTTON VALUE="Nimm mich!" NAME="InstallCert"> 4606</CENTER> 4607<BR><HR WIDTH=50%><BR> 4608 4609<SCRIPT LANGUAGE=VBS> 4610 Sub InstallCert_OnClick 4611 4612 sessionId = "template_for_sessId" 4613credentials = "" & _ 4614----END ms-enroll2a.html---- 4615 4616----BEGIN ms-enroll2b.html---- 4617"" 4618 On Error Resume Next 4619 result = certHelper.AcceptCredentials(sessionId, credentials, 0, 4620FALSE) 4621 if (IsEmpty(result)) Then 4622 sz = "The error '" & Err.Number & "' occurred." & chr(13) & 4623chr(10) & "This Digital ID could not be registered." 4624 msgOut = MsgBox(sz, 0, "Credentials Registration Error") 4625 navigate "error.html" 4626 else 4627 sz = "Digital ID successfully registered." 4628 msgOut = MsgBox(sz, 0, "Credentials Registration") 4629 navigate "success.html" 4630 end if 4631 Exit Sub 4632 End Sub 4633</SCRIPT> 4634</BODY> 4635</HTML> 4636----END ms-enroll2b.html---- 4637 46384.) What do do with the cert? 4639----------------------------- 4640 4641The cert is visible (without restarting MSIE) under the following menu: 4642View->Options->Security->Personal certs. You can examine it's contents at 4643least partially. 4644 4645To use it for client authentication you need to use SSL3.0 (fortunately 4646SSLeay supports it with 0.8.0). Furthermore MSIE is told to only supports a 4647kind of automatic selection of certs (I personally wasn't able to test it 4648myself). But there is a requirement that the issuer of the server cert and 4649the issuer of the client cert needs to be the same (according to a developer 4650from MS). Which means: you need may more then one cert to talk to all 4651servers... 4652 4653I'm sure we will get a bit more experience after ApacheSSL is available for 4654SSLeay 0.8.8. 4655 4656 4657I hope you enjoyed reading and that in future questions on this topic will 4658rarely appear on ssl-users@moncom.com ;-) 4659 4660Ilmenau, 9th of June 1997 4661Holger Reif <reif@prakinf.tu-ilmenau.de> 4662-- 4663read you later - Holger Reif 4664---------------------------------------- Signaturprojekt Deutsche Einheit 4665TU Ilmenau - Informatik - Telematik (Verdamp lang her) 4666Holger.Reif@PrakInf.TU-Ilmenau.DE Alt wie ein Baum werden, um ueber 4667http://Remus.PrakInf.TU-Ilmenau.DE/Reif/ alle 7 Bruecken gehen zu koennen 4668 4669 4670==== ns-ca.doc ======================================================== 4671 4672The following documentation was supplied by Jeff Barber, who provided the 4673patch to the CA program to add this functionality. 4674 4675eric 4676-- 4677Jeff Barber Email: jeffb@issl.atl.hp.com 4678 4679Hewlett Packard Phone: (404) 648-9503 4680Internet and System Security Lab Fax: (404) 648-9516 4681 4682 oo 4683---------------------cut /\ here for ns-ca.doc ------------------------------ 4684 4685This document briefly describes how to use SSLeay to implement a 4686certificate authority capable of dynamically serving up client 4687certificates for version 3.0 beta 5 (and presumably later) versions of 4688the Netscape Navigator. Before describing how this is done, it's 4689important to understand a little about how the browser implements its 4690client certificate support. This is documented in some detail in the 4691URLs based at <URL:http://home.netscape.com/eng/security/certs.html>. 4692Here's a brief overview: 4693 4694- The Navigator supports a new HTML tag "KEYGEN" which will cause 4695 the browser to generate an RSA key pair when you submit a form 4696 containing the tag. The public key, along with an optional 4697 challenge (supposedly provided for use in certificate revocation 4698 but I don't use it) is signed, DER-encoded, base-64 encoded 4699 and sent to the web server as the value of the variable 4700 whose NAME is provided in the KEYGEN tag. The private key is 4701 stored by the browser in a local key database. 4702 4703 This "Signed Public Key And Challenge" (SPKAC) arrives formatted 4704 into 64 character lines (which are of course URL-encoded when 4705 sent via HTTP -- i.e. spaces, newlines and most punctuatation are 4706 encoded as "%HH" where HH is the hex equivalent of the ASCII code). 4707 Note that the SPKAC does not contain the other usual attributes 4708 of a certificate request, especially the subject name fields. 4709 These must be otherwise encoded in the form for submission along 4710 with the SPKAC. 4711 4712- Either immediately (in response to this form submission), or at 4713 some later date (a real CA will probably verify your identity in 4714 some way before issuing the certificate), a web server can send a 4715 certificate based on the public key and other attributes back to 4716 the browser by encoding it in DER (the binary form) and sending it 4717 to the browser as MIME type: 4718 "Content-type: application/x-x509-user-cert" 4719 4720 The browser uses the public key encoded in the certificate to 4721 associate the certificate with the appropriate private key in 4722 its local key database. Now, the certificate is "installed". 4723 4724- When a server wants to require authentication based on client 4725 certificates, it uses the right signals via the SSL protocol to 4726 trigger the Navigator to ask you which certificate you want to 4727 send. Whether the certificate is accepted is dependent on CA 4728 certificates and so forth installed in the server and is beyond 4729 the scope of this document. 4730 4731 4732Now, here's how the SSLeay package can be used to provide client 4733certficates: 4734 4735- You prepare a file for input to the SSLeay ca application. 4736 The file contains a number of "name = value" pairs that identify 4737 the subject. The names here are the same subject name component 4738 identifiers used in the CA section of the lib/ssleay.conf file, 4739 such as "emailAddress", "commonName" "organizationName" and so 4740 forth. Both the long version and the short version (e.g. "Email", 4741 "CN", "O") can be used. 4742 4743 One more name is supported: this one is "SPKAC". Its value 4744 is simply the value of the base-64 encoded SPKAC sent by the 4745 browser (with all the newlines and other space charaters 4746 removed -- and newline escapes are NOT supported). 4747 4748 [ As of SSLeay 0.6.4, multiple lines are supported. 4749 Put a \ at the end of each line and it will be joined with the 4750 previous line with the '\n' removed - eay ] 4751 4752 Here's a sample input file: 4753 4754C = US 4755SP = Georgia 4756O = Some Organization, Inc. 4757OU = Netscape Compatibility Group 4758CN = John X. Doe 4759Email = jxdoe@someorg.com 4760SPKAC = MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwmk6FMJ4uAVIYbcvIOx5+bDGTfvL8X5gE+R67ccMk6rCSGbVQz2cetyQtnI+VIs0NwdD6wjuSuVtVFbLoHonowIDAQABFgAwDQYJKoZIhvcNAQEEBQADQQBFZDUWFl6BJdomtN1Bi53mwijy1rRgJ4YirF15yBEDM3DjAQkKXHYOIX+qpz4KXKnl6EYxTnGSFL5wWt8X2iyx 4761 4762- You execute the ca command (either from a CGI program run out of 4763 the web server, or as a later manual task) giving it the above 4764 file as input. For example, if the file were named /tmp/cert.req, 4765 you'd run: 4766 $SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert 4767 4768 The output is in DER format (binary) if a -out argument is 4769 provided, as above; otherwise, it's in the PEM format (base-64 4770 encoded DER). Also, the "-batch" switch is implied by the 4771 "-spkac" so you don't get asked whether to complete the signing 4772 (probably it shouldn't work this way but I was only interested 4773 in hacking together an online CA that could be used for issuing 4774 test certificates). 4775 4776 The "-spkac" capability doesn't support multiple files (I think). 4777 4778 Any CHALLENGE provided in the SPKAC is simply ignored. 4779 4780 The interactions between the identification fields you provide 4781 and those identified in your lib/ssleay.conf are the same as if 4782 you did an ordinary "ca -in infile -out outfile" -- that is, if 4783 something is marked as required in the ssleay.conf file and it 4784 isn't found in the -spkac file, the certificate won't be issued. 4785 4786- Now, you pick up the output from /tmp/cert and pass it back to 4787 the Navigator prepending the Content-type string described earlier. 4788 4789- In order to run the ca command out of a CGI program, you must 4790 provide a password to decrypt the CA's private key. You can 4791 do this by using "echo MyKeyPassword | $SSLDIR/bin/ca ..." 4792 I think there's a way to not encrypt the key file in the first 4793 place, but I didn't see how to do that, so I made a small change 4794 to the library that allows the password to be accepted from a pipe. 4795 Either way is UTTERLY INSECURE and a real CA would never do that. 4796 4797 [ You can use the 'ssleay rsa' command to remove the password 4798 from the private key, or you can use the '-key' option to the 4799 ca command to specify the decryption key on the command line 4800 or use the -nodes option when generating the key. 4801 ca will try to clear the command line version of the password 4802 but for quite a few operating systems, this is not possible. 4803 - eric ] 4804 4805So, what do you have to do to make use of this stuff to create an online 4806demo CA capability with SSLeay? 4807 48081 Create an HTML form for your users. The form should contain 4809 fields for all of the required or optional fields in ssleay.conf. 4810 The form must contain a KEYGEN tag somewhere with at least a NAME 4811 attribute. 4812 48132 Create a CGI program to process the form input submitted by the 4814 browser. The CGI program must URL-decode the variables and create 4815 the file described above, containing subject identification info 4816 as well as the SPKAC block. It should then run the the ca program 4817 with the -spkac option. If it works (check the exit status), 4818 return the new certificate with the appropriate MIME type. If not, 4819 return the output of the ca command with MIME type "text/plain". 4820 48213 Set up your web server to accept connections signed by your demo 4822 CA. This probably involves obtaining the PEM-encoded CA certificate 4823 (ordinarily in $SSLDIR/CA/cacert.pem) and installing it into a 4824 server database. See your server manual for instructions. 4825 4826 4827==== obj.doc ======================================================== 4828 4829The Object library. 4830 4831As part of my Crypto library, I found I required a method of identifying various 4832objects. These objects normally had 3 different values associated with 4833them, a short text name, a long (or lower case) text name, and an 4834ASN.1 Object Identifier (which is a sequence of numbers). 4835This library contains a static list of objects and functions to lookup 4836according to one type and to return the other types. 4837 4838To use these routines, 'Object.h' needs to be included. 4839 4840For each supported object, #define entries are defined as follows 4841#define SN_Algorithm "Algorithm" 4842#define LN_algorithm "algorithm" 4843#define NID_algorithm 38 4844#define OBJ_algorithm 1L,3L,14L,3L,2L 4845 4846SN_ stands for short name. 4847LN_ stands for either long name or lowercase name. 4848NID_ stands for Numeric ID. I each object has a unique NID and this 4849 should be used internally to identify objects. 4850OBJ_ stands for ASN.1 Object Identifier or ASN1_OBJECT as defined in the 4851 ASN1 routines. These values are used in ASN1 encoding. 4852 4853The following functions are to be used to return pointers into a static 4854definition of these types. What this means is "don't try to free() any 4855pointers returned from these functions. 4856 4857ASN1_OBJECT *OBJ_nid2obj( 4858int n); 4859 Return the ASN1_OBJECT that corresponds to a NID of n. 4860 4861char *OBJ_nid2ln( 4862int n); 4863 Return the long/lower case name of the object represented by the 4864 NID of n. 4865 4866char *OBJ_nid2sn( 4867int n); 4868 Return the short name for the object represented by the NID of n. 4869 4870ASN1_OBJECT *OBJ_dup( 4871ASN1_OBJECT *o); 4872 Duplicate and return a new ASN1_OBJECT that is the same as the 4873 passed parameter. 4874 4875int OBJ_obj2nid( 4876ASN1_OBJECT *o); 4877 Given ASN1_OBJECT o, return the NID that corresponds. 4878 4879int OBJ_ln2nid( 4880char *s); 4881 Given the long/lower case name 's', return the NID of the object. 4882 4883int OBJ_sn2nid( 4884char *s); 4885 Given the short name 's', return the NID of the object. 4886 4887char *OBJ_bsearch( 4888char *key, 4889char *base, 4890int num, 4891int size, 4892int (*cmp)()); 4893 Since I have come across a few platforms that do not have the 4894 bsearch() function, OBJ_bsearch is my version of that function. 4895 Feel free to use this function, but you may as well just use the 4896 normal system bsearch(3) if it is present. This version also 4897 has tolerance of being passed NULL pointers. 4898 4899==== keys =========================================================== 4900 4901EVP_PKEY_DSA 4902EVP_PKEY_DSA2 4903EVP_PKEY_DSA3 4904EVP_PKEY_DSA4 4905 4906EVP_PKEY_RSA 4907EVP_PKEY_RSA2 4908 4909valid DSA pkey types 4910 NID_dsa 4911 NID_dsaWithSHA 4912 NID_dsaWithSHA1 4913 NID_dsaWithSHA1_2 4914 4915valid RSA pkey types 4916 NID_rsaEncryption 4917 NID_rsa 4918 4919NID_dsaWithSHA NID_dsaWithSHA DSA SHA 4920NID_dsa NID_dsaWithSHA1 DSA SHA1 4921NID_md2 NID_md2WithRSAEncryption RSA-pkcs1 MD2 4922NID_md5 NID_md5WithRSAEncryption RSA-pkcs1 MD5 4923NID_mdc2 NID_mdc2WithRSA RSA-none MDC2 4924NID_ripemd160 NID_ripemd160WithRSA RSA-pkcs1 RIPEMD160 4925NID_sha NID_shaWithRSAEncryption RSA-pkcs1 SHA 4926NID_sha1 NID_sha1WithRSAEncryption RSA-pkcs1 SHA1 4927 4928==== rand.doc ======================================================== 4929 4930My Random number library. 4931 4932These routines can be used to generate pseudo random numbers and can be 4933used to 'seed' the pseudo random number generator (RNG). The RNG make no 4934effort to reproduce the same random number stream with each execution. 4935Various other routines in the SSLeay library 'seed' the RNG when suitable 4936'random' input data is available. Read the section at the end for details 4937on the design of the RNG. 4938 4939void RAND_bytes( 4940unsigned char *buf, 4941int num); 4942 This routine puts 'num' random bytes into 'buf'. One should make 4943 sure RAND_seed() has been called before using this routine. 4944 4945void RAND_seed( 4946unsigned char *buf, 4947int num); 4948 This routine adds more 'seed' data the RNG state. 'num' bytes 4949 are added to the RNG state, they are taken from 'buf'. This 4950 routine can be called with sensitive data such as user entered 4951 passwords. This sensitive data is in no way recoverable from 4952 the RAND library routines or state. Try to pass as much data 4953 from 'random' sources as possible into the RNG via this function. 4954 Also strongly consider using the RAND_load_file() and 4955 RAND_write_file() routines. 4956 4957void RAND_cleanup(); 4958 When a program has finished with the RAND library, if it so 4959 desires, it can 'zero' all RNG state. 4960 4961The following 3 routines are convenience routines that can be used to 4962'save' and 'restore' data from/to the RNG and it's state. 4963Since the more 'random' data that is feed as seed data the better, why not 4964keep it around between executions of the program? Of course the 4965application should pass more 'random' data in via RAND_seed() and 4966make sure no-one can read the 'random' data file. 4967 4968char *RAND_file_name( 4969char *buf, 4970int size); 4971 This routine returns a 'default' name for the location of a 'rand' 4972 file. The 'rand' file should keep a sequence of random bytes used 4973 to initialise the RNG. The filename is put in 'buf'. Buf is 'size' 4974 bytes long. Buf is returned if things go well, if they do not, 4975 NULL is returned. The 'rand' file name is generated in the 4976 following way. First, if there is a 'RANDFILE' environment 4977 variable, it is returned. Second, if there is a 'HOME' environment 4978 variable, $HOME/.rand is returned. Third, NULL is returned. NULL 4979 is also returned if a buf would overflow. 4980 4981int RAND_load_file( 4982char *file, 4983long number); 4984 This function 'adds' the 'file' into the RNG state. It does this by 4985 doing a RAND_seed() on the value returned from a stat() system call 4986 on the file and if 'number' is non-zero, upto 'number' bytes read 4987 from the file. The number of bytes passed to RAND_seed() is returned. 4988 4989int RAND_write_file( 4990char *file), 4991 RAND_write_file() writes N random bytes to the file 'file', where 4992 N is the size of the internal RND state (currently 1k). 4993 This is a suitable method of saving RNG state for reloading via 4994 RAND_load_file(). 4995 4996What follows is a description of this RNG and a description of the rational 4997behind it's design. 4998 4999It should be noted that this RNG is intended to be used to generate 5000'random' keys for various ciphers including generation of DH and RSA keys. 5001 5002It should also be noted that I have just created a system that I am happy with. 5003It may be overkill but that does not worry me. I have not spent that much 5004time on this algorithm so if there are glaring errors, please let me know. 5005Speed has not been a consideration in the design of these routines. 5006 5007First up I will state the things I believe I need for a good RNG. 50081) A good hashing algorithm to mix things up and to convert the RNG 'state' 5009 to random numbers. 50102) An initial source of random 'state'. 50113) The state should be very large. If the RNG is being used to generate 5012 4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum). 5013 If your RNG state only has 128 bits, you are obviously limiting the 5014 search space to 128 bits, not 2048. I'm probably getting a little 5015 carried away on this last point but it does indicate that it may not be 5016 a bad idea to keep quite a lot of RNG state. It should be easier to 5017 break a cipher than guess the RNG seed data. 50184) Any RNG seed data should influence all subsequent random numbers 5019 generated. This implies that any random seed data entered will have 5020 an influence on all subsequent random numbers generated. 50215) When using data to seed the RNG state, the data used should not be 5022 extractable from the RNG state. I believe this should be a 5023 requirement because one possible source of 'secret' semi random 5024 data would be a private key or a password. This data must 5025 not be disclosed by either subsequent random numbers or a 5026 'core' dump left by a program crash. 50276) Given the same initial 'state', 2 systems should deviate in their RNG state 5028 (and hence the random numbers generated) over time if at all possible. 50297) Given the random number output stream, it should not be possible to determine 5030 the RNG state or the next random number. 5031 5032 5033The algorithm is as follows. 5034 5035There is global state made up of a 1023 byte buffer (the 'state'), a 5036working message digest ('md') and a counter ('count'). 5037 5038Whenever seed data is added, it is inserted into the 'state' as 5039follows. 5040 The input is chopped up into units of 16 bytes (or less for 5041 the last block). Each of these blocks is run through the MD5 5042 message digest. The data passed to the MD5 digest is the 5043 current 'md', the same number of bytes from the 'state' 5044 (the location determined by in incremented looping index) as 5045 the current 'block' and the new key data 'block'. The result 5046 of this is kept in 'md' and also xored into the 'state' at the 5047 same locations that were used as input into the MD5. 5048 I believe this system addresses points 1 (MD5), 3 (the 'state'), 5049 4 (via the 'md'), 5 (by the use of MD5 and xor). 5050 5051When bytes are extracted from the RNG, the following process is used. 5052For each group of 8 bytes (or less), we do the following, 5053 Input into MD5, the top 8 bytes from 'md', the byte that are 5054 to be overwritten by the random bytes and bytes from the 5055 'state' (incrementing looping index). From this digest output 5056 (which is kept in 'md'), the top (upto) 8 bytes are 5057 returned to the caller and the bottom (upto) 8 bytes are xored 5058 into the 'state'. 5059 Finally, after we have finished 'generation' random bytes for the 5060 called, 'count' (which is incremented) and 'md' are fed into MD5 and 5061 the results are kept in 'md'. 5062 I believe the above addressed points 1 (use of MD5), 6 (by 5063 hashing into the 'state' the 'old' data from the caller that 5064 is about to be overwritten) and 7 (by not using the 8 bytes 5065 given to the caller to update the 'state', but they are used 5066 to update 'md'). 5067 5068So of the points raised, only 2 is not addressed, but sources of 5069random data will always be a problem. 5070 5071 5072==== rc2.doc ======================================================== 5073 5074The RC2 library. 5075 5076RC2 is a block cipher that operates on 64bit (8 byte) quantities. It 5077uses variable size key, but 128bit (16 byte) key would normally be considered 5078good. It can be used in all the modes that DES can be used. This 5079library implements the ecb, cbc, cfb64, ofb64 modes. 5080 5081I have implemented this library from an article posted to sci.crypt on 508211-Feb-1996. I personally don't know how far to trust the RC2 cipher. 5083While it is capable of having a key of any size, not much reseach has 5084publically been done on it at this point in time (Apr-1996) 5085since the cipher has only been public for a few months :-) 5086It is of a similar speed to DES and IDEA, so unless it is required for 5087meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable 5088to stick to IDEA, or for the paranoid, Tripple DES. 5089 5090Mind you, having said all that, I should mention that I just read alot and 5091implement ciphers, I'm a 'babe in the woods' when it comes to evaluating 5092ciphers :-). 5093 5094For all calls that have an 'input' and 'output' variables, they can be the 5095same. 5096 5097This library requires the inclusion of 'rc2.h'. 5098 5099All of the encryption functions take what is called an RC2_KEY as an 5100argument. An RC2_KEY is an expanded form of the RC2 key. 5101For all modes of the RC2 algorithm, the RC2_KEY used for 5102decryption is the same one that was used for encryption. 5103 5104The define RC2_ENCRYPT is passed to specify encryption for the functions 5105that require an encryption/decryption flag. RC2_DECRYPT is passed to 5106specify decryption. 5107 5108Please note that any of the encryption modes specified in my DES library 5109could be used with RC2. I have only implemented ecb, cbc, cfb64 and 5110ofb64 for the following reasons. 5111- ecb is the basic RC2 encryption. 5112- cbc is the normal 'chaining' form for block ciphers. 5113- cfb64 can be used to encrypt single characters, therefore input and output 5114 do not need to be a multiple of 8. 5115- ofb64 is similar to cfb64 but is more like a stream cipher, not as 5116 secure (not cipher feedback) but it does not have an encrypt/decrypt mode. 5117- If you want triple RC2, thats 384 bits of key and you must be totally 5118 obsessed with security. Still, if you want it, it is simple enough to 5119 copy the function from the DES library and change the des_encrypt to 5120 RC2_encrypt; an exercise left for the paranoid reader :-). 5121 5122The functions are as follows: 5123 5124void RC2_set_key( 5125RC2_KEY *ks; 5126int len; 5127unsigned char *key; 5128int bits; 5129 RC2_set_key converts an 'len' byte key into a RC2_KEY. 5130 A 'ks' is an expanded form of the 'key' which is used to 5131 perform actual encryption. It can be regenerated from the RC2 key 5132 so it only needs to be kept when encryption or decryption is about 5133 to occur. Don't save or pass around RC2_KEY's since they 5134 are CPU architecture dependent, 'key's are not. RC2 is an 5135 interesting cipher in that it can be used with a variable length 5136 key. 'len' is the length of 'key' to be used as the key. 5137 A 'len' of 16 is recomended. The 'bits' argument is an 5138 interesting addition which I only found out about in Aug 96. 5139 BSAFE uses this parameter to 'limit' the number of bits used 5140 for the key. To use the 'key' unmodified, set bits to 1024. 5141 This is what old versions of my RC2 library did (SSLeay 0.6.3). 5142 RSAs BSAFE library sets this parameter to be 128 if 128 bit 5143 keys are being used. So to be compatable with BSAFE, set it 5144 to 128, if you don't want to reduce RC2's key length, leave it 5145 at 1024. 5146 5147void RC2_encrypt( 5148unsigned long *data, 5149RC2_KEY *key, 5150int encrypt); 5151 This is the RC2 encryption function that gets called by just about 5152 every other RC2 routine in the library. You should not use this 5153 function except to implement 'modes' of RC2. I say this because the 5154 functions that call this routine do the conversion from 'char *' to 5155 long, and this needs to be done to make sure 'non-aligned' memory 5156 access do not occur. 5157 Data is a pointer to 2 unsigned long's and key is the 5158 RC2_KEY to use. Encryption or decryption is indicated by 'encrypt'. 5159 which can have the values RC2_ENCRYPT or RC2_DECRYPT. 5160 5161void RC2_ecb_encrypt( 5162unsigned char *in, 5163unsigned char *out, 5164RC2_KEY *key, 5165int encrypt); 5166 This is the basic Electronic Code Book form of RC2 (in DES this 5167 mode is called Electronic Code Book so I'm going to use the term 5168 for rc2 as well. 5169 Input is encrypted into output using the key represented by 5170 key. Depending on the encrypt, encryption or 5171 decryption occurs. Input is 8 bytes long and output is 8 bytes. 5172 5173void RC2_cbc_encrypt( 5174unsigned char *in, 5175unsigned char *out, 5176long length, 5177RC2_KEY *ks, 5178unsigned char *ivec, 5179int encrypt); 5180 This routine implements RC2 in Cipher Block Chaining mode. 5181 Input, which should be a multiple of 8 bytes is encrypted 5182 (or decrypted) to output which will also be a multiple of 8 bytes. 5183 The number of bytes is in length (and from what I've said above, 5184 should be a multiple of 8). If length is not a multiple of 8, bad 5185 things will probably happen. ivec is the initialisation vector. 5186 This function updates iv after each call so that it can be passed to 5187 the next call to RC2_cbc_encrypt(). 5188 5189void RC2_cfb64_encrypt( 5190unsigned char *in, 5191unsigned char *out, 5192long length, 5193RC2_KEY *schedule, 5194unsigned char *ivec, 5195int *num, 5196int encrypt); 5197 This is one of the more useful functions in this RC2 library, it 5198 implements CFB mode of RC2 with 64bit feedback. 5199 This allows you to encrypt an arbitrary number of bytes, 5200 you do not require 8 byte padding. Each call to this 5201 routine will encrypt the input bytes to output and then update ivec 5202 and num. Num contains 'how far' we are though ivec. 5203 'Encrypt' is used to indicate encryption or decryption. 5204 CFB64 mode operates by using the cipher to generate a stream 5205 of bytes which is used to encrypt the plain text. 5206 The cipher text is then encrypted to generate the next 64 bits to 5207 be xored (incrementally) with the next 64 bits of plain 5208 text. As can be seen from this, to encrypt or decrypt, 5209 the same 'cipher stream' needs to be generated but the way the next 5210 block of data is gathered for encryption is different for 5211 encryption and decryption. 5212 5213void RC2_ofb64_encrypt( 5214unsigned char *in, 5215unsigned char *out, 5216long length, 5217RC2_KEY *schedule, 5218unsigned char *ivec, 5219int *num); 5220 This functions implements OFB mode of RC2 with 64bit feedback. 5221 This allows you to encrypt an arbitrary number of bytes, 5222 you do not require 8 byte padding. Each call to this 5223 routine will encrypt the input bytes to output and then update ivec 5224 and num. Num contains 'how far' we are though ivec. 5225 This is in effect a stream cipher, there is no encryption or 5226 decryption mode. 5227 5228For reading passwords, I suggest using des_read_pw_string() from my DES library. 5229To generate a password from a text string, I suggest using MD5 (or MD2) to 5230produce a 16 byte message digest that can then be passed directly to 5231RC2_set_key(). 5232 5233===== 5234For more information about the specific RC2 modes in this library 5235(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the 5236documentation on my DES library. What is said about DES is directly 5237applicable for RC2. 5238 5239 5240==== rc4.doc ======================================================== 5241 5242The RC4 library. 5243RC4 is a stream cipher that operates on a byte stream. It can be used with 5244any length key but I would recommend normally using 16 bytes. 5245 5246This library requires the inclusion of 'rc4.h'. 5247 5248The RC4 encryption function takes what is called an RC4_KEY as an argument. 5249The RC4_KEY is generated by the RC4_set_key function from the key bytes. 5250 5251RC4, being a stream cipher, does not have an encryption or decryption mode. 5252It produces a stream of bytes that the input stream is xor'ed against and 5253so decryption is just a case of 'encrypting' again with the same key. 5254 5255I have only put in one 'mode' for RC4 which is the normal one. This means 5256there is no initialisation vector and there is no feedback of the cipher 5257text into the cipher. This implies that you should not ever use the 5258same key twice if you can help it. If you do, you leave yourself open to 5259known plain text attacks; if you know the plain text and 5260corresponding cipher text in one message, all messages that used the same 5261key can have the cipher text decoded for the corresponding positions in the 5262cipher stream. 5263 5264The main positive feature of RC4 is that it is a very fast cipher; about 4 5265times faster that DES. This makes it ideally suited to protocols where the 5266key is randomly chosen, like SSL. 5267 5268The functions are as follows: 5269 5270void RC4_set_key( 5271RC4_KEY *key; 5272int len; 5273unsigned char *data); 5274 This function initialises the RC4_KEY structure with the key passed 5275 in 'data', which is 'len' bytes long. The key data can be any 5276 length but 16 bytes seems to be a good number. 5277 5278void RC4( 5279RC4_KEY *key; 5280unsigned long len; 5281unsigned char *in; 5282unsigned char *out); 5283 Do the actual RC4 encryption/decryption. Using the 'key', 'len' 5284 bytes are transformed from 'in' to 'out'. As mentioned above, 5285 decryption is the operation as encryption. 5286 5287==== ref.doc ======================================================== 5288 5289I have lots more references etc, and will update this list in the future, 529030 Aug 1996 - eay 5291 5292 5293SSL The SSL Protocol - from Netscapes. 5294 5295RC4 Newsgroups: sci.crypt 5296 From: sterndark@netcom.com (David Sterndark) 5297 Subject: RC4 Algorithm revealed. 5298 Message-ID: <sternCvKL4B.Hyy@netcom.com> 5299 5300RC2 Newsgroups: sci.crypt 5301 From: pgut01@cs.auckland.ac.nz (Peter Gutmann) 5302 Subject: Specification for Ron Rivests Cipher No.2 5303 Message-ID: <4fk39f$f70@net.auckland.ac.nz> 5304 5305MD2 RFC1319 The MD2 Message-Digest Algorithm 5306MD5 RFC1321 The MD5 Message-Digest Algorithm 5307 5308X509 Certificates 5309 RFC1421 Privacy Enhancement for Internet Electronic Mail: Part I 5310 RFC1422 Privacy Enhancement for Internet Electronic Mail: Part II 5311 RFC1423 Privacy Enhancement for Internet Electronic Mail: Part III 5312 RFC1424 Privacy Enhancement for Internet Electronic Mail: Part IV 5313 5314RSA and various standard encoding 5315 PKCS#1 RSA Encryption Standard 5316 PKCS#5 Password-Based Encryption Standard 5317 PKCS#7 Cryptographic Message Syntax Standard 5318 A Layman's Guide to a Subset of ASN.1, BER, and DER 5319 An Overview of the PKCS Standards 5320 Some Examples of the PKCS Standards 5321 5322IDEA Chapter 3 The Block Cipher IDEA 5323 5324RSA, prime number generation and bignum algorithms 5325 Introduction To Algorithms, 5326 Thomas Cormen, Charles Leiserson, Ronald Rivest, 5327 Section 29 Arithmetic Circuits 5328 Section 33 Number-Theoretic Algorithms 5329 5330Fast Private Key algorithm 5331 Fast Decipherment Algorithm for RSA Public-Key Cryptosystem 5332 J.-J. Quisquater and C. Couvreur, Electronics Letters, 5333 14th October 1982, Vol. 18 No. 21 5334 5335Prime number generation and bignum algorithms. 5336 PGP-2.3a 5337 5338==== rsa.doc ======================================================== 5339 5340The RSA encryption and utility routines. 5341 5342The RSA routines are built on top of a big number library (the BN library). 5343There are support routines in the X509 library for loading and manipulating 5344the various objects in the RSA library. When errors are returned, read 5345about the ERR library for how to access the error codes. 5346 5347All RSA encryption is done according to the PKCS-1 standard which is 5348compatible with PEM and RSAref. This means that any values being encrypted 5349must be less than the size of the modulus in bytes, minus 10, bytes long. 5350 5351This library uses RAND_bytes()() for it's random data, make sure to feed 5352RAND_seed() with lots of interesting and varied data before using these 5353routines. 5354 5355The RSA library has one specific data type, the RSA structure. 5356It is composed of 8 BIGNUM variables (see the BN library for details) and 5357can hold either a private RSA key or a public RSA key. 5358Some RSA libraries have different structures for public and private keys, I 5359don't. For my libraries, a public key is determined by the fact that the 5360RSA->d value is NULL. These routines will operate on any size RSA keys. 5361While I'm sure 4096 bit keys are very very secure, they take a lot longer 5362to process that 1024 bit keys :-). 5363 5364The function in the RSA library are as follows. 5365 5366RSA *RSA_new(); 5367 This function creates a new RSA object. The sub-fields of the RSA 5368 type are also malloced so you should always use this routine to 5369 create RSA variables. 5370 5371void RSA_free( 5372RSA *rsa); 5373 This function 'frees' an RSA structure. This routine should always 5374 be used to free the RSA structure since it will also 'free' any 5375 sub-fields of the RSA type that need freeing. 5376 5377int RSA_size( 5378RSA *rsa); 5379 This function returns the size of the RSA modulus in bytes. Why do 5380 I need this you may ask, well the reason is that when you encrypt 5381 with RSA, the output string will be the size of the RSA modulus. 5382 So the output for the RSA_encrypt and the input for the RSA_decrypt 5383 routines need to be RSA_size() bytes long, because this is how many 5384 bytes are expected. 5385 5386For the following 4 RSA encryption routines, it should be noted that 5387RSA_private_decrypt() should be used on the output from 5388RSA_public_encrypt() and RSA_public_decrypt() should be used on 5389the output from RSA_private_encrypt(). 5390 5391int RSA_public_encrypt( 5392int from_len; 5393unsigned char *from 5394unsigned char *to 5395RSA *rsa); 5396 This function implements RSA public encryption, the rsa variable 5397 should be a public key (but can be a private key). 'from_len' 5398 bytes taken from 'from' and encrypted and put into 'to'. 'to' needs 5399 to be at least RSA_size(rsa) bytes long. The number of bytes 5400 written into 'to' is returned. -1 is returned on an error. The 5401 operation performed is 5402 to = from^rsa->e mod rsa->n. 5403 5404int RSA_private_encrypt( 5405int from_len; 5406unsigned char *from 5407unsigned char *to 5408RSA *rsa); 5409 This function implements RSA private encryption, the rsa variable 5410 should be a private key. 'from_len' bytes taken from 5411 'from' and encrypted and put into 'to'. 'to' needs 5412 to be at least RSA_size(rsa) bytes long. The number of bytes 5413 written into 'to' is returned. -1 is returned on an error. The 5414 operation performed is 5415 to = from^rsa->d mod rsa->n. 5416 5417int RSA_public_decrypt( 5418int from_len; 5419unsigned char *from 5420unsigned char *to 5421RSA *rsa); 5422 This function implements RSA public decryption, the rsa variable 5423 should be a public key (but can be a private key). 'from_len' 5424 bytes are taken from 'from' and decrypted. The decrypted data is 5425 put into 'to'. The number of bytes encrypted is returned. -1 is 5426 returned to indicate an error. The operation performed is 5427 to = from^rsa->e mod rsa->n. 5428 5429int RSA_private_decrypt( 5430int from_len; 5431unsigned char *from 5432unsigned char *to 5433RSA *rsa); 5434 This function implements RSA private decryption, the rsa variable 5435 should be a private key. 'from_len' bytes are taken 5436 from 'from' and decrypted. The decrypted data is 5437 put into 'to'. The number of bytes encrypted is returned. -1 is 5438 returned to indicate an error. The operation performed is 5439 to = from^rsa->d mod rsa->n. 5440 5441int RSA_mod_exp( 5442BIGNUM *n; 5443BIGNUM *p; 5444RSA *rsa); 5445 Normally you will never use this routine. 5446 This is really an internal function which is called by 5447 RSA_private_encrypt() and RSA_private_decrypt(). It performs 5448 n=n^p mod rsa->n except that it uses the 5 extra variables in the 5449 RSA structure to make this more efficient. 5450 5451RSA *RSA_generate_key( 5452int bits; 5453unsigned long e; 5454void (*callback)(); 5455char *cb_arg; 5456 This routine is used to generate RSA private keys. It takes 5457 quite a period of time to run and should only be used to 5458 generate initial private keys that should then be stored 5459 for later use. The passed callback function 5460 will be called periodically so that feedback can be given 5461 as to how this function is progressing. 5462 'bits' is the length desired for the modulus, so it would be 1024 5463 to generate a 1024 bit private key. 5464 'e' is the value to use for the public exponent 'e'. Traditionally 5465 it is set to either 3 or 0x10001. 5466 The callback function (if not NULL) is called in the following 5467 situations. 5468 when we have generated a suspected prime number to test, 5469 callback(0,num1++,cb_arg). When it passes a prime number test, 5470 callback(1,num2++,cb_arg). When it is rejected as one of 5471 the 2 primes required due to gcd(prime,e value) != 0, 5472 callback(2,num3++,cb_arg). When finally accepted as one 5473 of the 2 primes, callback(3,num4++,cb_arg). 5474 5475 5476==== rsaref.doc ======================================================== 5477 5478This package can be compiled to use the RSAref library. 5479This library is not allowed outside of the USA but inside the USA it is 5480claimed by RSA to be the only RSA public key library that can be used 5481besides BSAFE.. 5482 5483There are 2 files, rsaref/rsaref.c and rsaref/rsaref.h that contain the glue 5484code to use RSAref. These files were written by looking at the PGP 5485source code and seeing which routines it used to access RSAref. 5486I have also been sent by some-one a copy of the RSAref header file that 5487contains the library error codes. 5488 5489[ Jun 1996 update - I have recently gotten hold of RSAref 2.0 from 5490 South Africa and have been doing some performace tests. ] 5491 5492They have now been tested against the recently announced RSAEURO 5493library. 5494 5495There are 2 ways to use SSLeay and RSAref. First, to build so that 5496the programs must be linked with RSAref, add '-DRSAref' to CFLAG in the top 5497level makefile and -lrsaref (or where ever you are keeping RSAref) to 5498EX_LIBS. 5499 5500To build a makefile via util/mk1mf.pl to do this, use the 'rsaref' option. 5501 5502The second method is to build as per normal and link applications with 5503the RSAglue library. The correct library order would be 5504cc -o cmd cmd.o -lssl -lRSAglue -lcrypto -lrsaref -ldes 5505The RSAglue library is built in the rsa directory and is NOT 5506automatically installed. 5507 5508Be warned that the RSAEURO library, that is claimed to be compatible 5509with RSAref contains a different value for the maximum number of bits 5510supported. This changes structure sizes and so if you are using 5511RSAEURO, change the value of RSAref_MAX_BITS in rsa/rsaref.h 5512 5513 5514==== s_mult.doc ======================================================== 5515 5516s_mult is a test program I hacked up on a Sunday for testing non-blocking 5517IO. It has a select loop at it's centre that handles multiple readers 5518and writers. 5519 5520Try the following command 5521ssleay s_mult -echo -nbio -ssl -v 5522echo - sends any sent text back to the sender 5523nbio - turns on non-blocking IO 5524ssl - accept SSL connections, default is normal text 5525v - print lots 5526 type Q<cr> to quit 5527 5528In another window, run the following 5529ssleay s_client -pause </etc/termcap 5530 5531The pause option puts in a 1 second pause in each read(2)/write(2) call 5532so the other end will have read()s fail. 5533 5534==== session.doc ======================================================== 5535 5536I have just checked over and re-worked the session stuff. 5537The following brief example will ignore all setup information to do with 5538authentication. 5539 5540Things operate as follows. 5541 5542The SSL environment has a 'context', a SSL_CTX structure. This holds the 5543cached SSL_SESSIONS (which can be reused) and the certificate lookup 5544information. Each SSL structure needs to be associated with a SSL_CTX. 5545Normally only one SSL_CTX structure is needed per program. 5546 5547SSL_CTX *SSL_CTX_new(void ); 5548void SSL_CTX_free(SSL_CTX *); 5549These 2 functions create and destroy SSL_CTX structures 5550 5551The SSL_CTX has a session_cache_mode which is by default, 5552in SSL_SESS_CACHE_SERVER mode. What this means is that the library 5553will automatically add new session-id's to the cache apon sucsessful 5554SSL_accept() calls. 5555If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added 5556to the cache. 5557SSL_set_session_cache_mode(ctx,mode) will set the 'mode' and 5558SSL_get_session_cache_mode(ctx) will get the cache 'mode'. 5559The modes can be 5560SSL_SESS_CACHE_OFF - no caching 5561SSL_SESS_CACHE_CLIENT - only SSL_connect() 5562SSL_SESS_CACHE_SERVER - only SSL_accept() 5563SSL_SESS_NO_CACHE_BOTH - Either SSL_accept() or SSL_connect(). 5564If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are 5565not automatically removed each 255, SSL_connect()s or SSL_accept()s. 5566 5567By default, apon every 255 successful SSL_connect() or SSL_accept()s, 5568the cache is flush. Please note that this could be expensive on 5569a heavily loaded SSL server, in which case, turn this off and 5570clear the cache of old entries 'manually' (with one of the functions 5571listed below) every few hours. Perhaps I should up this number, it is hard 5572to say. Remember, the '255' new calls is just a mechanims to get called 5573every now and then, in theory at most 255 new session-id's will have been 5574added but if 100 are added every minute, you would still have 5575500 in the cache before any would start being flushed (assuming a 3 minute 5576timeout).. 5577 5578int SSL_CTX_sess_hits(SSL_CTX *ctx); 5579int SSL_CTX_sess_misses(SSL_CTX *ctx); 5580int SSL_CTX_sess_timeouts(SSL_CTX *ctx); 5581These 3 functions return statistics about the SSL_CTX. These 3 are the 5582number of session id reuses. hits is the number of reuses, misses are the 5583number of lookups that failed, and timeouts is the number of cached 5584entries ignored because they had timeouted. 5585 5586ctx->new_session_cb is a function pointer to a function of type 5587int new_session_callback(SSL *ssl,SSL_SESSION *new); 5588This function, if set in the SSL_CTX structure is called whenever a new 5589SSL_SESSION is added to the cache. If the callback returns non-zero, it 5590means that the application will have to do a SSL_SESSION_free() 5591on the structure (this is 5592to do with the cache keeping the reference counts correct, without the 5593application needing to know about it. 5594The 'active' parameter is the current SSL session for which this connection 5595was created. 5596 5597void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,int (*cb)()); 5598to set the callback, 5599int (*cb)() SSL_CTX_sess_get_new_cb(SSL_CTX *ctx) 5600to get the callback. 5601 5602If the 'get session' callback is set, when a session id is looked up and 5603it is not in the session-id cache, this callback is called. The callback is 5604of the form 5605SSL_SESSION *get_session_callback(unsigned char *sess_id,int sess_id_len, 5606 int *copy); 5607 5608The get_session_callback is intended to return null if no session id is found. 5609The reference count on the SSL_SESSION in incremented by the SSL library, 5610if copy is 1. Otherwise, the reference count is not modified. 5611 5612void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and 5613int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback. 5614 5615These callbacks are basically indended to be used by processes to 5616send their session-id's to other processes. I currently have not implemented 5617non-blocking semantics for these callbacks, it is upto the appication 5618to make the callbacks effiecent if they require blocking (perhaps 5619by 'saving' them and then 'posting them' when control returns from 5620the SSL_accept(). 5621 5622LHASH *SSL_CTX_sessions(SSL_CTX *ctx) 5623This returns the session cache. The lhash strucutre can be accessed for 5624statistics about the cache. 5625 5626void lh_stats(LHASH *lh, FILE *out); 5627void lh_node_stats(LHASH *lh, FILE *out); 5628void lh_node_usage_stats(LHASH *lh, FILE *out); 5629 5630can be used to print details about it's activity and current state. 5631You can also delve directly into the lhash structure for 14 different 5632counters that are kept against the structure. When I wrote the lhash library, 5633I was interested in gathering statistics :-). 5634Have a read of doc/lhash.doc in the SSLeay distribution area for more details 5635on the lhash library. 5636 5637Now as mentioned ealier, when a SSL is created, it needs a SSL_CTX. 5638SSL * SSL_new(SSL_CTX *); 5639 5640This stores a session. A session is secret information shared between 2 5641SSL contexts. It will only be created if both ends of the connection have 5642authenticated their peer to their satisfaction. It basically contains 5643the information required to use a particular secret key cipher. 5644 5645To retrieve the SSL_CTX being used by a SSL, 5646SSL_CTX *SSL_get_SSL_CTX(SSL *s); 5647 5648Now when a SSL session is established between to programs, the 'session' 5649information that is cached in the SSL_CTX can me manipulated by the 5650following functions. 5651int SSL_set_session(SSL *s, SSL_SESSION *session); 5652This will set the SSL_SESSION to use for the next SSL_connect(). If you use 5653this function on an already 'open' established SSL connection, 'bad things 5654will happen'. This function is meaning-less when used on a ssl strucutre 5655that is just about to be used in a SSL_accept() call since the 5656SSL_accept() will either create a new session or retrieve one from the 5657cache. 5658 5659SSL_SESSION *SSL_get_session(SSL *s); 5660This will return the SSL_SESSION for the current SSL, NULL if there is 5661no session associated with the SSL structure. 5662 5663The SSL sessions are kept in the SSL_CTX in a hash table, to remove a 5664session 5665void SSL_CTX_remove_session(SSL_CTX *,SSL_SESSION *c); 5666and to add one 5667int SSL_CTX_add_session(SSL_CTX *s, SSL_SESSION *c); 5668SSL_CTX_add_session() returns 1 if the session was already in the cache (so it 5669was not added). 5670Whenever a new session is created via SSL_connect()/SSL_accept(), 5671they are automatically added to the cache, depending on the session_cache_mode 5672settings. SSL_set_session() 5673does not add it to the cache. Just call SSL_CTX_add_session() if you do want the 5674session added. For a 'client' this would not normally be the case. 5675SSL_CTX_add_session() is not normally ever used, except for doing 'evil' things 5676which the next 2 funtions help you do. 5677 5678int i2d_SSL_SESSION(SSL_SESSION *in,unsigned char **pp); 5679SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a,unsigned char **pp,long length); 5680These 2 functions are in the standard ASN1 library form and can be used to 5681load and save to a byte format, the SSL_SESSION structure. 5682With these functions, you can save and read these structures to a files or 5683arbitary byte string. 5684The PEM_write_SSL_SESSION(fp,x) and PEM_read_SSL_SESSION(fp,x,cb) will 5685write to a file pointer in base64 encoding. 5686 5687What you can do with this, is pass session information between separate 5688processes. Please note, that you will probably also need to modify the 5689timeout information on the SSL_SESSIONs. 5690 5691long SSL_get_time(SSL_SESSION *s) 5692will return the 'time' that the session 5693was loaded. The timeout is relative to this time. This information is 5694saved when the SSL_SESSION is converted to binarary but it is stored 5695in as a unix long, which is rather OS dependant, but easy to convert back. 5696 5697long SSL_set_time(SSL_SESSION *s,long t) will set the above mentioned time. 5698The time value is just the value returned from time(3), and should really 5699be defined by be to be time_t. 5700 5701long SSL_get_timeout(SSL_SESSION *s); 5702long SSL_set_timeout(SSL_SESSION *s,long t); 5703These 2 retrieve and set the timeout which is just a number of secconds 5704from the 'SSL_get_time()' value. When this time period has elapesed, 5705the session will no longer be in the cache (well it will actually be removed 5706the next time it is attempted to be retrieved, so you could 'bump' 5707the timeout so it remains valid). 5708The 'time' and 'timeout' are set on a session when it is created, not reset 5709each time it is reused. If you did wish to 'bump it', just after establishing 5710a connection, do a 5711SSL_set_time(ssl,time(NULL)); 5712 5713You can also use 5714SSL_CTX_set_timeout(SSL_CTX *ctx,unsigned long t) and 5715SSL_CTX_get_timeout(SSL_CTX *ctx) to manipulate the default timeouts for 5716all SSL connections created against a SSL_CTX. If you set a timeout in 5717an SSL_CTX, all new SSL's created will inherit the timeout. It can be over 5718written by the SSL_set_timeout(SSL *s,unsigned long t) function call. 5719If you 'set' the timeout back to 0, the system default will be used. 5720 5721SSL_SESSION *SSL_SESSION_new(); 5722void SSL_SESSION_free(SSL_SESSION *ses); 5723These 2 functions are used to create and dispose of SSL_SESSION functions. 5724You should not ever normally need to use them unless you are using 5725i2d_SSL_SESSION() and/or d2i_SSL_SESSION(). If you 'load' a SSL_SESSION 5726via d2i_SSL_SESSION(), you will need to SSL_SESSION_free() it. 5727Both SSL_set_session() and SSL_CTX_add_session() will 'take copies' of the 5728structure (via reference counts) when it is passed to them. 5729 5730SSL_CTX_flush_sessions(ctx,time); 5731The first function will clear all sessions from the cache, which have expired 5732relative to 'time' (which could just be time(NULL)). 5733 5734SSL_CTX_flush_sessions(ctx,0); 5735This is a special case that clears everything. 5736 5737As a final comment, a 'session' is not enough to establish a new 5738connection. If a session has timed out, a certificate and private key 5739need to have been associated with the SSL structure. 5740SSL_copy_session_id(SSL *to,SSL *from); will copy not only the session 5741strucutre but also the private key and certificate associated with 5742'from'. 5743 5744EXAMPLES. 5745 5746So lets play at being a wierd SSL server. 5747 5748/* setup a context */ 5749ctx=SSL_CTX_new(); 5750 5751/* Lets load some session from binary into the cache, why one would do 5752 * this is not toally clear, but passing between programs does make sense 5753 * Perhaps you are using 4096 bit keys and are happy to keep them 5754 * valid for a week, to avoid the RSA overhead of 15 seconds, I'm not toally 5755 * sure, perhaps this is a process called from an SSL inetd and this is being 5756 * passed to the application. */ 5757session=d2i_SSL_SESSION(....) 5758SSL_CTX_add_session(ctx,session); 5759 5760/* Lets even add a session from a file */ 5761session=PEM_read_SSL_SESSION(....) 5762SSL_CTX_add_session(ctx,session); 5763 5764/* create a new SSL structure */ 5765ssl=SSL_new(ctx); 5766 5767/* At this point we want to be able to 'create' new session if 5768 * required, so we need a certificate and RSAkey. */ 5769SSL_use_RSAPrivateKey_file(ssl,...) 5770SSL_use_certificate_file(ssl,...) 5771 5772/* Now since we are a server, it make little sence to load a session against 5773 * the ssl strucutre since a SSL_accept() will either create a new session or 5774 * grab an existing one from the cache. */ 5775 5776/* grab a socket descriptor */ 5777fd=accept(...); 5778 5779/* associated it with the ssl strucutre */ 5780SSL_set_fd(ssl,fd); 5781 5782SSL_accept(ssl); /* 'do' SSL using out cert and RSA key */ 5783 5784/* Lets print out the session details or lets save it to a file, 5785 * perhaps with a secret key cipher, so that we can pass it to the FBI 5786 * when they want to decode the session :-). While we have RSA 5787 * this does not matter much but when I do SSLv3, this will allow a mechanism 5788 * for the server/client to record the information needed to decode 5789 * the traffic that went over the wire, even when using Diffie-Hellman */ 5790PEM_write_SSL_SESSION(SSL_get_session(ssl),stdout,....) 5791 5792Lets 'connect' back to the caller using the same session id. 5793 5794ssl2=SSL_new(ctx); 5795fd2=connect(them); 5796SSL_set_fd(ssl2,fd2); 5797SSL_set_session(ssl2,SSL_get_session(ssl)); 5798SSL_connect(ssl2); 5799 5800/* what the hell, lets accept no more connections using this session */ 5801SSL_CTX_remove_session(SSL_get_SSL_CTX(ssl),SSL_get_session(ssl)); 5802 5803/* we could have just as easily used ssl2 since they both are using the 5804 * same session. 5805 * You will note that both ssl and ssl2 are still using the session, and 5806 * the SSL_SESSION structure will be free()ed when both ssl and ssl2 5807 * finish using the session. Also note that you could continue to initiate 5808 * connections using this session by doing SSL_get_session(ssl) to get the 5809 * existing session, but SSL_accept() will not be able to find it to 5810 * use for incoming connections. 5811 * Of corse, the session will timeout at the far end and it will no 5812 * longer be accepted after a while. The time and timeout are ignored except 5813 * by SSL_accept(). */ 5814 5815/* Since we have had our server running for 10 weeks, and memory is getting 5816 * short, perhaps we should clear the session cache to remove those 5817 * 100000 session entries that have expired. Some may consider this 5818 * a memory leak :-) */ 5819 5820SSL_CTX_flush_sessions(ctx,time(NULL)); 5821 5822/* Ok, after a bit more time we wish to flush all sessions from the cache 5823 * so that all new connections will be authenticated and incure the 5824 * public key operation overhead */ 5825 5826SSL_CTX_flush_sessions(ctx,0); 5827 5828/* As a final note, to copy everything to do with a SSL, use */ 5829SSL_copy_session_id(SSL *to,SSL *from); 5830/* as this also copies the certificate and RSA key so new session can 5831 * be established using the same details */ 5832 5833 5834==== sha.doc ======================================================== 5835 5836The SHA (Secure Hash Algorithm) library. 5837SHA is a message digest algorithm that can be used to condense an arbitrary 5838length message down to a 20 byte hash. The functions all need to be passed 5839a SHA_CTX which is used to hold the SHA context during multiple SHA_Update() 5840function calls. The normal method of use for this library is as follows 5841This library contains both SHA and SHA-1 digest algorithms. SHA-1 is 5842an update to SHA (which should really be called SHA-0 now) which 5843tweaks the algorithm slightly. The SHA-1 algorithm is used by simply 5844using SHA1_Init(), SHA1_Update(), SHA1_Final() and SHA1() instead of the 5845SHA*() calls 5846 5847SHA_Init(...); 5848SHA_Update(...); 5849... 5850SHA_Update(...); 5851SHA_Final(...); 5852 5853This library requires the inclusion of 'sha.h'. 5854 5855The functions are as follows: 5856 5857void SHA_Init( 5858SHA_CTX *c); 5859 This function needs to be called to initiate a SHA_CTX structure for 5860 use. 5861 5862void SHA_Update( 5863SHA_CTX *c; 5864unsigned char *data; 5865unsigned long len); 5866 This updates the message digest context being generated with 'len' 5867 bytes from the 'data' pointer. The number of bytes can be any 5868 length. 5869 5870void SHA_Final( 5871unsigned char *md; 5872SHA_CTX *c; 5873 This function is called when a message digest of the data digested 5874 with SHA_Update() is wanted. The message digest is put in the 'md' 5875 array and is SHA_DIGEST_LENGTH (20) bytes long. 5876 5877unsigned char *SHA( 5878unsigned char *d; 5879unsigned long n; 5880unsigned char *md; 5881 This function performs a SHA_Init(), followed by a SHA_Update() 5882 followed by a SHA_Final() (using a local SHA_CTX). 5883 The resulting digest is put into 'md' if it is not NULL. 5884 Regardless of the value of 'md', the message 5885 digest is returned from the function. If 'md' was NULL, the message 5886 digest returned is being stored in a static structure. 5887 5888 5889==== speed.doc ======================================================== 5890 5891To get an idea of the performance of this library, use 5892ssleay speed 5893 5894perl util/sp-diff.pl file1 file2 5895 5896will print out the relative differences between the 2 files which are 5897expected to be the output from the speed program. 5898 5899The performace of the library is very dependant on the Compiler 5900quality and various flags used to build. 5901 5902--- 5903 5904These are some numbers I did comparing RSAref and SSLeay on a Pentium 100. 5905[ These numbers are all out of date, as of SSL - 0.6.1 the RSA 5906operations are about 2 times faster, so check the version number ] 5907 5908RSA performance. 5909 5910SSLeay 0.6.0 5911Pentium 100, 32meg, Windows NT Workstation 3.51 5912linux - gcc v 2.7.0 -O3 -fomit-frame-pointer -m486 5913and 5914Windows NT - Windows NT 3.51 - Visual C++ 4.1 - 586 code + 32bit assember 5915Windows 3.1 - Windows NT 3.51 - Visual C++ 1.52c - 286 code + 32bit assember 5916NT Dos Shell- Windows NT 3.51 - Visual C++ 1.52c - 286 code + 16bit assember 5917 5918Times are how long it takes to do an RSA private key operation. 5919 5920 512bits 1024bits 5921------------------------------- 5922SSLeay NT dll 0.042s 0.202s see above 5923SSLeay linux 0.046s 0.218s Assember inner loops (normal build) 5924SSLeay linux 0.067s 0.380s Pure C code with BN_LLONG defined 5925SSLeay W3.1 dll 0.108s 0.478s see above 5926SSLeay linux 0.109s 0.713s C without BN_LLONG. 5927RSAref2.0 linux 0.149s 0.936s 5928SSLeay MS-DOS 0.197s 1.049s see above 5929 5930486DX66, 32meg, Windows NT Server 3.51 5931 512bits 1024bits 5932------------------------------- 5933SSLeay NT dll 0.084s 0.495s <- SSLeay 0.6.3 5934SSLeay NT dll 0.154s 0.882s 5935SSLeay W3.1 dll 0.335s 1.538s 5936SSLeay MS-DOS 0.490s 2.790s 5937 5938What I find cute is that I'm still faster than RSAref when using standard C, 5939without using the 'long long' data type :-), %35 faster for 512bit and we 5940scale up to 3.2 times faster for the 'default linux' build. I should mention 5941that people should 'try' to use either x86-lnx.s (elf), x86-lnxa.s or 5942x86-sol.s for any x86 based unix they are building on. The only problems 5943with be with syntax but the performance gain is quite large, especially for 5944servers. The code is very simple, you just need to modify the 'header'. 5945 5946The message is, if you are stuck using RSAref, the RSA performance will be 5947bad. Considering the code was compiled for a pentium, the 486DX66 number 5948would indicate 'Use RSAref and turn you Pentium 100 into a 486DX66' :-). 5949[ As of verson 0.6.1, it would be correct to say 'turn you pentium 100 5950 into a 486DX33' :-) ] 5951 5952I won't tell people if the DLL's are using RSAref or my stuff if no-one 5953asks :-). 5954 5955eric 5956 5957PS while I know I could speed things up further, I will probably not do 5958 so due to the effort involved. I did do some timings on the 5959 SSLeay bignum format -> RSAref number format conversion that occurs 5960 each time RSAref is used by SSLeay, and the numbers are trivial. 5961 0.00012s a call for 512bit vs 0.149s for the time spent in the function. 5962 0.00018s for 1024bit vs 0.938s. Insignificant. 5963 So the 'way to go', to support faster RSA libraries, if people are keen, 5964 is to write 'glue' code in a similar way that I do for RSAref and send it 5965 to me :-). 5966 My base library still has the advantage of being able to operate on 5967 any size numbers, and is not that far from the performance from the 5968 leaders in the field. (-%30?) 5969 [ Well as of 0.6.1 I am now the leader in the filed on x86 (we at 5970 least very close :-) ] 5971 5972 I suppose I should also mention some other numbers RSAref numbers, again 5973 on my Pentium. 5974 DES CBC EDE-DES MD5 5975 RSAref linux 830k/s 302k/s 4390k/s 5976 SSLeay linux 855k/s 319k/s 10025k/s 5977 SSLeay NT 1158k/s 410k/s 10470k/s 5978 SSLeay w31 378k/s 143k/s 2383k/s (fully 16bit) 5979 5980 Got to admit that Visual C++ 4.[01] is a damn fine compiler :-) 5981-- 5982Eric Young | BOOL is tri-state according to Bill Gates. 5983AARNet: eay@cryptsoft.com | RTFM Win32 GetMessage(). 5984 5985 5986 5987 5988==== ssl-ciph.doc ======================================================== 5989 5990This is a quick high level summery of how things work now. 5991 5992Each SSLv2 and SSLv3 cipher is composed of 4 major attributes plus a few extra 5993minor ones. 5994 5995They are 'The key exchange algorithm', which is RSA for SSLv2 but can also 5996be Diffle-Hellman for SSLv3. 5997 5998An 'Authenticion algorithm', which can be RSA, Diffle-Helman, DSS or 5999none. 6000 6001The cipher 6002 6003The MAC digest. 6004 6005A cipher can also be an export cipher and is either an SSLv2 or a 6006SSLv3 ciphers. 6007 6008To specify which ciphers to use, one can either specify all the ciphers, 6009one at a time, or use 'aliases' to specify the preference and order for 6010the ciphers. 6011 6012There are a large number of aliases, but the most importaint are 6013kRSA, kDHr, kDHd and kEDH for key exchange types. 6014 6015aRSA, aDSS, aNULL and aDH for authentication 6016DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers 6017MD5, SHA0 and SHA1 digests 6018 6019Now where this becomes interesting is that these can be put together to 6020specify the order and ciphers you wish to use. 6021 6022To speed this up there are also aliases for certian groups of ciphers. 6023The main ones are 6024SSLv2 - all SSLv2 ciphers 6025SSLv3 - all SSLv3 ciphers 6026EXP - all export ciphers 6027LOW - all low strngth ciphers (no export ciphers, normally single DES) 6028MEDIUM - 128 bit encryption 6029HIGH - Triple DES 6030 6031These aliases can be joined in a : separated list which specifies to 6032add ciphers, move them to the current location and delete them. 6033 6034A simpler way to look at all of this is to use the 'ssleay ciphers -v' command. 6035The default library cipher spec is 6036!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP 6037which means, first, remove from consideration any ciphers that do not 6038authenticate. Next up, use ciphers using RC4 and RSA. Next include the HIGH, 6039MEDIUM and the LOW security ciphers. Finish up by adding all the export 6040ciphers on the end, then 'pull' all the SSLv2 and export ciphers to 6041the end of the list. 6042 6043The results are 6044$ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP' 6045 6046RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1 6047RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 6048EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 6049EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 6050DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1 6051IDEA-CBC-MD5 SSLv3 Kx=RSA Au=RSA Enc=IDEA(128) Mac=SHA1 6052EDH-RSA-DES-CBC-SHA SSLv3 Kx=DH Au=RSA Enc=DES(56) Mac=SHA1 6053EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH Au=DSS Enc=DES(56) Mac=SHA1 6054DES-CBC-SHA SSLv3 Kx=RSA Au=RSA Enc=DES(56) Mac=SHA1 6055DES-CBC3-MD5 SSLv2 Kx=RSA Au=RSA Enc=3DES(168) Mac=MD5 6056DES-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=DES(56) Mac=MD5 6057IDEA-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=IDEA(128) Mac=MD5 6058RC2-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC2(128) Mac=MD5 6059RC4-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 6060EXP-EDH-RSA-DES-CBC SSLv3 Kx=DH(512) Au=RSA Enc=DES(40) Mac=SHA1 export 6061EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512) Au=DSS Enc=DES(40) Mac=SHA1 export 6062EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 export 6063EXP-RC2-CBC-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export 6064EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export 6065EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export 6066EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export 6067 6068I would recoment people use the 'ssleay ciphers -v "text"' 6069command to check what they are going to use. 6070 6071Anyway, I'm falling asleep here so I'll do some more tomorrow. 6072 6073eric 6074 6075==== ssl.doc ======================================================== 6076 6077SSL_CTX_sessions(SSL_CTX *ctx) - the session-id hash table. 6078 6079/* Session-id cache stats */ 6080SSL_CTX_sess_number 6081SSL_CTX_sess_connect 6082SSL_CTX_sess_connect_good 6083SSL_CTX_sess_accept 6084SSL_CTX_sess_accept_good 6085SSL_CTX_sess_hits 6086SSL_CTX_sess_cb_hits 6087SSL_CTX_sess_misses 6088SSL_CTX_sess_timeouts 6089 6090/* Session-id application notification callbacks */ 6091SSL_CTX_sess_set_new_cb 6092SSL_CTX_sess_get_new_cb 6093SSL_CTX_sess_set_get_cb 6094SSL_CTX_sess_get_get_cb 6095 6096/* Session-id cache operation mode */ 6097SSL_CTX_set_session_cache_mode 6098SSL_CTX_get_session_cache_mode 6099 6100/* Set default timeout values to use. */ 6101SSL_CTX_set_timeout 6102SSL_CTX_get_timeout 6103 6104/* Global SSL initalisation informational callback */ 6105SSL_CTX_set_info_callback 6106SSL_CTX_get_info_callback 6107SSL_set_info_callback 6108SSL_get_info_callback 6109 6110/* If the SSL_accept/SSL_connect returned with -1, these indicate when 6111 * we should re-call *. 6112SSL_want 6113SSL_want_nothing 6114SSL_want_read 6115SSL_want_write 6116SSL_want_x509_lookup 6117 6118/* Where we are in SSL initalisation, used in non-blocking, perhaps 6119 * have a look at ssl/bio_ssl.c */ 6120SSL_state 6121SSL_is_init_finished 6122SSL_in_init 6123SSL_in_connect_init 6124SSL_in_accept_init 6125 6126/* Used to set the 'inital' state so SSL_in_connect_init and SSL_in_accept_init 6127 * can be used to work out which function to call. */ 6128SSL_set_connect_state 6129SSL_set_accept_state 6130 6131/* Where to look for certificates for authentication */ 6132SSL_set_default_verify_paths /* calles SSL_load_verify_locations */ 6133SSL_load_verify_locations 6134 6135/* get info from an established connection */ 6136SSL_get_session 6137SSL_get_certificate 6138SSL_get_SSL_CTX 6139 6140SSL_CTX_new 6141SSL_CTX_free 6142SSL_new 6143SSL_clear 6144SSL_free 6145 6146SSL_CTX_set_cipher_list 6147SSL_get_cipher 6148SSL_set_cipher_list 6149SSL_get_cipher_list 6150SSL_get_shared_ciphers 6151 6152SSL_accept 6153SSL_connect 6154SSL_read 6155SSL_write 6156 6157SSL_debug 6158 6159SSL_get_read_ahead 6160SSL_set_read_ahead 6161SSL_set_verify 6162 6163SSL_pending 6164 6165SSL_set_fd 6166SSL_set_rfd 6167SSL_set_wfd 6168SSL_set_bio 6169SSL_get_fd 6170SSL_get_rbio 6171SSL_get_wbio 6172 6173SSL_use_RSAPrivateKey 6174SSL_use_RSAPrivateKey_ASN1 6175SSL_use_RSAPrivateKey_file 6176SSL_use_PrivateKey 6177SSL_use_PrivateKey_ASN1 6178SSL_use_PrivateKey_file 6179SSL_use_certificate 6180SSL_use_certificate_ASN1 6181SSL_use_certificate_file 6182 6183ERR_load_SSL_strings 6184SSL_load_error_strings 6185 6186/* human readable version of the 'state' of the SSL connection. */ 6187SSL_state_string 6188SSL_state_string_long 6189/* These 2 report what kind of IO operation the library was trying to 6190 * perform last. Probably not very usefull. */ 6191SSL_rstate_string 6192SSL_rstate_string_long 6193 6194SSL_get_peer_certificate 6195 6196SSL_SESSION_new 6197SSL_SESSION_print_fp 6198SSL_SESSION_print 6199SSL_SESSION_free 6200i2d_SSL_SESSION 6201d2i_SSL_SESSION 6202 6203SSL_get_time 6204SSL_set_time 6205SSL_get_timeout 6206SSL_set_timeout 6207SSL_copy_session_id 6208SSL_set_session 6209SSL_CTX_add_session 6210SSL_CTX_remove_session 6211SSL_CTX_flush_sessions 6212 6213BIO_f_ssl 6214 6215/* used to hold information as to why a certificate verification failed */ 6216SSL_set_verify_result 6217SSL_get_verify_result 6218 6219/* can be used by the application to associate data with an SSL structure. 6220 * It needs to be 'free()ed' by the application */ 6221SSL_set_app_data 6222SSL_get_app_data 6223 6224/* The following all set values that are kept in the SSL_CTX but 6225 * are used as the default values when an SSL session is created. 6226 * They are over writen by the relevent SSL_xxxx functions */ 6227 6228/* SSL_set_verify */ 6229void SSL_CTX_set_default_verify 6230 6231/* This callback, if set, totaly overrides the normal SSLeay verification 6232 * functions and should return 1 on sucesss and 0 on failure */ 6233void SSL_CTX_set_cert_verify_callback 6234 6235/* The following are the same as the equivilent SSL_xxx functions. 6236 * Only one copy of this information is kept and if a particular 6237 * SSL structure has a local override, it is totally separate structure. 6238 */ 6239int SSL_CTX_use_RSAPrivateKey 6240int SSL_CTX_use_RSAPrivateKey_ASN1 6241int SSL_CTX_use_RSAPrivateKey_file 6242int SSL_CTX_use_PrivateKey 6243int SSL_CTX_use_PrivateKey_ASN1 6244int SSL_CTX_use_PrivateKey_file 6245int SSL_CTX_use_certificate 6246int SSL_CTX_use_certificate_ASN1 6247int SSL_CTX_use_certificate_file 6248 6249 6250==== ssl_ctx.doc ======================================================== 6251 6252This is now a bit dated, quite a few of the SSL_ functions could be 6253SSL_CTX_ functions. I will update this in the future. 30 Aug 1996 6254 6255From eay@orb.mincom.oz.au Mon Dec 11 21:37:08 1995 6256Received: by orb.mincom.oz.au id AA00696 6257 (5.65c/IDA-1.4.4 for eay); Mon, 11 Dec 1995 11:37:08 +1000 6258Date: Mon, 11 Dec 1995 11:37:08 +1000 (EST) 6259From: Eric Young <eay@mincom.oz.au> 6260X-Sender: eay@orb 6261To: sameer <sameer@c2.org> 6262Cc: Eric Young <eay@mincom.oz.au> 6263Subject: Re: PEM_readX509 oesn't seem to be working 6264In-Reply-To: <199512110102.RAA12521@infinity.c2.org> 6265Message-Id: <Pine.SOL.3.91.951211112115.28608D-100000@orb> 6266Mime-Version: 1.0 6267Content-Type: TEXT/PLAIN; charset=US-ASCII 6268Status: RO 6269X-Status: 6270 6271On Sun, 10 Dec 1995, sameer wrote: 6272> OK, that's solved. I've found out that it is saying "no 6273> certificate set" in SSL_accept because s->conn == NULL 6274> so there is some place I need to initialize s->conn that I am 6275> not initializing it. 6276 6277The full order of things for a server should be. 6278 6279ctx=SSL_CTX_new(); 6280 6281/* The next line should not really be using ctx->cert but I'll leave it 6282 * this way right now... I don't want a X509_ routine to know about an SSL 6283 * structure, there should be an SSL_load_verify_locations... hmm, I may 6284 * add it tonight. 6285 */ 6286X509_load_verify_locations(ctx->cert,CAfile,CApath); 6287 6288/* Ok now for each new connection we do the following */ 6289con=SSL_new(ctx); 6290SSL_set_fd(con,s); 6291SSL_set_verify(con,verify,verify_callback); 6292 6293/* set the certificate and private key to use. */ 6294SSL_use_certificate_ASN1(con,X509_certificate); 6295SSL_use_RSAPrivateKey_ASN1(con,RSA_private_key); 6296 6297SSL_accept(con); 6298 6299SSL_read(con)/SSL_write(con); 6300 6301There is a bit more than that but that is basically the structure. 6302 6303Create a context and specify where to lookup certificates. 6304 6305foreach connection 6306 { 6307 create a SSL structure 6308 set the certificate and private key 6309 do a SSL_accept 6310 6311 we should now be ok 6312 } 6313 6314eric 6315-- 6316Eric Young | Signature removed since it was generating 6317AARNet: eay@mincom.oz.au | more followups than the message contents :-) 6318 6319 6320 6321==== ssleay.doc ======================================================== 6322 6323SSLeay: a cryptographic kitchen sink. 6324 63251st December 1995 6326Way back at the start of April 1995, I was looking for a mindless 6327programming project. A friend of mine (Tim Hudson) said "why don't you do SSL, 6328it has DES encryption in it and I would not mind using it in a SSL telnet". 6329While it was true I had written a DES library in previous years, litle 6330did I know what an expansive task SSL would turn into. 6331 6332First of all, the SSL protocol contains DES encryption. Well and good. My 6333DES library was fast and portable. It also contained the RSA's RC4 stream 6334cipher. Again, not a problem, some-one had just posted to sci.crypt 6335something that was claimed to be RC4. It also contained IDEA, I had the 6336specifications, not a problem to implement. MD5, an RFC, trivial, at most 6337I could spend a week or so trying to see if I could speed up the 6338implementation. All in all a nice set of ciphers. 6339Then the first 'expantion of the scope', RSA public key 6340encryption. Since I did not knowing a thing about public key encryption 6341or number theory, this appeared quite a daunting task. Just writing a 6342big number library would be problomatic in itself, let alone making it fast. 6343At this point the scope of 'implementing SSL' expands eponentialy. 6344First of all, the RSA private keys were being kept in ASN.1 format. 6345Thankfully the RSA PKCS series of documents explains this format. So I now 6346needed to be able to encode and decode arbitary ASN.1 objects. The Public 6347keys were embeded in X509 certificates. Hmm... these are not only 6348ASN.1 objects but they make up a heirachy of authentication. To 6349authenticate a X509 certificate one needs to retrieve it's issuers 6350certificate etc etc. Hmm..., so I also need to implement some kind 6351of certificate management software. I would also have to implement 6352software to authenticate certificates. At this point the support code made 6353the SSL part of my library look quite small. 6354Around this time, the first version of SSLeay was released. 6355 6356Ah, but here was the problem, I was not happy with the code so far. As may 6357have become obvious, I had been treating all of this as a learning 6358exersize, so I have completely written the library myself. As such, due 6359to the way it had grown like a fungus, much of the library was not 6360'elagent' or neat. There were global and static variables all over the 6361place, the SSL part did not even handle non-blocking IO. 6362The Great rewrite began. 6363 6364As of this point in time, the 'Great rewrite' has almost finished. So what 6365follows is an approximate list of what is actually SSLeay 0.5.0 6366 6367/********* This needs to be updated for 0.6.0+ *************/ 6368 6369--- 6370The library contains the following routines. Please note that most of these 6371functions are not specfic for SSL or any other particular cipher 6372implementation. I have tried to make all the routines as general purpose 6373as possible. So you should not think of this library as an SSL 6374implemtation, but rather as a library of cryptographic functions 6375that also contains SSL. I refer to each of these function groupings as 6376libraries since they are often capable of functioning as independant 6377libraries 6378 6379First up, the general ciphers and message digests supported by the library. 6380 6381MD2 rfc???, a standard 'by parts' interface to this algorithm. 6382MD5 rfc???, the same type of interface as for the MD2 library except a 6383 different algorithm. 6384SHA THe Secure Hash Algorithm. Again the same type of interface as 6385 MD2/MD5 except the digest is 20 bytes. 6386SHA1 The 'revised' version of SHA. Just about identical to SHA except 6387 for one tweak of an inner loop. 6388DES This is my libdes library that has been floating around for the last 6389 few years. It has been enhanced for no other reason than completeness. 6390 It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and 6391 triple DES modes of ecb, cbc, cfb64 and ofb64. cfb64 and ofb64 are 6392 functional interfaces to the 64 bit modes of cfb and ofb used in 6393 such a way thay they function as single character interfaces. 6394RC4 The RSA Inc. stream cipher. 6395RC2 The RSA Inc. block cipher. 6396IDEA An implmentation of the IDEA cipher, the library supports ecb, cbc, 6397 cfb64 and ofb64 modes of operation. 6398 6399Now all the above mentioned ciphers and digests libraries support high 6400speed, minimal 'crap in the way' type interfaces. For fastest and 6401lowest level access, these routines should be used directly. 6402 6403Now there was also the matter of public key crypto systems. These are 6404based on large integer arithmatic. 6405 6406BN This is my large integer library. It supports all the normal 6407 arithmentic operations. It uses malloc extensivly and as such has 6408 no limits of the size of the numbers being manipulated. If you 6409 wish to use 4000 bit RSA moduli, these routines will handle it. 6410 This library also contains routines to 'generate' prime numbers and 6411 to test for primality. The RSA and DH libraries sit on top of this 6412 library. As of this point in time, I don't support SHA, but 6413 when I do add it, it will just sit on top of the routines contained 6414 in this library. 6415RSA This implements the RSA public key algorithm. It also contains 6416 routines that will generate a new private/public key pair. 6417 All the RSA functions conform to the PKCS#1 standard. 6418DH This is an implementation of the 6419 Diffie-Hellman protocol. There are all the require routines for 6420 the protocol, plus extra routines that can be used to generate a 6421 strong prime for use with a specified generator. While this last 6422 routine is not generally required by applications implementing DH, 6423 It is present for completeness and because I thing it is much 6424 better to be able to 'generate' your own 'magic' numbers as oposed 6425 to using numbers suplied by others. I conform to the PKCS#3 6426 standard where required. 6427 6428You may have noticed the preceeding section mentions the 'generation' of 6429prime numbers. Now this requries the use of 'random numbers'. 6430 6431RAND This psuedo-random number library is based on MD5 at it's core 6432 and a large internal state (2k bytes). Once you have entered enough 6433 seed data into this random number algorithm I don't feel 6434 you will ever need to worry about it generating predictable output. 6435 Due to the way I am writing a portable library, I have left the 6436 issue of how to get good initial random seed data upto the 6437 application but I do have support routines for saving and loading a 6438 persistant random number state for use between program runs. 6439 6440Now to make all these ciphers easier to use, a higher level 6441interface was required. In this form, the same function would be used to 6442encrypt 'by parts', via any one of the above mentioned ciphers. 6443 6444EVP The Digital EnVeloPe library is quite large. At it's core are 6445 function to perform encryption and decryption by parts while using 6446 an initial parameter to specify which of the 17 different ciphers 6447 or 4 different message digests to use. On top of these are implmented 6448 the digital signature functions, sign, verify, seal and open. 6449 Base64 encoding of binary data is also done in this library. 6450 6451PEM rfc???? describe the format for Privacy Enhanced eMail. 6452 As part of this standard, methods of encoding digital enveloped 6453 data is an ascii format are defined. As such, I use a form of these 6454 to encode enveloped data. While at this point in time full support 6455 for PEM has not been built into the library, a minimal subset of 6456 the secret key and Base64 encoding is present. These reoutines are 6457 mostly used to Ascii encode binary data with a 'type' associated 6458 with it and perhaps details of private key encryption used to 6459 encrypt the data. 6460 6461PKCS7 This is another Digital Envelope encoding standard which uses ASN.1 6462 to encode the data. At this point in time, while there are some 6463 routines to encode and decode this binary format, full support is 6464 not present. 6465 6466As Mentioned, above, there are several different ways to encode 6467data structures. 6468 6469ASN1 This library is more a set of primatives used to encode the packing 6470 and unpacking of data structures. It is used by the X509 6471 certificate standard and by the PKCS standards which are used by 6472 this library. It also contains routines for duplicating and signing 6473 the structures asocisated with X509. 6474 6475X509 The X509 library contains routines for packing and unpacking, 6476 verifying and just about every thing else you would want to do with 6477 X509 certificates. 6478 6479PKCS7 PKCS-7 is a standard for encoding digital envelope data 6480 structures. At this point in time the routines will load and save 6481 DER forms of these structees. They need to be re-worked to support 6482 the BER form which is the normal way PKCS-7 is encoded. If the 6483 previous 2 sentances don't make much sense, don't worry, this 6484 library is not used by this version of SSLeay anyway. 6485 6486OBJ ASN.1 uses 'object identifiers' to identify objects. A set of 6487 functions were requred to translate from ASN.1 to an intenger, to a 6488 character string. This library provieds these translations 6489 6490Now I mentioned an X509 library. X509 specified a hieachy of certificates 6491which needs to be traversed to authenticate particular certificates. 6492 6493METH This library is used to push 'methods' of retrieving certificates 6494 into the library. There are some supplied 'methods' with SSLeay 6495 but applications can add new methods if they so desire. 6496 This library has not been finished and is not being used in this 6497 version. 6498 6499Now all the above are required for use in the initial point of this project. 6500 6501SSL The SSL protocol. This is a full implmentation of SSL v 2. It 6502 support both server and client authentication. SSL v 3 support 6503 will be added when the SSL v 3 specification is released in it's 6504 final form. 6505 6506Now quite a few of the above mentioned libraries rely on a few 'complex' 6507data structures. For each of these I have a library. 6508 6509Lhash This is a hash table library which is used extensivly. 6510 6511STACK An implemetation of a Stack data structure. 6512 6513BUF A simple character array structure that also support a function to 6514 check that the array is greater that a certain size, if it is not, 6515 it is realloced so that is it. 6516 6517TXT_DB A simple memory based text file data base. The application can specify 6518 unique indexes that will be enforced at update time. 6519 6520CONF Most of the programs written for this library require a configuration 6521 file. Instead of letting programs constantly re-implment this 6522 subsystem, the CONF library provides a consistant and flexable 6523 interface to not only configuration files but also environment 6524 variables. 6525 6526But what about when something goes wrong? 6527The one advantage (and perhaps disadvantage) of all of these 6528functions being in one library was the ability to implement a 6529single error reporting system. 6530 6531ERR This library is used to report errors. The error system records 6532 library number, function number (in the library) and reason 6533 number. Multiple errors can be reported so that an 'error' trace 6534 is created. The errors can be printed in numeric or textual form. 6535 6536 6537==== ssluse.doc ======================================================== 6538 6539We have an SSL_CTX which contains global information for lots of 6540SSL connections. The session-id cache and the certificate verificate cache. 6541It also contains default values for use when certificates are used. 6542 6543SSL_CTX 6544 default cipher list 6545 session-id cache 6546 certificate cache 6547 default session-id timeout period 6548 New session-id callback 6549 Required session-id callback 6550 session-id stats 6551 Informational callback 6552 Callback that is set, overrides the SSLeay X509 certificate 6553 verification 6554 The default Certificate/Private Key pair 6555 Default read ahead mode. 6556 Default verify mode and verify callback. These are not used 6557 if the over ride callback mentioned above is used. 6558 6559Each SSL can have the following defined for it before a connection is made. 6560 6561Certificate 6562Private key 6563Ciphers to use 6564Certificate verify mode and callback 6565IO object to use in the comunication. 6566Some 'read-ahead' mode information. 6567A previous session-id to re-use. 6568 6569A connection is made by using SSL_connect or SSL_accept. 6570When non-blocking IO is being used, there are functions that can be used 6571to determin where and why the SSL_connect or SSL_accept did not complete. 6572This information can be used to recall the functions when the 'error' 6573condition has dissapeared. 6574 6575After the connection has been made, information can be retrived about the 6576SSL session and the session-id values that have been decided apon. 6577The 'peer' certificate can be retrieved. 6578 6579The session-id values include 6580'start time' 6581'timeout length' 6582 6583 6584 6585==== stack.doc ======================================================== 6586 6587The stack data structure is used to store an ordered list of objects. 6588It is basically misnamed to call it a stack but it can function that way 6589and that is what I originally used it for. Due to the way element 6590pointers are kept in a malloc()ed array, the most efficient way to use this 6591structure is to add and delete elements from the end via sk_pop() and 6592sk_push(). If you wish to do 'lookups' sk_find() is quite efficient since 6593it will sort the stack (if required) and then do a binary search to lookup 6594the requested item. This sorting occurs automatically so just sk_push() 6595elements on the stack and don't worry about the order. Do remember that if 6596you do a sk_find(), the order of the elements will change. 6597 6598You should never need to 'touch' this structure directly. 6599typedef struct stack_st 6600 { 6601 unsigned int num; 6602 char **data; 6603 int sorted; 6604 6605 unsigned int num_alloc; 6606 int (*comp)(); 6607 } STACK; 6608 6609'num' holds the number of elements in the stack, 'data' is the array of 6610elements. 'sorted' is 1 is the list has been sorted, 0 if not. 6611 6612num_alloc is the number of 'nodes' allocated in 'data'. When num becomes 6613larger than num_alloc, data is realloced to a larger size. 6614If 'comp' is set, it is a function that is used to compare 2 of the items 6615in the stack. The function should return -1, 0 or 1, depending on the 6616ordering. 6617 6618#define sk_num(sk) ((sk)->num) 6619#define sk_value(sk,n) ((sk)->data[n]) 6620 6621These 2 macros should be used to access the number of elements in the 6622'stack' and to access a pointer to one of the values. 6623 6624STACK *sk_new(int (*c)()); 6625 This creates a new stack. If 'c', the comparison function, is not 6626specified, the various functions that operate on a sorted 'stack' will not 6627work (sk_find()). NULL is returned on failure. 6628 6629void sk_free(STACK *); 6630 This function free()'s a stack structure. The elements in the 6631stack will not be freed so one should 'pop' and free all elements from the 6632stack before calling this function or call sk_pop_free() instead. 6633 6634void sk_pop_free(STACK *st; void (*func)()); 6635 This function calls 'func' for each element on the stack, passing 6636the element as the argument. sk_free() is then called to free the 'stack' 6637structure. 6638 6639int sk_insert(STACK *sk,char *data,int where); 6640 This function inserts 'data' into stack 'sk' at location 'where'. 6641If 'where' is larger that the number of elements in the stack, the element 6642is put at the end. This function tends to be used by other 'stack' 6643functions. Returns 0 on failure, otherwise the number of elements in the 6644new stack. 6645 6646char *sk_delete(STACK *st,int loc); 6647 Remove the item a location 'loc' from the stack and returns it. 6648Returns NULL if the 'loc' is out of range. 6649 6650char *sk_delete_ptr(STACK *st, char *p); 6651 If the data item pointed to by 'p' is in the stack, it is deleted 6652from the stack and returned. NULL is returned if the element is not in the 6653stack. 6654 6655int sk_find(STACK *st,char *data); 6656 Returns the location that contains a value that is equal to 6657the 'data' item. If the comparison function was not set, this function 6658does a linear search. This function actually qsort()s the stack if it is not 6659in order and then uses bsearch() to do the initial search. If the 6660search fails,, -1 is returned. For mutliple items with the same 6661value, the index of the first in the array is returned. 6662 6663int sk_push(STACK *st,char *data); 6664 Append 'data' to the stack. 0 is returned if there is a failure 6665(due to a malloc failure), else 1. This is 6666sk_insert(st,data,sk_num(st)); 6667 6668int sk_unshift(STACK *st,char *data); 6669 Prepend 'data' to the front (location 0) of the stack. This is 6670sk_insert(st,data,0); 6671 6672char *sk_shift(STACK *st); 6673 Return and delete from the stack the first element in the stack. 6674This is sk_delete(st,0); 6675 6676char *sk_pop(STACK *st); 6677 Return and delete the last element on the stack. This is 6678sk_delete(st,sk_num(sk)-1); 6679 6680void sk_zero(STACK *st); 6681 Removes all items from the stack. It does not 'free' 6682pointers but is a quick way to clear a 'stack of references'. 6683 6684==== threads.doc ======================================================== 6685 6686How to compile SSLeay for multi-threading. 6687 6688Well basically it is quite simple, set the compiler flags and build. 6689I have only really done much testing under Solaris and Windows NT. 6690If you library supports localtime_r() and gmtime_r() add, 6691-DTHREADS to the makefile parameters. You can probably survive with out 6692this define unless you are going to have multiple threads generating 6693certificates at once. It will not affect the SSL side of things. 6694 6695The approach I have taken to doing locking is to make the application provide 6696callbacks to perform locking and so that the SSLeay library can distinguish 6697between threads (for the error state). 6698 6699To have a look at an example program, 'cd mt; vi mttest.c'. 6700To build under solaris, sh solaris.sh, for Windows NT or Windows 95, 6701win32.bat 6702 6703This will build mttest which will fire up 10 threads that talk SSL 6704to each other 10 times. 6705To enable everything to work, the application needs to call 6706 6707CRYPTO_set_id_callback(id_function); 6708CRYPTO_set_locking_callback(locking_function); 6709 6710before any multithreading is started. 6711id_function does not need to be defined under Windows NT or 95, the 6712correct function will be called if it is not. Under unix, getpid() 6713is call if the id_callback is not defined, for solaris this is wrong 6714(since threads id's are not pid's) but under IRIX it is correct 6715(threads are just processes sharing the data segement). 6716 6717The locking_callback is used to perform locking by the SSLeay library. 6718eg. 6719 6720void solaris_locking_callback(mode,type,file,line) 6721int mode; 6722int type; 6723char *file; 6724int line; 6725 { 6726 if (mode & CRYPTO_LOCK) 6727 mutex_lock(&(lock_cs[type])); 6728 else 6729 mutex_unlock(&(lock_cs[type])); 6730 } 6731 6732Now in this case I have used mutexes instead of read/write locks, since they 6733are faster and there are not many read locks in SSLeay, you may as well 6734always use write locks. file and line are __FILE__ and __LINE__ from 6735the compile and can be usefull when debugging. 6736 6737Now as you can see, 'type' can be one of a range of values, these values are 6738defined in crypto/crypto.h 6739CRYPTO_get_lock_name(type) will return a text version of what the lock is. 6740There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup 6741for multi-threading can be 6742 6743static mutex_t lock_cs[CRYPTO_NUM_LOCKS]; 6744 6745void thread_setup() 6746 { 6747 int i; 6748 6749 for (i=0; i<CRYPTO_NUM_LOCKS; i++) 6750 mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL); 6751 CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id); 6752 CRYPTO_set_locking_callback((void (*)())solaris_locking_callback); 6753 } 6754 6755As a final note, under Windows NT or Windows 95, you have to be careful 6756not to mix the various threaded, unthreaded and debug libraries. 6757Normally if they are mixed incorrectly, mttest will crash just after printing 6758out some usage statistics at the end. This is because the 6759different system libraries use different malloc routines and if 6760data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a 6761different library malloc, things get very confused. 6762 6763The default SSLeay DLL builds use /MD, so if you use this on your 6764application, things will work as expected. If you use /MDd, 6765you will probably have to rebuild SSLeay using this flag. 6766I should modify util/mk1mf.pl so it does all this correctly, but 6767this has not been done yet. 6768 6769One last warning. Because locking overheads are actually quite large, the 6770statistics collected against the SSL_CTX for successfull connections etc 6771are not locked when updated. This does make it possible for these 6772values to be slightly lower than they should be, if you are 6773running multithreaded on a multi-processor box, but this does not really 6774matter much. 6775 6776 6777==== txt_db.doc ======================================================== 6778 6779TXT_DB, a simple text based in memory database. 6780 6781It holds rows of ascii data, for which the only special character is '\0'. 6782The rows can be of an unlimited length. 6783 6784==== why.doc ======================================================== 6785 6786This file is more of a note for other people who wish to understand why 6787the build environment is the way it is :-). 6788 6789The include files 'depend' as follows. 6790Each of 6791crypto/*/*.c includes crypto/cryptlib.h 6792ssl/*.c include ssl/ssl_locl.h 6793apps/*.c include apps/apps.h 6794crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h 6795all include e_os.h which contains OS/environment specific information. 6796If you need to add something todo with a particular environment, 6797add it to this file. It is worth remembering that quite a few libraries, 6798like lhash, des, md, sha etc etc do not include crypto/cryptlib.h. This 6799is because these libraries should be 'independantly compilable' and so I 6800try to keep them this way. 6801e_os.h is not so much a part of SSLeay, as the placing in one spot all the 6802evil OS dependant muck. 6803 6804I wanted to automate as many things as possible. This includes 6805error number generation. A 6806make errors 6807will scan the source files for error codes, append them to the correct 6808header files, and generate the functions to print the text version 6809of the error numbers. So don't even think about adding error numbers by 6810hand, put them in the form 6811XXXerr(XXXX_F_XXXX,YYYY_R_YYYY); 6812on line and it will be automatically picked up my a make errors. 6813 6814In a similar vein, programs to be added into ssleay in the apps directory 6815just need to have an entry added to E_EXE in makefile.ssl and 6816everthing will work as expected. Don't edit progs.h by hand. 6817 6818make links re-generates the symbolic links that are used. The reason why 6819I keep everything in its own directory, and don't put all the 6820test programs and header files in 'test' and 'include' is because I want 6821to keep the 'sub-libraries' independant. I still 'pull' out 6822indervidual libraries for use in specific projects where the code is 6823required. I have used the 'lhash' library in just about every software 6824project I have worked on :-). 6825 6826make depend generates dependancies and 6827make dclean removes them. 6828 6829You will notice that I use perl quite a bit when I could be using 'sed'. 6830The reason I decided to do this was to just stick to one 'extra' program. 6831For Windows NT, I have perl and no sed. 6832 6833The util/mk1mf.pl program can be used to generate a single makefile. 6834I use this because makefiles under Microsoft are horrific. 6835Each C compiler seems to have different linker formats, which have 6836to be used because the retarted C compilers explode when you do 6837cl -o file *.o. 6838 6839Now some would argue that I should just use the single makefile. I don't 6840like it during develoment for 2 reasons. First, the actuall make 6841command takes a long time. For my current setup, if I'm in 6842crypto/bn and I type make, only the crypto/bn directory gets rebuilt, 6843which is nice when you are modifying prototypes in bn.h which 6844half the SSLeay depends on. The second is that to add a new souce file 6845I just plonk it in at the required spot in the local makefile. This 6846then alows me to keep things local, I don't need to modify a 'global' 6847tables (the make for unix, the make for NT, the make for w31...). 6848When I am ripping apart a library structure, it is nice to only 6849have to worry about one directory :-). 6850 6851Having said all this, for the hell of it I put together 2 files that 6852#include all the souce code (generated by doing a ls */*.o after a build). 6853crypto.c takes only 30 seconds to build under NT and 2 minutes under linux 6854for my pentium100. Much faster that the normal build :-). 6855Again, the problem is that when using libraries, every program linked 6856to libcrypto.a would suddenly get 330k of library when it may only need 68571k. This technique does look like a nice way to do shared libraries though. 6858 6859Oh yes, as a final note, to 'build' a distribution, I just type 6860make dist. 6861This cleans and packages everything. The directory needs to be called 6862SSLeay since the make does a 'cd ..' and renames and tars things up. 6863 6864==== req.1 ======================================================== 6865 6866The 'req' command is used to manipulate and deal with pkcs#10 6867certificate requests. 6868 6869It's default mode of operation is to load a certificate and then 6870write it out again. 6871 6872By default the 'req' is read from stdin in 'PEM' format. 6873The -inform option can be used to specify 'pem' format or 'der' 6874format. PEM format is the base64 encoding of the DER format. 6875 6876By default 'req' then writes the request back out. -outform can be used 6877to indicate the desired output format, be it 'pem' or 'der'. 6878 6879To specify an input file, use the '-in' option and the '-out' option 6880can be used to specify the output file. 6881 6882If you wish to perform a command and not output the certificate 6883request afterwards, use the '-noout' option. 6884 6885When a certificate is loaded, it can be printed in a human readable 6886ascii format via the '-text' option. 6887 6888To check that the signature on a certificate request is correct, use 6889the '-verify' option to make sure that the private key contained in the 6890certificate request corresponds to the signature. 6891 6892Besides the default mode, there is also the 'generate a certificate 6893request' mode. There are several flags that trigger this mode. 6894 6895-new will generate a new RSA key (if required) and then prompts 6896the user for details for the certificate request. 6897-newkey has an argument that is the number of bits to make the new 6898key. This function also triggers '-new'. 6899 6900The '-new' option can have a key to use specified instead of having to 6901load one, '-key' is used to specify the file containg the key. 6902-keyform can be used to specify the format of the key. Only 6903'pem' and 'der' formats are supported, later, 'netscape' format may be added. 6904 6905Finally there is the '-x509' options which makes req output a self 6906signed x509 certificate instead of a certificate request. 6907 6908Now as you may have noticed, there are lots of default options that 6909cannot be specified via the command line. They are held in a 'template' 6910or 'configuration file'. The -config option specifies which configuration 6911file to use. See conf.doc for details on the syntax of this file. 6912 6913The req command uses the 'req' section of the config file. 6914 6915--- 6916# The following variables are defined. For this example I will populate 6917# the various values 6918[ req ] 6919default_bits = 512 # default number of bits to use. 6920default_keyfile = testkey.pem # Where to write the generated keyfile 6921 # if not specified. 6922distinguished_name= req_dn # The section that contains the 6923 # information about which 'object' we 6924 # want to put in the DN. 6925attributes = req_attr # The objects we want for the 6926 # attributes field. 6927encrypt_rsa_key = no # Should we encrypt newly generated 6928 # keys. I strongly recommend 'yes'. 6929 6930# The distinguished name section. For the following entries, the 6931# object names must exist in the SSLeay header file objects.h. If they 6932# do not, they will be silently ignored. The entries have the following 6933# format. 6934# <object_name> => string to prompt with 6935# <object_name>_default => default value for people 6936# <object_name>_value => Automatically use this value for this field. 6937# <object_name>_min => minimum number of characters for data (def. 0) 6938# <object_name>_max => maximum number of characters for data (def. inf.) 6939# All of these entries are optional except for the first one. 6940[ req_dn ] 6941countryName = Country Name (2 letter code) 6942countryName_default = AU 6943 6944stateOrProvinceName = State or Province Name (full name) 6945stateOrProvinceName_default = Queensland 6946 6947localityName = Locality Name (eg, city) 6948 6949organizationName = Organization Name (eg, company) 6950organizationName_default = Mincom Pty Ltd 6951 6952organizationalUnitName = Organizational Unit Name (eg, section) 6953organizationalUnitName_default = MTR 6954 6955commonName = Common Name (eg, YOUR name) 6956commonName_max = 64 6957 6958emailAddress = Email Address 6959emailAddress_max = 40 6960 6961# The next section is the attributes section. This is exactly the 6962# same as for the previous section except that the resulting objects are 6963# put in the attributes field. 6964[ req_attr ] 6965challengePassword = A challenge password 6966challengePassword_min = 4 6967challengePassword_max = 20 6968 6969unstructuredName = An optional company name 6970 6971---- 6972Also note that the order that attributes appear in this file is the 6973order they will be put into the distinguished name. 6974 6975Once this request has been generated, it can be sent to a CA for 6976certifying. 6977 6978---- 6979A few quick examples.... 6980 6981To generate a new request and a new key 6982req -new 6983 6984To generate a new request and a 1058 bit key 6985req -newkey 1058 6986 6987To generate a new request using a pre-existing key 6988req -new -key key.pem 6989 6990To generate a self signed x509 certificate from a certificate 6991request using a supplied key, and we want to see the text form of the 6992output certificate (which we will put in the file selfSign.pem 6993req -x509 -in req.pem -key key.pem -text -out selfSign.pem 6994 6995Verify that the signature is correct on a certificate request. 6996req -verify -in req.pem 6997 6998Verify that the signature was made using a specified public key. 6999req -verify -in req.pem -key key.pem 7000 7001Print the contents of a certificate request 7002req -text -in req.pem 7003 7004==== danger ======================================================== 7005 7006If you specify a SSLv2 cipher, and the mode is SSLv23 and the server 7007can talk SSLv3, it will claim there is no cipher since you should be 7008using SSLv3. 7009 7010When tracing debug stuff, remember BIO_s_socket() is different to 7011BIO_s_connect(). 7012 7013BSD/OS assember is not working 7014 7015