2 Bundle of old SSLeay documentation files [OBSOLETE!]
4 ==== readme ========================================================
6 This is the old 0.6.6 docuementation. Most of the cipher stuff is still
7 relevent but I'm working (very slowly) on new docuemtation.
8 The current version can be found online at
10 http://www.cryptsoft.com/ssleay/doc
12 ==== API.doc ========================================================
14 SSL - SSLv2/v3/v23 etc.
16 BIO - methods and how they plug together
18 MEM - memory allocation callback
20 CRYPTO - locking for threads
22 EVP - Ciphers/Digests/signatures
26 X509 - certificate retrieval
30 X509 - X509v3 extensions
32 Objects - adding object identifiers
38 ==== ssl/readme =====================================================
41 This file belongs in ../apps, but I'll leave it here because it deals
42 with SSL :-) It is rather dated but it gives you an idea of how
47 I have been changing things quite a bit and have not fully updated
48 this file, so take what you read with a grain of salt
51 The s_client and s_server programs can be used to test SSL capable
52 IP/port addresses and the verification of the X509 certificates in use
53 by these services. I strongly advise having a look at the code to get
54 an idea of how to use the authentication under SSLeay. Any feedback
55 on changes and improvements would be greatly accepted.
57 This file will probably be gibberish unless you have read
58 rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM
61 A Brief outline (and examples) how to use them to do so.
64 The environment variable SSL_CIPER is used to specify the prefered
65 cipher to use, play around with setting it's value to combinations of
66 RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL
67 in a : separated list.
69 This directory contains 3 X509 certificates which can be used by these programs.
70 client.pem: a file containing a certificate and private key to be used
72 server.pem :a file containing a certificate and private key to be used
74 eay1024.pem:the certificate used to sign client.pem and server.pem.
75 This would be your CA's certificate. There is also a link
76 from the file a8556381.0 to eay1024.PEM. The value a8556381
77 is returned by 'x509 -hash -noout <eay1024.pem' and is the
78 value used by X509 verification routines to 'find' this
79 certificte when search a directory for it.
80 [the above is not true any more, the CA cert is
81 ../certs/testca.pem which is signed by ../certs/mincomca.pem]
83 When testing the s_server, you may get
84 bind: Address already in use
85 errors. These indicate the port is still being held by the unix
86 kernel and you are going to have to wait for it to let go of it. If
87 this is the case, remember to use the port commands on the s_server and
88 s_client to talk on an alternative port.
92 This program can be used to connect to any IP/hostname:port that is
93 talking SSL. Once connected, it will attempt to authenticate the
94 certificate it was passed and if everything works as expected, a 2
95 directional channel will be open. Any text typed will be sent to the
96 other end. type Q<cr> to exit. Flags are as follows.
97 -host arg : Arg is the host or IP address to connect to.
98 -port arg : Arg is the port to connect to (https is 443).
99 -verify arg : Turn on authentication of the server certificate.
100 : Arg specifies the 'depth', this will covered below.
101 -cert arg : The optional certificate to use. This certificate
102 : will be returned to the server if the server
103 : requests it for client authentication.
104 -key arg : The private key that matches the certificate
105 : specified by the -cert option. If this is not
106 : specified (but -cert is), the -cert file will be
107 : searched for the Private key. Both files are
108 : assumed to be in PEM format.
109 -CApath arg : When to look for certificates when 'verifying' the
110 : certificate from the server.
111 -CAfile arg : A file containing certificates to be used for
112 : 'verifying' the server certificate.
113 -reconnect : Once a connection has been made, drop it and
114 : reconnect with same session-id. This is for testing :-).
116 The '-verify n' parameter specifies not only to verify the servers
117 certificate but to also only take notice of 'n' levels. The best way
118 to explain is to show via examples.
120 s_server -cert server.PEM is running.
124 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
125 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
126 verify error:num=1:unable to get issuer certificate
128 CIPHER is CBC-DES-MD5
129 What has happened is that the 'SSLeay demo server' certificate's
130 issuer ('CA') could not be found but because verify is not on, we
131 don't care and the connection has been made anyway. It is now 'up'
132 using CBC-DES-MD5 mode. This is an unauthenticate secure channel.
133 You may not be talking to the right person but the data going to them
138 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
139 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
140 verify error:num=1:unable to get issuer certificate
142 CIPHER is CBC-DES-MD5
143 We are 'verifying' but only to depth 0, so since the 'SSLeay demo server'
144 certificate passed the date and checksum, we are happy to proceed.
148 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
149 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
150 verify error:num=1:unable to get issuer certificate
153 verify error:unable to get issuer certificate
154 In this case we failed to make the connection because we could not
155 authenticate the certificate because we could not find the
158 s_client -verify 1 -CAfile eay1024.PEM
160 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
162 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
164 CIPHER is CBC-DES-MD5
165 We loaded the certificates from the file eay1024.PEM. Everything
166 checked out and so we made the connection.
168 s_client -verify 1 -CApath .
170 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
172 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
174 CIPHER is CBC-DES-MD5
175 We looked in out local directory for issuer certificates and 'found'
176 a8556381.0 and so everything is ok.
178 It is worth noting that 'CA' is a self certified certificate. If you
179 are passed one of these, it will fail to 'verify' at depth 0 because
180 we need to lookup the certifier of a certificate from some information
181 that we trust and keep locally.
183 SSL_CIPHER=CBC3-DES-MD5:RC4-MD5
185 s_client -verify 10 -CApath . -reconnect
187 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
189 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
191 drop the connection and reconnect with the same session id
192 CIPHER is CBC3-DES-MD5
193 This has done a full connection and then re-estabished it with the
194 same session id but a new socket. No RSA stuff occures on the second
195 connection. Note that we said we would prefer to use CBC3-DES-MD5
196 encryption and so, since the server supports it, we are.
200 This program accepts SSL connections on a specified port
201 Once connected, it will estabish an SSL connection and optionaly
202 attempt to authenticate the client. A 2 directional channel will be
203 open. Any text typed will be sent to the other end. Type Q<cr> to exit.
204 Flags are as follows.
205 -port arg : Arg is the port to listen on.
206 -verify arg : Turn on authentication of the client if they have a
207 : certificate. Arg specifies the 'depth'.
208 -Verify arg : Turn on authentication of the client. If they don't
209 : have a valid certificate, drop the connection.
210 -cert arg : The certificate to use. This certificate
211 : will be passed to the client. If it is not
212 : specified, it will default to server.PEM
213 -key arg : The private key that matches the certificate
214 : specified by the -cert option. If this is not
215 : specified (but -cert is), the -cert file will be
216 : searched for the Private key. Both files are
217 : assumed to be in PEM format. Default is server.PEM
218 -CApath arg : When to look for certificates when 'verifying' the
219 : certificate from the client.
220 -CAfile arg : A file containing certificates to be used for
221 : 'verifying' the client certificate.
223 For the following 'demo' I will specify the s_server command and
224 the s_client command and then list the output from the s_server.
228 CIPHER is CBC-DES-MD5
229 Everything up and running
234 CIPHER is CBC-DES-MD5
235 Ok since no certificate was returned and we don't care.
238 ./s_client -cert client.PEM
240 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
241 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
242 verify error:num=1:unable to get issuer certificate
244 CIPHER is CBC-DES-MD5
245 Ok since we were only verifying to level 0
248 s_client -cert client.PEM
250 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
251 issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
252 verify error:num=1:unable to get issuer certificate
255 verify error:unable to get issuer certificate
256 Bad because we could not authenticate the returned certificate.
258 s_server -verify 4 -CApath .
259 s_client -cert client.PEM
261 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
263 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
265 CIPHER is CBC-DES-MD5
266 Ok because we could authenticate the returned certificate :-).
268 s_server -Verify 0 -CApath .
272 SSL error:function is:REQUEST_CERTIFICATE
273 :error is :client end did not return a certificate
274 Error because no certificate returned.
276 s_server -Verify 4 -CApath .
277 s_client -cert client.PEM
279 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
281 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
283 CIPHER is CBC-DES-MD5
284 Full authentication of the client.
286 So in summary to do full authentication of both ends
287 s_server -Verify 9 -CApath .
288 s_client -cert client.PEM -CApath . -verify 9
291 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
293 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
295 CIPHER is CBC-DES-MD5
298 depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
300 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
302 CIPHER is CBC-DES-MD5
304 For general probing of the 'internet https' servers for the
305 distribution area, run
306 s_client -host www.netscape.com -port 443 -verify 4 -CApath ../rsa/hash
309 and you should be talking to the https server on that host.
311 www.rsa.com was refusing to respond to connections on 443 when I was
318 ==== a_verify.doc ========================================================
320 From eay@mincom.com Fri Oct 4 18:29:06 1996
321 Received: by orb.mincom.oz.au id AA29080
322 (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000
323 Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST)
324 From: Eric Young <eay@mincom.oz.au>
326 To: wplatzer <wplatzer@iaik.tu-graz.ac.at>
327 Cc: Eric Young <eay@mincom.oz.au>, SSL Mailing List <ssl-users@mincom.com>
328 Subject: Re: Netscape's Public Key
329 In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at>
330 Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb>
332 Content-Type: TEXT/PLAIN; charset=US-ASCII
336 On Thu, 3 Oct 1996, wplatzer wrote:
337 > I get Public Key from Netscape (Gold 3.0b4), but cannot do anything
338 > with it... It looks like (asn1parse):
340 > 0:d=0 hl=3 l=180 cons: SEQUENCE
341 > 3:d=1 hl=2 l= 96 cons: SEQUENCE
342 > 5:d=2 hl=2 l= 92 cons: SEQUENCE
343 > 7:d=3 hl=2 l= 13 cons: SEQUENCE
344 > 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption
345 > 20:d=4 hl=2 l= 0 prim: NULL
346 > 22:d=3 hl=2 l= 75 prim: BIT STRING
347 > 99:d=2 hl=2 l= 0 prim: IA5STRING :
348 > 101:d=1 hl=2 l= 13 cons: SEQUENCE
349 > 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption
350 > 114:d=2 hl=2 l= 0 prim: NULL
351 > 116:d=1 hl=2 l= 65 prim: BIT STRING
353 > The first BIT STRING is the public key and the second BIT STRING is
355 > But a public key consists of the public exponent and the modulus. Are
356 > both numbers in the first BIT STRING?
357 > Is there a document simply describing this coding stuff (checking
358 > signature, get the public key, etc.)?
360 Minimal in SSLeay. If you want to see what the modulus and exponent are,
361 try asn1parse -offset 25 -length 75 <key.pem
362 asn1parse will currently stuff up on the 'length 75' part (fixed in next
363 release) but it will print the stuff. If you are after more
364 documentation on ASN.1, have a look at www.rsa.com and get their PKCS
365 documents, most of my initial work on SSLeay was done using them.
368 util/crypto.num and util/ssl.num are lists of all exported functions in
369 the library (but not macros :-(.
371 The ones for extracting public keys from certificates and certificate
372 requests are EVP_PKEY * X509_REQ_extract_key(X509_REQ *req);
373 EVP_PKEY * X509_extract_key(X509 *x509);
375 To verify a signature on a signed ASN.1 object
376 int X509_verify(X509 *a,EVP_PKEY *key);
377 int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key);
378 int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key);
379 int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key);
381 I should mention that EVP_PKEY can be used to hold a public or a private key,
382 since for things like RSA and DSS, a public key is just a subset of what
383 is stored for the private key.
385 To sign any of the above structures
387 int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md);
388 int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md);
389 int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md);
390 int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md);
392 where md is the message digest to sign with.
394 There are all defined in x509.h and all the _sign and _verify functions are
395 actually macros to the ASN1_sign() and ASN1_verify() functions.
396 These functions will put the correct algorithm identifiers in the correct
397 places in the structures.
401 Eric Young | BOOL is tri-state according to Bill Gates.
402 AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage().
404 ==== x509 =======================================================
410 X509_get_serialNumber()
418 X509_set_serialNumber()
425 X509_get_extensions()
426 X509_set_extensions()
428 X509_EXTENSIONS_clear()
429 X509_EXTENSIONS_retrieve()
430 X509_EXTENSIONS_add()
431 X509_EXTENSIONS_delete()
433 ==== x509 attribute ================================================
436 STACK of X509_ATTRIBUTES
445 get_obj_by_nid(STACK , nid)
446 get_num_by_nid(STACK , nid)
447 get_data_by_nid(STACK , nid, index)
449 X509_ATTRIBUTE *X509_ATTRIBUTE_new(void );
450 void X509_ATTRIBUTE_free(X509_ATTRIBUTE *a);
452 X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **ex,
453 int nid, STACK *value);
455 X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **ex,
456 int nid, STACK *value);
458 int X509_ATTRIBUTE_set_object(X509_ATTRIBUTE *ex,ASN1_OBJECT *obj);
459 int X509_ATTRIBUTE_add_data(X509_ATTRIBUTE *ex, int index,
462 ASN1_OBJECT * X509_ATTRIBUTE_get_object(X509_ATTRIBUTE *ex);
463 int X509_ATTRIBUTE_get_num(X509_ATTRIBUTE *ne);
464 ASN1_TYPE * X509_ATTRIBUTE_get_data(X509_ATTRIBUTE *ne,int index);
466 ASN1_TYPE * X509_ATTRIBUTE_get_data_by_NID(X509_ATTRIBUTE *ne,
469 X509_ATTRIBUTE *PKCS7_get_s_att_by_NID(PKCS7 *p7,int nid);
470 X509_ATTRIBUTE *PKCS7_get_u_att_by_NID(PKCS7 *p7,int nid);
472 ==== x509 v3 ========================================================
476 The X509_EXTENSION_METHOD includes extensions and attributes and/or names.
477 Basically everthing that can be added to an X509 with an OID identifying it.
479 It operates via 2 methods per object id.
480 int a2i_XXX(X509 *x,char *str,int len);
481 int i2a_XXX(BIO *bp,X509 *x);
483 The a2i_XXX function will add the object with a value converted from the
484 string into the X509. Len can be -1 in which case the length is calculated
485 via strlen(str). Applications can always use direct knowledge to load and
486 unload the relevent objects themselves.
488 i2a_XXX will print to the passed BIO, a text representation of the
489 relevet object. Use a memory BIO if you want it printed to a buffer :-).
491 X509_add_by_NID(X509 *x,int nid,char *str,int len);
492 X509_add_by_OBJ(X509 *x,ASN1_OBJECT *obj,char *str,int len);
494 X509_print_by_name(BIO *bp,X509 *x);
495 X509_print_by_NID(BIO *bp,X509 *x);
496 X509_print_by_OBJ(BIO *bp,X509 *x);
498 ==== verify ========================================================
500 X509_verify_cert_chain(
501 CERT_STORE *cert_store,
502 STACK /* X509 */ *certs,
504 int (*verify_error_callback)()
505 char *argument_to_callback, /* SSL */
508 char *app_verify_arg, /* from SSL_CTX */
509 STACK /* X509 */ *certs,
511 int (*verify_error_callback)()
514 int X509_verify_cert(
515 CERT_STORE *cert_store,
518 int (*verify_error_callback)(),
521 ==== apps.doc ========================================================
525 Ok, where to begin....
526 In the begining, when SSLeay was small (April 1995), there
527 were but few applications, they did happily cohabit in
528 the one bin directory. Then over time, they did multiply and grow,
529 and they started to look like microsoft software; 500k to print 'hello world'.
530 A new approach was needed. They were coalessed into one 'Monolithic'
531 application, ssleay. This one program is composed of many programs that
532 can all be compiled independantly.
534 ssleay has 3 modes of operation.
535 1) If the ssleay binaray has the name of one of its component programs, it
536 executes that program and then exits. This can be achieve by using hard or
537 symbolic links, or failing that, just renaming the binary.
538 2) If the first argument to ssleay is the name of one of the component
539 programs, that program runs that program and then exits.
540 3) If there are no arguments, ssleay enters a 'command' mode. Each line is
541 interpreted as a program name plus arguments. After each 'program' is run,
542 ssleay returns to the comand line.
544 dgst - message digests
545 enc - encryption and base64 encoding
547 ans1parse - 'pulls' appart ASN.1 encoded objects like certificates.
549 dh - Diffle-Hellman parameter manipulation.
550 rsa - RSA manipulations.
551 crl - Certificate revokion list manipulations
552 x509 - X509 cert fiddles, including signing.
553 pkcs7 - pkcs7 manipulation, only DER versions right now.
555 genrsa - generate an RSA private key.
556 gendh - Generate a set of Diffle-Hellman parameters.
557 req - Generate a PKCS#10 object, a certificate request.
559 s_client - SSL client program
560 s_server - SSL server program
561 s_time - A SSL protocol timing program
562 s_mult - Another SSL server, but it multiplexes
564 s_filter - under development
566 errstr - Convert SSLeay error numbers to strings.
567 ca - Sign certificate requests, and generate
568 certificate revokion lists
569 crl2pkcs7 - put a crl and certifcates into a pkcs7 object.
570 speed - Benchmark the ciphers.
571 verify - Check certificates
572 hashdir - under development
574 [ there a now a few more options, play with the program to see what they
577 ==== asn1.doc ========================================================
581 ASN.1 is a specification for how to encode structured 'data' in binary form.
582 The approach I have take to the manipulation of structures and their encoding
583 into ASN.1 is as follows.
585 For each distinct structure there are 4 function of the following form
586 TYPE *TYPE_new(void);
587 void TYPE_free(TYPE *);
588 TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length);
589 long i2d_TYPE(TYPE *a,unsigned char **pp); /* CHECK RETURN VALUE */
591 where TYPE is the type of the 'object'. The TYPE that have these functions
592 can be in one of 2 forms, either the internal C malloc()ed data structure
593 or in the DER (a variant of ASN.1 encoding) binary encoding which is just
594 an array of unsigned bytes. The 'i2d' functions converts from the internal
595 form to the DER form and the 'd2i' functions convert from the DER form to
598 The 'new' function returns a malloc()ed version of the structure with all
599 substructures either created or left as NULL pointers. For 'optional'
600 fields, they are normally left as NULL to indicate no value. For variable
601 size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the
602 STACK data type is used to hold the values. Have a read of stack.doc
603 and have a look at the relevant header files to see what I mean. If there
604 is an error while malloc()ing the structure, NULL is returned.
606 The 'free' function will free() all the sub components of a particular
607 structure. If any of those sub components have been 'removed', replace
608 them with NULL pointers, the 'free' functions are tolerant of NULL fields.
610 The 'd2i' function copies a binary representation into a C structure. It
611 operates as follows. 'a' is a pointer to a pointer to
612 the structure to populate, 'pp' is a pointer to a pointer to where the DER
613 byte string is located and 'length' is the length of the '*pp' data.
614 If there are no errors, a pointer to the populated structure is returned.
615 If there is an error, NULL is returned. Errors can occur because of
616 malloc() failures but normally they will be due to syntax errors in the DER
617 encoded data being parsed. It is also an error if there was an
618 attempt to read more that 'length' bytes from '*p'. If
619 everything works correctly, the value in '*p' is updated
620 to point at the location just beyond where the DER
621 structure was read from. In this way, chained calls to 'd2i' type
622 functions can be made, with the pointer into the 'data' array being
623 'walked' along the input byte array.
624 Depending on the value passed for 'a', different things will be done. If
625 'a' is NULL, a new structure will be malloc()ed and returned. If '*a' is
626 NULL, a new structure will be malloc()ed and put into '*a' and returned.
627 If '*a' is not NULL, the structure in '*a' will be populated, or in the
628 case of an error, free()ed and then returned.
629 Having these semantics means that a structure
630 can call a 'd2i' function to populate a field and if the field is currently
631 NULL, the structure will be created.
633 The 'i2d' function type is used to copy a C structure to a byte array.
634 The parameter 'a' is the structure to convert and '*p' is where to put it.
635 As for the 'd2i' type structure, 'p' is updated to point after the last
636 byte written. If p is NULL, no data is written. The function also returns
637 the number of bytes written. Where this becomes useful is that if the
638 function is called with a NULL 'p' value, the length is returned. This can
639 then be used to malloc() an array of bytes and then the same function can
640 be recalled passing the malloced array to be written to. e.g.
643 unsigned char *bytes,*p;
644 len=i2d_X509(x,NULL); /* get the size of the ASN1 encoding of 'x' */
645 if ((bytes=(unsigned char *)malloc(len)) == NULL)
650 Please note that a new variable, 'p' was passed to i2d_X509. After the
651 call to i2d_X509 p has been incremented by len bytes.
653 Now the reason for this functional organisation is that it allows nested
654 structures to be built up by calling these functions as required. There
655 are various macros used to help write the general 'i2d', 'd2i', 'new' and
656 'free' functions. They are discussed in another file and would only be
657 used by some-one wanting to add new structures to the library. As you
658 might be able to guess, the process of writing ASN.1 files can be a bit CPU
659 expensive for complex structures. I'm willing to live with this since the
660 simpler library code make my life easier and hopefully most programs using
661 these routines will have their execution profiles dominated by cipher or
662 message digest routines.
663 What follows is a list of 'TYPE' values and the corresponding ASN.1
664 structure and where it is used.
668 ASN1_BIT_STRING BIT STRING
669 ASN1_OCTET_STRING OCTET STRING
670 ASN1_OBJECT OBJECT IDENTIFIER
671 ASN1_PRINTABLESTRING PrintableString
672 ASN1_T61STRING T61String
673 ASN1_IA5STRING IA5String
675 ASN1_TYPE Any of the above mentioned types plus SEQUENCE and SET
677 Most of the above mentioned types are actualled stored in the
678 ASN1_BIT_STRING type and macros are used to differentiate between them.
681 typedef struct asn1_object_st
683 /* both null if a dynamic ASN1_OBJECT, one is
684 * defined if a 'static' ASN1_OBJECT */
690 This is used to store ASN1 OBJECTS. Read 'objects.doc' for details ono
691 routines to manipulate this structure. 'sn' and 'ln' are used to hold text
692 strings that represent the object (short name and long or lower case name).
693 These are used by the 'OBJ' library. 'nid' is a number used by the OBJ
694 library to uniquely identify objects. The ASN1 routines will populate the
695 'length' and 'data' fields which will contain the bit string representing
698 typedef struct asn1_bit_string_st
704 This structure is used to hold all the other base ASN1 types except for
705 ASN1_UTCTIME (which is really just a 'char *'). Length is the number of
706 bytes held in data and type is the ASN1 type of the object (there is a list
709 typedef struct asn1_type_st
714 ASN1_INTEGER * integer;
715 ASN1_BIT_STRING * bit_string;
716 ASN1_OCTET_STRING * octet_string;
717 ASN1_OBJECT * object;
718 ASN1_PRINTABLESTRING * printablestring;
719 ASN1_T61STRING * t61string;
720 ASN1_IA5STRING * ia5string;
721 ASN1_UTCTIME * utctime;
722 ASN1_BIT_STRING * set;
723 ASN1_BIT_STRING * sequence;
726 This structure is used in a few places when 'any' type of object can be
730 X509_CINF CertificateInfo
731 X509_ALGOR AlgorithmIdentifier
733 X509_NAME_ENTRY A single sub component of the name.
735 X509_PUBKEY SubjectPublicKeyInfo
736 The above mentioned types are declared in x509.h. They are all quite
737 straight forward except for the X509_NAME/X509_NAME_ENTRY pair.
738 A X509_NAME is a STACK (see stack.doc) of X509_NAME_ENTRY's.
739 typedef struct X509_name_entry_st
742 ASN1_BIT_STRING *value;
744 int size; /* temp variable */
746 The size is a temporary variable used by i2d_NAME and set is the set number
747 for the particular NAME_ENTRY. A X509_NAME is encoded as a sequence of
748 sequence of sets. Normally each set contains only a single item.
749 Sometimes it contains more. Normally throughout this library there will be
750 only one item per set. The set field contains the 'set' that this entry is
751 a member of. So if you have just created a X509_NAME structure and
752 populated it with X509_NAME_ENTRYs, you should then traverse the X509_NAME
753 (which is just a STACK) and set the 'set/' field to incrementing numbers.
754 For more details on why this is done, read the ASN.1 spec for Distinguished
757 X509_REQ CertificateRequest
758 X509_REQ_INFO CertificateRequestInfo
759 These are used to hold certificate requests.
761 X509_CRL CertificateRevocationList
762 These are used to hold a certificate revocation list
764 RSAPrivateKey PrivateKeyInfo
765 RSAPublicKey PublicKeyInfo
766 Both these 'function groups' operate on 'RSA' structures (see rsa.doc).
767 The difference is that the RSAPublicKey operations only manipulate the m
768 and e fields in the RSA structure.
770 DSAPrivateKey DSS private key
771 DSAPublicKey DSS public key
772 Both these 'function groups' operate on 'DSS' structures (see dsa.doc).
773 The difference is that the RSAPublicKey operations only manipulate the
774 XXX fields in the DSA structure.
777 This is used to hold the p and g value for The Diffie-Hellman operation.
778 The function deal with the 'DH' strucure (see dh.doc).
780 Now all of these function types can be used with several other functions to give
781 quite useful set of general manipulation routines. Normally one would
782 not uses these functions directly but use them via macros.
784 char *ASN1_dup(int (*i2d)(),char *(*d2i)(),char *x);
785 'x' is the input structure case to a 'char *', 'i2d' is the 'i2d_TYPE'
786 function for the type that 'x' is and d2i is the 'd2i_TYPE' function for the
787 type that 'x' is. As is obvious from the parameters, this function
788 duplicates the strucutre by transforming it into the DER form and then
789 re-loading it into a new strucutre and returning the new strucutre. This
790 is obviously a bit cpu intensive but when faced with a complex dynamic
791 structure this is the simplest programming approach. There are macros for
792 duplicating the major data types but is simple to add extras.
794 char *ASN1_d2i_fp(char *(*new)(),char *(*d2i)(),FILE *fp,unsigned char **x);
795 'x' is a pointer to a pointer of the 'desired type'. new and d2i are the
796 corresponding 'TYPE_new' and 'd2i_TYPE' functions for the type and 'fp' is
797 an open file pointer to read from. This function reads from 'fp' as much
798 data as it can and then uses 'd2i' to parse the bytes to load and return
799 the parsed strucutre in 'x' (if it was non-NULL) and to actually return the
800 strucutre. The behavior of 'x' is as per all the other d2i functions.
802 char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x);
803 The 'BIO' is the new IO type being used in SSLeay (see bio.doc). This
804 function is the same as ASN1_d2i_fp() except for the BIO argument.
805 ASN1_d2i_fp() actually calls this function.
807 int ASN1_i2d_fp(int (*i2d)(),FILE *out,unsigned char *x);
808 'x' is converted to bytes by 'i2d' and then written to 'out'. ASN1_i2d_fp
809 and ASN1_d2i_fp are not really symetric since ASN1_i2d_fp will read all
810 available data from the file pointer before parsing a single item while
811 ASN1_i2d_fp can be used to write a sequence of data objects. To read a
812 series of objects from a file I would sugest loading the file into a buffer
813 and calling the relevent 'd2i' functions.
815 char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x);
816 This function is the same as ASN1_i2d_fp() except for the BIO argument.
817 ASN1_i2d_fp() actually calls this function.
819 char * PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
820 This function will read the next PEM encoded (base64) object of the same
821 type as 'x' (loaded by the d2i function). 'name' is the name that is in
822 the '-----BEGIN name-----' that designates the start of that object type.
823 If the data is encrypted, 'cb' will be called to prompt for a password. If
824 it is NULL a default function will be used to prompt from the password.
825 'x' is delt with as per the standard 'd2i' function interface. This
826 function can be used to read a series of objects from a file. While any
827 data type can be encrypted (see PEM_ASN1_write) only RSA private keys tend
830 char * PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *fp,
831 char **x,int (*cb)());
832 Same as PEM_ASN1_read() except using a BIO. This is called by
835 int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,EVP_CIPHER *enc,
836 unsigned char *kstr,int klen,int (*callback)());
838 int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *fp,
839 char *x,EVP_CIPHER *enc,unsigned char *kstr,int klen,
842 int ASN1_sign(int (*i2d)(), X509_ALGOR *algor1, X509_ALGOR *algor2,
843 ASN1_BIT_STRING *signature, char *data, RSA *rsa, EVP_MD *type);
844 int ASN1_verify(int (*i2d)(), X509_ALGOR *algor1,
845 ASN1_BIT_STRING *signature,char *data, RSA *rsa);
847 int ASN1_BIT_STRING_cmp(ASN1_BIT_STRING *a, ASN1_BIT_STRING *b);
848 ASN1_BIT_STRING *ASN1_BIT_STRING_type_new(int type );
850 int ASN1_UTCTIME_check(ASN1_UTCTIME *a);
851 void ASN1_UTCTIME_print(BIO *fp,ASN1_UTCTIME *a);
852 ASN1_UTCTIME *ASN1_UTCTIME_dup(ASN1_UTCTIME *a);
854 ASN1_BIT_STRING *d2i_asn1_print_type(ASN1_BIT_STRING **a,unsigned char **pp,
855 long length,int type);
857 int i2d_ASN1_SET(STACK *a, unsigned char **pp,
858 int (*func)(), int ex_tag, int ex_class);
859 STACK * d2i_ASN1_SET(STACK **a, unsigned char **pp, long length,
860 char *(*func)(), int ex_tag, int ex_class);
862 int i2a_ASN1_OBJECT(BIO *bp,ASN1_OBJECT *object);
863 int i2a_ASN1_INTEGER(BIO *bp, ASN1_INTEGER *a);
864 int a2i_ASN1_INTEGER(BIO *bp,ASN1_INTEGER *bs,char *buf,int size);
866 int ASN1_INTEGER_set(ASN1_INTEGER *a, long v);
867 long ASN1_INTEGER_get(ASN1_INTEGER *a);
868 ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai);
869 BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn);
871 /* given a string, return the correct type. Max is the maximum number
872 * of bytes to parse. It stops parsing when 'max' bytes have been
873 * processed or a '\0' is hit */
874 int ASN1_PRINTABLE_type(unsigned char *s,int max);
876 void ASN1_parse(BIO *fp,unsigned char *pp,long len);
878 int i2d_ASN1_bytes(ASN1_BIT_STRING *a, unsigned char **pp, int tag, int class);
879 ASN1_BIT_STRING *d2i_ASN1_bytes(ASN1_OCTET_STRING **a, unsigned char **pp,
880 long length, int Ptag, int Pclass);
883 int asn1_Finish(ASN1_CTX *c);
886 int ASN1_get_object(unsigned char **pp, long *plength, int *ptag,
887 int *pclass, long omax);
888 int ASN1_check_infinite_end(unsigned char **p,long len);
889 void ASN1_put_object(unsigned char **pp, int constructed, int length,
891 int ASN1_object_size(int constructed, int length, int tag);
893 X509 * X509_get_cert(CERTIFICATE_CTX *ctx,X509_NAME * name,X509 *tmp_x509);
894 int X509_add_cert(CERTIFICATE_CTX *ctx,X509 *);
896 char * X509_cert_verify_error_string(int n);
897 int X509_add_cert_file(CERTIFICATE_CTX *c,char *file, int type);
898 char * X509_gmtime (char *s, long adj);
899 int X509_add_cert_dir (CERTIFICATE_CTX *c,char *dir, int type);
900 int X509_load_verify_locations (CERTIFICATE_CTX *ctx,
901 char *file_env, char *dir_env);
902 int X509_set_default_verify_paths(CERTIFICATE_CTX *cts);
903 X509 * X509_new_D2i_X509(int len, unsigned char *p);
904 char * X509_get_default_cert_area(void );
905 char * X509_get_default_cert_dir(void );
906 char * X509_get_default_cert_file(void );
907 char * X509_get_default_cert_dir_env(void );
908 char * X509_get_default_cert_file_env(void );
909 char * X509_get_default_private_dir(void );
910 X509_REQ *X509_X509_TO_req(X509 *x, RSA *rsa);
911 int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)());
913 CERTIFICATE_CTX *CERTIFICATE_CTX_new();
914 void CERTIFICATE_CTX_free(CERTIFICATE_CTX *c);
916 void X509_NAME_print(BIO *fp, X509_NAME *name, int obase);
917 int X509_print_fp(FILE *fp,X509 *x);
918 int X509_print(BIO *fp,X509 *x);
920 X509_INFO * X509_INFO_new(void);
921 void X509_INFO_free(X509_INFO *a);
923 char * X509_NAME_oneline(X509_NAME *a);
925 #define X509_verify(x,rsa)
926 #define X509_REQ_verify(x,rsa)
927 #define X509_CRL_verify(x,rsa)
929 #define X509_sign(x,rsa,md)
930 #define X509_REQ_sign(x,rsa,md)
931 #define X509_CRL_sign(x,rsa,md)
933 #define X509_dup(x509)
934 #define d2i_X509_fp(fp,x509)
935 #define i2d_X509_fp(fp,x509)
936 #define d2i_X509_bio(bp,x509)
937 #define i2d_X509_bio(bp,x509)
939 #define X509_CRL_dup(crl)
940 #define d2i_X509_CRL_fp(fp,crl)
941 #define i2d_X509_CRL_fp(fp,crl)
942 #define d2i_X509_CRL_bio(bp,crl)
943 #define i2d_X509_CRL_bio(bp,crl)
945 #define X509_REQ_dup(req)
946 #define d2i_X509_REQ_fp(fp,req)
947 #define i2d_X509_REQ_fp(fp,req)
948 #define d2i_X509_REQ_bio(bp,req)
949 #define i2d_X509_REQ_bio(bp,req)
951 #define RSAPrivateKey_dup(rsa)
952 #define d2i_RSAPrivateKey_fp(fp,rsa)
953 #define i2d_RSAPrivateKey_fp(fp,rsa)
954 #define d2i_RSAPrivateKey_bio(bp,rsa)
955 #define i2d_RSAPrivateKey_bio(bp,rsa)
957 #define X509_NAME_dup(xn)
958 #define X509_NAME_ENTRY_dup(ne)
960 void X509_REQ_print_fp(FILE *fp,X509_REQ *req);
961 void X509_REQ_print(BIO *fp,X509_REQ *req);
963 RSA *X509_REQ_extract_key(X509_REQ *req);
964 RSA *X509_extract_key(X509 *x509);
966 int X509_issuer_and_serial_cmp(X509 *a, X509 *b);
967 unsigned long X509_issuer_and_serial_hash(X509 *a);
969 X509_NAME * X509_get_issuer_name(X509 *a);
970 int X509_issuer_name_cmp(X509 *a, X509 *b);
971 unsigned long X509_issuer_name_hash(X509 *a);
973 X509_NAME * X509_get_subject_name(X509 *a);
974 int X509_subject_name_cmp(X509 *a,X509 *b);
975 unsigned long X509_subject_name_hash(X509 *x);
977 int X509_NAME_cmp (X509_NAME *a, X509_NAME *b);
978 unsigned long X509_NAME_hash(X509_NAME *x);
981 ==== bio.doc ========================================================
985 This documentation is rather sparse, you are probably best
986 off looking at the code for specific details.
988 The BIO library is a IO abstraction that was originally
989 inspired by the need to have callbacks to perform IO to FILE
990 pointers when using Windows 3.1 DLLs. There are two types
991 of BIO; a source/sink type and a filter type.
992 The source/sink methods are as follows:
993 - BIO_s_mem() memory buffer - a read/write byte array that
994 grows until memory runs out :-).
995 - BIO_s_file() FILE pointer - A wrapper around the normal
996 'FILE *' commands, good for use with stdin/stdout.
997 - BIO_s_fd() File descriptor - A wrapper around file
998 descriptors, often used with pipes.
999 - BIO_s_socket() Socket - Used around sockets. It is
1000 mostly in the Microsoft world that sockets are different
1001 from file descriptors and there are all those ugly winsock
1003 - BIO_s_null() Null - read nothing and write nothing.; a
1004 useful endpoint for filter type BIO's specifically things
1005 like the message digest BIO.
1007 The filter types are
1008 - BIO_f_buffer() IO buffering - does output buffering into
1009 larger chunks and performs input buffering to allow gets()
1011 - BIO_f_md() Message digest - a transparent filter that can
1012 be asked to return a message digest for the data that has
1014 - BIO_f_cipher() Encrypt or decrypt all data passing
1016 - BIO_f_base64() Base64 decode on read and encode on write.
1017 - BIO_f_ssl() A filter that performs SSL encryption on the
1018 data sent through it.
1021 The BIO library has a set of base functions that are
1022 implemented for each particular type. Filter BIOs will
1023 normally call the equivalent function on the source/sink BIO
1024 that they are layered on top of after they have performed
1025 some modification to the data stream. Multiple filter BIOs
1026 can be 'push' into a stack of modifers, so to read from a
1027 file, unbase64 it, then decrypt it, a BIO_f_cipher,
1028 BIO_f_base64 and a BIO_s_file would probably be used. If a
1029 sha-1 and md5 message digest needed to be generated, a stack
1030 two BIO_f_md() BIOs and a BIO_s_null() BIO could be used.
1031 The base functions are
1032 - BIO *BIO_new(BIO_METHOD *type); Create a new BIO of type 'type'.
1033 - int BIO_free(BIO *a); Free a BIO structure. Depending on
1034 the configuration, this will free the underlying data
1035 object for a source/sink BIO.
1036 - int BIO_read(BIO *b, char *data, int len); Read upto 'len'
1038 - int BIO_gets(BIO *bp,char *buf, int size); Depending on
1039 the BIO, this can either be a 'get special' or a get one
1040 line of data, as per fgets();
1041 - int BIO_write(BIO *b, char *data, int len); Write 'len'
1042 bytes from 'data' to the 'b' BIO.
1043 - int BIO_puts(BIO *bp,char *buf); Either a 'put special' or
1044 a write null terminated string as per fputs().
1045 - long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg); A
1046 control function which is used to manipulate the BIO
1047 structure and modify it's state and or report on it. This
1048 function is just about never used directly, rather it
1049 should be used in conjunction with BIO_METHOD specific
1051 - BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the
1052 top of the 'old' BIO list. new_top should be a filter BIO.
1053 All writes will go through 'new_top' first and last on read.
1055 - BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if
1058 If a particular low level BIO method is not supported
1059 (normally BIO_gets()), -2 will be returned if that method is
1060 called. Otherwise the IO methods (read, write, gets, puts)
1061 will return the number of bytes read or written, and 0 or -1
1062 for error (or end of input). For the -1 case,
1063 BIO_should_retry(bio) can be called to determine if it was a
1064 genuine error or a temporary problem. -2 will also be
1065 returned if the BIO has not been initalised yet, in all
1066 cases, the correct error codes are set (accessible via the
1070 The following functions are convenience functions:
1071 - int BIO_printf(BIO *bio, char * format, ..); printf but
1073 - long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a
1074 convenience function to allow a different argument types
1075 to be passed to BIO_ctrl().
1076 - int BIO_dump(BIO *b,char *bytes,int len); output 'len'
1077 bytes from 'bytes' in a hex dump debug format.
1078 - long BIO_debug_callback(BIO *bio, int cmd, char *argp, int
1079 argi, long argl, long ret) - a default debug BIO callback,
1080 this is mentioned below. To use this one normally has to
1081 use the BIO_set_callback_arg() function to assign an
1082 output BIO for the callback to use.
1083 - BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack'
1084 of BIOs, this function scan the list and returns the first
1085 that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX.
1086 - void BIO_free_all(BIO *bio); Free the bio and all other BIOs
1087 in the list. It walks the bio->next_bio list.
1091 Extra commands are normally implemented as macros calling BIO_ctrl().
1092 - BIO_number_read(BIO *bio) - the number of bytes processed
1094 - BIO_number_written(BIO *bio) - the number of bytes written
1095 by BIO_write(bio,.).
1096 - BIO_reset(BIO *bio) - 'reset' the BIO.
1097 - BIO_eof(BIO *bio) - non zero if we are at the current end
1099 - BIO_set_close(BIO *bio, int close_flag) - set the close flag.
1100 - BIO_get_close(BIO *bio) - return the close flag.
1101 BIO_pending(BIO *bio) - return the number of bytes waiting
1102 to be read (normally buffered internally).
1103 - BIO_flush(BIO *bio) - output any data waiting to be output.
1104 - BIO_should_retry(BIO *io) - after a BIO_read/BIO_write
1105 operation returns 0 or -1, a call to this function will
1106 return non zero if you should retry the call later (this
1107 is for non-blocking IO).
1108 - BIO_should_read(BIO *io) - we should retry when data can
1110 - BIO_should_write(BIO *io) - we should retry when data can
1112 - BIO_method_name(BIO *io) - return a string for the method name.
1113 - BIO_method_type(BIO *io) - return the unique ID of the BIO method.
1114 - BIO_set_callback(BIO *io, long (*callback)(BIO *io, int
1115 cmd, char *argp, int argi, long argl, long ret); - sets
1117 - BIO_get_callback(BIO *io) - return the assigned function
1119 - BIO_set_callback_arg(BIO *io, char *arg) - assign some
1120 data against the BIO. This is normally used by the debug
1121 callback but could in reality be used for anything. To
1122 get an idea of how all this works, have a look at the code
1123 in the default debug callback mentioned above. The
1124 callback can modify the return values.
1126 Details of the BIO_METHOD structure.
1127 typedef struct bio_method_st
1140 The 'type' is the numeric type of the BIO, these are listed in buffer.h;
1141 'Name' is a textual representation of the BIO 'type'.
1142 The 7 function pointers point to the respective function
1143 methods, some of which can be NULL if not implemented.
1145 typedef struct bio_st
1148 long (*callback)(BIO * bio, int mode, char *argp, int
1149 argi, long argl, long ret);
1150 char *cb_arg; /* first argument for the callback */
1153 int flags; /* extra storage */
1156 struct bio_st *next_bio; /* used by filter BIOs */
1158 unsigned long num_read;
1159 unsigned long num_write;
1162 - 'Method' is the BIO method.
1163 - 'callback', when configured, is called before and after
1164 each BIO method is called for that particular BIO. This
1165 is intended primarily for debugging and of informational feedback.
1166 - 'init' is 0 when the BIO can be used for operation.
1167 Often, after a BIO is created, a number of operations may
1168 need to be performed before it is available for use. An
1169 example is for BIO_s_sock(). A socket needs to be
1170 assigned to the BIO before it can be used.
1171 - 'shutdown', this flag indicates if the underlying
1172 comunication primative being used should be closed/freed
1173 when the BIO is closed.
1174 - 'flags' is used to hold extra state. It is primarily used
1175 to hold information about why a non-blocking operation
1176 failed and to record startup protocol information for the
1178 - 'num' and 'ptr' are used to hold instance specific state
1179 like file descriptors or local data structures.
1180 - 'next_bio' is used by filter BIOs to hold the pointer of the
1181 next BIO in the chain. written data is sent to this BIO and
1182 data read is taken from it.
1183 - 'references' is used to indicate the number of pointers to
1184 this structure. This needs to be '1' before a call to
1185 BIO_free() is made if the BIO_free() function is to
1186 actually free() the structure, otherwise the reference
1187 count is just decreased. The actual BIO subsystem does
1188 not really use this functionality but it is useful when
1189 used in more advanced applicaion.
1190 - num_read and num_write are the total number of bytes
1191 read/written via the 'read()' and 'write()' methods.
1193 BIO_ctrl operations.
1194 The following is the list of standard commands passed as the
1195 second parameter to BIO_ctrl() and should be supported by
1196 all BIO as best as possible. Some are optional, some are
1197 manditory, in any case, where is makes sense, a filter BIO
1198 should pass such requests to underlying BIO's.
1199 - BIO_CTRL_RESET - Reset the BIO back to an initial state.
1200 - BIO_CTRL_EOF - return 0 if we are not at the end of input,
1202 - BIO_CTRL_INFO - BIO specific special command, normal
1204 - BIO_CTRL_SET - set IO specific parameter.
1205 - BIO_CTRL_GET - get IO specific parameter.
1206 - BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one
1207 of BIO_CLOSE or BIO_NOCLOSE.
1208 - BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag.
1209 - BIO_CTRL_PENDING - Return the number of bytes available
1211 - BIO_CTRL_FLUSH - Output pending data, return number of bytes output.
1212 - BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned)
1213 should we 'retry' when IO is possible on the underlying IO object.
1214 - BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on.
1216 The following command is a special BIO_s_file() specific option.
1217 - BIO_CTRL_SET_FILENAME - specify a file to open for IO.
1219 The BIO_CTRL_RETRY_TYPE needs a little more explanation.
1220 When performing non-blocking IO, or say reading on a memory
1221 BIO, when no data is present (or cannot be written),
1222 BIO_read() and/or BIO_write() will return -1.
1223 BIO_should_retry(bio) will return true if this is due to an
1224 IO condition rather than an actual error. In the case of
1225 BIO_s_mem(), a read when there is no data will return -1 and
1226 a should retry when there is more 'read' data.
1227 The retry type is deduced from 2 macros
1228 BIO_should_read(bio) and BIO_should_write(bio).
1229 Now while it may appear obvious that a BIO_read() failure
1230 should indicate that a retry should be performed when more
1231 read data is available, this is often not true when using
1232 things like an SSL BIO. During the SSL protocol startup
1233 multiple reads and writes are performed, triggered by any
1234 SSL_read or SSL_write.
1235 So to write code that will transparently handle either a
1240 if (BIO_should_retry(bio))
1242 if (BIO_should_read(bio))
1244 /* call us again when BIO can be read */
1246 if (BIO_should_write(bio))
1248 /* call us again when BIO can be written */
1253 At this point in time only read and write conditions can be
1254 used but in the future I can see the situation for other
1255 conditions, specifically with SSL there could be a condition
1256 of a X509 certificate lookup taking place and so the non-
1257 blocking BIO_read would require a retry when the certificate
1258 lookup subsystem has finished it's lookup. This is all
1259 makes more sense and is easy to use in a event loop type
1261 When using the SSL BIO, either SSL_read() or SSL_write()s
1262 can be called during the protocol startup and things will
1263 still work correctly.
1264 The nice aspect of the use of the BIO_should_retry() macro
1265 is that all the errno codes that indicate a non-fatal error
1266 are encapsulated in one place. The Windows specific error
1267 codes and WSAGetLastError() calls are also hidden from the
1270 Notes on each BIO method.
1271 Normally buffer.h is just required but depending on the
1272 BIO_METHOD, ssl.h or evp.h will also be required.
1274 BIO_METHOD *BIO_s_mem(void);
1275 - BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) -
1276 set the underlying BUF_MEM structure for the BIO to use.
1277 - BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL,
1278 set it to point to the memory array and return the number
1280 A read/write BIO. Any data written is appended to the
1281 memory array and any read is read from the front. This BIO
1282 can be used for read/write at the same time. BIO_gets() is
1283 supported in the fgets() sense.
1284 BIO_CTRL_INFO can be used to retrieve pointers to the memory
1285 buffer and it's length.
1287 BIO_METHOD *BIO_s_file(void);
1288 - BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use.
1289 - BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use.
1290 - BIO_read_filename(BIO *bio, char *name) - read from file.
1291 - BIO_write_filename(BIO *bio, char *name) - write to file.
1292 - BIO_append_filename(BIO *bio, char *name) - append to file.
1293 This BIO sits over the normal system fread()/fgets() type
1294 functions. Gets() is supported. This BIO in theory could be
1295 used for read and write but it is best to think of each BIO
1296 of this type as either a read or a write BIO, not both.
1298 BIO_METHOD *BIO_s_socket(void);
1299 BIO_METHOD *BIO_s_fd(void);
1300 - BIO_sock_should_retry(int i) - the underlying function
1301 used to determine if a call should be retried; the
1302 argument is the '0' or '-1' returned by the previous BIO
1304 - BIO_fd_should_retry(int i) - same as the
1305 - BIO_sock_should_retry() except that it is different internally.
1306 - BIO_set_fd(BIO *bio, int fd, int close_flag) - set the
1307 file descriptor to use
1308 - BIO_get_fd(BIO *bio, int *fd) - get the file descriptor.
1309 These two methods are very similar. Gets() is not
1310 supported, if you want this functionality, put a
1311 BIO_f_buffer() onto it. This BIO is bi-directional if the
1312 underlying file descriptor is. This is normally the case
1313 for sockets but not the case for stdio descriptors.
1315 BIO_METHOD *BIO_s_null(void);
1316 Read and write as much data as you like, it all disappears
1319 BIO_METHOD *BIO_f_buffer(void);
1320 - BIO_get_buffer_num_lines(BIO *bio) - return the number of
1321 complete lines in the buffer.
1322 - BIO_set_buffer_size(BIO *bio, long size) - set the size of
1324 This type performs input and output buffering. It performs
1325 both at the same time. The size of the buffer can be set
1326 via the set buffer size option. Data buffered for output is
1327 only written when the buffer fills.
1329 BIO_METHOD *BIO_f_ssl(void);
1330 - BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL
1332 - BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure
1334 The SSL bio is a little different from normal BIOs because
1335 the underlying SSL structure is a little different. A SSL
1336 structure performs IO via a read and write BIO. These can
1337 be different and are normally set via the
1338 SSL_set_rbio()/SSL_set_wbio() calls. The SSL_set_fd() calls
1339 are just wrappers that create socket BIOs and then call
1340 SSL_set_bio() where the read and write BIOs are the same.
1341 The BIO_push() operation makes the SSLs IO BIOs the same, so
1342 make sure the BIO pushed is capable of two directional
1343 traffic. If it is not, you will have to install the BIOs
1344 via the more conventional SSL_set_bio() call. BIO_pop() will retrieve
1347 BIO_METHOD *BIO_f_md(void);
1348 - BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest
1350 - BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest
1351 method in use in mdp, return 0 if not set yet.
1352 - BIO_reset() reinitializes the digest (EVP_DigestInit())
1353 and passes the reset to the underlying BIOs.
1354 All data read or written via BIO_read() or BIO_write() to
1355 this BIO will be added to the calculated digest. This
1356 implies that this BIO is only one directional. If read and
1357 write operations are performed, two separate BIO_f_md() BIOs
1358 are reuqired to generate digests on both the input and the
1359 output. BIO_gets(BIO *bio, char *md, int size) will place the
1360 generated digest into 'md' and return the number of bytes.
1361 The EVP_MAX_MD_SIZE should probably be used to size the 'md'
1362 array. Reading the digest will also reset it.
1364 BIO_METHOD *BIO_f_cipher(void);
1365 - BIO_reset() reinitializes the cipher.
1366 - BIO_flush() should be called when the last bytes have been
1367 output to flush the final block of block ciphers.
1368 - BIO_get_cipher_status(BIO *b), when called after the last
1369 read from a cipher BIO, returns non-zero if the data
1370 decrypted correctly, otherwise, 0.
1371 - BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key,
1372 unsigned char *iv, int encrypt) This function is used to
1373 setup a cipher BIO. The length of key and iv are
1374 specified by the choice of EVP_CIPHER. Encrypt is 1 to
1375 encrypt and 0 to decrypt.
1377 BIO_METHOD *BIO_f_base64(void);
1378 - BIO_flush() should be called when the last bytes have been output.
1379 This BIO base64 encodes when writing and base64 decodes when
1380 reading. It will scan the input until a suitable begin line
1381 is found. After reading data, BIO_reset() will reset the
1382 BIO to start scanning again. Do not mix reading and writing
1383 on the same base64 BIO. It is meant as a single stream BIO.
1387 one/both BIO_s_file()
1397 It is easy to mix one and two directional BIOs, all one has
1398 to do is to keep two separate BIO pointers for reading and
1399 writing and be careful about usage of underlying BIOs. The
1400 SSL bio by it's very nature has to be two directional but
1401 the BIO_push() command will push the one BIO into the SSL
1402 BIO for both reading and writing.
1404 The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c.
1407 ==== blowfish.doc ========================================================
1409 The Blowfish library.
1411 Blowfish is a block cipher that operates on 64bit (8 byte) quantities. It
1412 uses variable size key, but 128bit (16 byte) key would normally be considered
1413 good. It can be used in all the modes that DES can be used. This
1414 library implements the ecb, cbc, cfb64, ofb64 modes.
1416 Blowfish is quite a bit faster that DES, and much faster than IDEA or
1417 RC2. It is one of the faster block ciphers.
1419 For all calls that have an 'input' and 'output' variables, they can be the
1422 This library requires the inclusion of 'blowfish.h'.
1424 All of the encryption functions take what is called an BF_KEY as an
1425 argument. An BF_KEY is an expanded form of the Blowfish key.
1426 For all modes of the Blowfish algorithm, the BF_KEY used for
1427 decryption is the same one that was used for encryption.
1429 The define BF_ENCRYPT is passed to specify encryption for the functions
1430 that require an encryption/decryption flag. BF_DECRYPT is passed to
1433 Please note that any of the encryption modes specified in my DES library
1434 could be used with Blowfish. I have only implemented ecb, cbc, cfb64 and
1435 ofb64 for the following reasons.
1436 - ecb is the basic Blowfish encryption.
1437 - cbc is the normal 'chaining' form for block ciphers.
1438 - cfb64 can be used to encrypt single characters, therefore input and output
1439 do not need to be a multiple of 8.
1440 - ofb64 is similar to cfb64 but is more like a stream cipher, not as
1441 secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
1442 - If you want triple Blowfish, thats 384 bits of key and you must be totally
1443 obsessed with security. Still, if you want it, it is simple enough to
1444 copy the function from the DES library and change the des_encrypt to
1445 BF_encrypt; an exercise left for the paranoid reader :-).
1447 The functions are as follows:
1453 BF_set_key converts an 'len' byte key into a BF_KEY.
1454 A 'ks' is an expanded form of the 'key' which is used to
1455 perform actual encryption. It can be regenerated from the Blowfish key
1456 so it only needs to be kept when encryption or decryption is about
1457 to occur. Don't save or pass around BF_KEY's since they
1458 are CPU architecture dependent, 'key's are not. Blowfish is an
1459 interesting cipher in that it can be used with a variable length
1460 key. 'len' is the length of 'key' to be used as the key.
1461 A 'len' of 16 is recomended by me, but blowfish can use upto
1462 72 bytes. As a warning, blowfish has a very very slow set_key
1463 function, it actually runs BF_encrypt 521 times.
1465 void BF_encrypt(unsigned long *data, BF_KEY *key);
1466 void BF_decrypt(unsigned long *data, BF_KEY *key);
1467 These are the Blowfish encryption function that gets called by just
1468 about every other Blowfish routine in the library. You should not
1469 use this function except to implement 'modes' of Blowfish.
1470 I say this because the
1471 functions that call this routine do the conversion from 'char *' to
1472 long, and this needs to be done to make sure 'non-aligned' memory
1473 access do not occur.
1474 Data is a pointer to 2 unsigned long's and key is the
1477 void BF_ecb_encrypt(
1482 This is the basic Electronic Code Book form of Blowfish (in DES this
1483 mode is called Electronic Code Book so I'm going to use the term
1484 for blowfish as well.
1485 Input is encrypted into output using the key represented by
1486 key. Depending on the encrypt, encryption or
1487 decryption occurs. Input is 8 bytes long and output is 8 bytes.
1489 void BF_cbc_encrypt(
1494 unsigned char *ivec,
1496 This routine implements Blowfish in Cipher Block Chaining mode.
1497 Input, which should be a multiple of 8 bytes is encrypted
1498 (or decrypted) to output which will also be a multiple of 8 bytes.
1499 The number of bytes is in length (and from what I've said above,
1500 should be a multiple of 8). If length is not a multiple of 8, bad
1501 things will probably happen. ivec is the initialisation vector.
1502 This function updates iv after each call so that it can be passed to
1503 the next call to BF_cbc_encrypt().
1505 void BF_cfb64_encrypt(
1510 unsigned char *ivec,
1513 This is one of the more useful functions in this Blowfish library, it
1514 implements CFB mode of Blowfish with 64bit feedback.
1515 This allows you to encrypt an arbitrary number of bytes,
1516 you do not require 8 byte padding. Each call to this
1517 routine will encrypt the input bytes to output and then update ivec
1518 and num. Num contains 'how far' we are though ivec.
1519 'Encrypt' is used to indicate encryption or decryption.
1520 CFB64 mode operates by using the cipher to generate a stream
1521 of bytes which is used to encrypt the plain text.
1522 The cipher text is then encrypted to generate the next 64 bits to
1523 be xored (incrementally) with the next 64 bits of plain
1524 text. As can be seen from this, to encrypt or decrypt,
1525 the same 'cipher stream' needs to be generated but the way the next
1526 block of data is gathered for encryption is different for
1527 encryption and decryption.
1529 void BF_ofb64_encrypt(
1534 unsigned char *ivec,
1536 This functions implements OFB mode of Blowfish with 64bit feedback.
1537 This allows you to encrypt an arbitrary number of bytes,
1538 you do not require 8 byte padding. Each call to this
1539 routine will encrypt the input bytes to output and then update ivec
1540 and num. Num contains 'how far' we are though ivec.
1541 This is in effect a stream cipher, there is no encryption or
1544 For reading passwords, I suggest using des_read_pw_string() from my DES library.
1545 To generate a password from a text string, I suggest using MD5 (or MD2) to
1546 produce a 16 byte message digest that can then be passed directly to
1550 For more information about the specific Blowfish modes in this library
1551 (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
1552 documentation on my DES library. What is said about DES is directly
1553 applicable for Blowfish.
1556 ==== bn.doc ========================================================
1558 The Big Number library.
1560 #include "bn.h" when using this library.
1562 This big number library was written for use in implementing the RSA and DH
1563 public key encryption algorithms. As such, features such as negative
1564 numbers have not been extensively tested but they should work as expected.
1565 This library uses dynamic memory allocation for storing its data structures
1566 and so there are no limit on the size of the numbers manipulated by these
1567 routines but there is always the requirement to check return codes from
1568 functions just in case a memory allocation error has occurred.
1570 The basic object in this library is a BIGNUM. It is used to hold a single
1571 large integer. This type should be considered opaque and fields should not
1572 be modified or accessed directly.
1573 typedef struct bignum_st
1575 int top; /* Index of last used d. */
1576 BN_ULONG *d; /* Pointer to an array of 'BITS2' bit chunks. */
1577 int max; /* Size of the d array. */
1580 The big number is stored in a malloced array of BN_ULONG's. A BN_ULONG can
1581 be either 16, 32 or 64 bits in size, depending on the 'number of bits'
1583 The 'd' field is this array. 'max' is the size of the 'd' array that has
1584 been allocated. 'top' is the 'last' entry being used, so for a value of 4,
1585 bn.d[0]=4 and bn.top=1. 'neg' is 1 if the number is negative.
1586 When a BIGNUM is '0', the 'd' field can be NULL and top == 0.
1588 Various routines in this library require the use of 'temporary' BIGNUM
1589 variables during their execution. Due to the use of dynamic memory
1590 allocation to create BIGNUMs being rather expensive when used in
1591 conjunction with repeated subroutine calls, the BN_CTX structure is
1592 used. This structure contains BN_CTX BIGNUMs. BN_CTX
1593 is the maximum number of temporary BIGNUMs any publicly exported
1597 typedef struct bignum_ctx
1599 int tos; /* top of stack */
1600 BIGNUM *bn[BN_CTX]; /* The variables */
1603 The functions that follow have been grouped according to function. Most
1604 arithmetic functions return a result in the first argument, sometimes this
1605 first argument can also be an input parameter, sometimes it cannot. These
1606 restrictions are documented.
1608 extern BIGNUM *BN_value_one;
1609 There is one variable defined by this library, a BIGNUM which contains the
1610 number 1. This variable is useful for use in comparisons and assignment.
1614 int BN_num_bits(BIGNUM *a);
1615 This function returns the size of 'a' in bits.
1617 int BN_num_bytes(BIGNUM *a);
1618 This function (macro) returns the size of 'a' in bytes.
1619 For conversion of BIGNUMs to byte streams, this is the number of
1620 bytes the output string will occupy. If the output byte
1621 format specifies that the 'top' bit indicates if the number is
1622 signed, so an extra '0' byte is required if the top bit on a
1623 positive number is being written, it is upto the application to
1624 make this adjustment. Like I said at the start, I don't
1625 really support negative numbers :-).
1627 Creation/Destruction routines.
1630 Return a new BIGNUM object. The number initially has a value of 0. If
1631 there is an error, NULL is returned.
1633 void BN_free(BIGNUM *a);
1636 void BN_clear(BIGNUM *a);
1637 Sets 'a' to a value of 0 and also zeros all unused allocated
1638 memory. This function is used to clear a variable of 'sensitive'
1639 data that was held in it.
1641 void BN_clear_free(BIGNUM *a);
1642 This function zeros the memory used by 'a' and then free()'s it.
1643 This function should be used to BN_free() BIGNUMS that have held
1644 sensitive numeric values like RSA private key values. Both this
1645 function and BN_clear tend to only be used by RSA and DH routines.
1647 BN_CTX *BN_CTX_new(void);
1648 Returns a new BN_CTX. NULL on error.
1650 void BN_CTX_free(BN_CTX *c);
1651 Free a BN_CTX structure. The BIGNUMs in 'c' are BN_clear_free()ed.
1653 BIGNUM *bn_expand(BIGNUM *b, int bits);
1654 This is an internal function that should not normally be used. It
1655 ensures that 'b' has enough room for a 'bits' bit number. It is
1656 mostly used by the various BIGNUM routines. If there is an error,
1657 NULL is returned. if not, 'b' is returned.
1659 BIGNUM *BN_copy(BIGNUM *to, BIGNUM *from);
1660 The 'from' is copied into 'to'. NULL is returned if there is an
1661 error, otherwise 'to' is returned.
1663 BIGNUM *BN_dup(BIGNUM *a);
1664 A new BIGNUM is created and returned containing the value of 'a'.
1665 NULL is returned on error.
1667 Comparison and Test Functions.
1669 int BN_is_zero(BIGNUM *a)
1670 Return 1 if 'a' is zero, else 0.
1673 Return 1 is 'a' is one, else 0.
1676 Return 1 if 'a' == w, else 0. 'w' is a BN_ULONG.
1678 int BN_cmp(BIGNUM *a, BIGNUM *b);
1679 Return -1 if 'a' is less than 'b', 0 if 'a' and 'b' are the same
1680 and 1 is 'a' is greater than 'b'. This is a signed comparison.
1682 int BN_ucmp(BIGNUM *a, BIGNUM *b);
1683 This function is the same as BN_cmp except that the comparison
1684 ignores the sign of the numbers.
1686 Arithmetic Functions
1687 For all of these functions, 0 is returned if there is an error and 1 is
1688 returned for success. The return value should always be checked. eg.
1689 if (!BN_add(r,a,b)) goto err;
1690 Unless explicitly mentioned, the 'return' value can be one of the
1691 'parameters' to the function.
1693 int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b);
1694 Add 'a' and 'b' and return the result in 'r'. This is r=a+b.
1696 int BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b);
1697 Subtract 'a' from 'b' and put the result in 'r'. This is r=a-b.
1699 int BN_lshift(BIGNUM *r, BIGNUM *a, int n);
1700 Shift 'a' left by 'n' bits. This is r=a*(2^n).
1702 int BN_lshift1(BIGNUM *r, BIGNUM *a);
1703 Shift 'a' left by 1 bit. This form is more efficient than
1704 BN_lshift(r,a,1). This is r=a*2.
1706 int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
1707 Shift 'a' right by 'n' bits. This is r=int(a/(2^n)).
1709 int BN_rshift1(BIGNUM *r, BIGNUM *a);
1710 Shift 'a' right by 1 bit. This form is more efficient than
1711 BN_rshift(r,a,1). This is r=int(a/2).
1713 int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b);
1714 Multiply a by b and return the result in 'r'. 'r' must not be
1715 either 'a' or 'b'. It has to be a different BIGNUM.
1718 int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
1719 Multiply a by a and return the result in 'r'. 'r' must not be
1720 'a'. This function is alot faster than BN_mul(r,a,a). This is r=a*a.
1722 int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
1723 Divide 'm' by 'd' and return the result in 'dv' and the remainder
1724 in 'rem'. Either of 'dv' or 'rem' can be NULL in which case that
1725 value is not returned. 'ctx' needs to be passed as a source of
1726 temporary BIGNUM variables.
1727 This is dv=int(m/d), rem=m%d.
1729 int BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
1730 Find the remainder of 'm' divided by 'd' and return it in 'rem'.
1731 'ctx' holds the temporary BIGNUMs required by this function.
1732 This function is more efficient than BN_div(NULL,rem,m,d,ctx);
1735 int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BIGNUM *m,BN_CTX *ctx);
1736 Multiply 'a' by 'b' and return the remainder when divided by 'm'.
1737 'ctx' holds the temporary BIGNUMs required by this function.
1740 int BN_mod_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx);
1741 Raise 'a' to the 'p' power and return the remainder when divided by
1742 'm'. 'ctx' holds the temporary BIGNUMs required by this function.
1745 int BN_reciprocal(BIGNUM *r, BIGNUM *m, BN_CTX *ctx);
1746 Return the reciprocal of 'm'. 'ctx' holds the temporary variables
1747 required. This function returns -1 on error, otherwise it returns
1748 the number of bits 'r' is shifted left to make 'r' into an integer.
1749 This number of bits shifted is required in BN_mod_mul_reciprocal().
1750 This is r=(1/m)<<(BN_num_bits(m)+1).
1752 int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y, BIGNUM *m,
1753 BIGNUM *i, int nb, BN_CTX *ctx);
1754 This function is used to perform an efficient BN_mod_mul()
1755 operation. If one is going to repeatedly perform BN_mod_mul() with
1756 the same modulus is worth calculating the reciprocal of the modulus
1757 and then using this function. This operation uses the fact that
1758 a/b == a*r where r is the reciprocal of b. On modern computers
1759 multiplication is very fast and big number division is very slow.
1760 'x' is multiplied by 'y' and then divided by 'm' and the remainder
1761 is returned. 'i' is the reciprocal of 'm' and 'nb' is the number
1762 of bits as returned from BN_reciprocal(). Normal usage is as follows.
1763 bn=BN_reciprocal(i,m);
1765 { BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); }
1766 This is r=(x*y)%m. Internally it is approximately
1767 r=(x*y)-m*(x*y/m) or r=(x*y)-m*((x*y*i) >> bn)
1768 This function is used in BN_mod_exp() and BN_is_prime().
1770 Assignment Operations
1772 int BN_one(BIGNUM *a)
1773 Set 'a' to hold the value one.
1776 int BN_zero(BIGNUM *a)
1777 Set 'a' to hold the value zero.
1780 int BN_set_word(BIGNUM *a, unsigned long w);
1781 Set 'a' to hold the value of 'w'. 'w' is an unsigned long.
1784 unsigned long BN_get_word(BIGNUM *a);
1785 Returns 'a' in an unsigned long. Not remarkably, often 'a' will
1786 be biger than a word, in which case 0xffffffffL is returned.
1789 These functions are much more efficient that the normal bignum arithmetic
1792 BN_ULONG BN_mod_word(BIGNUM *a, unsigned long w);
1793 Return the remainder of 'a' divided by 'w'.
1794 This is return(a%w).
1796 int BN_add_word(BIGNUM *a, unsigned long w);
1797 Add 'w' to 'a'. This function does not take the sign of 'a' into
1798 account. This is a+=w;
1802 int BN_is_bit_set(BIGNUM *a, int n);
1803 This function return 1 if bit 'n' is set in 'a' else 0.
1805 int BN_set_bit(BIGNUM *a, int n);
1806 This function sets bit 'n' to 1 in 'a'.
1807 This is a&= ~(1<<n);
1809 int BN_clear_bit(BIGNUM *a, int n);
1810 This function sets bit 'n' to zero in 'a'. Return 0 if less
1811 than 'n' bits in 'a' else 1. This is a&= ~(1<<n);
1813 int BN_mask_bits(BIGNUM *a, int n);
1814 Truncate 'a' to n bits long. This is a&= ~((~0)<<n)
1816 Format conversion routines.
1818 BIGNUM *BN_bin2bn(unsigned char *s, int len,BIGNUM *ret);
1819 This function converts 'len' bytes in 's' into a BIGNUM which
1820 is put in 'ret'. If ret is NULL, a new BIGNUM is created.
1821 Either this new BIGNUM or ret is returned. The number is
1822 assumed to be in bigendian form in 's'. By this I mean that
1823 to 'ret' is created as follows for 'len' == 5.
1824 ret = s[0]*2^32 + s[1]*2^24 + s[2]*2^16 + s[3]*2^8 + s[4];
1825 This function cannot be used to convert negative numbers. It
1826 is always assumed the number is positive. The application
1827 needs to diddle the 'neg' field of th BIGNUM its self.
1828 The better solution would be to save the numbers in ASN.1 format
1829 since this is a defined standard for storing big numbers.
1830 Look at the functions
1832 ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai);
1833 BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn);
1834 int i2d_ASN1_INTEGER(ASN1_INTEGER *a,unsigned char **pp);
1835 ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **a,unsigned char **pp,
1838 int BN_bn2bin(BIGNUM *a, unsigned char *to);
1839 This function converts 'a' to a byte string which is put into
1840 'to'. The representation is big-endian in that the most
1841 significant byte of 'a' is put into to[0]. This function
1842 returns the number of bytes used to hold 'a'. BN_num_bytes(a)
1843 would return the same value and can be used to determine how
1844 large 'to' needs to be. If the number is negative, this
1845 information is lost. Since this library was written to
1846 manipulate large positive integers, the inability to save and
1847 restore them is not considered to be a problem by me :-).
1848 As for BN_bin2bn(), look at the ASN.1 integer encoding funtions
1849 for SSLeay. They use BN_bin2bn() and BN_bn2bin() internally.
1851 char *BN_bn2ascii(BIGNUM *a);
1852 This function returns a malloc()ed string that contains the
1853 ascii hexadecimal encoding of 'a'. The number is in bigendian
1854 format with a '-' in front if the number is negative.
1856 int BN_ascii2bn(BIGNUM **bn, char *a);
1857 The inverse of BN_bn2ascii. The function returns the number of
1858 characters from 'a' were processed in generating a the bignum.
1859 error is inticated by 0 being returned. The number is a
1860 hex digit string, optionally with a leading '-'. If *bn
1861 is null, a BIGNUM is created and returned via that variable.
1863 int BN_print_fp(FILE *fp, BIGNUM *a);
1864 'a' is printed to file pointer 'fp'. It is in the same format
1865 that is output from BN_bn2ascii(). 0 is returned on error,
1868 int BN_print(BIO *bp, BIGNUM *a);
1869 Same as BN_print except that the output is done to the SSLeay libraries
1870 BIO routines. BN_print_fp() actually calls this function.
1872 Miscellaneous Routines.
1874 int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
1875 This function returns in 'rnd' a random BIGNUM that is bits
1876 long. If bottom is 1, the number returned is odd. If top is set,
1877 the top 2 bits of the number are set. This is useful because if
1878 this is set, 2 'n; bit numbers multiplied together will return a 2n
1879 bit number. If top was not set, they could produce a 2n-1 bit
1882 BIGNUM *BN_mod_inverse(BIGNUM *a, BIGNUM *n,BN_CTX *ctx);
1883 This function create a new BIGNUM and returns it. This number
1884 is the inverse mod 'n' of 'a'. By this it is meant that the
1885 returned value 'r' satisfies (a*r)%n == 1. This function is
1886 used in the generation of RSA keys. 'ctx', as per usual,
1887 is used to hold temporary variables that are required by the
1888 function. NULL is returned on error.
1890 int BN_gcd(BIGNUM *r,BIGNUM *a,BIGNUM *b,BN_CTX *ctx);
1891 'r' has the greatest common divisor of 'a' and 'b'. 'ctx' is
1892 used for temporary variables and 0 is returned on error.
1894 int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(),BN_CTX *ctx,
1896 This function is used to check if a BIGNUM ('p') is prime.
1897 It performs this test by using the Miller-Rabin randomised
1898 primality test. This is a probalistic test that requires a
1899 number of rounds to ensure the number is prime to a high
1900 degree of probability. Since this can take quite some time, a
1901 callback function can be passed and it will be called each
1902 time 'p' passes a round of the prime testing. 'callback' will
1903 be called as follows, callback(1,n,cb_arg) where n is the number of
1904 the round, just passed. As per usual 'ctx' contains temporary
1905 variables used. If ctx is NULL, it does not matter, a local version
1906 will be malloced. This parameter is present to save some mallocing
1907 inside the function but probably could be removed.
1908 0 is returned on error.
1909 'ncheck' is the number of Miller-Rabin tests to run. It is
1910 suggested to use the value 'BN_prime_checks' by default.
1912 BIGNUM *BN_generate_prime(
1917 void (*callback)());
1919 This function is used to generate prime numbers. It returns a
1920 new BIGNUM that has a high probability of being a prime.
1921 'bits' is the number of bits that
1922 are to be in the prime. If 'strong' is true, the returned prime
1923 will also be a strong prime ((p-1)/2 is also prime).
1924 While searching for the prime ('p'), we
1925 can add the requirement that the prime fill the following
1926 condition p%a == rem. This can be used to help search for
1927 primes with specific features, which is required when looking
1928 for primes suitable for use with certain 'g' values in the
1929 Diffie-Hellman key exchange algorithm. If 'a' is NULL,
1930 this condition is not checked. If rem is NULL, rem is assumed
1931 to be 1. Since this search for a prime
1932 can take quite some time, if callback is not NULL, it is called
1933 in the following situations.
1934 We have a suspected prime (from a quick sieve),
1935 callback(0,sus_prime++,cb_arg). Each item to be passed to BN_is_prime().
1936 callback(1,round++,cb_arg). Each successful 'round' in BN_is_prime().
1937 callback(2,round,cb_arg). For each successful BN_is_prime() test.
1942 DSA wants 64*32 to use word mont mul, but RSA wants to use full.
1944 ==== callback.doc ========================================================
1946 Callback functions used in SSLeay.
1948 --------------------------
1951 Each BIO structure can have a callback defined against it. This callback is
1952 called 2 times for each BIO 'function'. It is passed 6 parameters.
1953 BIO_debug_callback() is an example callback which is defined in
1954 crypto/buffer/bio_cb.c and is used in apps/dgst.c This is intended mostly
1955 for debuging or to notify the application of IO.
1957 long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl,
1959 bio is the BIO being called, cmd is the type of BIO function being called.
1960 Look at the BIO_CB_* defines in buffer.h. Argp and argi are the arguments
1961 passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts(). In the case of
1962 BIO_ctrl(), argl is also defined. The first time the callback is called,
1963 before the underlying function has been executed, 0 is passed as 'ret', and
1964 if the return code from the callback is not > 0, the call is aborted
1965 and the returned <= 0 value is returned.
1966 The second time the callback is called, the 'cmd' value also has
1967 BIO_CB_RETURN logically 'or'ed with it. The 'ret' value is the value returned
1968 from the actuall function call and whatever the callback returns is returned
1969 from the BIO function.
1971 BIO_set_callback(b,cb) can be used to set the callback function
1972 (b is a BIO), and BIO_set_callback_arg(b,arg) can be used to
1973 set the cb_arg argument in the BIO strucutre. This field is only intended
1974 to be used by application, primarily in the callback function since it is
1975 accessable since the BIO is passed.
1977 --------------------------
1980 The pem library only really uses one type of callback,
1981 static int def_callback(char *buf, int num, int verify);
1982 which is used to return a password string if required.
1983 'buf' is the buffer to put the string in. 'num' is the size of 'buf'
1984 and 'verify' is used to indicate that the password should be checked.
1985 This last flag is mostly used when reading a password for encryption.
1987 For all of these functions, a NULL callback will call the above mentioned
1988 default callback. This default function does not work under Windows 3.1.
1989 For other machines, it will use an application defined prompt string
1990 (EVP_set_pw_prompt(), which defines a library wide prompt string)
1991 if defined, otherwise it will use it's own PEM password prompt.
1992 It will then call EVP_read_pw_string() to get a password from the console.
1993 If your application wishes to use nice fancy windows to retrieve passwords,
1994 replace this function. The callback should return the number of bytes read
1995 into 'buf'. If the number of bytes <= 0, it is considered an error.
1997 Functions that take this callback are listed below. For the 'read' type
1998 functions, the callback will only be required if the PEM data is encrypted.
2000 For the Write functions, normally a password can be passed in 'kstr', of
2001 'klen' bytes which will be used if the 'enc' cipher is not NULL. If
2002 'kstr' is NULL, the callback will be used to retrieve a password.
2004 int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len,
2006 char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)());
2007 char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
2008 int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x,
2009 EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
2010 int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,
2011 EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
2012 STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)());
2013 STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)());
2015 #define PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb)
2016 #define PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb)
2017 #define PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb)
2018 #define PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb)
2019 #define PEM_read_SSL_SESSION(fp,x,cb)
2020 #define PEM_read_X509(fp,x,cb)
2021 #define PEM_read_X509_REQ(fp,x,cb)
2022 #define PEM_read_X509_CRL(fp,x,cb)
2023 #define PEM_read_RSAPrivateKey(fp,x,cb)
2024 #define PEM_read_DSAPrivateKey(fp,x,cb)
2025 #define PEM_read_PrivateKey(fp,x,cb)
2026 #define PEM_read_PKCS7(fp,x,cb)
2027 #define PEM_read_DHparams(fp,x,cb)
2028 #define PEM_read_bio_SSL_SESSION(bp,x,cb)
2029 #define PEM_read_bio_X509(bp,x,cb)
2030 #define PEM_read_bio_X509_REQ(bp,x,cb)
2031 #define PEM_read_bio_X509_CRL(bp,x,cb)
2032 #define PEM_read_bio_RSAPrivateKey(bp,x,cb)
2033 #define PEM_read_bio_DSAPrivateKey(bp,x,cb)
2034 #define PEM_read_bio_PrivateKey(bp,x,cb)
2035 #define PEM_read_bio_PKCS7(bp,x,cb)
2036 #define PEM_read_bio_DHparams(bp,x,cb)
2037 int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
2038 RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)());
2040 Now you will notice that macros like
2041 #define PEM_write_X509(fp,x) \
2042 PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \
2043 (char *)x, NULL,NULL,0,NULL)
2044 Don't do encryption normally. If you want to PEM encrypt your X509 structure,
2045 either just call PEM_ASN1_write directly or just define you own
2046 macro variant. As you can see, this macro just sets all encryption related
2050 --------------------------
2053 #define SSL_set_info_callback(ssl,cb)
2054 #define SSL_CTX_set_info_callback(ctx,cb)
2055 void callback(SSL *ssl,int location,int ret)
2056 This callback is called each time around the SSL_connect()/SSL_accept()
2057 state machine. So it will be called each time the SSL protocol progresses.
2058 It is mostly present for use when debugging. When SSL_connect() or
2059 SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or
2060 SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned.
2061 Have a look at the SSL_CB_* defines in ssl.h. If an info callback is defined
2062 against the SSL_CTX, it is called unless there is one set against the SSL.
2064 void client_info_callback() in apps/s_client() for an example.
2066 Certificate verification.
2067 void SSL_set_verify(SSL *s, int mode, int (*callback) ());
2068 void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)());
2069 This callback is used to help verify client and server X509 certificates.
2070 It is actually passed to X509_cert_verify(), along with the SSL structure
2071 so you have to read about X509_cert_verify() :-). The SSL_CTX version is used
2072 if the SSL version is not defined. X509_cert_verify() is the function used
2073 by the SSL part of the library to verify certificates. This function is
2074 nearly always defined by the application.
2076 void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg);
2077 int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain);
2078 This call is used to replace the SSLeay certificate verification code.
2079 The 'arg' is kept in the SSL_CTX and is passed to the callback.
2080 If the callback returns 0, the certificate is rejected, otherwise it
2081 is accepted. The callback is replacing the X509_cert_verify() call.
2082 This feature is not often used, but if you wished to implement
2083 some totally different certificate authentication system, this 'hook' is
2086 SSLeay keeps a cache of session-ids against each SSL_CTX. These callbacks can
2087 be used to notify the application when a SSL_SESSION is added to the cache
2088 or to retrieve a SSL_SESSION that is not in the cache from the application.
2089 #define SSL_CTX_sess_set_get_cb(ctx,cb)
2090 SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy);
2091 If defined, this callback is called to return the SESSION_ID for the
2092 session-id in 'session_id', of 'session_id_len' bytes. 'copy' is set to 1
2093 if the server is to 'take a copy' of the SSL_SESSION structure. It is 0
2094 if the SSL_SESSION is being 'passed in' so the SSLeay library is now
2095 responsible for 'free()ing' the structure. Basically it is used to indicate
2096 if the reference count on the SSL_SESSION structure needs to be incremented.
2098 #define SSL_CTX_sess_set_new_cb(ctx,cb)
2099 int callback(SSL *s, SSL_SESSION *sess);
2100 When a new connection is established, if the SSL_SESSION is going to be added
2101 to the cache, this callback is called. Return 1 if a 'copy' is required,
2102 otherwise, return 0. This return value just causes the reference count
2103 to be incremented (on return of a 1), this means the application does
2104 not need to worry about incrementing the refernece count (and the
2105 locking that implies in a multi-threaded application).
2107 void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)());
2108 This sets the SSL password reading function.
2109 It is mostly used for windowing applications
2110 and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey()
2111 calls inside the SSL library. The only reason this is present is because the
2112 calls to PEM_* functions is hidden in the SSLeay library so you have to
2113 pass in the callback some how.
2115 #define SSL_CTX_set_client_cert_cb(ctx,cb)
2116 int callback(SSL *s,X509 **x509, EVP_PKEY **pkey);
2117 Called when a client certificate is requested but there is not one set
2118 against the SSL_CTX or the SSL. If the callback returns 1, x509 and
2119 pkey need to point to valid data. The library will free these when
2120 required so if the application wants to keep these around, increment
2121 their reference counts. If 0 is returned, no client cert is
2122 available. If -1 is returned, it is assumed that the callback needs
2123 to be called again at a later point in time. SSL_connect will return
2124 -1 and SSL_want_x509_lookup(ssl) returns true. Remember that
2125 application data can be attached to an SSL structure via the
2126 SSL_set_app_data(SSL *ssl,char *data) call.
2128 --------------------------
2131 int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(),
2132 int *error,char *arg,STACK *cert_chain);
2133 int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg,
2136 X509_cert_verify() is used to authenticate X509 certificates. The 'ctx' holds
2137 the details of the various caches and files used to locate certificates.
2138 'xs' is the certificate to verify and 'cb' is the application callback (more
2139 detail later). 'error' will be set to the error code and 'arg' is passed
2140 to the 'cb' callback. Look at the VERIFY_* defines in crypto/x509/x509.h
2142 When ever X509_cert_verify() makes a 'negative' decision about a
2143 certitificate, the callback is called. If everything checks out, the
2144 callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self
2145 signed cert that is not the passed certificate).
2147 The callback is passed the X509_cert_verify opinion of the certificate
2148 in 'ok', the certificate in 'xs', the issuer certificate in 'xi',
2149 the 'depth' of the certificate in the verification 'chain', the
2150 VERIFY_* code in 'error' and the argument passed to X509_cert_verify()
2151 in 'arg'. cert_chain is a list of extra certs to use if they are not
2154 The callback can be used to look at the error reason, and then return 0
2155 for an 'error' or '1' for ok. This will override the X509_cert_verify()
2156 opinion of the certificates validity. Processing will continue depending on
2157 the return value. If one just wishes to use the callback for informational
2158 reason, just return the 'ok' parameter.
2160 --------------------------
2161 The BN and DH library.
2163 BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add,
2164 BIGNUM *rem,void (*callback)(int,int));
2165 int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int),
2167 Read doc/bn.doc for the description of these 2.
2169 DH *DH_generate_parameters(int prime_len,int generator,
2170 void (*callback)(int,int));
2171 Read doc/bn.doc for the description of the callback, since it is just passed
2172 to BN_generate_prime(), except that it is also called as
2173 callback(3,0) by this function.
2175 --------------------------
2178 void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file,
2180 void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount,
2181 int type,char *file, int line));
2182 void CRYPTO_set_id_callback(unsigned long (*func)(void));
2184 Read threads.doc for info on these ones.
2187 ==== cipher.doc ========================================================
2189 The Cipher subroutines.
2191 These routines require "evp.h" to be included.
2193 These functions are a higher level interface to the various cipher
2194 routines found in this library. As such, they allow the same code to be
2195 used to encrypt and decrypt via different ciphers with only a change
2196 in an initial parameter. These routines also provide buffering for block
2199 These routines all take a pointer to the following structure to specify
2200 which cipher to use. If you wish to use a new cipher with these routines,
2201 you would probably be best off looking an how an existing cipher is
2202 implemented and copying it. At this point in time, I'm not going to go
2203 into many details. This structure should be considered opaque
2205 typedef struct pem_cipher_st
2211 void (*enc_init)(); /* init for encryption */
2212 void (*dec_init)(); /* init for decryption */
2213 void (*do_cipher)(); /* encrypt data */
2216 The type field is the object NID of the cipher type
2217 (read the section on Objects for an explanation of what a NID is).
2218 The cipher block_size is how many bytes need to be passed
2219 to the cipher at a time. Key_len is the
2220 length of the key the cipher requires and iv_len is the length of the
2221 initialisation vector required. enc_init is the function
2222 called to initialise the ciphers context for encryption and dec_init is the
2223 function to initialise for decryption (they need to be different, especially
2224 for the IDEA cipher).
2226 One reason for specifying the Cipher via a pointer to a structure
2227 is that if you only use des-cbc, only the des-cbc routines will
2228 be included when you link the program. If you passed an integer
2229 that specified which cipher to use, the routine that mapped that
2230 integer to a set of cipher functions would cause all the ciphers
2231 to be link into the code. This setup also allows new ciphers
2232 to be added by the application (with some restrictions).
2234 The thirteen ciphers currently defined in this library are
2236 EVP_CIPHER *EVP_des_ecb(); /* DES in ecb mode, iv=0, block=8, key= 8 */
2237 EVP_CIPHER *EVP_des_ede(); /* DES in ecb ede mode, iv=0, block=8, key=16 */
2238 EVP_CIPHER *EVP_des_ede3(); /* DES in ecb ede mode, iv=0, block=8, key=24 */
2239 EVP_CIPHER *EVP_des_cfb(); /* DES in cfb mode, iv=8, block=1, key= 8 */
2240 EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */
2241 EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */
2242 EVP_CIPHER *EVP_des_ofb(); /* DES in ofb mode, iv=8, block=1, key= 8 */
2243 EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */
2244 EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */
2245 EVP_CIPHER *EVP_des_cbc(); /* DES in cbc mode, iv=8, block=8, key= 8 */
2246 EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */
2247 EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */
2248 EVP_CIPHER *EVP_desx_cbc(); /* DES in desx cbc mode,iv=8, block=8, key=24 */
2249 EVP_CIPHER *EVP_rc4(); /* RC4, iv=0, block=1, key=16 */
2250 EVP_CIPHER *EVP_idea_ecb(); /* IDEA in ecb mode, iv=0, block=8, key=16 */
2251 EVP_CIPHER *EVP_idea_cfb(); /* IDEA in cfb mode, iv=8, block=1, key=16 */
2252 EVP_CIPHER *EVP_idea_ofb(); /* IDEA in ofb mode, iv=8, block=1, key=16 */
2253 EVP_CIPHER *EVP_idea_cbc(); /* IDEA in cbc mode, iv=8, block=8, key=16 */
2254 EVP_CIPHER *EVP_rc2_ecb(); /* RC2 in ecb mode, iv=0, block=8, key=16 */
2255 EVP_CIPHER *EVP_rc2_cfb(); /* RC2 in cfb mode, iv=8, block=1, key=16 */
2256 EVP_CIPHER *EVP_rc2_ofb(); /* RC2 in ofb mode, iv=8, block=1, key=16 */
2257 EVP_CIPHER *EVP_rc2_cbc(); /* RC2 in cbc mode, iv=8, block=8, key=16 */
2258 EVP_CIPHER *EVP_bf_ecb(); /* Blowfish in ecb mode,iv=0, block=8, key=16 */
2259 EVP_CIPHER *EVP_bf_cfb(); /* Blowfish in cfb mode,iv=8, block=1, key=16 */
2260 EVP_CIPHER *EVP_bf_ofb(); /* Blowfish in ofb mode,iv=8, block=1, key=16 */
2261 EVP_CIPHER *EVP_bf_cbc(); /* Blowfish in cbc mode,iv=8, block=8, key=16 */
2263 The meaning of the compound names is as follows.
2264 des The base cipher is DES.
2265 idea The base cipher is IDEA
2266 rc4 The base cipher is RC4-128
2267 rc2 The base cipher is RC2-128
2268 ecb Electronic Code Book form of the cipher.
2269 cbc Cipher Block Chaining form of the cipher.
2270 cfb 64 bit Cipher Feedback form of the cipher.
2271 ofb 64 bit Output Feedback form of the cipher.
2272 ede The cipher is used in Encrypt, Decrypt, Encrypt mode. The first
2273 and last keys are the same.
2274 ede3 The cipher is used in Encrypt, Decrypt, Encrypt mode.
2276 All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument.
2277 The state of the cipher is kept in this structure.
2279 typedef struct EVP_CIPHER_Ctx_st
2282 int encrypt; /* encrypt or decrypt */
2283 int buf_len; /* number we have left */
2284 unsigned char buf[8];
2286 .... /* cipher specific stuff */
2290 Cipher is a pointer the the EVP_CIPHER for the current context. The encrypt
2291 flag indicates encryption or decryption. buf_len is the number of bytes
2292 currently being held in buf.
2293 The 'c' union holds the cipher specify context.
2295 The following functions are to be used.
2297 int EVP_read_pw_string(
2302 This function is the same as des_read_pw_string() (des.doc).
2304 void EVP_set_pw_prompt(char *prompt);
2305 This function sets the 'default' prompt to use to use in
2306 EVP_read_pw_string when the prompt parameter is NULL. If the
2307 prompt parameter is NULL, this 'default prompt' feature is turned
2308 off. Be warned, this is a global variable so weird things
2309 will happen if it is used under Win16 and care must be taken
2310 with a multi-threaded version of the library.
2312 char *EVP_get_pw_prompt();
2313 This returns a pointer to the default prompt string. NULL
2319 unsigned char *salt,
2320 unsigned char *data,
2325 This function is used to generate a key and an initialisation vector
2326 for a specified cipher from a key string and a salt. Type
2327 specifies the cipher the 'key' is being generated for. Md is the
2328 message digest algorithm to use to generate the key and iv. The salt
2329 is an optional 8 byte object that is used to help seed the key
2331 If the salt value is NULL, it is just not used. Datal is the
2332 number of bytes to use from 'data' in the key generation.
2333 This function returns the key size for the specified cipher, if
2334 data is NULL, this value is returns and no other
2335 computation is performed. Count is
2336 the number of times to loop around the key generator. I would
2337 suggest leaving it's value as 1. Key and iv are the structures to
2338 place the returning iv and key in. If they are NULL, no value is
2339 generated for that particular value.
2340 The algorithm used is as follows
2342 /* M[] is an array of message digests
2343 * MD() is the message digest function */
2344 M[0]=MD(data . salt);
2345 for (i=1; i<count; i++) M[0]=MD(M[0]);
2348 while (data still needed for key and iv)
2350 M[i]=MD(M[i-1] . data . salt);
2351 for (i=1; i<count; i++) M[i]=MD(M[i]);
2355 If the salt is NULL, it is not used.
2356 The digests are concatenated together.
2357 M = M[0] . M[1] . M[2] .......
2359 For key= 8, iv=8 => key=M[0.. 8], iv=M[ 9 .. 16].
2360 For key=16, iv=0 => key=M[0..16].
2361 For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24].
2362 For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32].
2364 This routine will produce DES-CBC keys and iv that are compatible
2365 with the PKCS-5 standard when md2 or md5 are used. If md5 is
2366 used, the salt is NULL and count is 1, this routine will produce
2367 the password to key mapping normally used with RC4.
2368 I have attempted to logically extend the PKCS-5 standard to
2369 generate keys and iv for ciphers that require more than 16 bytes,
2370 if anyone knows what the correct standard is, please inform me.
2371 When using sha or sha1, things are a bit different under this scheme,
2372 since sha produces a 20 byte digest. So for ciphers requiring
2373 24 bits of data, 20 will come from the first MD and 4 will
2374 come from the second.
2376 I have considered having a separate function so this 'routine'
2377 can be used without the requirement of passing a EVP_CIPHER *,
2378 but I have decided to not bother. If you wish to use the
2379 function without official EVP_CIPHER structures, just declare
2380 a local one and set the key_len and iv_len fields to the
2383 The following routines perform encryption and decryption 'by parts'. By
2384 this I mean that there are groups of 3 routines. An Init function that is
2385 used to specify a cipher and initialise data structures. An Update routine
2386 that does encryption/decryption, one 'chunk' at a time. And finally a
2387 'Final' function that finishes the encryption/decryption process.
2388 All these functions take a EVP_CIPHER pointer to specify which cipher to
2389 encrypt/decrypt with. They also take a EVP_CIPHER_CTX object as an
2390 argument. This structure is used to hold the state information associated
2391 with the operation in progress.
2393 void EVP_EncryptInit(
2394 EVP_CIPHER_CTX *ctx,
2398 This function initialise a EVP_CIPHER_CTX for encryption using the
2399 cipher passed in the 'type' field. The cipher is initialised to use
2400 'key' as the key and 'iv' for the initialisation vector (if one is
2401 required). If the type, key or iv is NULL, the value currently in the
2402 EVP_CIPHER_CTX is reused. So to perform several decrypt
2403 using the same cipher, key and iv, initialise with the cipher,
2404 key and iv the first time and then for subsequent calls,
2405 reuse 'ctx' but pass NULL for type, key and iv. You must make sure
2406 to pass a key that is large enough for a particular cipher. I
2407 would suggest using the EVP_BytesToKey() function.
2409 void EVP_EncryptUpdate(
2410 EVP_CIPHER_CTX *ctx,
2415 This function takes 'inl' bytes from 'in' and outputs bytes
2416 encrypted by the cipher 'ctx' was initialised with into 'out'. The
2417 number of bytes written to 'out' is put into outl. If a particular
2418 cipher encrypts in blocks, less or more bytes than input may be
2419 output. Currently the largest block size used by supported ciphers
2420 is 8 bytes, so 'out' should have room for 'inl+7' bytes. Normally
2421 EVP_EncryptInit() is called once, followed by lots and lots of
2422 calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal
2425 void EVP_EncryptFinal(
2426 EVP_CIPHER_CTX *ctx,
2429 Because quite a large number of ciphers are block ciphers, there is
2430 often an incomplete block to write out at the end of the
2431 encryption. EVP_EncryptFinal() performs processing on this last
2432 block. The last block in encoded in such a way that it is possible
2433 to determine how many bytes in the last block are valid. For 8 byte
2434 block size ciphers, if only 5 bytes in the last block are valid, the
2435 last three bytes will be filled with the value 3. If only 2 were
2436 valid, the other 6 would be filled with sixes. If all 8 bytes are
2437 valid, a extra 8 bytes are appended to the cipher stream containing
2438 nothing but 8 eights. These last bytes are output into 'out' and
2439 the number of bytes written is put into 'outl' These last bytes
2440 are output into 'out' and the number of bytes written is put into
2441 'outl'. This form of block cipher finalisation is compatible with
2442 PKCS-5. Please remember that even if you are using ciphers like
2443 RC4 that has no blocking and so the function will not write
2444 anything into 'out', it would still be a good idea to pass a
2445 variable for 'out' that can hold 8 bytes just in case the cipher is
2446 changed some time in the future. It should also be remembered
2447 that the EVP_CIPHER_CTX contains the password and so when one has
2448 finished encryption with a particular EVP_CIPHER_CTX, it is good
2449 practice to zero the structure
2450 (ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)).
2452 void EVP_DecryptInit(
2453 EVP_CIPHER_CTX *ctx,
2457 This function is basically the same as EVP_EncryptInit() accept that
2458 is prepares the EVP_CIPHER_CTX for decryption.
2460 void EVP_DecryptUpdate(
2461 EVP_CIPHER_CTX *ctx,
2466 This function is basically the same as EVP_EncryptUpdate()
2467 except that it performs decryption. There is one
2468 fundamental difference though. 'out' can not be the same as
2469 'in' for any ciphers with a block size greater than 1 if more
2470 than one call to EVP_DecryptUpdate() will be made. This
2471 is because this routine can hold a 'partial' block between
2472 calls. When a partial block is decrypted (due to more bytes
2473 being passed via this function, they will be written to 'out'
2474 overwriting the input bytes in 'in' that have not been read
2475 yet. From this it should also be noted that 'out' should
2476 be at least one 'block size' larger than 'inl'. This problem
2477 only occurs on the second and subsequent call to
2478 EVP_DecryptUpdate() when using a block cipher.
2480 int EVP_DecryptFinal(
2481 EVP_CIPHER_CTX *ctx,
2484 This function is different to EVP_EncryptFinal in that it 'removes'
2485 any padding bytes appended when the data was encrypted. Due to the
2486 way in which 1 to 8 bytes may have been appended when encryption
2487 using a block cipher, 'out' can end up with 0 to 7 bytes being put
2488 into it. When decoding the padding bytes, it is possible to detect
2489 an incorrect decryption. If the decryption appears to be wrong, 0
2490 is returned. If everything seems ok, 1 is returned. For ciphers
2491 with a block size of 1 (RC4), this function would normally not
2492 return any bytes and would always return 1. Just because this
2493 function returns 1 does not mean the decryption was correct. It
2494 would normally be wrong due to either the wrong key/iv or
2495 corruption of the cipher data fed to EVP_DecryptUpdate().
2496 As for EVP_EncryptFinal, it is a good idea to zero the
2497 EVP_CIPHER_CTX after use since the structure contains the key used
2498 to decrypt the data.
2500 The following Cipher routines are convenience routines that call either
2501 EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX
2502 was setup to encrypt or decrypt.
2504 void EVP_CipherInit(
2505 EVP_CIPHER_CTX *ctx,
2510 This function take arguments that are the same as EVP_EncryptInit()
2511 and EVP_DecryptInit() except for the extra 'enc' flag. If 1, the
2512 EVP_CIPHER_CTX is setup for encryption, if 0, decryption.
2514 void EVP_CipherUpdate(
2515 EVP_CIPHER_CTX *ctx,
2520 Again this function calls either EVP_EncryptUpdate() or
2521 EVP_DecryptUpdate() depending on state in the 'ctx' structure.
2522 As noted for EVP_DecryptUpdate(), when this routine is used
2523 for decryption with block ciphers, 'out' should not be the
2526 int EVP_CipherFinal(
2527 EVP_CIPHER_CTX *ctx,
2528 unsigned char *outm,
2530 This routine call EVP_EncryptFinal() or EVP_DecryptFinal()
2531 depending on the state information in 'ctx'. 1 is always returned
2532 if the mode is encryption, otherwise the return value is the return
2533 value of EVP_DecryptFinal().
2535 ==== cipher.m ========================================================
2537 Date: Tue, 15 Oct 1996 08:16:14 +1000 (EST)
2538 From: Eric Young <eay@mincom.com>
2540 To: Roland Haring <rharing@tandem.cl>
2541 Cc: ssl-users@mincom.com
2542 Subject: Re: Symmetric encryption with ssleay
2543 In-Reply-To: <m0vBpyq-00001aC@tandemnet.tandem.cl>
2544 Message-Id: <Pine.SOL.3.91.961015075623.11394A-100000@orb>
2546 Content-Type: TEXT/PLAIN; charset=US-ASCII
2547 Sender: ssl-lists-owner@mincom.com
2552 On Fri, 11 Oct 1996, Roland Haring wrote:
2554 > Would somebody be so kind to give me the minimum basic
2555 > calls I need to do to libcrypto.a to get some text encrypted
2556 > and decrypted again? ...hopefully with code included to do
2557 > base64 encryption and decryption ... e.g. that sign-it.c code
2558 > posted some while ago was a big help :-) (please, do not point
2559 > me to apps/enc.c where I suspect my Heissenbug to be hidden :-)
2561 Ok, the base64 encoding stuff in 'enc.c' does the wrong thing sometimes
2562 when the data is less than a line long (this is for decoding). I'll dig
2563 up the exact fix today and post it. I am taking longer on 0.6.5 than I
2564 intended so I'll just post this patch.
2566 The documentation to read is in
2568 doc/encode.doc (very sparse :-).
2572 The basic calls to encrypt with say triple DES are
2575 char key[EVP_MAX_KEY_LENGTH];
2576 char iv[EVP_MAX_IV_LENGTH];
2578 unsigned char out[512+8];
2581 /* optional generation of key/iv data from text password using md5
2582 * via an upward compatable verson of PKCS#5. */
2583 EVP_BytesToKey(EVP_des_ede3_cbc,EVP_md5,NULL,passwd,strlen(passwd),
2586 /* Initalise the EVP_CIPHER_CTX */
2587 EVP_EncryptInit(ctx,EVP_des_ede3_cbc,key,iv);
2591 /* This is processing 512 bytes at a time, the bytes are being
2592 * copied into 'out', outl bytes are output. 'out' should not be the
2593 * same as 'in' for reasons mentioned in the documentation. */
2594 EVP_EncryptUpdate(ctx,out,&outl,in,512);
2597 /* Output the last 'block'. If the cipher is a block cipher, the last
2598 * block is encoded in such a way so that a wrong decryption will normally be
2599 * detected - again, one of the PKCS standards. */
2601 EVP_EncryptFinal(ctx,out,&outl);
2603 To decrypt, use the EVP_DecryptXXXXX functions except that EVP_DecryptFinal()
2604 will return 0 if the decryption fails (only detectable on block ciphers).
2610 which does either encryption or decryption depending on an extra
2611 parameter to EVP_CipherInit().
2614 To do the base64 encoding,
2623 where the encoding is quite simple, but the decoding can be a bit more
2624 fun (due to dud input).
2626 EVP_DecodeUpdate() returns -1 for an error on an input line, 0 if the
2627 'last line' was just processed, and 1 if more lines should be submitted.
2629 EVP_DecodeFinal() returns -1 for an error or 1 if things are ok.
2632 EVP_DecodeInit(....)
2635 i=EVP_DecodeUpdate(....);
2636 if (i < 0) goto err;
2638 /* process the data */
2642 EVP_DecodeFinal(....);
2643 /* process the data */
2645 The problem in 'enc.c' is that I was stuff the processing up after the
2646 EVP_DecodeFinal(...) when the for(..) loop was not being run (one line of
2647 base64 data) and this was because 'enc.c' tries to scan over a file until
2648 it hits the first valid base64 encoded line.
2650 hope this helps a bit.
2653 Eric Young | BOOL is tri-state according to Bill Gates.
2654 AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage().
2656 ==== conf.doc ========================================================
2660 The CONF library is a simple set of routines that can be used to configure
2661 programs. It is a superset of the genenv() function with some extra
2664 The library consists of 5 functions.
2666 LHASH *CONF_load(LHASH *config,char *file);
2667 This function is called to load in a configuration file. Multiple
2668 configuration files can be loaded, with each subsequent 'load' overwriting
2669 any already defined 'variables'. If there is an error, NULL is returned.
2670 If config is NULL, a new LHASH structure is created and returned, otherwise
2671 the new data in the 'file' is loaded into the 'config' structure.
2673 void CONF_free(LHASH *config);
2674 This function free()s the data in config.
2676 char *CONF_get_string(LHASH *config,char *section,char *name);
2677 This function returns the string found in 'config' that corresponds to the
2678 'section' and 'name' specified. Classes and the naming system used will be
2679 discussed later in this document. If the variable is not defined, an NULL
2682 long CONF_get_long(LHASH *config,char *section, char *name);
2683 This function is the same as CONF_get_string() except that it converts the
2684 string to an long and returns it. If variable is not a number or the
2685 variable does not exist, 0 is returned. This is a little problematic but I
2686 don't know of a simple way around it.
2688 STACK *CONF_get_section(LHASH *config, char *section);
2689 This function returns a 'stack' of CONF_VALUE items that are all the
2690 items defined in a particular section. DO NOT free() any of the
2691 variable returned. They will disappear when CONF_free() is called.
2694 The configuration file is divided into 'sections'. Each section is started by
2695 a line of the form '[ section ]'. All subsequent variable definitions are
2696 of this section. A variable definition is a simple alpha-numeric name
2697 followed by an '=' and then the data. A section or variable name can be
2698 described by a regular expression of the following form '[A-Za-z0-9_]+'.
2699 The value of the variable is the text after the '=' until the end of the
2700 line, stripped of leading and trailing white space.
2701 At this point I should mention that a '#' is a comment character, \ is the
2702 escape character, and all three types of quote can be used to stop any
2703 special interpretation of the data.
2704 Now when the data is being loaded, variable expansion can occur. This is
2705 done by expanding any $NAME sequences into the value represented by the
2706 variable NAME. If the variable is not in the current section, the different
2707 section can be specified by using the $SECTION::NAME form. The ${NAME} form
2708 also works and is very useful for expanding variables inside strings.
2710 When a variable is looked up, there are 2 special section. 'default', which
2711 is the initial section, and 'ENV' which is the processes environment
2712 variables (accessed via getenv()). When a variable is looked up, it is
2713 first 'matched' with it's section (if one was specified), if this fails, the
2714 'default' section is matched.
2715 If the 'lhash' variable passed was NULL, the environment is searched.
2717 Now why do we bother with sections? So we can have multiple programs using
2718 the same configuration file, or multiple instances of the same program
2719 using different variables. It also provides a nice mechanism to override
2720 the processes environment variables (eg ENV::HOME=/tmp). If there is a
2721 program specific variable missing, we can have default values.
2722 Multiple configuration files can be loaded, with each new value clearing
2723 any predefined values. A system config file can provide 'default' values,
2724 and application/usr specific files can provide overriding values.
2728 # This is a simple example
2729 SSLEAY_HOME = /usr/local/ssl
2730 ENV::PATH = $SSLEAY_HOME/bin:$PATH # override my path
2733 cert_dir = $SSLEAY_HOME/certs # /usr/local/ssl/certs
2736 CIPHER = DES-EDE-MD5:RC4-MD5
2737 USER_CERT = $HOME/${USER}di'r 5' # /home/eay/eaydir 5
2738 USER_CERT = $HOME/\${USER}di\'r # /home/eay/${USER}di'r
2739 USER_CERT = "$HOME/${US"ER}di\'r # $HOME/${USER}di'r
2743 9ab # TEST=123456789ab
2744 TTT = 1234\n\n # TTT=1234<nl><nl>
2748 ==== des.doc ========================================================
2752 Please note that this library was originally written to operate with
2753 eBones, a version of Kerberos that had had encryption removed when it left
2754 the USA and then put back in. As such there are some routines that I will
2755 advise not using but they are still in the library for historical reasons.
2756 For all calls that have an 'input' and 'output' variables, they can be the
2759 This library requires the inclusion of 'des.h'.
2761 All of the encryption functions take what is called a des_key_schedule as an
2762 argument. A des_key_schedule is an expanded form of the des key.
2763 A des_key is 8 bytes of odd parity, the type used to hold the key is a
2764 des_cblock. A des_cblock is an array of 8 bytes, often in this library
2765 description I will refer to input bytes when the function specifies
2766 des_cblock's as input or output, this just means that the variable should
2767 be a multiple of 8 bytes.
2769 The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to
2770 specify decryption. The functions and global variable are as follows:
2773 DES keys are supposed to be odd parity. If this variable is set to
2774 a non-zero value, des_set_key() will check that the key has odd
2775 parity and is not one of the known weak DES keys. By default this
2776 variable is turned off;
2778 void des_set_odd_parity(
2780 This function takes a DES key (8 bytes) and sets the parity to odd.
2782 int des_is_weak_key(
2784 This function returns a non-zero value if the DES key passed is a
2785 weak, DES key. If it is a weak key, don't use it, try a different
2786 one. If you are using 'random' keys, the chances of hitting a weak
2787 key are 1/2^52 so it is probably not worth checking for them.
2791 des_key_schedule schedule);
2792 Des_set_key converts an 8 byte DES key into a des_key_schedule.
2793 A des_key_schedule is an expanded form of the key which is used to
2794 perform actual encryption. It can be regenerated from the DES key
2795 so it only needs to be kept when encryption or decryption is about
2796 to occur. Don't save or pass around des_key_schedule's since they
2797 are CPU architecture dependent, DES keys are not. If des_check_key
2798 is non zero, zero is returned if the key has the wrong parity or
2799 the key is a weak key, else 1 is returned.
2803 des_key_schedule schedule);
2804 An alternative name for des_set_key().
2806 int des_rw_mode; /* defaults to DES_PCBC_MODE */
2807 This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default).
2808 This specifies the function to use in the enc_read() and enc_write()
2812 unsigned long *data,
2813 des_key_schedule ks,
2815 This is the DES encryption function that gets called by just about
2816 every other DES routine in the library. You should not use this
2817 function except to implement 'modes' of DES. I say this because the
2818 functions that call this routine do the conversion from 'char *' to
2819 long, and this needs to be done to make sure 'non-aligned' memory
2820 access do not occur. The characters are loaded 'little endian',
2821 have a look at my source code for more details on how I use this
2823 Data is a pointer to 2 unsigned long's and ks is the
2824 des_key_schedule to use. enc, is non zero specifies encryption,
2828 unsigned long *data,
2829 des_key_schedule ks,
2831 This functions is the same as des_encrypt() except that the DES
2832 initial permutation (IP) and final permutation (FP) have been left
2833 out. As for des_encrypt(), you should not use this function.
2834 It is used by the routines in my library that implement triple DES.
2835 IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same
2836 as des_encrypt() des_encrypt() des_encrypt() except faster :-).
2838 void des_ecb_encrypt(
2841 des_key_schedule ks,
2843 This is the basic Electronic Code Book form of DES, the most basic
2844 form. Input is encrypted into output using the key represented by
2845 ks. If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise
2846 decryption occurs. Input is 8 bytes long and output is 8 bytes.
2847 (the des_cblock structure is 8 chars).
2849 void des_ecb3_encrypt(
2852 des_key_schedule ks1,
2853 des_key_schedule ks2,
2854 des_key_schedule ks3,
2856 This is the 3 key EDE mode of ECB DES. What this means is that
2857 the 8 bytes of input is encrypted with ks1, decrypted with ks2 and
2858 then encrypted again with ks3, before being put into output;
2859 C=E(ks3,D(ks2,E(ks1,M))). There is a macro, des_ecb2_encrypt()
2860 that only takes 2 des_key_schedules that implements,
2861 C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1.
2863 void des_cbc_encrypt(
2867 des_key_schedule ks,
2870 This routine implements DES in Cipher Block Chaining mode.
2871 Input, which should be a multiple of 8 bytes is encrypted
2872 (or decrypted) to output which will also be a multiple of 8 bytes.
2873 The number of bytes is in length (and from what I've said above,
2874 should be a multiple of 8). If length is not a multiple of 8, I'm
2875 not being held responsible :-). ivec is the initialisation vector.
2876 This function does not modify this variable. To correctly implement
2877 cbc mode, you need to do one of 2 things; copy the last 8 bytes of
2878 cipher text for use as the next ivec in your application,
2879 or use des_ncbc_encrypt().
2880 Only this routine has this problem with updating the ivec, all
2881 other routines that are implementing cbc mode update ivec.
2883 void des_ncbc_encrypt(
2887 des_key_schedule sk,
2890 For historical reasons, des_cbc_encrypt() did not update the
2891 ivec with the value requires so that subsequent calls to
2892 des_cbc_encrypt() would 'chain'. This was needed so that the same
2893 'length' values would not need to be used when decrypting.
2894 des_ncbc_encrypt() does the right thing. It is the same as
2895 des_cbc_encrypt accept that ivec is updates with the correct value
2896 to pass in subsequent calls to des_ncbc_encrypt(). I advise using
2897 des_ncbc_encrypt() instead of des_cbc_encrypt();
2899 void des_xcbc_encrypt(
2903 des_key_schedule sk,
2908 This is RSA's DESX mode of DES. It uses inw and outw to
2909 'whiten' the encryption. inw and outw are secret (unlike the iv)
2910 and are as such, part of the key. So the key is sort of 24 bytes.
2911 This is much better than cbc des.
2913 void des_3cbc_encrypt(
2917 des_key_schedule sk1,
2918 des_key_schedule sk2,
2922 This function is flawed, do not use it. I have left it in the
2923 library because it is used in my des(1) program and will function
2924 correctly when used by des(1). If I removed the function, people
2925 could end up unable to decrypt files.
2926 This routine implements outer triple cbc encryption using 2 ks and
2927 2 ivec's. Use des_ede2_cbc_encrypt() instead.
2929 void des_ede3_cbc_encrypt(
2933 des_key_schedule ks1,
2934 des_key_schedule ks2,
2935 des_key_schedule ks3,
2938 This function implements outer triple CBC DES encryption with 3
2939 keys. What this means is that each 'DES' operation
2940 inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))).
2941 Again, this is cbc mode so an ivec is requires.
2942 This mode is used by SSL.
2943 There is also a des_ede2_cbc_encrypt() that only uses 2
2944 des_key_schedule's, the first being reused for the final
2945 encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of triple DES
2946 is used by the RSAref library.
2948 void des_pcbc_encrypt(
2952 des_key_schedule ks,
2955 This is Propagating Cipher Block Chaining mode of DES. It is used
2956 by Kerberos v4. It's parameters are the same as des_ncbc_encrypt().
2958 void des_cfb_encrypt(
2963 des_key_schedule ks,
2966 Cipher Feedback Back mode of DES. This implementation 'feeds back'
2967 in numbit blocks. The input (and output) is in multiples of numbits
2968 bits. numbits should to be a multiple of 8 bits. Length is the
2969 number of bytes input. If numbits is not a multiple of 8 bits,
2970 the extra bits in the bytes will be considered padding. So if
2971 numbits is 12, for each 2 input bytes, the 4 high bits of the
2972 second byte will be ignored. So to encode 72 bits when using
2973 a numbits of 12 take 12 bytes. To encode 72 bits when using
2974 numbits of 9 will take 16 bytes. To encode 80 bits when using
2975 numbits of 16 will take 10 bytes. etc, etc. This padding will
2976 apply to both input and output.
2979 void des_cfb64_encrypt(
2983 des_key_schedule ks,
2987 This is one of the more useful functions in this DES library, it
2988 implements CFB mode of DES with 64bit feedback. Why is this
2989 useful you ask? Because this routine will allow you to encrypt an
2990 arbitrary number of bytes, no 8 byte padding. Each call to this
2991 routine will encrypt the input bytes to output and then update ivec
2992 and num. num contains 'how far' we are though ivec. If this does
2993 not make much sense, read more about cfb mode of DES :-).
2995 void des_ede3_cfb64_encrypt(
2999 des_key_schedule ks1,
3000 des_key_schedule ks2,
3001 des_key_schedule ks3,
3005 Same as des_cfb64_encrypt() accept that the DES operation is
3006 triple DES. As usual, there is a macro for
3007 des_ede2_cfb64_encrypt() which reuses ks1.
3009 void des_ofb_encrypt(
3014 des_key_schedule ks,
3016 This is a implementation of Output Feed Back mode of DES. It is
3017 the same as des_cfb_encrypt() in that numbits is the size of the
3018 units dealt with during input and output (in bits).
3020 void des_ofb64_encrypt(
3024 des_key_schedule ks,
3027 The same as des_cfb64_encrypt() except that it is Output Feed Back
3030 void des_ede3_ofb64_encrypt(
3034 des_key_schedule ks1,
3035 des_key_schedule ks2,
3036 des_key_schedule ks3,
3039 Same as des_ofb64_encrypt() accept that the DES operation is
3040 triple DES. As usual, there is a macro for
3041 des_ede2_ofb64_encrypt() which reuses ks1.
3043 int des_read_pw_string(
3048 This routine is used to get a password from the terminal with echo
3049 turned off. Buf is where the string will end up and length is the
3050 size of buf. Prompt is a string presented to the 'user' and if
3051 verify is set, the key is asked for twice and unless the 2 copies
3052 match, an error is returned. A return code of -1 indicates a
3053 system error, 1 failure due to use interaction, and 0 is success.
3055 unsigned long des_cbc_cksum(
3059 des_key_schedule ks,
3061 This function produces an 8 byte checksum from input that it puts in
3062 output and returns the last 4 bytes as a long. The checksum is
3063 generated via cbc mode of DES in which only the last 8 byes are
3064 kept. I would recommend not using this function but instead using
3065 the EVP_Digest routines, or at least using MD5 or SHA. This
3066 function is used by Kerberos v4 so that is why it stays in the
3073 This is my fast version of the unix crypt(3) function. This version
3074 takes only a small amount of space relative to other fast
3075 crypt() implementations. This is different to the normal crypt
3076 in that the third parameter is the buffer that the return value
3077 is written into. It needs to be at least 14 bytes long. This
3078 function is thread safe, unlike the normal crypt.
3083 This function calls des_fcrypt() with a static array passed as the
3084 third parameter. This emulates the normal non-thread safe semantics
3087 void des_string_to_key(
3090 This function takes str and converts it into a DES key. I would
3091 recommend using MD5 instead and use the first 8 bytes of output.
3092 When I wrote the first version of these routines back in 1990, MD5
3093 did not exist but I feel these routines are still sound. This
3094 routines is compatible with the one in MIT's libdes.
3096 void des_string_to_2keys(
3100 This function takes str and converts it into 2 DES keys.
3101 I would recommend using MD5 and using the 16 bytes as the 2 keys.
3102 I have nothing against these 2 'string_to_key' routines, it's just
3103 that if you say that your encryption key is generated by using the
3104 16 bytes of an MD5 hash, every-one knows how you generated your
3107 int des_read_password(
3111 This routine combines des_read_pw_string() with des_string_to_key().
3113 int des_read_2passwords(
3118 This routine combines des_read_pw_string() with des_string_to_2key().
3120 void des_random_seed(
3122 This routine sets a starting point for des_random_key().
3124 void des_random_key(
3126 This function return a random key. Make sure to 'seed' the random
3127 number generator (with des_random_seed()) before using this function.
3128 I personally now use a MD5 based random number system.
3134 des_key_schedule ks,
3136 This function will write to a file descriptor the encrypted data
3137 from buf. This data will be preceded by a 4 byte 'byte count' and
3138 will be padded out to 8 bytes. The encryption is either CBC of
3139 PCBC depending on the value of des_rw_mode. If it is DES_PCBC_MODE,
3140 pcbc is used, if DES_CBC_MODE, cbc is used. The default is to use
3147 des_key_schedule ks,
3149 This routines read stuff written by des_enc_read() and decrypts it.
3150 I have used these routines quite a lot but I don't believe they are
3151 suitable for non-blocking io. If you are after a full
3152 authentication/encryption over networks, have a look at SSL instead.
3154 unsigned long des_quad_cksum(
3160 This is a function from Kerberos v4 that is not anything to do with
3161 DES but was needed. It is a cksum that is quicker to generate than
3162 des_cbc_cksum(); I personally would use MD5 routines now.
3165 Quite a bit of the following information has been taken from
3168 Electronic funds transfer - Requirements for interfaces,
3169 Part 5.2: Modes of operation for an n-bit block cipher algorithm
3172 There are several different modes in which DES can be used, they are
3175 Electronic Codebook Mode (ECB) (des_ecb_encrypt())
3176 - 64 bits are enciphered at a time.
3177 - The order of the blocks can be rearranged without detection.
3178 - The same plaintext block always produces the same ciphertext block
3179 (for the same key) making it vulnerable to a 'dictionary attack'.
3180 - An error will only affect one ciphertext block.
3182 Cipher Block Chaining Mode (CBC) (des_cbc_encrypt())
3183 - a multiple of 64 bits are enciphered at a time.
3184 - The CBC mode produces the same ciphertext whenever the same
3185 plaintext is encrypted using the same key and starting variable.
3186 - The chaining operation makes the ciphertext blocks dependent on the
3187 current and all preceding plaintext blocks and therefore blocks can not
3189 - The use of different starting variables prevents the same plaintext
3190 enciphering to the same ciphertext.
3191 - An error will affect the current and the following ciphertext blocks.
3193 Cipher Feedback Mode (CFB) (des_cfb_encrypt())
3194 - a number of bits (j) <= 64 are enciphered at a time.
3195 - The CFB mode produces the same ciphertext whenever the same
3196 plaintext is encrypted using the same key and starting variable.
3197 - The chaining operation makes the ciphertext variables dependent on the
3198 current and all preceding variables and therefore j-bit variables are
3199 chained together and can not be rearranged.
3200 - The use of different starting variables prevents the same plaintext
3201 enciphering to the same ciphertext.
3202 - The strength of the CFB mode depends on the size of k (maximal if
3203 j == k). In my implementation this is always the case.
3204 - Selection of a small value for j will require more cycles through
3205 the encipherment algorithm per unit of plaintext and thus cause
3206 greater processing overheads.
3207 - Only multiples of j bits can be enciphered.
3208 - An error will affect the current and the following ciphertext variables.
3210 Output Feedback Mode (OFB) (des_ofb_encrypt())
3211 - a number of bits (j) <= 64 are enciphered at a time.
3212 - The OFB mode produces the same ciphertext whenever the same
3213 plaintext enciphered using the same key and starting variable. More
3214 over, in the OFB mode the same key stream is produced when the same
3215 key and start variable are used. Consequently, for security reasons
3216 a specific start variable should be used only once for a given key.
3217 - The absence of chaining makes the OFB more vulnerable to specific attacks.
3218 - The use of different start variables values prevents the same
3219 plaintext enciphering to the same ciphertext, by producing different
3221 - Selection of a small value for j will require more cycles through
3222 the encipherment algorithm per unit of plaintext and thus cause
3223 greater processing overheads.
3224 - Only multiples of j bits can be enciphered.
3225 - OFB mode of operation does not extend ciphertext errors in the
3226 resultant plaintext output. Every bit error in the ciphertext causes
3227 only one bit to be in error in the deciphered plaintext.
3228 - OFB mode is not self-synchronising. If the two operation of
3229 encipherment and decipherment get out of synchronism, the system needs
3230 to be re-initialised.
3231 - Each re-initialisation should use a value of the start variable
3232 different from the start variable values used before with the same
3233 key. The reason for this is that an identical bit stream would be
3234 produced each time from the same parameters. This would be
3235 susceptible to a ' known plaintext' attack.
3237 Triple ECB Mode (des_ecb3_encrypt())
3238 - Encrypt with key1, decrypt with key2 and encrypt with key3 again.
3239 - As for ECB encryption but increases the key length to 168 bits.
3240 There are theoretic attacks that can be used that make the effective
3241 key length 112 bits, but this attack also requires 2^56 blocks of
3242 memory, not very likely, even for the NSA.
3243 - If both keys are the same it is equivalent to encrypting once with
3245 - If the first and last key are the same, the key length is 112 bits.
3246 There are attacks that could reduce the key space to 55 bit's but it
3247 requires 2^56 blocks of memory.
3248 - If all 3 keys are the same, this is effectively the same as normal
3251 Triple CBC Mode (des_ede3_cbc_encrypt())
3252 - Encrypt with key1, decrypt with key2 and then encrypt with key3.
3253 - As for CBC encryption but increases the key length to 168 bits with
3254 the same restrictions as for triple ecb mode.
3256 ==== digest.doc ========================================================
3259 The Message Digest subroutines.
3261 These routines require "evp.h" to be included.
3263 These functions are a higher level interface to the various message digest
3264 routines found in this library. As such, they allow the same code to be
3265 used to digest via different algorithms with only a change in an initial
3266 parameter. They are basically just a front-end to the MD2, MD5, SHA
3270 These routines all take a pointer to the following structure to specify
3271 which message digest algorithm to use.
3272 typedef struct evp_md_st
3281 int required_pkey_type; /*EVP_PKEY_xxx */
3286 If additional message digest algorithms are to be supported, a structure of
3287 this type needs to be declared and populated and then the Digest routines
3288 can be used with that algorithm. The type field is the object NID of the
3289 digest type (read the section on Objects for an explanation). The pkey_type
3290 is the Object type to use when the a message digest is generated by there
3291 routines and then is to be signed with the pkey algorithm. Md_size is
3292 the size of the message digest returned. Init, update
3293 and final are the relevant functions to perform the message digest function
3294 by parts. One reason for specifying the message digest to use via this
3295 mechanism is that if you only use md5, only the md5 routines will
3296 be included in you linked program. If you passed an integer
3297 that specified which message digest to use, the routine that mapped that
3298 integer to a set of message digest functions would cause all the message
3299 digests functions to be link into the code. This setup also allows new
3300 message digest functions to be added by the application.
3302 The six message digests defined in this library are
3304 EVP_MD *EVP_md2(void); /* RSA sign/verify */
3305 EVP_MD *EVP_md5(void); /* RSA sign/verify */
3306 EVP_MD *EVP_sha(void); /* RSA sign/verify */
3307 EVP_MD *EVP_sha1(void); /* RSA sign/verify */
3308 EVP_MD *EVP_dss(void); /* DSA sign/verify */
3309 EVP_MD *EVP_dss1(void); /* DSA sign/verify */
3311 All the message digest routines take a EVP_MD_CTX pointer as an argument.
3312 The state of the message digest is kept in this structure.
3314 typedef struct pem_md_ctx_st
3318 unsigned char base[4]; /* this is used in my library as a
3319 * 'pointer' to all union elements
3327 The Digest functions are as follows.
3329 void EVP_DigestInit(
3332 This function is used to initialise the EVP_MD_CTX. The message
3333 digest that will associated with 'ctx' is specified by 'type'.
3335 void EVP_DigestUpdate(
3337 unsigned char *data,
3339 This function is used to pass more data to the message digest
3340 function. 'cnt' bytes are digested from 'data'.
3342 void EVP_DigestFinal(
3346 This function finishes the digestion and puts the message digest
3347 into 'md'. The length of the message digest is put into len;
3348 EVP_MAX_MD_SIZE is the size of the largest message digest that
3349 can be returned from this function. Len can be NULL if the
3350 size of the digest is not required.
3353 ==== encode.doc ========================================================
3356 void EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
3357 void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,
3358 int *outl,unsigned char *in,int inl);
3359 void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl);
3360 int EVP_EncodeBlock(unsigned char *t, unsigned char *f, int n);
3362 void EVP_DecodeInit(EVP_ENCODE_CTX *ctx);
3363 int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl,
3364 unsigned char *in, int inl);
3365 int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned
3366 char *out, int *outl);
3367 int EVP_DecodeBlock(unsigned char *t, unsigned
3371 ==== envelope.doc ========================================================
3373 The following routines are use to create 'digital' envelopes.
3374 By this I mean that they perform various 'higher' level cryptographic
3375 functions. Have a read of 'cipher.doc' and 'digest.doc' since those
3376 routines are used by these functions.
3377 cipher.doc contains documentation about the cipher part of the
3378 envelope library and digest.doc contatins the description of the
3379 message digests supported.
3381 To 'sign' a document involves generating a message digest and then encrypting
3382 the digest with an private key.
3384 #define EVP_SignInit(a,b) EVP_DigestInit(a,b)
3385 #define EVP_SignUpdate(a,b,c) EVP_DigestUpdate(a,b,c)
3386 Due to the fact this operation is basically just an extended message
3387 digest, the first 2 functions are macro calls to Digest generating
3395 This finalisation function finishes the generation of the message
3396 digest and then encrypts the digest (with the correct message digest
3397 object identifier) with the EVP_PKEY private key. 'ctx' is the message digest
3398 context. 'md' will end up containing the encrypted message digest. This
3399 array needs to be EVP_PKEY_size(pkey) bytes long. 's' will actually
3400 contain the exact length. 'pkey' of course is the private key. It is
3401 one of EVP_PKEY_RSA or EVP_PKEY_DSA type.
3402 If there is an error, 0 is returned, otherwise 1.
3404 Verify is used to check an signed message digest.
3406 #define EVP_VerifyInit(a,b) EVP_DigestInit(a,b)
3407 #define EVP_VerifyUpdate(a,b,c) EVP_DigestUpdate(a,b,c)
3408 Since the first step is to generate a message digest, the first 2 functions
3411 int EVP_VerifyFinal(
3416 This function finishes the generation of the message digest and then
3417 compares it with the supplied encrypted message digest. 'md' contains the
3418 's' bytes of encrypted message digest. 'pkey' is used to public key decrypt
3419 the digest. It is then compared with the message digest just generated.
3420 If they match, 1 is returned else 0.
3422 int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek,
3423 int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk);
3424 Must have at least one public key, error is 0. I should also mention that
3425 the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size.
3427 #define EVP_SealUpdate(a,b,c,d,e) EVP_EncryptUpdate(a,b,c,d,e)
3428 void EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl);
3431 int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek,
3432 int ekl,unsigned char *iv,EVP_PKEY *priv);
3435 #define EVP_OpenUpdate(a,b,c,d,e) EVP_DecryptUpdate(a,b,c,d,e)
3437 int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
3438 Decrypt final return code
3441 ==== error.doc ========================================================
3445 The 'error' system I've implemented is intended to server 2 purpose, to
3446 record the reason why a command failed and to record where in the libraries
3447 the failure occurred. It is more or less setup to record a 'trace' of which
3448 library components were being traversed when the error occurred.
3450 When an error is recorded, it is done so a as single unsigned long which is
3451 composed of three parts. The top byte is the 'library' number, the middle
3452 12 bytes is the function code, and the bottom 12 bits is the 'reason' code.
3454 Each 'library', or should a say, 'section' of the SSLeay library has a
3455 different unique 'library' error number. Each function in the library has
3456 a number that is unique for that library. Each 'library' also has a number
3457 for each 'error reason' that is only unique for that 'library'.
3459 Due to the way these error routines record a 'error trace', there is an
3460 array per thread that is used to store the error codes.
3461 The various functions in this library are used to access
3462 and manipulate this array.
3464 void ERR_put_error(int lib, int func,int reason);
3465 This routine records an error in library 'lib', function 'func'
3466 and reason 'reason'. As errors get 'put' into the buffer, they wrap
3467 around and overwrite old errors if too many are written. It is assumed
3468 that the last errors are the most important.
3470 unsigned long ERR_get_error(void );
3471 This function returns the last error added to the error buffer.
3472 In effect it is popping the value off the buffer so repeated calls will
3473 continue to return values until there are no more errors to return in which
3476 unsigned long ERR_peek_error(void );
3477 This function returns the value of the last error added to the
3478 error buffer but does not 'pop' it from the buffer.
3480 void ERR_clear_error(void );
3481 This function clears the error buffer, discarding all unread
3484 While the above described error system obviously produces lots of different
3485 error number, a method for 'reporting' these errors in a human readable
3486 form is required. To achieve this, each library has the option of
3487 'registering' error strings.
3489 typedef struct ERR_string_data_st
3491 unsigned long error;
3495 The 'ERR_STRING_DATA' contains an error code and the corresponding text
3496 string. To add new function error strings for a library, the
3497 ERR_STRING_DATA needs to be 'registered' with the library.
3499 void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err);
3500 This function 'registers' the array of ERR_STRING_DATA pointed to by
3501 'err' as error text strings for the error library 'lib'.
3503 void ERR_free_strings(void);
3504 This function free()s all the loaded error strings.
3506 char *ERR_error_string(unsigned long error,char *buf);
3507 This function returns a text string that is a human readable
3508 version of the error represented by 'error'. Buff should be at least 120
3509 bytes long and if it is NULL, the return value is a pointer to a static
3510 variable that will contain the error string, otherwise 'buf' is returned.
3511 If there is not a text string registered for a particular error, a text
3512 string containing the error number is returned instead.
3514 void ERR_print_errors(BIO *bp);
3515 void ERR_print_errors_fp(FILE *fp);
3516 This function is a convenience routine that prints the error string
3517 for each error until all errors have been accounted for.
3519 char *ERR_lib_error_string(unsigned long e);
3520 char *ERR_func_error_string(unsigned long e);
3521 char *ERR_reason_error_string(unsigned long e);
3522 The above three functions return the 3 different components strings for the
3523 error 'e'. ERR_error_string() uses these functions.
3525 void ERR_load_ERR_strings(void );
3526 This function 'registers' the error strings for the 'ERR' module.
3528 void ERR_load_crypto_strings(void );
3529 This function 'register' the error strings for just about every
3530 library in the SSLeay package except for the SSL routines. There is no
3531 need to ever register any error text strings and you will probably save in
3532 program size. If on the other hand you do 'register' all errors, it is
3533 quite easy to determine why a particular routine failed.
3535 As a final footnote as to why the error system is designed as it is.
3536 1) I did not want a single 'global' error code.
3537 2) I wanted to know which subroutine a failure occurred in.
3538 3) For Windows NT etc, it should be simple to replace the 'key' routines
3539 with code to pass error codes back to the application.
3540 4) I wanted the option of meaningful error text strings.
3542 Late breaking news - the changes to support threads.
3544 Each 'thread' has an 'ERR_STATE' state associated with it.
3545 ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling
3548 ERR_remove_state(unsigned long pid); will 'free()' this state. If pid == 0
3549 the current 'thread/process' will have it's error state removed.
3550 If you do not remove the error state of a thread, this could be considered a
3551 form of memory leak, so just after 'reaping' a thread that has died,
3552 call ERR_remove_state(pid).
3554 Have a read of thread.doc for more details for what is required for
3555 multi-threading support. All the other error routines will
3556 work correctly when using threads.
3559 ==== idea.doc ========================================================
3562 IDEA is a block cipher that operates on 64bit (8 byte) quantities. It
3563 uses a 128bit (16 byte) key. It can be used in all the modes that DES can
3564 be used. This library implements the ecb, cbc, cfb64 and ofb64 modes.
3566 For all calls that have an 'input' and 'output' variables, they can be the
3569 This library requires the inclusion of 'idea.h'.
3571 All of the encryption functions take what is called an IDEA_KEY_SCHEDULE as an
3572 argument. An IDEA_KEY_SCHEDULE is an expanded form of the idea key.
3573 For all modes of the IDEA algorithm, the IDEA_KEY_SCHEDULE used for
3574 decryption is different to the one used for encryption.
3576 The define IDEA_ENCRYPT is passed to specify encryption for the functions
3577 that require an encryption/decryption flag. IDEA_DECRYPT is passed to
3578 specify decryption. For some mode there is no encryption/decryption
3579 flag since this is determined by the IDEA_KEY_SCHEDULE.
3581 So to encrypt you would do the following
3582 idea_set_encrypt_key(key,encrypt_ks);
3583 idea_ecb_encrypt(...,encrypt_ks);
3584 idea_cbc_encrypt(....,encrypt_ks,...,IDEA_ENCRYPT);
3587 idea_set_encrypt_key(key,encrypt_ks);
3588 idea_set_decrypt_key(encrypt_ks,decrypt_ks);
3589 idea_ecb_encrypt(...,decrypt_ks);
3590 idea_cbc_encrypt(....,decrypt_ks,...,IDEA_DECRYPT);
3592 Please note that any of the encryption modes specified in my DES library
3593 could be used with IDEA. I have only implemented ecb, cbc, cfb64 and
3594 ofb64 for the following reasons.
3595 - ecb is the basic IDEA encryption.
3596 - cbc is the normal 'chaining' form for block ciphers.
3597 - cfb64 can be used to encrypt single characters, therefore input and output
3598 do not need to be a multiple of 8.
3599 - ofb64 is similar to cfb64 but is more like a stream cipher, not as
3600 secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
3601 - If you want triple IDEA, thats 384 bits of key and you must be totally
3602 obsessed with security. Still, if you want it, it is simple enough to
3603 copy the function from the DES library and change the des_encrypt to
3604 idea_encrypt; an exercise left for the paranoid reader :-).
3606 The functions are as follows:
3608 void idea_set_encrypt_key(
3610 IDEA_KEY_SCHEDULE *ks);
3611 idea_set_encrypt_key converts a 16 byte IDEA key into an
3612 IDEA_KEY_SCHEDULE. The IDEA_KEY_SCHEDULE is an expanded form of
3613 the key which can be used to perform IDEA encryption.
3614 An IDEA_KEY_SCHEDULE is an expanded form of the key which is used to
3615 perform actual encryption. It can be regenerated from the IDEA key
3616 so it only needs to be kept when encryption is about
3617 to occur. Don't save or pass around IDEA_KEY_SCHEDULE's since they
3618 are CPU architecture dependent, IDEA keys are not.
3620 void idea_set_decrypt_key(
3621 IDEA_KEY_SCHEDULE *encrypt_ks,
3622 IDEA_KEY_SCHEDULE *decrypt_ks);
3623 This functions converts an encryption IDEA_KEY_SCHEDULE into a
3624 decryption IDEA_KEY_SCHEDULE. For all decryption, this conversion
3625 of the key must be done. In some modes of IDEA, an
3626 encryption/decryption flag is also required, this is because these
3627 functions involve block chaining and the way this is done changes
3628 depending on which of encryption of decryption is being done.
3629 Please note that there is no quick way to generate the decryption
3630 key schedule other than generating the encryption key schedule and
3634 unsigned long *data,
3635 IDEA_KEY_SCHEDULE *ks);
3636 This is the IDEA encryption function that gets called by just about
3637 every other IDEA routine in the library. You should not use this
3638 function except to implement 'modes' of IDEA. I say this because the
3639 functions that call this routine do the conversion from 'char *' to
3640 long, and this needs to be done to make sure 'non-aligned' memory
3641 access do not occur.
3642 Data is a pointer to 2 unsigned long's and ks is the
3643 IDEA_KEY_SCHEDULE to use. Encryption or decryption depends on the
3646 void idea_ecb_encrypt(
3647 unsigned char *input,
3648 unsigned char *output,
3649 IDEA_KEY_SCHEDULE *ks);
3650 This is the basic Electronic Code Book form of IDEA (in DES this
3651 mode is called Electronic Code Book so I'm going to use the term
3652 for idea as well :-).
3653 Input is encrypted into output using the key represented by
3654 ks. Depending on the IDEA_KEY_SCHEDULE, encryption or
3655 decryption occurs. Input is 8 bytes long and output is 8 bytes.
3657 void idea_cbc_encrypt(
3658 unsigned char *input,
3659 unsigned char *output,
3661 IDEA_KEY_SCHEDULE *ks,
3662 unsigned char *ivec,
3664 This routine implements IDEA in Cipher Block Chaining mode.
3665 Input, which should be a multiple of 8 bytes is encrypted
3666 (or decrypted) to output which will also be a multiple of 8 bytes.
3667 The number of bytes is in length (and from what I've said above,
3668 should be a multiple of 8). If length is not a multiple of 8, bad
3669 things will probably happen. ivec is the initialisation vector.
3670 This function updates iv after each call so that it can be passed to
3671 the next call to idea_cbc_encrypt().
3673 void idea_cfb64_encrypt(
3677 des_key_schedule ks,
3681 This is one of the more useful functions in this IDEA library, it
3682 implements CFB mode of IDEA with 64bit feedback.
3683 This allows you to encrypt an arbitrary number of bytes,
3684 you do not require 8 byte padding. Each call to this
3685 routine will encrypt the input bytes to output and then update ivec
3686 and num. Num contains 'how far' we are though ivec.
3687 Enc is used to indicate encryption or decryption.
3688 One very important thing to remember is that when decrypting, use
3689 the encryption form of the key.
3690 CFB64 mode operates by using the cipher to
3691 generate a stream of bytes which is used to encrypt the plain text.
3692 The cipher text is then encrypted to generate the next 64 bits to
3693 be xored (incrementally) with the next 64 bits of plain
3694 text. As can be seen from this, to encrypt or decrypt,
3695 the same 'cipher stream' needs to be generated but the way the next
3696 block of data is gathered for encryption is different for
3697 encryption and decryption. What this means is that to encrypt
3698 idea_set_encrypt_key(key,ks);
3699 idea_cfb64_encrypt(...,ks,..,IDEA_ENCRYPT)
3701 idea_set_encrypt_key(key,ks)
3702 idea_cfb64_encrypt(...,ks,...,IDEA_DECRYPT)
3703 Note: The same IDEA_KEY_SCHEDULE but different encryption flags.
3704 For idea_cbc or idea_ecb, idea_set_decrypt_key() would need to be
3705 used to generate the IDEA_KEY_SCHEDULE for decryption.
3706 The reason I'm stressing this point is that I just wasted 3 hours
3707 today trying to decrypt using this mode and the decryption form of
3710 void idea_ofb64_encrypt(
3714 des_key_schedule ks,
3717 This functions implements OFB mode of IDEA with 64bit feedback.
3718 This allows you to encrypt an arbitrary number of bytes,
3719 you do not require 8 byte padding. Each call to this
3720 routine will encrypt the input bytes to output and then update ivec
3721 and num. Num contains 'how far' we are though ivec.
3722 This is in effect a stream cipher, there is no encryption or
3723 decryption mode. The same key and iv should be used to
3724 encrypt and decrypt.
3726 For reading passwords, I suggest using des_read_pw_string() from my DES library.
3727 To generate a password from a text string, I suggest using MD5 (or MD2) to
3728 produce a 16 byte message digest that can then be passed directly to
3729 idea_set_encrypt_key().
3732 For more information about the specific IDEA modes in this library
3733 (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
3734 documentation on my DES library. What is said about DES is directly
3735 applicable for IDEA.
3738 ==== legal.doc ========================================================
3740 From eay@mincom.com Thu Jun 27 00:25:45 1996
3741 Received: by orb.mincom.oz.au id AA15821
3742 (5.65c/IDA-1.4.4 for eay); Wed, 26 Jun 1996 14:25:45 +1000
3743 Date: Wed, 26 Jun 1996 14:25:45 +1000 (EST)
3744 From: Eric Young <eay@mincom.oz.au>
3746 To: Ken Toll <ktoll@ren.digitalage.com>
3747 Cc: Eric Young <eay@mincom.oz.au>, ssl-talk@netscape.com
3748 Subject: Re: Unidentified subject!
3749 In-Reply-To: <9606261950.ZM28943@ren.digitalage.com>
3750 Message-Id: <Pine.SOL.3.91.960626131156.28573K-100000@orb>
3752 Content-Type: TEXT/PLAIN; charset=US-ASCII
3757 This is a little off topic but since SSLeay is a free implementation of
3758 the SSLv2 protocol, I feel it is worth responding on the topic of if it
3759 is actually legal for Americans to use free cryptographic software.
3761 On Wed, 26 Jun 1996, Ken Toll wrote:
3762 > Is the U.S the only country that SSLeay cannot be used commercially
3763 > (because of RSAref) or is that going to be an issue with every country
3764 > that a client/server application (non-web browser/server) is deployed
3767 >From what I understand, the software patents that apply to algorithms
3768 like RSA and DH only apply in the USA. The IDEA algorithm I believe is
3769 patened in europe (USA?), but considing how little it is used by other SSL
3770 implementations, it quite easily be left out of the SSLeay build
3771 (this can be done with a compile flag).
3773 Actually if the RSA patent did apply outside the USA, it could be rather
3774 interesting since RSA is not alowed to let RSA toolkits outside of the USA
3775 [1], and since these are the only forms that they will alow the algorithm
3776 to be used in, it would mean that non-one outside of the USA could produce
3777 public key software which would be a very strong statment for
3778 international patent law to make :-). This logic is a little flawed but
3779 it still points out some of the more interesting permutations of USA
3780 patent law and ITAR restrictions.
3782 Inside the USA there is also the unresolved issue of RC4/RC2 which were
3783 made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2). I have
3784 copies of the origional postings if people are interested. RSA I believe
3785 claim that they were 'trade-secrets' and that some-one broke an NDA in
3786 revealing them. Other claim they reverse engineered the algorithms from
3787 compiled binaries. If the algorithms were reverse engineered, I belive
3788 RSA had no legal leg to stand on. If an NDA was broken, I don't know.
3789 Regardless, RSA, I belive, is willing to go to court over the issue so
3790 licencing is probably the best idea, or at least talk to them.
3791 If there are people who actually know more about this, pease let me know, I
3792 don't want to vilify or spread miss-information if I can help it.
3794 If you are not producing a web browser, it is easy to build SSLeay with
3795 RC2/RC4 removed. Since RC4 is the defacto standard cipher in
3796 all web software (and it is damn fast) it is more or less required for
3797 www use. For non www use of SSL, especially for an application where
3798 interoperability with other vendors is not critical just leave it out.
3800 Removing IDEA, RC2 and RC4 would only leave DES and Triple DES but
3801 they should be ok. Considing that Triple DES can encrypt at rates of
3802 410k/sec on a pentium 100, and 940k/sec on a P6/200, this is quite
3803 reasonable performance. Single DES clocks in at 1160k/s and 2467k/s
3804 respectivly is actually quite fast for those not so paranoid (56 bit key).[1]
3806 > Is it possible to get a certificate for commercial use outside of the U.S.?
3809 Thawte Consulting issues certificates (they are the people who sell the
3810 Sioux httpd server and are based in South Africa)
3811 Verisign will issue certificates for Sioux (sold from South Africa), so this
3812 proves that they will issue certificate for OS use if they are
3813 happy with the quality of the software.
3815 (The above mentioned companies just the ones that I know for sure are issuing
3816 certificates outside the USA).
3818 There is always the point that if you are using SSL for an intra net,
3819 SSLeay provides programs that can be used so you can issue your own
3820 certificates. They need polishing but at least it is a good starting point.
3822 I am not doing anything outside Australian law by implementing these
3823 algorithms (to the best of my knowedge). It is another example of how
3824 the world legal system does not cope with the internet very well.
3826 I may start making shared libraries available (I have now got DLL's for
3827 Windows). This will mean that distributions into the usa could be
3828 shipped with a version with a reduced cipher set and the versions outside
3829 could use the DLL/shared library with all the ciphers (and without RSAref).
3831 This could be completly hidden from the application, so this would not
3832 even require a re-linking.
3834 This is the reverse of what people were talking about doing to get around
3835 USA export regulations :-)
3839 [1]: The RSAref2.0 tookit is available on at least 3 ftp sites in Europe
3840 and one in South Africa.
3842 [2]: Since I always get questions when I post benchmark numbers :-),
3843 DES performace figures are in 1000's of bytes per second in cbc
3844 mode using an 8192 byte buffer. The pentium 100 was running Windows NT
3845 3.51 DLLs and the 686/200 was running NextStep.
3846 I quote pentium 100 benchmarks because it is basically the
3847 'entry level' computer that most people buy for personal use.
3848 Windows 95 is the OS shipping on those boxes, so I'll give
3849 NT numbers (the same Win32 runtime environment). The 686
3850 numbers are present as an indication of where we will be in a
3853 Eric Young | BOOL is tri-state according to Bill Gates.
3854 AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage().
3858 ==== lhash.doc ========================================================
3862 I wrote this library in 1991 and have since forgotten why I called it lhash.
3863 It implements a hash table from an article I read at the
3864 time from 'Communications of the ACM'. What makes this hash
3865 table different is that as the table fills, the hash table is
3866 increased (or decreased) in size via realloc().
3867 When a 'resize' is done, instead of all hashes being redistributed over
3868 twice as many 'buckets', one bucket is split. So when an 'expand' is done,
3869 there is only a minimal cost to redistribute some values. Subsequent
3870 inserts will cause more single 'bucket' redistributions but there will
3871 never be a sudden large cost due to redistributing all the 'buckets'.
3873 The state for a particular hash table is kept in the LHASH structure.
3874 The LHASH structure also records statistics about most aspects of accessing
3875 the hash table. This is mostly a legacy of my writing this library for
3876 the reasons of implementing what looked like a nice algorithm rather than
3877 for a particular software product.
3879 Internal stuff you probably don't want to know about.
3880 The decision to increase or decrease the hash table size is made depending
3881 on the 'load' of the hash table. The load is the number of items in the
3882 hash table divided by the size of the hash table. The default values are
3883 as follows. If (hash->up_load < load) => expand.
3884 if (hash->down_load > load) => contract. The 'up_load' has a default value of
3885 1 and 'down_load' has a default value of 2. These numbers can be modified
3886 by the application by just playing with the 'up_load' and 'down_load'
3887 variables. The 'load' is kept in a form which is multiplied by 256. So
3888 hash->up_load=8*256; will cause a load of 8 to be set.
3890 If you are interested in performance the field to watch is
3891 num_comp_calls. The hash library keeps track of the 'hash' value for
3892 each item so when a lookup is done, the 'hashes' are compared, if
3893 there is a match, then a full compare is done, and
3894 hash->num_comp_calls is incremented. If num_comp_calls is not equal
3895 to num_delete plus num_retrieve it means that your hash function is
3896 generating hashes that are the same for different values. It is
3897 probably worth changing your hash function if this is the case because
3898 even if your hash table has 10 items in a 'bucked', it can be searched
3899 with 10 'unsigned long' compares and 10 linked list traverses. This
3900 will be much less expensive that 10 calls to you compare function.
3903 unsigned long (*hash)(),
3905 This function is used to create a new LHASH structure. It is passed
3906 function pointers that are used to store and retrieve values passed
3907 into the hash table. The 'hash'
3908 function is a hashing function that will return a hashed value of
3909 it's passed structure. 'cmp' is passed 2 parameters, it returns 0
3910 is they are equal, otherwise, non zero.
3911 If there are any problems (usually malloc failures), NULL is
3912 returned, otherwise a new LHASH structure is returned. The
3913 hash value is normally truncated to a power of 2, so make sure
3914 that your hash function returns well mixed low order bits.
3918 This function free()s a LHASH structure. If there is malloced
3919 data in the hash table, it will not be freed. Consider using the
3920 lh_doall function to deallocate any remaining entries in the hash
3926 This function inserts the data pointed to by data into the lh hash
3927 table. If there is already and entry in the hash table entry, the
3928 value being replaced is returned. A NULL is returned if the new
3929 entry does not clash with an entry already in the table (the normal
3930 case) or on a malloc() failure (perhaps I should change this....).
3931 The 'char *data' is exactly what is passed to the hash and
3932 comparison functions specified in lh_new().
3937 This routine deletes an entry from the hash table. The value being
3938 deleted is returned. NULL is returned if there is no such value in
3944 If 'data' is in the hash table it is returned, else NULL is
3945 returned. The way these routines would normally be uses is that a
3946 dummy structure would have key fields populated and then
3947 ret=lh_retrieve(hash,&dummy);. Ret would now be a pointer to a fully
3948 populated structure.
3952 void (*func)(char *a));
3953 This function will, for every entry in the hash table, call function
3954 'func' with the data item as parameters.
3955 This function can be quite useful when used as follows.
3956 void cleanup(STUFF *a)
3958 lh_doall(hash,cleanup);
3960 This can be used to free all the entries, lh_free() then
3961 cleans up the 'buckets' that point to nothing. Be careful
3962 when doing this. If you delete entries from the hash table,
3963 in the call back function, the table may decrease in size,
3964 moving item that you are
3965 currently on down lower in the hash table. This could cause
3966 some entries to be skipped. The best solution to this problem
3967 is to set lh->down_load=0 before you start. This will stop
3968 the hash table ever being decreased in size.
3972 void(*func)(char *a,char *arg));
3974 This function is the same as lh_doall except that the function
3975 called will be passed 'arg' as the second argument.
3977 unsigned long lh_strhash(
3979 This function is a demo string hashing function. Since the LHASH
3980 routines would normally be passed structures, this routine would
3981 not normally be passed to lh_new(), rather it would be used in the
3982 function passed to lh_new().
3984 The next three routines print out various statistics about the state of the
3985 passed hash table. These numbers are all kept in the lhash structure.
3990 This function prints out statistics on the size of the hash table,
3991 how many entries are in it, and the number and result of calls to
3992 the routines in this library.
3997 For each 'bucket' in the hash table, the number of entries is
4000 void lh_node_usage_stats(
4003 This function prints out a short summary of the state of the hash
4004 table. It prints what I call the 'load' and the 'actual load'.
4005 The load is the average number of data items per 'bucket' in the
4006 hash table. The 'actual load' is the average number of items per
4007 'bucket', but only for buckets which contain entries. So the
4008 'actual load' is the average number of searches that will need to
4009 find an item in the hash table, while the 'load' is the average number
4010 that will be done to record a miss.
4012 ==== md2.doc ========================================================
4015 MD2 is a message digest algorithm that can be used to condense an arbitrary
4016 length message down to a 16 byte hash. The functions all need to be passed
4017 a MD2_CTX which is used to hold the MD2 context during multiple MD2_Update()
4018 function calls. The normal method of use for this library is as follows
4026 This library requires the inclusion of 'md2.h'.
4028 The main negative about MD2 is that it is slow, especially when compared
4031 The functions are as follows:
4035 This function needs to be called to initiate a MD2_CTX structure for
4040 unsigned char *data;
4042 This updates the message digest context being generated with 'len'
4043 bytes from the 'data' pointer. The number of bytes can be any
4049 This function is called when a message digest of the data digested
4050 with MD2_Update() is wanted. The message digest is put in the 'md'
4051 array and is MD2_DIGEST_LENGTH (16) bytes long.
4057 This function performs a MD2_Init(), followed by a MD2_Update()
4058 followed by a MD2_Final() (using a local MD2_CTX).
4059 The resulting digest is put into 'md' if it is not NULL.
4060 Regardless of the value of 'md', the message
4061 digest is returned from the function. If 'md' was NULL, the message
4062 digest returned is being stored in a static structure.
4064 ==== md5.doc ========================================================
4067 MD5 is a message digest algorithm that can be used to condense an arbitrary
4068 length message down to a 16 byte hash. The functions all need to be passed
4069 a MD5_CTX which is used to hold the MD5 context during multiple MD5_Update()
4070 function calls. This library also contains random number routines that are
4073 The normal method of use for this library is as follows
4081 This library requires the inclusion of 'md5.h'.
4083 The functions are as follows:
4087 This function needs to be called to initiate a MD5_CTX structure for
4092 unsigned char *data;
4094 This updates the message digest context being generated with 'len'
4095 bytes from the 'data' pointer. The number of bytes can be any
4101 This function is called when a message digest of the data digested
4102 with MD5_Update() is wanted. The message digest is put in the 'md'
4103 array and is MD5_DIGEST_LENGTH (16) bytes long.
4109 This function performs a MD5_Init(), followed by a MD5_Update()
4110 followed by a MD5_Final() (using a local MD5_CTX).
4111 The resulting digest is put into 'md' if it is not NULL.
4112 Regardless of the value of 'md', the message
4113 digest is returned from the function. If 'md' was NULL, the message
4114 digest returned is being stored in a static structure.
4117 ==== memory.doc ========================================================
4119 In the interests of debugging SSLeay, there is an option to compile
4120 using some simple memory leak checking.
4122 All malloc(), free() and realloc() calls in SSLeay now go via
4123 Malloc(), Free() and Realloc() (except those in crypto/lhash).
4125 If CRYPTO_MDEBUG is defined, these calls are #defined to
4126 CRYPTO_malloc(), CRYPTO_free() and CRYPTO_realloc().
4127 If it is not defined, they are #defined to malloc(), free() and realloc().
4129 the CRYPTO_malloc() routines by default just call the underlying library
4132 If CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON) is called, memory leak detection is
4133 turned on. CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_OFF) turns it off.
4135 When turned on, each Malloc() or Realloc() call is recored along with the file
4136 and line number from where the call was made. (This is done using the
4137 lhash library which always uses normal system malloc(3) routines).
4139 void CRYPTO_mem_leaks(BIO *b);
4140 void CRYPTO_mem_leaks_fp(FILE *fp);
4141 These both print out the list of memory that has not been free()ed.
4142 This will probably be rather hard to read, but if you look for the 'top level'
4143 structure allocation, this will often give an idea as to what is not being
4144 free()ed. I don't expect people to use this stuff normally.
4146 ==== ca.1 ========================================================
4148 From eay@orb.mincom.oz.au Thu Dec 28 23:56:45 1995
4149 Received: by orb.mincom.oz.au id AA07374
4150 (5.65c/IDA-1.4.4 for eay); Thu, 28 Dec 1995 13:56:45 +1000
4151 Date: Thu, 28 Dec 1995 13:56:45 +1000 (EST)
4152 From: Eric Young <eay@mincom.oz.au>
4154 To: sameer <sameer@c2.org>
4155 Cc: ssleay@mincom.oz.au
4157 In-Reply-To: <199512230440.UAA23410@infinity.c2.org>
4158 Message-Id: <Pine.SOL.3.91.951228133525.7269A-100000@orb>
4160 Content-Type: TEXT/PLAIN; charset=US-ASCII
4164 On Fri, 22 Dec 1995, sameer wrote:
4165 > I could use documentation on 'ca'. Thanks.
4168 The ca program uses the ssleay.conf file for most of its configuration
4172 -verbose - Talk alot while doing things
4173 -config file - A config file. If you don't want to use the
4175 -name arg - The particular CA definition to use
4176 In the config file, the section to use for parameters. This lets
4177 multiple setups to be contained in the one file. By default, the
4178 default_ca variable is looked up in the [ ca ] section. So in the
4179 shipped ssleay.conf, the CA definition used is CA_default. It could be
4181 -gencrl days - Generate a new CRL, days is when the next CRL is due
4182 This will generate a new certificate revocion list.
4183 -days arg - number of days to certify the certificate for
4184 When certifiying certificates, this is the number of days to use.
4185 -md arg - md to use, one of md2, md5, sha or sha1
4186 -policy arg - The CA 'policy' to support
4187 I'll describe this later, but there are 2 policies definied in the
4189 -keyfile arg - PEM RSA private key file
4190 -key arg - key to decode the RSA private key if it is encrypted
4191 since we need to keep the CA's RSA key encrypted
4192 -cert - The CA certificate
4193 -in file - The input PEM encoded certificate request(s)
4194 -out file - Where to put the output file(s)
4195 -outdir dir - Where to put output certificates
4196 The -out options concatinates all the output certificied
4197 certificates to one file, -outdir puts them in a directory,
4198 named by serial number.
4199 -infiles .... - The last argument, requests to process
4200 The certificate requests to process, -in is the same.
4202 Just about all the above have default values defined in ssleay.conf.
4204 The key variables in ssleay.conf are (for the pariticular '-name' being
4205 used, in the default, it is CA_default).
4207 dir is where all the CA database stuff is kept.
4208 certs is where all the previously issued certificates are kept.
4209 The database is a simple text database containing the following tab separated
4211 status: a value of 'R' - revoked, 'E' -expired or 'V' valid.
4212 issued date: When the certificate was certified.
4213 revoked date: When it was revoked, blank if not revoked.
4214 serial number: The certificate serial number.
4215 certificate: Where the certificate is located.
4216 CN: The name of the certificate.
4218 The demo file has quite a few made up values it it. The last 2 were
4219 added by the ca program and are acurate.
4220 The CA program does not update the 'certificate' file correctly right now.
4221 The serial field should be unique as should the CN/status combination.
4222 The ca program checks these at startup. What still needs to be
4223 wrtten is a program to 'regenerate' the data base file from the issued
4224 certificate list (and a CRL list).
4226 Back to the CA_default variables.
4228 Most of the variables are commented.
4230 policy is the default policy.
4232 Ok for policies, they define the order and which fields must be present
4233 in the certificate request and what gets filled in.
4237 means that the country name must match the CA certificate.
4238 organizationalUnitName = optional
4239 The org.Unit,Name does not have to be present and
4240 commonName = supplied
4241 commonName must be supplied in the certificate request.
4243 For the 'policy_match' polocy, the order of the attributes in the
4244 generated certiticate would be
4248 organizationalUnitName
4252 Have a play, it sort of makes sense. If you think about how the persona
4253 requests operate, it is similar to the 'policy_match' policy and the
4254 'policy_anything' is similar to what versign is doing.
4256 I hope this helps a bit. Some backend scripts are definitly needed to
4257 update the database and to make certificate revocion easy. All
4258 certificates issued should also be kept forever (or until they expire?)
4261 eric (who has to run off an buy some cheap knee pads for the caving in 4
4265 Eric Young | Signature removed since it was generating
4266 AARNet: eay@mincom.oz.au | more followups than the message contents :-)
4269 ==== ms3-ca.doc ========================================================
4271 Date: Mon, 9 Jun 97 08:00:33 +0200
4272 From: Holger.Reif@PrakInf.TU-Ilmenau.DE (Holger Reif)
4274 Organization: TU Ilmenau, Fak. IA, FG Telematik
4275 Content-Length: 14575
4279 Loading client certs into MSIE 3.01
4280 ===================================
4282 This document conatains all the information necessary to succesfully set up
4283 some scripts to issue client certs to Microsoft Internet Explorer. It
4284 includes the required knowledge about the model MSIE uses for client
4285 certification and includes complete sample scripts ready to play with. The
4286 scripts were tested against a modified ca program of SSLeay 0.6.6 and should
4287 work with the regular ca program that comes with version 0.8.0. I haven't
4288 tested against MSIE 4.0
4290 You can use the information contained in this document in either way you
4291 want. However if you feel it saved you a lot of time I ask you to be as fair
4292 as to mention my name: Holger Reif <reif@prakinf.tu-ilmenau.de>.
4294 1.) The model used by MSIE
4295 --------------------------
4297 The Internet Explorer doesn't come with a embedded engine for installing
4298 client certs like Netscape's Navigator. It rather uses the CryptoAPI (CAPI)
4299 defined by Microsoft. CAPI comes with WindowsNT 4.0 or is installed together
4300 with Internet Explorer since 3.01. The advantage of this approach is a higher
4301 flexibility because the certificates in the (per user) system open
4302 certificate store may be used by other applications as well. The drawback
4303 however is that you need to do a bit more work to get a client cert issued.
4305 CAPI defines functions which will handle basic cryptographic work, eg.
4306 generating keys, encrypting some data, signing text or building a certificate
4307 request. The procedure is as follows: A CAPI function generates you a key
4308 pair and saves it into the certificate store. After that one builds a
4309 Distinguished Name. Together with that key pair another CAPI function forms a
4310 PKCS#10 request which you somehow need to submit to a CA. Finally the issued
4311 cert is given to a yet another CAPI function which saves it into the
4314 The certificate store with the user's keys and certs is in the registry. You
4315 will find it under HKEY_CURRENT_USER/Software/Microsoft/Cryptography/ (I
4316 leave it to you as a little exercise to figure out what all the entries mean
4317 ;-). Note that the keys are protected only with the user's usual Windows
4320 2.) The practical usage
4321 -----------------------
4323 Unfortunatly since CAPI is a system API you can't access its functions from
4324 HTML code directly. For this purpose Microsoft provides a wrapper called
4325 certenr3.dll. This DLL accesses the CAPI functions and provides an interface
4326 usable from Visual Basic Script. One needs to install that library on the
4327 computer which wants to have client cert. The easiest way is to load it as an
4328 ActiveX control (certenr3.dll is properly authenticode signed by MS ;-). If
4329 you have ever enrolled e cert request at a CA you will have installed it.
4331 At time of writing certenr3.dll is contained in
4332 http://www.microsoft.com/workshop/prog/security/csa/certenr3.exe. It comes
4333 with an README file which explains the available functions. It is labeled
4334 beta but every CA seems to use it anyway. The license.txt allows you the
4335 usage for your own purposes (as far as I understood) and a somehow limited
4338 The two functions of main interest are GenerateKeyPair and AcceptCredentials.
4339 For complete explanation of all possible parameters see the README file. Here
4340 are only minimal required parameters and their values.
4342 GenerateKeyPair(sessionID, FASLE, szName, 0, "ClientAuth", TRUE, FALSE, 1)
4343 - sessionID is a (locally to that computer) unique string to correlate the
4344 generated key pair with a cert installed later.
4345 - szName is the DN of the form "C=DE; S=Thueringen; L=Ilmenau; CN=Holger
4346 Reif; 1.2.840.113549.1.9.1=reif@prakinf.tu-ilmenau.de". Note that S is the
4347 abreviation for StateOrProvince. The recognized abreviation include CN, O, C,
4348 OU, G, I, L, S, T. If the abreviation is unknown (eg. for PKCS#9 email addr)
4349 you need to use the full object identifier. The starting point for searching
4350 them could be crypto/objects.h since all OIDs know to SSLeay are listed
4352 - note: the possible ninth parameter which should give a default name to the
4353 certificate storage location doesn't seem to work. Changes to the constant
4354 values in the call above doesn't seem to make sense. You can't generate
4355 PKCS#10 extensions with that function.
4357 The result of GenerateKeyPair is the base64 encoded PKCS#10 request. However
4358 it has a little strange format that SSLeay doesn't accept. (BTW I feel the
4359 decision of rejecting that format as standard conforming.) It looks like
4361 1st line with 76 chars
4362 2nd line with 76 chars
4364 (n-2)th line with 76 chars
4365 (n-1)th line contains a multiple of 4 chars less then 76 (possible
4367 (n)th line has zero or 4 chars (then with 1 or 2 equal signs - the
4368 original text's lenght wasn'T a multiple of 3)
4369 The line separator has two chars: 0x0d 0x0a
4371 AcceptCredentials(sessionID, credentials, 0, FALSE)
4372 - sessionID needs to be the same as while generating the key pair
4373 - credentials is the base64 encoded PKCS#7 object containing the cert.
4375 CRL's and CA certs are not required simply just the client cert. (It seems to
4376 me that both are not even checked somehow.) The only format of the base64
4377 encoded object I succesfully used was all characters in a very long string
4378 without line feeds or carriage returns. (Hey, it doesn't matter, only a
4381 The result should be S_OK. For error handling see the example that comes with
4384 A note about ASN.1 character encodings. certenr3.dll seems to know only about
4385 2 of them: UniversalString and PrintableString. First it is definitely wrong
4386 for an email address which is IA5STRING (checked by ssleay's ca). Second
4387 unfortunately MSIE (at least until version 3.02) can't handle UniversalString
4388 correctly - they just blow up you cert store! Therefore ssleay's ca (starting
4389 from version 0.8.0) tries to convert the encodings automatically to IA5STRING
4390 or TeletexString. The beef is it will work only for the latin-1 (western)
4391 charset. Microsoft still has to do abit of homework...
4396 At least you need two steps: generating the key & request and then installing
4397 the certificate. A real world CA would have some more steps involved, eg.
4398 accepting some license. Note that both scripts shown below are just
4399 experimental state without any warrenty!
4401 First how to generate a request. Note that we can't use a static page because
4402 of the sessionID. I generate it from system time plus pid and hope it is
4403 unique enough. Your are free to feed it through md5 to get more impressive
4404 ID's ;-) Then the intended text is read in with sed which inserts the
4407 -----BEGIN ms-enroll.cgi-----
4409 SESSION_ID=`date '+%y%m%d%H%M%S'`$$
4410 echo Content-type: text/html
4412 sed s/template_for_sessId/$SESSION_ID/ <<EOF
4414 <TITLE>Certificate Enrollment Test Page</TITLE>
4418 classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43"
4419 codebase=certenr3.dll
4425 <H2>enrollment for a personal cert</H2>
4426 <BR><HR WIDTH=50%><BR><P>
4427 <FORM NAME="MSIE_Enrollment" ACTION="ms-gencert.cgi" ENCTYPE=x-www-form-
4428 encoded METHOD=POST>
4430 <TR><TD>Country</TD><TD><INPUT NAME="Country" VALUE=""></TD></TR>
4431 <TR><TD>State</TD><TD><INPUT NAME="StateOrProvince" VALUE=""></TD></TR>
4432 <TR><TD>Location</TD><TD><INPUT NAME="Location" VALUE=""></TD></TR>
4433 <TR><TD>Organization</TD><TD><INPUT NAME="Organization"
4435 <TR><TD>Organizational Unit</TD>
4436 <TD><INPUT NAME="OrganizationalUnit" VALUE=""></TD></TR>
4437 <TR><TD>Name</TD><TD><INPUT NAME="CommonName" VALUE=""></TD></TR>
4438 <TR><TD>eMail Address</TD>
4439 <TD><INPUT NAME="EmailAddress" VALUE=""></TD></TR>
4441 <TD><INPUT TYPE="BUTTON" NAME="submit" VALUE="Beantragen"></TD></TR>
4443 <INPUT TYPE="hidden" NAME="SessionId" VALUE="template_for_sessId">
4444 <INPUT TYPE="hidden" NAME="Request" VALUE="">
4446 <BR><HR WIDTH=50%><BR><P>
4449 <SCRIPT LANGUAGE=VBS>
4454 Set TheForm = Document.MSIE_Enrollment
4455 sessionId = TheForm.SessionId.value
4457 C = TheForm.Country.value
4458 SP = TheForm.StateOrProvince.value
4459 L = TheForm.Location.value
4460 O = TheForm.Organization.value
4461 OU = TheForm.OrganizationalUnit.value
4462 CN = TheForm.CommonName.value
4463 Email = TheForm.EmailAddress.value
4464 szPurpose = "ClientAuth"
4465 doAcceptanceUINow = FALSE
4470 Call Add_RDN("C", C)
4471 Call Add_RDN("S", SP)
4472 Call Add_RDN("L", L)
4473 Call Add_RDN("O", O)
4474 Call Add_RDN("OU", OU)
4475 Call Add_RDN("CN", CN)
4476 Call Add_RDN("1.2.840.113549.1.9.1", Email)
4481 On Error Resume Next
4482 sz10 = certHelper.GenerateKeyPair(sessionId, _
4483 FALSE, DN, 0, ClientAuth, FASLE, TRUE, 1)_
4484 theError = Err.Number
4486 if (sz10 = Empty OR theError <> 0) Then
4487 sz = "The error '" & Hex(theError) & "' occurred." & chr(13) & _
4488 chr(10) & "Your credentials could not be generated."
4489 result = MsgBox(sz, 0, "Credentials Enrollment")
4492 TheForm.Request.value = sz10
4497 Sub Add_RDN(sn, value)
4498 if (value <> "") then
4502 DN = DN & sn & "=" & value
4509 -----END ms-enroll.cgi-----
4511 Second, how to extract the request and feed the certificate back? We need to
4512 "normalize" the base64 encoding of the PKCS#10 format which means
4513 regenerating the lines and wrapping with BEGIN and END line. This is done by
4514 gawk. The request is taken by ca the normal way. Then the cert needs to be
4515 packed into a PKCS#7 structure (note: the use of a CRL is necessary for
4516 crl2pkcs7 as of version 0.6.6. Starting with 0.8.0 it it might probably be
4517 ommited). Finally we need to format the PKCS#7 object and generate the HTML
4518 text. I use two templates to have a clearer script.
4520 1st note: postit2 is slightly modified from a program I found at ncsa's ftp
4521 site. Grab it from http://www.easterngraphics.com/certs/IX9704/postit2.c. You
4522 need utils.c from there too.
4524 2nd note: I'm note quite sure wether the gawk script really handles all
4525 possible inputs for the request right! Today I don't use this construction
4528 3d note: the cert must be of version 3! This could be done with the nsComment
4529 line in ssleay.cnf...
4531 ------BEGIN ms-gencert.cgi-----
4533 FILE="/tmp/"`date '+%y%m%d%H%M%S'-`$$
4536 HOME=`pwd`; export HOME # as ssleay.cnf insists on having such an env var
4537 cd /usr/local/ssl #where demoCA (as named in ssleay.conf) is located
4539 postit2 -s " " -i 0x0d > "$FILE".inp # process the FORM vars
4541 SESSION_ID=`gawk '$1 == "SessionId" { print $2; exit }' "$FILE".inp`
4546 print "-----BEGIN CERTIFICATE REQUEST-----"; \
4551 if (length($2) == 72) print($2); \
4556 if (req_seen == 1) { \
4557 if (length($1) >= 72) print($1); \
4558 else if (length(lastline) < 72) { \
4560 print (lastline,$1); \
4566 print "-----END CERTIFICATE REQUEST-----"; \
4567 }' > "$FILE".pem < "$FILE".inp
4569 ssleay ca -batch -in "$FILE".pem -key passwd -out "$FILE".out
4570 ssleay crl2pkcs7 -certfile "$FILE".out -out "$FILE".pkcs7 -in demoCA/crl.pem
4572 sed s/template_for_sessId/$SESSION_ID/ <ms-enroll2a.html >"$FILE".cert
4573 /usr/local/bin/gawk \
4576 dq = sprintf("%c",34); \
4578 $0 ~ "PKCS7" { next; } \
4580 print dq$0dq" & _"; \
4581 }' <"$FILE".pkcs7 >> "$FILE".cert
4582 cat ms-enroll2b.html >>"$FILE".cert
4584 echo Content-type: text/html
4585 echo Content-length: `wc -c "$FILE".cert`
4589 -----END ms-gencert.cgi-----
4591 ----BEGIN ms-enroll2a.html----
4592 <HTML><HEAD><TITLE>Certificate Acceptance Test Page</TITLE></HEAD><BODY>
4595 classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43"
4596 codebase=certenr3.dll
4602 <H2>Your personal certificate</H2>
4603 <BR><HR WIDTH=50%><BR><P>
4605 <P><INPUT TYPE=BUTTON VALUE="Nimm mich!" NAME="InstallCert">
4607 <BR><HR WIDTH=50%><BR>
4609 <SCRIPT LANGUAGE=VBS>
4610 Sub InstallCert_OnClick
4612 sessionId = "template_for_sessId"
4613 credentials = "" & _
4614 ----END ms-enroll2a.html----
4616 ----BEGIN ms-enroll2b.html----
4618 On Error Resume Next
4619 result = certHelper.AcceptCredentials(sessionId, credentials, 0,
4621 if (IsEmpty(result)) Then
4622 sz = "The error '" & Err.Number & "' occurred." & chr(13) &
4623 chr(10) & "This Digital ID could not be registered."
4624 msgOut = MsgBox(sz, 0, "Credentials Registration Error")
4625 navigate "error.html"
4627 sz = "Digital ID successfully registered."
4628 msgOut = MsgBox(sz, 0, "Credentials Registration")
4629 navigate "success.html"
4636 ----END ms-enroll2b.html----
4638 4.) What do do with the cert?
4639 -----------------------------
4641 The cert is visible (without restarting MSIE) under the following menu:
4642 View->Options->Security->Personal certs. You can examine it's contents at
4645 To use it for client authentication you need to use SSL3.0 (fortunately
4646 SSLeay supports it with 0.8.0). Furthermore MSIE is told to only supports a
4647 kind of automatic selection of certs (I personally wasn't able to test it
4648 myself). But there is a requirement that the issuer of the server cert and
4649 the issuer of the client cert needs to be the same (according to a developer
4650 from MS). Which means: you need may more then one cert to talk to all
4653 I'm sure we will get a bit more experience after ApacheSSL is available for
4657 I hope you enjoyed reading and that in future questions on this topic will
4658 rarely appear on ssl-users@moncom.com ;-)
4660 Ilmenau, 9th of June 1997
4661 Holger Reif <reif@prakinf.tu-ilmenau.de>
4663 read you later - Holger Reif
4664 ---------------------------------------- Signaturprojekt Deutsche Einheit
4665 TU Ilmenau - Informatik - Telematik (Verdamp lang her)
4666 Holger.Reif@PrakInf.TU-Ilmenau.DE Alt wie ein Baum werden, um ueber
4667 http://Remus.PrakInf.TU-Ilmenau.DE/Reif/ alle 7 Bruecken gehen zu koennen
4670 ==== ns-ca.doc ========================================================
4672 The following documentation was supplied by Jeff Barber, who provided the
4673 patch to the CA program to add this functionality.
4677 Jeff Barber Email: jeffb@issl.atl.hp.com
4679 Hewlett Packard Phone: (404) 648-9503
4680 Internet and System Security Lab Fax: (404) 648-9516
4683 ---------------------cut /\ here for ns-ca.doc ------------------------------
4685 This document briefly describes how to use SSLeay to implement a
4686 certificate authority capable of dynamically serving up client
4687 certificates for version 3.0 beta 5 (and presumably later) versions of
4688 the Netscape Navigator. Before describing how this is done, it's
4689 important to understand a little about how the browser implements its
4690 client certificate support. This is documented in some detail in the
4691 URLs based at <URL:http://home.netscape.com/eng/security/certs.html>.
4692 Here's a brief overview:
4694 - The Navigator supports a new HTML tag "KEYGEN" which will cause
4695 the browser to generate an RSA key pair when you submit a form
4696 containing the tag. The public key, along with an optional
4697 challenge (supposedly provided for use in certificate revocation
4698 but I don't use it) is signed, DER-encoded, base-64 encoded
4699 and sent to the web server as the value of the variable
4700 whose NAME is provided in the KEYGEN tag. The private key is
4701 stored by the browser in a local key database.
4703 This "Signed Public Key And Challenge" (SPKAC) arrives formatted
4704 into 64 character lines (which are of course URL-encoded when
4705 sent via HTTP -- i.e. spaces, newlines and most punctuatation are
4706 encoded as "%HH" where HH is the hex equivalent of the ASCII code).
4707 Note that the SPKAC does not contain the other usual attributes
4708 of a certificate request, especially the subject name fields.
4709 These must be otherwise encoded in the form for submission along
4712 - Either immediately (in response to this form submission), or at
4713 some later date (a real CA will probably verify your identity in
4714 some way before issuing the certificate), a web server can send a
4715 certificate based on the public key and other attributes back to
4716 the browser by encoding it in DER (the binary form) and sending it
4717 to the browser as MIME type:
4718 "Content-type: application/x-x509-user-cert"
4720 The browser uses the public key encoded in the certificate to
4721 associate the certificate with the appropriate private key in
4722 its local key database. Now, the certificate is "installed".
4724 - When a server wants to require authentication based on client
4725 certificates, it uses the right signals via the SSL protocol to
4726 trigger the Navigator to ask you which certificate you want to
4727 send. Whether the certificate is accepted is dependent on CA
4728 certificates and so forth installed in the server and is beyond
4729 the scope of this document.
4732 Now, here's how the SSLeay package can be used to provide client
4735 - You prepare a file for input to the SSLeay ca application.
4736 The file contains a number of "name = value" pairs that identify
4737 the subject. The names here are the same subject name component
4738 identifiers used in the CA section of the lib/ssleay.conf file,
4739 such as "emailAddress", "commonName" "organizationName" and so
4740 forth. Both the long version and the short version (e.g. "Email",
4741 "CN", "O") can be used.
4743 One more name is supported: this one is "SPKAC". Its value
4744 is simply the value of the base-64 encoded SPKAC sent by the
4745 browser (with all the newlines and other space charaters
4746 removed -- and newline escapes are NOT supported).
4748 [ As of SSLeay 0.6.4, multiple lines are supported.
4749 Put a \ at the end of each line and it will be joined with the
4750 previous line with the '\n' removed - eay ]
4752 Here's a sample input file:
4756 O = Some Organization, Inc.
4757 OU = Netscape Compatibility Group
4759 Email = jxdoe@someorg.com
4760 SPKAC = MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwmk6FMJ4uAVIYbcvIOx5+bDGTfvL8X5gE+R67ccMk6rCSGbVQz2cetyQtnI+VIs0NwdD6wjuSuVtVFbLoHonowIDAQABFgAwDQYJKoZIhvcNAQEEBQADQQBFZDUWFl6BJdomtN1Bi53mwijy1rRgJ4YirF15yBEDM3DjAQkKXHYOIX+qpz4KXKnl6EYxTnGSFL5wWt8X2iyx
4762 - You execute the ca command (either from a CGI program run out of
4763 the web server, or as a later manual task) giving it the above
4764 file as input. For example, if the file were named /tmp/cert.req,
4766 $SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert
4768 The output is in DER format (binary) if a -out argument is
4769 provided, as above; otherwise, it's in the PEM format (base-64
4770 encoded DER). Also, the "-batch" switch is implied by the
4771 "-spkac" so you don't get asked whether to complete the signing
4772 (probably it shouldn't work this way but I was only interested
4773 in hacking together an online CA that could be used for issuing
4776 The "-spkac" capability doesn't support multiple files (I think).
4778 Any CHALLENGE provided in the SPKAC is simply ignored.
4780 The interactions between the identification fields you provide
4781 and those identified in your lib/ssleay.conf are the same as if
4782 you did an ordinary "ca -in infile -out outfile" -- that is, if
4783 something is marked as required in the ssleay.conf file and it
4784 isn't found in the -spkac file, the certificate won't be issued.
4786 - Now, you pick up the output from /tmp/cert and pass it back to
4787 the Navigator prepending the Content-type string described earlier.
4789 - In order to run the ca command out of a CGI program, you must
4790 provide a password to decrypt the CA's private key. You can
4791 do this by using "echo MyKeyPassword | $SSLDIR/bin/ca ..."
4792 I think there's a way to not encrypt the key file in the first
4793 place, but I didn't see how to do that, so I made a small change
4794 to the library that allows the password to be accepted from a pipe.
4795 Either way is UTTERLY INSECURE and a real CA would never do that.
4797 [ You can use the 'ssleay rsa' command to remove the password
4798 from the private key, or you can use the '-key' option to the
4799 ca command to specify the decryption key on the command line
4800 or use the -nodes option when generating the key.
4801 ca will try to clear the command line version of the password
4802 but for quite a few operating systems, this is not possible.
4805 So, what do you have to do to make use of this stuff to create an online
4806 demo CA capability with SSLeay?
4808 1 Create an HTML form for your users. The form should contain
4809 fields for all of the required or optional fields in ssleay.conf.
4810 The form must contain a KEYGEN tag somewhere with at least a NAME
4813 2 Create a CGI program to process the form input submitted by the
4814 browser. The CGI program must URL-decode the variables and create
4815 the file described above, containing subject identification info
4816 as well as the SPKAC block. It should then run the the ca program
4817 with the -spkac option. If it works (check the exit status),
4818 return the new certificate with the appropriate MIME type. If not,
4819 return the output of the ca command with MIME type "text/plain".
4821 3 Set up your web server to accept connections signed by your demo
4822 CA. This probably involves obtaining the PEM-encoded CA certificate
4823 (ordinarily in $SSLDIR/CA/cacert.pem) and installing it into a
4824 server database. See your server manual for instructions.
4827 ==== obj.doc ========================================================
4831 As part of my Crypto library, I found I required a method of identifying various
4832 objects. These objects normally had 3 different values associated with
4833 them, a short text name, a long (or lower case) text name, and an
4834 ASN.1 Object Identifier (which is a sequence of numbers).
4835 This library contains a static list of objects and functions to lookup
4836 according to one type and to return the other types.
4838 To use these routines, 'Object.h' needs to be included.
4840 For each supported object, #define entries are defined as follows
4841 #define SN_Algorithm "Algorithm"
4842 #define LN_algorithm "algorithm"
4843 #define NID_algorithm 38
4844 #define OBJ_algorithm 1L,3L,14L,3L,2L
4846 SN_ stands for short name.
4847 LN_ stands for either long name or lowercase name.
4848 NID_ stands for Numeric ID. I each object has a unique NID and this
4849 should be used internally to identify objects.
4850 OBJ_ stands for ASN.1 Object Identifier or ASN1_OBJECT as defined in the
4851 ASN1 routines. These values are used in ASN1 encoding.
4853 The following functions are to be used to return pointers into a static
4854 definition of these types. What this means is "don't try to free() any
4855 pointers returned from these functions.
4857 ASN1_OBJECT *OBJ_nid2obj(
4859 Return the ASN1_OBJECT that corresponds to a NID of n.
4863 Return the long/lower case name of the object represented by the
4868 Return the short name for the object represented by the NID of n.
4870 ASN1_OBJECT *OBJ_dup(
4872 Duplicate and return a new ASN1_OBJECT that is the same as the
4877 Given ASN1_OBJECT o, return the NID that corresponds.
4881 Given the long/lower case name 's', return the NID of the object.
4885 Given the short name 's', return the NID of the object.
4893 Since I have come across a few platforms that do not have the
4894 bsearch() function, OBJ_bsearch is my version of that function.
4895 Feel free to use this function, but you may as well just use the
4896 normal system bsearch(3) if it is present. This version also
4897 has tolerance of being passed NULL pointers.
4899 ==== keys ===========================================================
4909 valid DSA pkey types
4915 valid RSA pkey types
4919 NID_dsaWithSHA NID_dsaWithSHA DSA SHA
4920 NID_dsa NID_dsaWithSHA1 DSA SHA1
4921 NID_md2 NID_md2WithRSAEncryption RSA-pkcs1 MD2
4922 NID_md5 NID_md5WithRSAEncryption RSA-pkcs1 MD5
4923 NID_mdc2 NID_mdc2WithRSA RSA-none MDC2
4924 NID_ripemd160 NID_ripemd160WithRSA RSA-pkcs1 RIPEMD160
4925 NID_sha NID_shaWithRSAEncryption RSA-pkcs1 SHA
4926 NID_sha1 NID_sha1WithRSAEncryption RSA-pkcs1 SHA1
4928 ==== rand.doc ========================================================
4930 My Random number library.
4932 These routines can be used to generate pseudo random numbers and can be
4933 used to 'seed' the pseudo random number generator (RNG). The RNG make no
4934 effort to reproduce the same random number stream with each execution.
4935 Various other routines in the SSLeay library 'seed' the RNG when suitable
4936 'random' input data is available. Read the section at the end for details
4937 on the design of the RNG.
4942 This routine puts 'num' random bytes into 'buf'. One should make
4943 sure RAND_seed() has been called before using this routine.
4948 This routine adds more 'seed' data the RNG state. 'num' bytes
4949 are added to the RNG state, they are taken from 'buf'. This
4950 routine can be called with sensitive data such as user entered
4951 passwords. This sensitive data is in no way recoverable from
4952 the RAND library routines or state. Try to pass as much data
4953 from 'random' sources as possible into the RNG via this function.
4954 Also strongly consider using the RAND_load_file() and
4955 RAND_write_file() routines.
4957 void RAND_cleanup();
4958 When a program has finished with the RAND library, if it so
4959 desires, it can 'zero' all RNG state.
4961 The following 3 routines are convenience routines that can be used to
4962 'save' and 'restore' data from/to the RNG and it's state.
4963 Since the more 'random' data that is feed as seed data the better, why not
4964 keep it around between executions of the program? Of course the
4965 application should pass more 'random' data in via RAND_seed() and
4966 make sure no-one can read the 'random' data file.
4968 char *RAND_file_name(
4971 This routine returns a 'default' name for the location of a 'rand'
4972 file. The 'rand' file should keep a sequence of random bytes used
4973 to initialise the RNG. The filename is put in 'buf'. Buf is 'size'
4974 bytes long. Buf is returned if things go well, if they do not,
4975 NULL is returned. The 'rand' file name is generated in the
4976 following way. First, if there is a 'RANDFILE' environment
4977 variable, it is returned. Second, if there is a 'HOME' environment
4978 variable, $HOME/.rand is returned. Third, NULL is returned. NULL
4979 is also returned if a buf would overflow.
4984 This function 'adds' the 'file' into the RNG state. It does this by
4985 doing a RAND_seed() on the value returned from a stat() system call
4986 on the file and if 'number' is non-zero, upto 'number' bytes read
4987 from the file. The number of bytes passed to RAND_seed() is returned.
4989 int RAND_write_file(
4991 RAND_write_file() writes N random bytes to the file 'file', where
4992 N is the size of the internal RND state (currently 1k).
4993 This is a suitable method of saving RNG state for reloading via
4996 What follows is a description of this RNG and a description of the rational
4999 It should be noted that this RNG is intended to be used to generate
5000 'random' keys for various ciphers including generation of DH and RSA keys.
5002 It should also be noted that I have just created a system that I am happy with.
5003 It may be overkill but that does not worry me. I have not spent that much
5004 time on this algorithm so if there are glaring errors, please let me know.
5005 Speed has not been a consideration in the design of these routines.
5007 First up I will state the things I believe I need for a good RNG.
5008 1) A good hashing algorithm to mix things up and to convert the RNG 'state'
5010 2) An initial source of random 'state'.
5011 3) The state should be very large. If the RNG is being used to generate
5012 4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum).
5013 If your RNG state only has 128 bits, you are obviously limiting the
5014 search space to 128 bits, not 2048. I'm probably getting a little
5015 carried away on this last point but it does indicate that it may not be
5016 a bad idea to keep quite a lot of RNG state. It should be easier to
5017 break a cipher than guess the RNG seed data.
5018 4) Any RNG seed data should influence all subsequent random numbers
5019 generated. This implies that any random seed data entered will have
5020 an influence on all subsequent random numbers generated.
5021 5) When using data to seed the RNG state, the data used should not be
5022 extractable from the RNG state. I believe this should be a
5023 requirement because one possible source of 'secret' semi random
5024 data would be a private key or a password. This data must
5025 not be disclosed by either subsequent random numbers or a
5026 'core' dump left by a program crash.
5027 6) Given the same initial 'state', 2 systems should deviate in their RNG state
5028 (and hence the random numbers generated) over time if at all possible.
5029 7) Given the random number output stream, it should not be possible to determine
5030 the RNG state or the next random number.
5033 The algorithm is as follows.
5035 There is global state made up of a 1023 byte buffer (the 'state'), a
5036 working message digest ('md') and a counter ('count').
5038 Whenever seed data is added, it is inserted into the 'state' as
5040 The input is chopped up into units of 16 bytes (or less for
5041 the last block). Each of these blocks is run through the MD5
5042 message digest. The data passed to the MD5 digest is the
5043 current 'md', the same number of bytes from the 'state'
5044 (the location determined by in incremented looping index) as
5045 the current 'block' and the new key data 'block'. The result
5046 of this is kept in 'md' and also xored into the 'state' at the
5047 same locations that were used as input into the MD5.
5048 I believe this system addresses points 1 (MD5), 3 (the 'state'),
5049 4 (via the 'md'), 5 (by the use of MD5 and xor).
5051 When bytes are extracted from the RNG, the following process is used.
5052 For each group of 8 bytes (or less), we do the following,
5053 Input into MD5, the top 8 bytes from 'md', the byte that are
5054 to be overwritten by the random bytes and bytes from the
5055 'state' (incrementing looping index). From this digest output
5056 (which is kept in 'md'), the top (upto) 8 bytes are
5057 returned to the caller and the bottom (upto) 8 bytes are xored
5059 Finally, after we have finished 'generation' random bytes for the
5060 called, 'count' (which is incremented) and 'md' are fed into MD5 and
5061 the results are kept in 'md'.
5062 I believe the above addressed points 1 (use of MD5), 6 (by
5063 hashing into the 'state' the 'old' data from the caller that
5064 is about to be overwritten) and 7 (by not using the 8 bytes
5065 given to the caller to update the 'state', but they are used
5068 So of the points raised, only 2 is not addressed, but sources of
5069 random data will always be a problem.
5072 ==== rc2.doc ========================================================
5076 RC2 is a block cipher that operates on 64bit (8 byte) quantities. It
5077 uses variable size key, but 128bit (16 byte) key would normally be considered
5078 good. It can be used in all the modes that DES can be used. This
5079 library implements the ecb, cbc, cfb64, ofb64 modes.
5081 I have implemented this library from an article posted to sci.crypt on
5082 11-Feb-1996. I personally don't know how far to trust the RC2 cipher.
5083 While it is capable of having a key of any size, not much reseach has
5084 publically been done on it at this point in time (Apr-1996)
5085 since the cipher has only been public for a few months :-)
5086 It is of a similar speed to DES and IDEA, so unless it is required for
5087 meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable
5088 to stick to IDEA, or for the paranoid, Tripple DES.
5090 Mind you, having said all that, I should mention that I just read alot and
5091 implement ciphers, I'm a 'babe in the woods' when it comes to evaluating
5094 For all calls that have an 'input' and 'output' variables, they can be the
5097 This library requires the inclusion of 'rc2.h'.
5099 All of the encryption functions take what is called an RC2_KEY as an
5100 argument. An RC2_KEY is an expanded form of the RC2 key.
5101 For all modes of the RC2 algorithm, the RC2_KEY used for
5102 decryption is the same one that was used for encryption.
5104 The define RC2_ENCRYPT is passed to specify encryption for the functions
5105 that require an encryption/decryption flag. RC2_DECRYPT is passed to
5108 Please note that any of the encryption modes specified in my DES library
5109 could be used with RC2. I have only implemented ecb, cbc, cfb64 and
5110 ofb64 for the following reasons.
5111 - ecb is the basic RC2 encryption.
5112 - cbc is the normal 'chaining' form for block ciphers.
5113 - cfb64 can be used to encrypt single characters, therefore input and output
5114 do not need to be a multiple of 8.
5115 - ofb64 is similar to cfb64 but is more like a stream cipher, not as
5116 secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
5117 - If you want triple RC2, thats 384 bits of key and you must be totally
5118 obsessed with security. Still, if you want it, it is simple enough to
5119 copy the function from the DES library and change the des_encrypt to
5120 RC2_encrypt; an exercise left for the paranoid reader :-).
5122 The functions are as follows:
5129 RC2_set_key converts an 'len' byte key into a RC2_KEY.
5130 A 'ks' is an expanded form of the 'key' which is used to
5131 perform actual encryption. It can be regenerated from the RC2 key
5132 so it only needs to be kept when encryption or decryption is about
5133 to occur. Don't save or pass around RC2_KEY's since they
5134 are CPU architecture dependent, 'key's are not. RC2 is an
5135 interesting cipher in that it can be used with a variable length
5136 key. 'len' is the length of 'key' to be used as the key.
5137 A 'len' of 16 is recomended. The 'bits' argument is an
5138 interesting addition which I only found out about in Aug 96.
5139 BSAFE uses this parameter to 'limit' the number of bits used
5140 for the key. To use the 'key' unmodified, set bits to 1024.
5141 This is what old versions of my RC2 library did (SSLeay 0.6.3).
5142 RSAs BSAFE library sets this parameter to be 128 if 128 bit
5143 keys are being used. So to be compatable with BSAFE, set it
5144 to 128, if you don't want to reduce RC2's key length, leave it
5148 unsigned long *data,
5151 This is the RC2 encryption function that gets called by just about
5152 every other RC2 routine in the library. You should not use this
5153 function except to implement 'modes' of RC2. I say this because the
5154 functions that call this routine do the conversion from 'char *' to
5155 long, and this needs to be done to make sure 'non-aligned' memory
5156 access do not occur.
5157 Data is a pointer to 2 unsigned long's and key is the
5158 RC2_KEY to use. Encryption or decryption is indicated by 'encrypt'.
5159 which can have the values RC2_ENCRYPT or RC2_DECRYPT.
5161 void RC2_ecb_encrypt(
5166 This is the basic Electronic Code Book form of RC2 (in DES this
5167 mode is called Electronic Code Book so I'm going to use the term
5169 Input is encrypted into output using the key represented by
5170 key. Depending on the encrypt, encryption or
5171 decryption occurs. Input is 8 bytes long and output is 8 bytes.
5173 void RC2_cbc_encrypt(
5178 unsigned char *ivec,
5180 This routine implements RC2 in Cipher Block Chaining mode.
5181 Input, which should be a multiple of 8 bytes is encrypted
5182 (or decrypted) to output which will also be a multiple of 8 bytes.
5183 The number of bytes is in length (and from what I've said above,
5184 should be a multiple of 8). If length is not a multiple of 8, bad
5185 things will probably happen. ivec is the initialisation vector.
5186 This function updates iv after each call so that it can be passed to
5187 the next call to RC2_cbc_encrypt().
5189 void RC2_cfb64_encrypt(
5194 unsigned char *ivec,
5197 This is one of the more useful functions in this RC2 library, it
5198 implements CFB mode of RC2 with 64bit feedback.
5199 This allows you to encrypt an arbitrary number of bytes,
5200 you do not require 8 byte padding. Each call to this
5201 routine will encrypt the input bytes to output and then update ivec
5202 and num. Num contains 'how far' we are though ivec.
5203 'Encrypt' is used to indicate encryption or decryption.
5204 CFB64 mode operates by using the cipher to generate a stream
5205 of bytes which is used to encrypt the plain text.
5206 The cipher text is then encrypted to generate the next 64 bits to
5207 be xored (incrementally) with the next 64 bits of plain
5208 text. As can be seen from this, to encrypt or decrypt,
5209 the same 'cipher stream' needs to be generated but the way the next
5210 block of data is gathered for encryption is different for
5211 encryption and decryption.
5213 void RC2_ofb64_encrypt(
5218 unsigned char *ivec,
5220 This functions implements OFB mode of RC2 with 64bit feedback.
5221 This allows you to encrypt an arbitrary number of bytes,
5222 you do not require 8 byte padding. Each call to this
5223 routine will encrypt the input bytes to output and then update ivec
5224 and num. Num contains 'how far' we are though ivec.
5225 This is in effect a stream cipher, there is no encryption or
5228 For reading passwords, I suggest using des_read_pw_string() from my DES library.
5229 To generate a password from a text string, I suggest using MD5 (or MD2) to
5230 produce a 16 byte message digest that can then be passed directly to
5234 For more information about the specific RC2 modes in this library
5235 (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
5236 documentation on my DES library. What is said about DES is directly
5240 ==== rc4.doc ========================================================
5243 RC4 is a stream cipher that operates on a byte stream. It can be used with
5244 any length key but I would recommend normally using 16 bytes.
5246 This library requires the inclusion of 'rc4.h'.
5248 The RC4 encryption function takes what is called an RC4_KEY as an argument.
5249 The RC4_KEY is generated by the RC4_set_key function from the key bytes.
5251 RC4, being a stream cipher, does not have an encryption or decryption mode.
5252 It produces a stream of bytes that the input stream is xor'ed against and
5253 so decryption is just a case of 'encrypting' again with the same key.
5255 I have only put in one 'mode' for RC4 which is the normal one. This means
5256 there is no initialisation vector and there is no feedback of the cipher
5257 text into the cipher. This implies that you should not ever use the
5258 same key twice if you can help it. If you do, you leave yourself open to
5259 known plain text attacks; if you know the plain text and
5260 corresponding cipher text in one message, all messages that used the same
5261 key can have the cipher text decoded for the corresponding positions in the
5264 The main positive feature of RC4 is that it is a very fast cipher; about 4
5265 times faster that DES. This makes it ideally suited to protocols where the
5266 key is randomly chosen, like SSL.
5268 The functions are as follows:
5273 unsigned char *data);
5274 This function initialises the RC4_KEY structure with the key passed
5275 in 'data', which is 'len' bytes long. The key data can be any
5276 length but 16 bytes seems to be a good number.
5282 unsigned char *out);
5283 Do the actual RC4 encryption/decryption. Using the 'key', 'len'
5284 bytes are transformed from 'in' to 'out'. As mentioned above,
5285 decryption is the operation as encryption.
5287 ==== ref.doc ========================================================
5289 I have lots more references etc, and will update this list in the future,
5293 SSL The SSL Protocol - from Netscapes.
5295 RC4 Newsgroups: sci.crypt
5296 From: sterndark@netcom.com (David Sterndark)
5297 Subject: RC4 Algorithm revealed.
5298 Message-ID: <sternCvKL4B.Hyy@netcom.com>
5300 RC2 Newsgroups: sci.crypt
5301 From: pgut01@cs.auckland.ac.nz (Peter Gutmann)
5302 Subject: Specification for Ron Rivests Cipher No.2
5303 Message-ID: <4fk39f$f70@net.auckland.ac.nz>
5305 MD2 RFC1319 The MD2 Message-Digest Algorithm
5306 MD5 RFC1321 The MD5 Message-Digest Algorithm
5309 RFC1421 Privacy Enhancement for Internet Electronic Mail: Part I
5310 RFC1422 Privacy Enhancement for Internet Electronic Mail: Part II
5311 RFC1423 Privacy Enhancement for Internet Electronic Mail: Part III
5312 RFC1424 Privacy Enhancement for Internet Electronic Mail: Part IV
5314 RSA and various standard encoding
5315 PKCS#1 RSA Encryption Standard
5316 PKCS#5 Password-Based Encryption Standard
5317 PKCS#7 Cryptographic Message Syntax Standard
5318 A Layman's Guide to a Subset of ASN.1, BER, and DER
5319 An Overview of the PKCS Standards
5320 Some Examples of the PKCS Standards
5322 IDEA Chapter 3 The Block Cipher IDEA
5324 RSA, prime number generation and bignum algorithms
5325 Introduction To Algorithms,
5326 Thomas Cormen, Charles Leiserson, Ronald Rivest,
5327 Section 29 Arithmetic Circuits
5328 Section 33 Number-Theoretic Algorithms
5330 Fast Private Key algorithm
5331 Fast Decipherment Algorithm for RSA Public-Key Cryptosystem
5332 J.-J. Quisquater and C. Couvreur, Electronics Letters,
5333 14th October 1982, Vol. 18 No. 21
5335 Prime number generation and bignum algorithms.
5338 ==== rsa.doc ========================================================
5340 The RSA encryption and utility routines.
5342 The RSA routines are built on top of a big number library (the BN library).
5343 There are support routines in the X509 library for loading and manipulating
5344 the various objects in the RSA library. When errors are returned, read
5345 about the ERR library for how to access the error codes.
5347 All RSA encryption is done according to the PKCS-1 standard which is
5348 compatible with PEM and RSAref. This means that any values being encrypted
5349 must be less than the size of the modulus in bytes, minus 10, bytes long.
5351 This library uses RAND_bytes()() for it's random data, make sure to feed
5352 RAND_seed() with lots of interesting and varied data before using these
5355 The RSA library has one specific data type, the RSA structure.
5356 It is composed of 8 BIGNUM variables (see the BN library for details) and
5357 can hold either a private RSA key or a public RSA key.
5358 Some RSA libraries have different structures for public and private keys, I
5359 don't. For my libraries, a public key is determined by the fact that the
5360 RSA->d value is NULL. These routines will operate on any size RSA keys.
5361 While I'm sure 4096 bit keys are very very secure, they take a lot longer
5362 to process that 1024 bit keys :-).
5364 The function in the RSA library are as follows.
5367 This function creates a new RSA object. The sub-fields of the RSA
5368 type are also malloced so you should always use this routine to
5369 create RSA variables.
5373 This function 'frees' an RSA structure. This routine should always
5374 be used to free the RSA structure since it will also 'free' any
5375 sub-fields of the RSA type that need freeing.
5379 This function returns the size of the RSA modulus in bytes. Why do
5380 I need this you may ask, well the reason is that when you encrypt
5381 with RSA, the output string will be the size of the RSA modulus.
5382 So the output for the RSA_encrypt and the input for the RSA_decrypt
5383 routines need to be RSA_size() bytes long, because this is how many
5386 For the following 4 RSA encryption routines, it should be noted that
5387 RSA_private_decrypt() should be used on the output from
5388 RSA_public_encrypt() and RSA_public_decrypt() should be used on
5389 the output from RSA_private_encrypt().
5391 int RSA_public_encrypt(
5396 This function implements RSA public encryption, the rsa variable
5397 should be a public key (but can be a private key). 'from_len'
5398 bytes taken from 'from' and encrypted and put into 'to'. 'to' needs
5399 to be at least RSA_size(rsa) bytes long. The number of bytes
5400 written into 'to' is returned. -1 is returned on an error. The
5401 operation performed is
5402 to = from^rsa->e mod rsa->n.
5404 int RSA_private_encrypt(
5409 This function implements RSA private encryption, the rsa variable
5410 should be a private key. 'from_len' bytes taken from
5411 'from' and encrypted and put into 'to'. 'to' needs
5412 to be at least RSA_size(rsa) bytes long. The number of bytes
5413 written into 'to' is returned. -1 is returned on an error. The
5414 operation performed is
5415 to = from^rsa->d mod rsa->n.
5417 int RSA_public_decrypt(
5422 This function implements RSA public decryption, the rsa variable
5423 should be a public key (but can be a private key). 'from_len'
5424 bytes are taken from 'from' and decrypted. The decrypted data is
5425 put into 'to'. The number of bytes encrypted is returned. -1 is
5426 returned to indicate an error. The operation performed is
5427 to = from^rsa->e mod rsa->n.
5429 int RSA_private_decrypt(
5434 This function implements RSA private decryption, the rsa variable
5435 should be a private key. 'from_len' bytes are taken
5436 from 'from' and decrypted. The decrypted data is
5437 put into 'to'. The number of bytes encrypted is returned. -1 is
5438 returned to indicate an error. The operation performed is
5439 to = from^rsa->d mod rsa->n.
5445 Normally you will never use this routine.
5446 This is really an internal function which is called by
5447 RSA_private_encrypt() and RSA_private_decrypt(). It performs
5448 n=n^p mod rsa->n except that it uses the 5 extra variables in the
5449 RSA structure to make this more efficient.
5451 RSA *RSA_generate_key(
5456 This routine is used to generate RSA private keys. It takes
5457 quite a period of time to run and should only be used to
5458 generate initial private keys that should then be stored
5459 for later use. The passed callback function
5460 will be called periodically so that feedback can be given
5461 as to how this function is progressing.
5462 'bits' is the length desired for the modulus, so it would be 1024
5463 to generate a 1024 bit private key.
5464 'e' is the value to use for the public exponent 'e'. Traditionally
5465 it is set to either 3 or 0x10001.
5466 The callback function (if not NULL) is called in the following
5468 when we have generated a suspected prime number to test,
5469 callback(0,num1++,cb_arg). When it passes a prime number test,
5470 callback(1,num2++,cb_arg). When it is rejected as one of
5471 the 2 primes required due to gcd(prime,e value) != 0,
5472 callback(2,num3++,cb_arg). When finally accepted as one
5473 of the 2 primes, callback(3,num4++,cb_arg).
5476 ==== rsaref.doc ========================================================
5478 This package can be compiled to use the RSAref library.
5479 This library is not allowed outside of the USA but inside the USA it is
5480 claimed by RSA to be the only RSA public key library that can be used
5483 There are 2 files, rsaref/rsaref.c and rsaref/rsaref.h that contain the glue
5484 code to use RSAref. These files were written by looking at the PGP
5485 source code and seeing which routines it used to access RSAref.
5486 I have also been sent by some-one a copy of the RSAref header file that
5487 contains the library error codes.
5489 [ Jun 1996 update - I have recently gotten hold of RSAref 2.0 from
5490 South Africa and have been doing some performace tests. ]
5492 They have now been tested against the recently announced RSAEURO
5495 There are 2 ways to use SSLeay and RSAref. First, to build so that
5496 the programs must be linked with RSAref, add '-DRSAref' to CFLAG in the top
5497 level makefile and -lrsaref (or where ever you are keeping RSAref) to
5500 To build a makefile via util/mk1mf.pl to do this, use the 'rsaref' option.
5502 The second method is to build as per normal and link applications with
5503 the RSAglue library. The correct library order would be
5504 cc -o cmd cmd.o -lssl -lRSAglue -lcrypto -lrsaref -ldes
5505 The RSAglue library is built in the rsa directory and is NOT
5506 automatically installed.
5508 Be warned that the RSAEURO library, that is claimed to be compatible
5509 with RSAref contains a different value for the maximum number of bits
5510 supported. This changes structure sizes and so if you are using
5511 RSAEURO, change the value of RSAref_MAX_BITS in rsa/rsaref.h
5514 ==== s_mult.doc ========================================================
5516 s_mult is a test program I hacked up on a Sunday for testing non-blocking
5517 IO. It has a select loop at it's centre that handles multiple readers
5520 Try the following command
5521 ssleay s_mult -echo -nbio -ssl -v
5522 echo - sends any sent text back to the sender
5523 nbio - turns on non-blocking IO
5524 ssl - accept SSL connections, default is normal text
5528 In another window, run the following
5529 ssleay s_client -pause </etc/termcap
5531 The pause option puts in a 1 second pause in each read(2)/write(2) call
5532 so the other end will have read()s fail.
5534 ==== session.doc ========================================================
5536 I have just checked over and re-worked the session stuff.
5537 The following brief example will ignore all setup information to do with
5540 Things operate as follows.
5542 The SSL environment has a 'context', a SSL_CTX structure. This holds the
5543 cached SSL_SESSIONS (which can be reused) and the certificate lookup
5544 information. Each SSL structure needs to be associated with a SSL_CTX.
5545 Normally only one SSL_CTX structure is needed per program.
5547 SSL_CTX *SSL_CTX_new(void );
5548 void SSL_CTX_free(SSL_CTX *);
5549 These 2 functions create and destroy SSL_CTX structures
5551 The SSL_CTX has a session_cache_mode which is by default,
5552 in SSL_SESS_CACHE_SERVER mode. What this means is that the library
5553 will automatically add new session-id's to the cache apon sucsessful
5555 If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added
5557 SSL_set_session_cache_mode(ctx,mode) will set the 'mode' and
5558 SSL_get_session_cache_mode(ctx) will get the cache 'mode'.
5560 SSL_SESS_CACHE_OFF - no caching
5561 SSL_SESS_CACHE_CLIENT - only SSL_connect()
5562 SSL_SESS_CACHE_SERVER - only SSL_accept()
5563 SSL_SESS_NO_CACHE_BOTH - Either SSL_accept() or SSL_connect().
5564 If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are
5565 not automatically removed each 255, SSL_connect()s or SSL_accept()s.
5567 By default, apon every 255 successful SSL_connect() or SSL_accept()s,
5568 the cache is flush. Please note that this could be expensive on
5569 a heavily loaded SSL server, in which case, turn this off and
5570 clear the cache of old entries 'manually' (with one of the functions
5571 listed below) every few hours. Perhaps I should up this number, it is hard
5572 to say. Remember, the '255' new calls is just a mechanims to get called
5573 every now and then, in theory at most 255 new session-id's will have been
5574 added but if 100 are added every minute, you would still have
5575 500 in the cache before any would start being flushed (assuming a 3 minute
5578 int SSL_CTX_sess_hits(SSL_CTX *ctx);
5579 int SSL_CTX_sess_misses(SSL_CTX *ctx);
5580 int SSL_CTX_sess_timeouts(SSL_CTX *ctx);
5581 These 3 functions return statistics about the SSL_CTX. These 3 are the
5582 number of session id reuses. hits is the number of reuses, misses are the
5583 number of lookups that failed, and timeouts is the number of cached
5584 entries ignored because they had timeouted.
5586 ctx->new_session_cb is a function pointer to a function of type
5587 int new_session_callback(SSL *ssl,SSL_SESSION *new);
5588 This function, if set in the SSL_CTX structure is called whenever a new
5589 SSL_SESSION is added to the cache. If the callback returns non-zero, it
5590 means that the application will have to do a SSL_SESSION_free()
5591 on the structure (this is
5592 to do with the cache keeping the reference counts correct, without the
5593 application needing to know about it.
5594 The 'active' parameter is the current SSL session for which this connection
5597 void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,int (*cb)());
5598 to set the callback,
5599 int (*cb)() SSL_CTX_sess_get_new_cb(SSL_CTX *ctx)
5600 to get the callback.
5602 If the 'get session' callback is set, when a session id is looked up and
5603 it is not in the session-id cache, this callback is called. The callback is
5605 SSL_SESSION *get_session_callback(unsigned char *sess_id,int sess_id_len,
5608 The get_session_callback is intended to return null if no session id is found.
5609 The reference count on the SSL_SESSION in incremented by the SSL library,
5610 if copy is 1. Otherwise, the reference count is not modified.
5612 void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and
5613 int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback.
5615 These callbacks are basically indended to be used by processes to
5616 send their session-id's to other processes. I currently have not implemented
5617 non-blocking semantics for these callbacks, it is upto the appication
5618 to make the callbacks effiecent if they require blocking (perhaps
5619 by 'saving' them and then 'posting them' when control returns from
5622 LHASH *SSL_CTX_sessions(SSL_CTX *ctx)
5623 This returns the session cache. The lhash strucutre can be accessed for
5624 statistics about the cache.
5626 void lh_stats(LHASH *lh, FILE *out);
5627 void lh_node_stats(LHASH *lh, FILE *out);
5628 void lh_node_usage_stats(LHASH *lh, FILE *out);
5630 can be used to print details about it's activity and current state.
5631 You can also delve directly into the lhash structure for 14 different
5632 counters that are kept against the structure. When I wrote the lhash library,
5633 I was interested in gathering statistics :-).
5634 Have a read of doc/lhash.doc in the SSLeay distribution area for more details
5635 on the lhash library.
5637 Now as mentioned ealier, when a SSL is created, it needs a SSL_CTX.
5638 SSL * SSL_new(SSL_CTX *);
5640 This stores a session. A session is secret information shared between 2
5641 SSL contexts. It will only be created if both ends of the connection have
5642 authenticated their peer to their satisfaction. It basically contains
5643 the information required to use a particular secret key cipher.
5645 To retrieve the SSL_CTX being used by a SSL,
5646 SSL_CTX *SSL_get_SSL_CTX(SSL *s);
5648 Now when a SSL session is established between to programs, the 'session'
5649 information that is cached in the SSL_CTX can me manipulated by the
5650 following functions.
5651 int SSL_set_session(SSL *s, SSL_SESSION *session);
5652 This will set the SSL_SESSION to use for the next SSL_connect(). If you use
5653 this function on an already 'open' established SSL connection, 'bad things
5654 will happen'. This function is meaning-less when used on a ssl strucutre
5655 that is just about to be used in a SSL_accept() call since the
5656 SSL_accept() will either create a new session or retrieve one from the
5659 SSL_SESSION *SSL_get_session(SSL *s);
5660 This will return the SSL_SESSION for the current SSL, NULL if there is
5661 no session associated with the SSL structure.
5663 The SSL sessions are kept in the SSL_CTX in a hash table, to remove a
5665 void SSL_CTX_remove_session(SSL_CTX *,SSL_SESSION *c);
5667 int SSL_CTX_add_session(SSL_CTX *s, SSL_SESSION *c);
5668 SSL_CTX_add_session() returns 1 if the session was already in the cache (so it
5670 Whenever a new session is created via SSL_connect()/SSL_accept(),
5671 they are automatically added to the cache, depending on the session_cache_mode
5672 settings. SSL_set_session()
5673 does not add it to the cache. Just call SSL_CTX_add_session() if you do want the
5674 session added. For a 'client' this would not normally be the case.
5675 SSL_CTX_add_session() is not normally ever used, except for doing 'evil' things
5676 which the next 2 funtions help you do.
5678 int i2d_SSL_SESSION(SSL_SESSION *in,unsigned char **pp);
5679 SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a,unsigned char **pp,long length);
5680 These 2 functions are in the standard ASN1 library form and can be used to
5681 load and save to a byte format, the SSL_SESSION structure.
5682 With these functions, you can save and read these structures to a files or
5683 arbitary byte string.
5684 The PEM_write_SSL_SESSION(fp,x) and PEM_read_SSL_SESSION(fp,x,cb) will
5685 write to a file pointer in base64 encoding.
5687 What you can do with this, is pass session information between separate
5688 processes. Please note, that you will probably also need to modify the
5689 timeout information on the SSL_SESSIONs.
5691 long SSL_get_time(SSL_SESSION *s)
5692 will return the 'time' that the session
5693 was loaded. The timeout is relative to this time. This information is
5694 saved when the SSL_SESSION is converted to binarary but it is stored
5695 in as a unix long, which is rather OS dependant, but easy to convert back.
5697 long SSL_set_time(SSL_SESSION *s,long t) will set the above mentioned time.
5698 The time value is just the value returned from time(3), and should really
5699 be defined by be to be time_t.
5701 long SSL_get_timeout(SSL_SESSION *s);
5702 long SSL_set_timeout(SSL_SESSION *s,long t);
5703 These 2 retrieve and set the timeout which is just a number of secconds
5704 from the 'SSL_get_time()' value. When this time period has elapesed,
5705 the session will no longer be in the cache (well it will actually be removed
5706 the next time it is attempted to be retrieved, so you could 'bump'
5707 the timeout so it remains valid).
5708 The 'time' and 'timeout' are set on a session when it is created, not reset
5709 each time it is reused. If you did wish to 'bump it', just after establishing
5711 SSL_set_time(ssl,time(NULL));
5714 SSL_CTX_set_timeout(SSL_CTX *ctx,unsigned long t) and
5715 SSL_CTX_get_timeout(SSL_CTX *ctx) to manipulate the default timeouts for
5716 all SSL connections created against a SSL_CTX. If you set a timeout in
5717 an SSL_CTX, all new SSL's created will inherit the timeout. It can be over
5718 written by the SSL_set_timeout(SSL *s,unsigned long t) function call.
5719 If you 'set' the timeout back to 0, the system default will be used.
5721 SSL_SESSION *SSL_SESSION_new();
5722 void SSL_SESSION_free(SSL_SESSION *ses);
5723 These 2 functions are used to create and dispose of SSL_SESSION functions.
5724 You should not ever normally need to use them unless you are using
5725 i2d_SSL_SESSION() and/or d2i_SSL_SESSION(). If you 'load' a SSL_SESSION
5726 via d2i_SSL_SESSION(), you will need to SSL_SESSION_free() it.
5727 Both SSL_set_session() and SSL_CTX_add_session() will 'take copies' of the
5728 structure (via reference counts) when it is passed to them.
5730 SSL_CTX_flush_sessions(ctx,time);
5731 The first function will clear all sessions from the cache, which have expired
5732 relative to 'time' (which could just be time(NULL)).
5734 SSL_CTX_flush_sessions(ctx,0);
5735 This is a special case that clears everything.
5737 As a final comment, a 'session' is not enough to establish a new
5738 connection. If a session has timed out, a certificate and private key
5739 need to have been associated with the SSL structure.
5740 SSL_copy_session_id(SSL *to,SSL *from); will copy not only the session
5741 strucutre but also the private key and certificate associated with
5746 So lets play at being a wierd SSL server.
5748 /* setup a context */
5751 /* Lets load some session from binary into the cache, why one would do
5752 * this is not toally clear, but passing between programs does make sense
5753 * Perhaps you are using 4096 bit keys and are happy to keep them
5754 * valid for a week, to avoid the RSA overhead of 15 seconds, I'm not toally
5755 * sure, perhaps this is a process called from an SSL inetd and this is being
5756 * passed to the application. */
5757 session=d2i_SSL_SESSION(....)
5758 SSL_CTX_add_session(ctx,session);
5760 /* Lets even add a session from a file */
5761 session=PEM_read_SSL_SESSION(....)
5762 SSL_CTX_add_session(ctx,session);
5764 /* create a new SSL structure */
5767 /* At this point we want to be able to 'create' new session if
5768 * required, so we need a certificate and RSAkey. */
5769 SSL_use_RSAPrivateKey_file(ssl,...)
5770 SSL_use_certificate_file(ssl,...)
5772 /* Now since we are a server, it make little sence to load a session against
5773 * the ssl strucutre since a SSL_accept() will either create a new session or
5774 * grab an existing one from the cache. */
5776 /* grab a socket descriptor */
5779 /* associated it with the ssl strucutre */
5782 SSL_accept(ssl); /* 'do' SSL using out cert and RSA key */
5784 /* Lets print out the session details or lets save it to a file,
5785 * perhaps with a secret key cipher, so that we can pass it to the FBI
5786 * when they want to decode the session :-). While we have RSA
5787 * this does not matter much but when I do SSLv3, this will allow a mechanism
5788 * for the server/client to record the information needed to decode
5789 * the traffic that went over the wire, even when using Diffie-Hellman */
5790 PEM_write_SSL_SESSION(SSL_get_session(ssl),stdout,....)
5792 Lets 'connect' back to the caller using the same session id.
5796 SSL_set_fd(ssl2,fd2);
5797 SSL_set_session(ssl2,SSL_get_session(ssl));
5800 /* what the hell, lets accept no more connections using this session */
5801 SSL_CTX_remove_session(SSL_get_SSL_CTX(ssl),SSL_get_session(ssl));
5803 /* we could have just as easily used ssl2 since they both are using the
5805 * You will note that both ssl and ssl2 are still using the session, and
5806 * the SSL_SESSION structure will be free()ed when both ssl and ssl2
5807 * finish using the session. Also note that you could continue to initiate
5808 * connections using this session by doing SSL_get_session(ssl) to get the
5809 * existing session, but SSL_accept() will not be able to find it to
5810 * use for incoming connections.
5811 * Of corse, the session will timeout at the far end and it will no
5812 * longer be accepted after a while. The time and timeout are ignored except
5813 * by SSL_accept(). */
5815 /* Since we have had our server running for 10 weeks, and memory is getting
5816 * short, perhaps we should clear the session cache to remove those
5817 * 100000 session entries that have expired. Some may consider this
5818 * a memory leak :-) */
5820 SSL_CTX_flush_sessions(ctx,time(NULL));
5822 /* Ok, after a bit more time we wish to flush all sessions from the cache
5823 * so that all new connections will be authenticated and incure the
5824 * public key operation overhead */
5826 SSL_CTX_flush_sessions(ctx,0);
5828 /* As a final note, to copy everything to do with a SSL, use */
5829 SSL_copy_session_id(SSL *to,SSL *from);
5830 /* as this also copies the certificate and RSA key so new session can
5831 * be established using the same details */
5834 ==== sha.doc ========================================================
5836 The SHA (Secure Hash Algorithm) library.
5837 SHA is a message digest algorithm that can be used to condense an arbitrary
5838 length message down to a 20 byte hash. The functions all need to be passed
5839 a SHA_CTX which is used to hold the SHA context during multiple SHA_Update()
5840 function calls. The normal method of use for this library is as follows
5841 This library contains both SHA and SHA-1 digest algorithms. SHA-1 is
5842 an update to SHA (which should really be called SHA-0 now) which
5843 tweaks the algorithm slightly. The SHA-1 algorithm is used by simply
5844 using SHA1_Init(), SHA1_Update(), SHA1_Final() and SHA1() instead of the
5853 This library requires the inclusion of 'sha.h'.
5855 The functions are as follows:
5859 This function needs to be called to initiate a SHA_CTX structure for
5864 unsigned char *data;
5866 This updates the message digest context being generated with 'len'
5867 bytes from the 'data' pointer. The number of bytes can be any
5873 This function is called when a message digest of the data digested
5874 with SHA_Update() is wanted. The message digest is put in the 'md'
5875 array and is SHA_DIGEST_LENGTH (20) bytes long.
5881 This function performs a SHA_Init(), followed by a SHA_Update()
5882 followed by a SHA_Final() (using a local SHA_CTX).
5883 The resulting digest is put into 'md' if it is not NULL.
5884 Regardless of the value of 'md', the message
5885 digest is returned from the function. If 'md' was NULL, the message
5886 digest returned is being stored in a static structure.
5889 ==== speed.doc ========================================================
5891 To get an idea of the performance of this library, use
5894 perl util/sp-diff.pl file1 file2
5896 will print out the relative differences between the 2 files which are
5897 expected to be the output from the speed program.
5899 The performace of the library is very dependant on the Compiler
5900 quality and various flags used to build.
5904 These are some numbers I did comparing RSAref and SSLeay on a Pentium 100.
5905 [ These numbers are all out of date, as of SSL - 0.6.1 the RSA
5906 operations are about 2 times faster, so check the version number ]
5911 Pentium 100, 32meg, Windows NT Workstation 3.51
5912 linux - gcc v 2.7.0 -O3 -fomit-frame-pointer -m486
5914 Windows NT - Windows NT 3.51 - Visual C++ 4.1 - 586 code + 32bit assember
5915 Windows 3.1 - Windows NT 3.51 - Visual C++ 1.52c - 286 code + 32bit assember
5916 NT Dos Shell- Windows NT 3.51 - Visual C++ 1.52c - 286 code + 16bit assember
5918 Times are how long it takes to do an RSA private key operation.
5921 -------------------------------
5922 SSLeay NT dll 0.042s 0.202s see above
5923 SSLeay linux 0.046s 0.218s Assember inner loops (normal build)
5924 SSLeay linux 0.067s 0.380s Pure C code with BN_LLONG defined
5925 SSLeay W3.1 dll 0.108s 0.478s see above
5926 SSLeay linux 0.109s 0.713s C without BN_LLONG.
5927 RSAref2.0 linux 0.149s 0.936s
5928 SSLeay MS-DOS 0.197s 1.049s see above
5930 486DX66, 32meg, Windows NT Server 3.51
5932 -------------------------------
5933 SSLeay NT dll 0.084s 0.495s <- SSLeay 0.6.3
5934 SSLeay NT dll 0.154s 0.882s
5935 SSLeay W3.1 dll 0.335s 1.538s
5936 SSLeay MS-DOS 0.490s 2.790s
5938 What I find cute is that I'm still faster than RSAref when using standard C,
5939 without using the 'long long' data type :-), %35 faster for 512bit and we
5940 scale up to 3.2 times faster for the 'default linux' build. I should mention
5941 that people should 'try' to use either x86-lnx.s (elf), x86-lnxa.s or
5942 x86-sol.s for any x86 based unix they are building on. The only problems
5943 with be with syntax but the performance gain is quite large, especially for
5944 servers. The code is very simple, you just need to modify the 'header'.
5946 The message is, if you are stuck using RSAref, the RSA performance will be
5947 bad. Considering the code was compiled for a pentium, the 486DX66 number
5948 would indicate 'Use RSAref and turn you Pentium 100 into a 486DX66' :-).
5949 [ As of verson 0.6.1, it would be correct to say 'turn you pentium 100
5950 into a 486DX33' :-) ]
5952 I won't tell people if the DLL's are using RSAref or my stuff if no-one
5957 PS while I know I could speed things up further, I will probably not do
5958 so due to the effort involved. I did do some timings on the
5959 SSLeay bignum format -> RSAref number format conversion that occurs
5960 each time RSAref is used by SSLeay, and the numbers are trivial.
5961 0.00012s a call for 512bit vs 0.149s for the time spent in the function.
5962 0.00018s for 1024bit vs 0.938s. Insignificant.
5963 So the 'way to go', to support faster RSA libraries, if people are keen,
5964 is to write 'glue' code in a similar way that I do for RSAref and send it
5966 My base library still has the advantage of being able to operate on
5967 any size numbers, and is not that far from the performance from the
5968 leaders in the field. (-%30?)
5969 [ Well as of 0.6.1 I am now the leader in the filed on x86 (we at
5970 least very close :-) ]
5972 I suppose I should also mention some other numbers RSAref numbers, again
5975 RSAref linux 830k/s 302k/s 4390k/s
5976 SSLeay linux 855k/s 319k/s 10025k/s
5977 SSLeay NT 1158k/s 410k/s 10470k/s
5978 SSLeay w31 378k/s 143k/s 2383k/s (fully 16bit)
5980 Got to admit that Visual C++ 4.[01] is a damn fine compiler :-)
5982 Eric Young | BOOL is tri-state according to Bill Gates.
5983 AARNet: eay@cryptsoft.com | RTFM Win32 GetMessage().
5988 ==== ssl-ciph.doc ========================================================
5990 This is a quick high level summery of how things work now.
5992 Each SSLv2 and SSLv3 cipher is composed of 4 major attributes plus a few extra
5995 They are 'The key exchange algorithm', which is RSA for SSLv2 but can also
5996 be Diffle-Hellman for SSLv3.
5998 An 'Authenticion algorithm', which can be RSA, Diffle-Helman, DSS or
6005 A cipher can also be an export cipher and is either an SSLv2 or a
6008 To specify which ciphers to use, one can either specify all the ciphers,
6009 one at a time, or use 'aliases' to specify the preference and order for
6012 There are a large number of aliases, but the most importaint are
6013 kRSA, kDHr, kDHd and kEDH for key exchange types.
6015 aRSA, aDSS, aNULL and aDH for authentication
6016 DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers
6017 MD5, SHA0 and SHA1 digests
6019 Now where this becomes interesting is that these can be put together to
6020 specify the order and ciphers you wish to use.
6022 To speed this up there are also aliases for certian groups of ciphers.
6024 SSLv2 - all SSLv2 ciphers
6025 SSLv3 - all SSLv3 ciphers
6026 EXP - all export ciphers
6027 LOW - all low strngth ciphers (no export ciphers, normally single DES)
6028 MEDIUM - 128 bit encryption
6031 These aliases can be joined in a : separated list which specifies to
6032 add ciphers, move them to the current location and delete them.
6034 A simpler way to look at all of this is to use the 'ssleay ciphers -v' command.
6035 The default library cipher spec is
6036 !ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP
6037 which means, first, remove from consideration any ciphers that do not
6038 authenticate. Next up, use ciphers using RC4 and RSA. Next include the HIGH,
6039 MEDIUM and the LOW security ciphers. Finish up by adding all the export
6040 ciphers on the end, then 'pull' all the SSLv2 and export ciphers to
6041 the end of the list.
6044 $ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP'
6046 RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1
6047 RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
6048 EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
6049 EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1
6050 DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1
6051 IDEA-CBC-MD5 SSLv3 Kx=RSA Au=RSA Enc=IDEA(128) Mac=SHA1
6052 EDH-RSA-DES-CBC-SHA SSLv3 Kx=DH Au=RSA Enc=DES(56) Mac=SHA1
6053 EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH Au=DSS Enc=DES(56) Mac=SHA1
6054 DES-CBC-SHA SSLv3 Kx=RSA Au=RSA Enc=DES(56) Mac=SHA1
6055 DES-CBC3-MD5 SSLv2 Kx=RSA Au=RSA Enc=3DES(168) Mac=MD5
6056 DES-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=DES(56) Mac=MD5
6057 IDEA-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=IDEA(128) Mac=MD5
6058 RC2-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC2(128) Mac=MD5
6059 RC4-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
6060 EXP-EDH-RSA-DES-CBC SSLv3 Kx=DH(512) Au=RSA Enc=DES(40) Mac=SHA1 export
6061 EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512) Au=DSS Enc=DES(40) Mac=SHA1 export
6062 EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 export
6063 EXP-RC2-CBC-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
6064 EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
6065 EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
6066 EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
6068 I would recoment people use the 'ssleay ciphers -v "text"'
6069 command to check what they are going to use.
6071 Anyway, I'm falling asleep here so I'll do some more tomorrow.
6075 ==== ssl.doc ========================================================
6077 SSL_CTX_sessions(SSL_CTX *ctx) - the session-id hash table.
6079 /* Session-id cache stats */
6081 SSL_CTX_sess_connect
6082 SSL_CTX_sess_connect_good
6084 SSL_CTX_sess_accept_good
6086 SSL_CTX_sess_cb_hits
6088 SSL_CTX_sess_timeouts
6090 /* Session-id application notification callbacks */
6091 SSL_CTX_sess_set_new_cb
6092 SSL_CTX_sess_get_new_cb
6093 SSL_CTX_sess_set_get_cb
6094 SSL_CTX_sess_get_get_cb
6096 /* Session-id cache operation mode */
6097 SSL_CTX_set_session_cache_mode
6098 SSL_CTX_get_session_cache_mode
6100 /* Set default timeout values to use. */
6104 /* Global SSL initalisation informational callback */
6105 SSL_CTX_set_info_callback
6106 SSL_CTX_get_info_callback
6107 SSL_set_info_callback
6108 SSL_get_info_callback
6110 /* If the SSL_accept/SSL_connect returned with -1, these indicate when
6111 * we should re-call *.
6116 SSL_want_x509_lookup
6118 /* Where we are in SSL initalisation, used in non-blocking, perhaps
6119 * have a look at ssl/bio_ssl.c */
6121 SSL_is_init_finished
6126 /* Used to set the 'inital' state so SSL_in_connect_init and SSL_in_accept_init
6127 * can be used to work out which function to call. */
6128 SSL_set_connect_state
6129 SSL_set_accept_state
6131 /* Where to look for certificates for authentication */
6132 SSL_set_default_verify_paths /* calles SSL_load_verify_locations */
6133 SSL_load_verify_locations
6135 /* get info from an established connection */
6146 SSL_CTX_set_cipher_list
6150 SSL_get_shared_ciphers
6173 SSL_use_RSAPrivateKey
6174 SSL_use_RSAPrivateKey_ASN1
6175 SSL_use_RSAPrivateKey_file
6177 SSL_use_PrivateKey_ASN1
6178 SSL_use_PrivateKey_file
6180 SSL_use_certificate_ASN1
6181 SSL_use_certificate_file
6183 ERR_load_SSL_strings
6184 SSL_load_error_strings
6186 /* human readable version of the 'state' of the SSL connection. */
6188 SSL_state_string_long
6189 /* These 2 report what kind of IO operation the library was trying to
6190 * perform last. Probably not very usefull. */
6192 SSL_rstate_string_long
6194 SSL_get_peer_certificate
6197 SSL_SESSION_print_fp
6210 SSL_CTX_remove_session
6211 SSL_CTX_flush_sessions
6215 /* used to hold information as to why a certificate verification failed */
6216 SSL_set_verify_result
6217 SSL_get_verify_result
6219 /* can be used by the application to associate data with an SSL structure.
6220 * It needs to be 'free()ed' by the application */
6224 /* The following all set values that are kept in the SSL_CTX but
6225 * are used as the default values when an SSL session is created.
6226 * They are over writen by the relevent SSL_xxxx functions */
6228 /* SSL_set_verify */
6229 void SSL_CTX_set_default_verify
6231 /* This callback, if set, totaly overrides the normal SSLeay verification
6232 * functions and should return 1 on sucesss and 0 on failure */
6233 void SSL_CTX_set_cert_verify_callback
6235 /* The following are the same as the equivilent SSL_xxx functions.
6236 * Only one copy of this information is kept and if a particular
6237 * SSL structure has a local override, it is totally separate structure.
6239 int SSL_CTX_use_RSAPrivateKey
6240 int SSL_CTX_use_RSAPrivateKey_ASN1
6241 int SSL_CTX_use_RSAPrivateKey_file
6242 int SSL_CTX_use_PrivateKey
6243 int SSL_CTX_use_PrivateKey_ASN1
6244 int SSL_CTX_use_PrivateKey_file
6245 int SSL_CTX_use_certificate
6246 int SSL_CTX_use_certificate_ASN1
6247 int SSL_CTX_use_certificate_file
6250 ==== ssl_ctx.doc ========================================================
6252 This is now a bit dated, quite a few of the SSL_ functions could be
6253 SSL_CTX_ functions. I will update this in the future. 30 Aug 1996
6255 From eay@orb.mincom.oz.au Mon Dec 11 21:37:08 1995
6256 Received: by orb.mincom.oz.au id AA00696
6257 (5.65c/IDA-1.4.4 for eay); Mon, 11 Dec 1995 11:37:08 +1000
6258 Date: Mon, 11 Dec 1995 11:37:08 +1000 (EST)
6259 From: Eric Young <eay@mincom.oz.au>
6261 To: sameer <sameer@c2.org>
6262 Cc: Eric Young <eay@mincom.oz.au>
6263 Subject: Re: PEM_readX509 oesn't seem to be working
6264 In-Reply-To: <199512110102.RAA12521@infinity.c2.org>
6265 Message-Id: <Pine.SOL.3.91.951211112115.28608D-100000@orb>
6267 Content-Type: TEXT/PLAIN; charset=US-ASCII
6271 On Sun, 10 Dec 1995, sameer wrote:
6272 > OK, that's solved. I've found out that it is saying "no
6273 > certificate set" in SSL_accept because s->conn == NULL
6274 > so there is some place I need to initialize s->conn that I am
6275 > not initializing it.
6277 The full order of things for a server should be.
6281 /* The next line should not really be using ctx->cert but I'll leave it
6282 * this way right now... I don't want a X509_ routine to know about an SSL
6283 * structure, there should be an SSL_load_verify_locations... hmm, I may
6286 X509_load_verify_locations(ctx->cert,CAfile,CApath);
6288 /* Ok now for each new connection we do the following */
6291 SSL_set_verify(con,verify,verify_callback);
6293 /* set the certificate and private key to use. */
6294 SSL_use_certificate_ASN1(con,X509_certificate);
6295 SSL_use_RSAPrivateKey_ASN1(con,RSA_private_key);
6299 SSL_read(con)/SSL_write(con);
6301 There is a bit more than that but that is basically the structure.
6303 Create a context and specify where to lookup certificates.
6307 create a SSL structure
6308 set the certificate and private key
6316 Eric Young | Signature removed since it was generating
6317 AARNet: eay@mincom.oz.au | more followups than the message contents :-)
6321 ==== ssleay.doc ========================================================
6323 SSLeay: a cryptographic kitchen sink.
6326 Way back at the start of April 1995, I was looking for a mindless
6327 programming project. A friend of mine (Tim Hudson) said "why don't you do SSL,
6328 it has DES encryption in it and I would not mind using it in a SSL telnet".
6329 While it was true I had written a DES library in previous years, litle
6330 did I know what an expansive task SSL would turn into.
6332 First of all, the SSL protocol contains DES encryption. Well and good. My
6333 DES library was fast and portable. It also contained the RSA's RC4 stream
6334 cipher. Again, not a problem, some-one had just posted to sci.crypt
6335 something that was claimed to be RC4. It also contained IDEA, I had the
6336 specifications, not a problem to implement. MD5, an RFC, trivial, at most
6337 I could spend a week or so trying to see if I could speed up the
6338 implementation. All in all a nice set of ciphers.
6339 Then the first 'expantion of the scope', RSA public key
6340 encryption. Since I did not knowing a thing about public key encryption
6341 or number theory, this appeared quite a daunting task. Just writing a
6342 big number library would be problomatic in itself, let alone making it fast.
6343 At this point the scope of 'implementing SSL' expands eponentialy.
6344 First of all, the RSA private keys were being kept in ASN.1 format.
6345 Thankfully the RSA PKCS series of documents explains this format. So I now
6346 needed to be able to encode and decode arbitary ASN.1 objects. The Public
6347 keys were embeded in X509 certificates. Hmm... these are not only
6348 ASN.1 objects but they make up a heirachy of authentication. To
6349 authenticate a X509 certificate one needs to retrieve it's issuers
6350 certificate etc etc. Hmm..., so I also need to implement some kind
6351 of certificate management software. I would also have to implement
6352 software to authenticate certificates. At this point the support code made
6353 the SSL part of my library look quite small.
6354 Around this time, the first version of SSLeay was released.
6356 Ah, but here was the problem, I was not happy with the code so far. As may
6357 have become obvious, I had been treating all of this as a learning
6358 exersize, so I have completely written the library myself. As such, due
6359 to the way it had grown like a fungus, much of the library was not
6360 'elagent' or neat. There were global and static variables all over the
6361 place, the SSL part did not even handle non-blocking IO.
6362 The Great rewrite began.
6364 As of this point in time, the 'Great rewrite' has almost finished. So what
6365 follows is an approximate list of what is actually SSLeay 0.5.0
6367 /********* This needs to be updated for 0.6.0+ *************/
6370 The library contains the following routines. Please note that most of these
6371 functions are not specfic for SSL or any other particular cipher
6372 implementation. I have tried to make all the routines as general purpose
6373 as possible. So you should not think of this library as an SSL
6374 implemtation, but rather as a library of cryptographic functions
6375 that also contains SSL. I refer to each of these function groupings as
6376 libraries since they are often capable of functioning as independant
6379 First up, the general ciphers and message digests supported by the library.
6381 MD2 rfc???, a standard 'by parts' interface to this algorithm.
6382 MD5 rfc???, the same type of interface as for the MD2 library except a
6383 different algorithm.
6384 SHA THe Secure Hash Algorithm. Again the same type of interface as
6385 MD2/MD5 except the digest is 20 bytes.
6386 SHA1 The 'revised' version of SHA. Just about identical to SHA except
6387 for one tweak of an inner loop.
6388 DES This is my libdes library that has been floating around for the last
6389 few years. It has been enhanced for no other reason than completeness.
6390 It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and
6391 triple DES modes of ecb, cbc, cfb64 and ofb64. cfb64 and ofb64 are
6392 functional interfaces to the 64 bit modes of cfb and ofb used in
6393 such a way thay they function as single character interfaces.
6394 RC4 The RSA Inc. stream cipher.
6395 RC2 The RSA Inc. block cipher.
6396 IDEA An implmentation of the IDEA cipher, the library supports ecb, cbc,
6397 cfb64 and ofb64 modes of operation.
6399 Now all the above mentioned ciphers and digests libraries support high
6400 speed, minimal 'crap in the way' type interfaces. For fastest and
6401 lowest level access, these routines should be used directly.
6403 Now there was also the matter of public key crypto systems. These are
6404 based on large integer arithmatic.
6406 BN This is my large integer library. It supports all the normal
6407 arithmentic operations. It uses malloc extensivly and as such has
6408 no limits of the size of the numbers being manipulated. If you
6409 wish to use 4000 bit RSA moduli, these routines will handle it.
6410 This library also contains routines to 'generate' prime numbers and
6411 to test for primality. The RSA and DH libraries sit on top of this
6412 library. As of this point in time, I don't support SHA, but
6413 when I do add it, it will just sit on top of the routines contained
6415 RSA This implements the RSA public key algorithm. It also contains
6416 routines that will generate a new private/public key pair.
6417 All the RSA functions conform to the PKCS#1 standard.
6418 DH This is an implementation of the
6419 Diffie-Hellman protocol. There are all the require routines for
6420 the protocol, plus extra routines that can be used to generate a
6421 strong prime for use with a specified generator. While this last
6422 routine is not generally required by applications implementing DH,
6423 It is present for completeness and because I thing it is much
6424 better to be able to 'generate' your own 'magic' numbers as oposed
6425 to using numbers suplied by others. I conform to the PKCS#3
6426 standard where required.
6428 You may have noticed the preceeding section mentions the 'generation' of
6429 prime numbers. Now this requries the use of 'random numbers'.
6431 RAND This psuedo-random number library is based on MD5 at it's core
6432 and a large internal state (2k bytes). Once you have entered enough
6433 seed data into this random number algorithm I don't feel
6434 you will ever need to worry about it generating predictable output.
6435 Due to the way I am writing a portable library, I have left the
6436 issue of how to get good initial random seed data upto the
6437 application but I do have support routines for saving and loading a
6438 persistant random number state for use between program runs.
6440 Now to make all these ciphers easier to use, a higher level
6441 interface was required. In this form, the same function would be used to
6442 encrypt 'by parts', via any one of the above mentioned ciphers.
6444 EVP The Digital EnVeloPe library is quite large. At it's core are
6445 function to perform encryption and decryption by parts while using
6446 an initial parameter to specify which of the 17 different ciphers
6447 or 4 different message digests to use. On top of these are implmented
6448 the digital signature functions, sign, verify, seal and open.
6449 Base64 encoding of binary data is also done in this library.
6451 PEM rfc???? describe the format for Privacy Enhanced eMail.
6452 As part of this standard, methods of encoding digital enveloped
6453 data is an ascii format are defined. As such, I use a form of these
6454 to encode enveloped data. While at this point in time full support
6455 for PEM has not been built into the library, a minimal subset of
6456 the secret key and Base64 encoding is present. These reoutines are
6457 mostly used to Ascii encode binary data with a 'type' associated
6458 with it and perhaps details of private key encryption used to
6461 PKCS7 This is another Digital Envelope encoding standard which uses ASN.1
6462 to encode the data. At this point in time, while there are some
6463 routines to encode and decode this binary format, full support is
6466 As Mentioned, above, there are several different ways to encode
6469 ASN1 This library is more a set of primatives used to encode the packing
6470 and unpacking of data structures. It is used by the X509
6471 certificate standard and by the PKCS standards which are used by
6472 this library. It also contains routines for duplicating and signing
6473 the structures asocisated with X509.
6475 X509 The X509 library contains routines for packing and unpacking,
6476 verifying and just about every thing else you would want to do with
6479 PKCS7 PKCS-7 is a standard for encoding digital envelope data
6480 structures. At this point in time the routines will load and save
6481 DER forms of these structees. They need to be re-worked to support
6482 the BER form which is the normal way PKCS-7 is encoded. If the
6483 previous 2 sentances don't make much sense, don't worry, this
6484 library is not used by this version of SSLeay anyway.
6486 OBJ ASN.1 uses 'object identifiers' to identify objects. A set of
6487 functions were requred to translate from ASN.1 to an intenger, to a
6488 character string. This library provieds these translations
6490 Now I mentioned an X509 library. X509 specified a hieachy of certificates
6491 which needs to be traversed to authenticate particular certificates.
6493 METH This library is used to push 'methods' of retrieving certificates
6494 into the library. There are some supplied 'methods' with SSLeay
6495 but applications can add new methods if they so desire.
6496 This library has not been finished and is not being used in this
6499 Now all the above are required for use in the initial point of this project.
6501 SSL The SSL protocol. This is a full implmentation of SSL v 2. It
6502 support both server and client authentication. SSL v 3 support
6503 will be added when the SSL v 3 specification is released in it's
6506 Now quite a few of the above mentioned libraries rely on a few 'complex'
6507 data structures. For each of these I have a library.
6509 Lhash This is a hash table library which is used extensivly.
6511 STACK An implemetation of a Stack data structure.
6513 BUF A simple character array structure that also support a function to
6514 check that the array is greater that a certain size, if it is not,
6515 it is realloced so that is it.
6517 TXT_DB A simple memory based text file data base. The application can specify
6518 unique indexes that will be enforced at update time.
6520 CONF Most of the programs written for this library require a configuration
6521 file. Instead of letting programs constantly re-implment this
6522 subsystem, the CONF library provides a consistant and flexable
6523 interface to not only configuration files but also environment
6526 But what about when something goes wrong?
6527 The one advantage (and perhaps disadvantage) of all of these
6528 functions being in one library was the ability to implement a
6529 single error reporting system.
6531 ERR This library is used to report errors. The error system records
6532 library number, function number (in the library) and reason
6533 number. Multiple errors can be reported so that an 'error' trace
6534 is created. The errors can be printed in numeric or textual form.
6537 ==== ssluse.doc ========================================================
6539 We have an SSL_CTX which contains global information for lots of
6540 SSL connections. The session-id cache and the certificate verificate cache.
6541 It also contains default values for use when certificates are used.
6547 default session-id timeout period
6548 New session-id callback
6549 Required session-id callback
6551 Informational callback
6552 Callback that is set, overrides the SSLeay X509 certificate
6554 The default Certificate/Private Key pair
6555 Default read ahead mode.
6556 Default verify mode and verify callback. These are not used
6557 if the over ride callback mentioned above is used.
6559 Each SSL can have the following defined for it before a connection is made.
6564 Certificate verify mode and callback
6565 IO object to use in the comunication.
6566 Some 'read-ahead' mode information.
6567 A previous session-id to re-use.
6569 A connection is made by using SSL_connect or SSL_accept.
6570 When non-blocking IO is being used, there are functions that can be used
6571 to determin where and why the SSL_connect or SSL_accept did not complete.
6572 This information can be used to recall the functions when the 'error'
6573 condition has dissapeared.
6575 After the connection has been made, information can be retrived about the
6576 SSL session and the session-id values that have been decided apon.
6577 The 'peer' certificate can be retrieved.
6579 The session-id values include
6585 ==== stack.doc ========================================================
6587 The stack data structure is used to store an ordered list of objects.
6588 It is basically misnamed to call it a stack but it can function that way
6589 and that is what I originally used it for. Due to the way element
6590 pointers are kept in a malloc()ed array, the most efficient way to use this
6591 structure is to add and delete elements from the end via sk_pop() and
6592 sk_push(). If you wish to do 'lookups' sk_find() is quite efficient since
6593 it will sort the stack (if required) and then do a binary search to lookup
6594 the requested item. This sorting occurs automatically so just sk_push()
6595 elements on the stack and don't worry about the order. Do remember that if
6596 you do a sk_find(), the order of the elements will change.
6598 You should never need to 'touch' this structure directly.
6599 typedef struct stack_st
6605 unsigned int num_alloc;
6609 'num' holds the number of elements in the stack, 'data' is the array of
6610 elements. 'sorted' is 1 is the list has been sorted, 0 if not.
6612 num_alloc is the number of 'nodes' allocated in 'data'. When num becomes
6613 larger than num_alloc, data is realloced to a larger size.
6614 If 'comp' is set, it is a function that is used to compare 2 of the items
6615 in the stack. The function should return -1, 0 or 1, depending on the
6618 #define sk_num(sk) ((sk)->num)
6619 #define sk_value(sk,n) ((sk)->data[n])
6621 These 2 macros should be used to access the number of elements in the
6622 'stack' and to access a pointer to one of the values.
6624 STACK *sk_new(int (*c)());
6625 This creates a new stack. If 'c', the comparison function, is not
6626 specified, the various functions that operate on a sorted 'stack' will not
6627 work (sk_find()). NULL is returned on failure.
6629 void sk_free(STACK *);
6630 This function free()'s a stack structure. The elements in the
6631 stack will not be freed so one should 'pop' and free all elements from the
6632 stack before calling this function or call sk_pop_free() instead.
6634 void sk_pop_free(STACK *st; void (*func)());
6635 This function calls 'func' for each element on the stack, passing
6636 the element as the argument. sk_free() is then called to free the 'stack'
6639 int sk_insert(STACK *sk,char *data,int where);
6640 This function inserts 'data' into stack 'sk' at location 'where'.
6641 If 'where' is larger that the number of elements in the stack, the element
6642 is put at the end. This function tends to be used by other 'stack'
6643 functions. Returns 0 on failure, otherwise the number of elements in the
6646 char *sk_delete(STACK *st,int loc);
6647 Remove the item a location 'loc' from the stack and returns it.
6648 Returns NULL if the 'loc' is out of range.
6650 char *sk_delete_ptr(STACK *st, char *p);
6651 If the data item pointed to by 'p' is in the stack, it is deleted
6652 from the stack and returned. NULL is returned if the element is not in the
6655 int sk_find(STACK *st,char *data);
6656 Returns the location that contains a value that is equal to
6657 the 'data' item. If the comparison function was not set, this function
6658 does a linear search. This function actually qsort()s the stack if it is not
6659 in order and then uses bsearch() to do the initial search. If the
6660 search fails,, -1 is returned. For mutliple items with the same
6661 value, the index of the first in the array is returned.
6663 int sk_push(STACK *st,char *data);
6664 Append 'data' to the stack. 0 is returned if there is a failure
6665 (due to a malloc failure), else 1. This is
6666 sk_insert(st,data,sk_num(st));
6668 int sk_unshift(STACK *st,char *data);
6669 Prepend 'data' to the front (location 0) of the stack. This is
6670 sk_insert(st,data,0);
6672 char *sk_shift(STACK *st);
6673 Return and delete from the stack the first element in the stack.
6674 This is sk_delete(st,0);
6676 char *sk_pop(STACK *st);
6677 Return and delete the last element on the stack. This is
6678 sk_delete(st,sk_num(sk)-1);
6680 void sk_zero(STACK *st);
6681 Removes all items from the stack. It does not 'free'
6682 pointers but is a quick way to clear a 'stack of references'.
6684 ==== threads.doc ========================================================
6686 How to compile SSLeay for multi-threading.
6688 Well basically it is quite simple, set the compiler flags and build.
6689 I have only really done much testing under Solaris and Windows NT.
6690 If you library supports localtime_r() and gmtime_r() add,
6691 -DTHREADS to the makefile parameters. You can probably survive with out
6692 this define unless you are going to have multiple threads generating
6693 certificates at once. It will not affect the SSL side of things.
6695 The approach I have taken to doing locking is to make the application provide
6696 callbacks to perform locking and so that the SSLeay library can distinguish
6697 between threads (for the error state).
6699 To have a look at an example program, 'cd mt; vi mttest.c'.
6700 To build under solaris, sh solaris.sh, for Windows NT or Windows 95,
6703 This will build mttest which will fire up 10 threads that talk SSL
6704 to each other 10 times.
6705 To enable everything to work, the application needs to call
6707 CRYPTO_set_id_callback(id_function);
6708 CRYPTO_set_locking_callback(locking_function);
6710 before any multithreading is started.
6711 id_function does not need to be defined under Windows NT or 95, the
6712 correct function will be called if it is not. Under unix, getpid()
6713 is call if the id_callback is not defined, for Solaris this is wrong
6714 (since threads id's are not pid's) but under Linux it is correct
6715 (threads are just processes sharing the data segement).
6717 The locking_callback is used to perform locking by the SSLeay library.
6720 void solaris_locking_callback(mode,type,file,line)
6726 if (mode & CRYPTO_LOCK)
6727 mutex_lock(&(lock_cs[type]));
6729 mutex_unlock(&(lock_cs[type]));
6732 Now in this case I have used mutexes instead of read/write locks, since they
6733 are faster and there are not many read locks in SSLeay, you may as well
6734 always use write locks. file and line are __FILE__ and __LINE__ from
6735 the compile and can be usefull when debugging.
6737 Now as you can see, 'type' can be one of a range of values, these values are
6738 defined in crypto/crypto.h
6739 CRYPTO_get_lock_name(type) will return a text version of what the lock is.
6740 There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup
6741 for multi-threading can be
6743 static mutex_t lock_cs[CRYPTO_NUM_LOCKS];
6749 for (i=0; i<CRYPTO_NUM_LOCKS; i++)
6750 mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL);
6751 CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id);
6752 CRYPTO_set_locking_callback((void (*)())solaris_locking_callback);
6755 As a final note, under Windows NT or Windows 95, you have to be careful
6756 not to mix the various threaded, unthreaded and debug libraries.
6757 Normally if they are mixed incorrectly, mttest will crash just after printing
6758 out some usage statistics at the end. This is because the
6759 different system libraries use different malloc routines and if
6760 data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a
6761 different library malloc, things get very confused.
6763 The default SSLeay DLL builds use /MD, so if you use this on your
6764 application, things will work as expected. If you use /MDd,
6765 you will probably have to rebuild SSLeay using this flag.
6766 I should modify util/mk1mf.pl so it does all this correctly, but
6767 this has not been done yet.
6769 One last warning. Because locking overheads are actually quite large, the
6770 statistics collected against the SSL_CTX for successfull connections etc
6771 are not locked when updated. This does make it possible for these
6772 values to be slightly lower than they should be, if you are
6773 running multithreaded on a multi-processor box, but this does not really
6777 ==== txt_db.doc ========================================================
6779 TXT_DB, a simple text based in memory database.
6781 It holds rows of ascii data, for which the only special character is '\0'.
6782 The rows can be of an unlimited length.
6784 ==== why.doc ========================================================
6786 This file is more of a note for other people who wish to understand why
6787 the build environment is the way it is :-).
6789 The include files 'depend' as follows.
6791 crypto/*/*.c includes crypto/cryptlib.h
6792 ssl/*.c include ssl/ssl_locl.h
6793 apps/*.c include apps/apps.h
6794 crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h
6795 all include e_os.h which contains OS/environment specific information.
6796 If you need to add something todo with a particular environment,
6797 add it to this file. It is worth remembering that quite a few libraries,
6798 like lhash, des, md, sha etc etc do not include crypto/cryptlib.h. This
6799 is because these libraries should be 'independantly compilable' and so I
6800 try to keep them this way.
6801 e_os.h is not so much a part of SSLeay, as the placing in one spot all the
6802 evil OS dependant muck.
6804 I wanted to automate as many things as possible. This includes
6805 error number generation. A
6807 will scan the source files for error codes, append them to the correct
6808 header files, and generate the functions to print the text version
6809 of the error numbers. So don't even think about adding error numbers by
6810 hand, put them in the form
6811 XXXerr(XXXX_F_XXXX,YYYY_R_YYYY);
6812 on line and it will be automatically picked up my a make errors.
6814 In a similar vein, programs to be added into ssleay in the apps directory
6815 just need to have an entry added to E_EXE in makefile.ssl and
6816 everthing will work as expected. Don't edit progs.h by hand.
6818 make links re-generates the symbolic links that are used. The reason why
6819 I keep everything in its own directory, and don't put all the
6820 test programs and header files in 'test' and 'include' is because I want
6821 to keep the 'sub-libraries' independant. I still 'pull' out
6822 indervidual libraries for use in specific projects where the code is
6823 required. I have used the 'lhash' library in just about every software
6824 project I have worked on :-).
6826 make depend generates dependancies and
6827 make dclean removes them.
6829 You will notice that I use perl quite a bit when I could be using 'sed'.
6830 The reason I decided to do this was to just stick to one 'extra' program.
6831 For Windows NT, I have perl and no sed.
6833 The util/mk1mf.pl program can be used to generate a single makefile.
6834 I use this because makefiles under Microsoft are horrific.
6835 Each C compiler seems to have different linker formats, which have
6836 to be used because the retarted C compilers explode when you do
6839 Now some would argue that I should just use the single makefile. I don't
6840 like it during develoment for 2 reasons. First, the actuall make
6841 command takes a long time. For my current setup, if I'm in
6842 crypto/bn and I type make, only the crypto/bn directory gets rebuilt,
6843 which is nice when you are modifying prototypes in bn.h which
6844 half the SSLeay depends on. The second is that to add a new souce file
6845 I just plonk it in at the required spot in the local makefile. This
6846 then alows me to keep things local, I don't need to modify a 'global'
6847 tables (the make for unix, the make for NT, the make for w31...).
6848 When I am ripping apart a library structure, it is nice to only
6849 have to worry about one directory :-).
6851 Having said all this, for the hell of it I put together 2 files that
6852 #include all the souce code (generated by doing a ls */*.o after a build).
6853 crypto.c takes only 30 seconds to build under NT and 2 minutes under linux
6854 for my pentium100. Much faster that the normal build :-).
6855 Again, the problem is that when using libraries, every program linked
6856 to libcrypto.a would suddenly get 330k of library when it may only need
6857 1k. This technique does look like a nice way to do shared libraries though.
6859 Oh yes, as a final note, to 'build' a distribution, I just type
6861 This cleans and packages everything. The directory needs to be called
6862 SSLeay since the make does a 'cd ..' and renames and tars things up.
6864 ==== req.1 ========================================================
6866 The 'req' command is used to manipulate and deal with pkcs#10
6867 certificate requests.
6869 It's default mode of operation is to load a certificate and then
6872 By default the 'req' is read from stdin in 'PEM' format.
6873 The -inform option can be used to specify 'pem' format or 'der'
6874 format. PEM format is the base64 encoding of the DER format.
6876 By default 'req' then writes the request back out. -outform can be used
6877 to indicate the desired output format, be it 'pem' or 'der'.
6879 To specify an input file, use the '-in' option and the '-out' option
6880 can be used to specify the output file.
6882 If you wish to perform a command and not output the certificate
6883 request afterwards, use the '-noout' option.
6885 When a certificate is loaded, it can be printed in a human readable
6886 ascii format via the '-text' option.
6888 To check that the signature on a certificate request is correct, use
6889 the '-verify' option to make sure that the private key contained in the
6890 certificate request corresponds to the signature.
6892 Besides the default mode, there is also the 'generate a certificate
6893 request' mode. There are several flags that trigger this mode.
6895 -new will generate a new RSA key (if required) and then prompts
6896 the user for details for the certificate request.
6897 -newkey has an argument that is the number of bits to make the new
6898 key. This function also triggers '-new'.
6900 The '-new' option can have a key to use specified instead of having to
6901 load one, '-key' is used to specify the file containg the key.
6902 -keyform can be used to specify the format of the key. Only
6903 'pem' and 'der' formats are supported, later, 'netscape' format may be added.
6905 Finally there is the '-x509' options which makes req output a self
6906 signed x509 certificate instead of a certificate request.
6908 Now as you may have noticed, there are lots of default options that
6909 cannot be specified via the command line. They are held in a 'template'
6910 or 'configuration file'. The -config option specifies which configuration
6911 file to use. See conf.doc for details on the syntax of this file.
6913 The req command uses the 'req' section of the config file.
6916 # The following variables are defined. For this example I will populate
6917 # the various values
6919 default_bits = 512 # default number of bits to use.
6920 default_keyfile = testkey.pem # Where to write the generated keyfile
6922 distinguished_name= req_dn # The section that contains the
6923 # information about which 'object' we
6924 # want to put in the DN.
6925 attributes = req_attr # The objects we want for the
6927 encrypt_rsa_key = no # Should we encrypt newly generated
6928 # keys. I strongly recommend 'yes'.
6930 # The distinguished name section. For the following entries, the
6931 # object names must exist in the SSLeay header file objects.h. If they
6932 # do not, they will be silently ignored. The entries have the following
6934 # <object_name> => string to prompt with
6935 # <object_name>_default => default value for people
6936 # <object_name>_value => Automatically use this value for this field.
6937 # <object_name>_min => minimum number of characters for data (def. 0)
6938 # <object_name>_max => maximum number of characters for data (def. inf.)
6939 # All of these entries are optional except for the first one.
6941 countryName = Country Name (2 letter code)
6942 countryName_default = AU
6944 stateOrProvinceName = State or Province Name (full name)
6945 stateOrProvinceName_default = Queensland
6947 localityName = Locality Name (eg, city)
6949 organizationName = Organization Name (eg, company)
6950 organizationName_default = Mincom Pty Ltd
6952 organizationalUnitName = Organizational Unit Name (eg, section)
6953 organizationalUnitName_default = MTR
6955 commonName = Common Name (eg, YOUR name)
6958 emailAddress = Email Address
6959 emailAddress_max = 40
6961 # The next section is the attributes section. This is exactly the
6962 # same as for the previous section except that the resulting objects are
6963 # put in the attributes field.
6965 challengePassword = A challenge password
6966 challengePassword_min = 4
6967 challengePassword_max = 20
6969 unstructuredName = An optional company name
6972 Also note that the order that attributes appear in this file is the
6973 order they will be put into the distinguished name.
6975 Once this request has been generated, it can be sent to a CA for
6979 A few quick examples....
6981 To generate a new request and a new key
6984 To generate a new request and a 1058 bit key
6987 To generate a new request using a pre-existing key
6988 req -new -key key.pem
6990 To generate a self signed x509 certificate from a certificate
6991 request using a supplied key, and we want to see the text form of the
6992 output certificate (which we will put in the file selfSign.pem
6993 req -x509 -in req.pem -key key.pem -text -out selfSign.pem
6995 Verify that the signature is correct on a certificate request.
6996 req -verify -in req.pem
6998 Verify that the signature was made using a specified public key.
6999 req -verify -in req.pem -key key.pem
7001 Print the contents of a certificate request
7002 req -text -in req.pem
7004 ==== danger ========================================================
7006 If you specify a SSLv2 cipher, and the mode is SSLv23 and the server
7007 can talk SSLv3, it will claim there is no cipher since you should be
7010 When tracing debug stuff, remember BIO_s_socket() is different to
7013 BSD/OS assember is not working