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