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