From db1842132fc4e87cdc006757fbc27dc1c1562337 Mon Sep 17 00:00:00 2001 From: "Ralf S. Engelschall" Date: Wed, 30 Dec 1998 22:58:47 +0000 Subject: Cleanup of doc/ directory: The old/obsolete SSLeay files are now assembled together in a ssleay.txt file. --- doc/API.doc | 24 - doc/README | 6 + doc/a_verify.doc | 85 - doc/apps.doc | 53 - doc/asn1.doc | 401 ---- doc/bio.doc | 423 ---- doc/blowfish.doc | 146 -- doc/bn.doc | 381 ---- doc/ca.1 | 121 - doc/callback.doc | 240 -- doc/cipher.doc | 345 --- doc/cipher.m | 128 -- doc/conf.doc | 89 - doc/danger | 8 - doc/des.doc | 505 ----- doc/digest.doc | 94 - doc/encode.doc | 15 - doc/envelope.doc | 67 - doc/error.doc | 115 - doc/idea.doc | 176 -- doc/legal.doc | 117 - doc/lhash.doc | 151 -- doc/md2.doc | 49 - doc/md5.doc | 50 - doc/memory.doc | 27 - doc/ms3-ca.doc | 398 ---- doc/ns-ca.doc | 154 -- doc/obj.doc | 69 - doc/rand.doc | 141 -- doc/rc2.doc | 165 -- doc/rc4.doc | 44 - doc/readme | 6 - doc/ref.doc | 48 - doc/req.1 | 137 -- doc/rsa.doc | 135 -- doc/rsaref.doc | 35 - doc/s_mult.doc | 17 - doc/session.doc | 297 --- doc/sha.doc | 52 - doc/speed.doc | 96 - doc/ssl-ciph.doc | 84 - doc/ssl.doc | 172 -- doc/ssl_ctx.doc | 68 - doc/ssleay.doc | 213 -- doc/ssleay.txt | 6607 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/ssluse.doc | 45 - doc/stack.doc | 96 - doc/threads.doc | 90 - doc/txt_db.doc | 4 - doc/verify | 22 - doc/why.doc | 79 - 51 files changed, 6613 insertions(+), 6477 deletions(-) delete mode 100644 doc/API.doc create mode 100644 doc/README delete mode 100644 doc/a_verify.doc delete mode 100644 doc/apps.doc delete mode 100644 doc/asn1.doc delete mode 100644 doc/bio.doc delete mode 100644 doc/blowfish.doc delete mode 100644 doc/bn.doc delete mode 100644 doc/ca.1 delete mode 100644 doc/callback.doc delete mode 100644 doc/cipher.doc delete mode 100644 doc/cipher.m delete mode 100644 doc/conf.doc delete mode 100644 doc/danger delete mode 100644 doc/des.doc delete mode 100644 doc/digest.doc delete mode 100644 doc/encode.doc delete mode 100644 doc/envelope.doc delete mode 100644 doc/error.doc delete mode 100644 doc/idea.doc delete mode 100644 doc/legal.doc delete mode 100644 doc/lhash.doc delete mode 100644 doc/md2.doc delete mode 100644 doc/md5.doc delete mode 100644 doc/memory.doc delete mode 100644 doc/ms3-ca.doc delete mode 100644 doc/ns-ca.doc delete mode 100644 doc/obj.doc delete mode 100644 doc/rand.doc delete mode 100644 doc/rc2.doc delete mode 100644 doc/rc4.doc delete mode 100644 doc/readme delete mode 100644 doc/ref.doc delete mode 100644 doc/req.1 delete mode 100644 doc/rsa.doc delete mode 100644 doc/rsaref.doc delete mode 100644 doc/s_mult.doc delete mode 100644 doc/session.doc delete mode 100644 doc/sha.doc delete mode 100644 doc/speed.doc delete mode 100644 doc/ssl-ciph.doc delete mode 100644 doc/ssl.doc delete mode 100644 doc/ssl_ctx.doc delete mode 100644 doc/ssleay.doc create mode 100644 doc/ssleay.txt delete mode 100644 doc/ssluse.doc delete mode 100644 doc/stack.doc delete mode 100644 doc/threads.doc delete mode 100644 doc/txt_db.doc delete mode 100644 doc/verify delete mode 100644 doc/why.doc (limited to 'doc') diff --git a/doc/API.doc b/doc/API.doc deleted file mode 100644 index fe2820259a..0000000000 --- a/doc/API.doc +++ /dev/null @@ -1,24 +0,0 @@ -SSL - SSLv2/v3/v23 etc. - -BIO - methods and how they plug together - -MEM - memory allocation callback - -CRYPTO - locking for threads - -EVP - Ciphers/Digests/signatures - -RSA - methods - -X509 - certificate retrieval - -X509 - validation - -X509 - X509v3 extensions - -Objects - adding object identifiers - -ASN.1 - parsing - -PEM - parsing - diff --git a/doc/README b/doc/README new file mode 100644 index 0000000000..81c59803fd --- /dev/null +++ b/doc/README @@ -0,0 +1,6 @@ + + openssl.pod ..... Documentation of OpenSSL `openssl' command + crypto.pod ...... Documentation of OpenSSL crypto.h+libcrypto.a + ssl.pod ......... Documentation of OpenSSL ssl.h+libssl.a + ssleay.txt ...... Assembled documentation files of ancestor SSLeay [obsolete} + diff --git a/doc/a_verify.doc b/doc/a_verify.doc deleted file mode 100644 index 06eec17c2b..0000000000 --- a/doc/a_verify.doc +++ /dev/null @@ -1,85 +0,0 @@ -From eay@mincom.com Fri Oct 4 18:29:06 1996 -Received: by orb.mincom.oz.au id AA29080 - (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000 -Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST) -From: Eric Young -X-Sender: eay@orb -To: wplatzer -Cc: Eric Young , SSL Mailing List -Subject: Re: Netscape's Public Key -In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at> -Message-Id: -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII -Status: RO -X-Status: - -On Thu, 3 Oct 1996, wplatzer wrote: -> I get Public Key from Netscape (Gold 3.0b4), but cannot do anything -> with it... It looks like (asn1parse): -> -> 0:d=0 hl=3 l=180 cons: SEQUENCE -> 3:d=1 hl=2 l= 96 cons: SEQUENCE -> 5:d=2 hl=2 l= 92 cons: SEQUENCE -> 7:d=3 hl=2 l= 13 cons: SEQUENCE -> 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption -> 20:d=4 hl=2 l= 0 prim: NULL -> 22:d=3 hl=2 l= 75 prim: BIT STRING -> 99:d=2 hl=2 l= 0 prim: IA5STRING : -> 101:d=1 hl=2 l= 13 cons: SEQUENCE -> 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption -> 114:d=2 hl=2 l= 0 prim: NULL -> 116:d=1 hl=2 l= 65 prim: BIT STRING -> -> The first BIT STRING is the public key and the second BIT STRING is -> the signature. -> But a public key consists of the public exponent and the modulus. Are -> both numbers in the first BIT STRING? -> Is there a document simply describing this coding stuff (checking -> signature, get the public key, etc.)? - -Minimal in SSLeay. If you want to see what the modulus and exponent are, -try asn1parse -offset 25 -length 75 next_bio list. - - - -Extra commands are normally implemented as macros calling BIO_ctrl(). -- BIO_number_read(BIO *bio) - the number of bytes processed - by BIO_read(bio,.). -- BIO_number_written(BIO *bio) - the number of bytes written - by BIO_write(bio,.). -- BIO_reset(BIO *bio) - 'reset' the BIO. -- BIO_eof(BIO *bio) - non zero if we are at the current end - of input. -- BIO_set_close(BIO *bio, int close_flag) - set the close flag. -- BIO_get_close(BIO *bio) - return the close flag. - BIO_pending(BIO *bio) - return the number of bytes waiting - to be read (normally buffered internally). -- BIO_flush(BIO *bio) - output any data waiting to be output. -- BIO_should_retry(BIO *io) - after a BIO_read/BIO_write - operation returns 0 or -1, a call to this function will - return non zero if you should retry the call later (this - is for non-blocking IO). -- BIO_should_read(BIO *io) - we should retry when data can - be read. -- BIO_should_write(BIO *io) - we should retry when data can - be written. -- BIO_method_name(BIO *io) - return a string for the method name. -- BIO_method_type(BIO *io) - return the unique ID of the BIO method. -- BIO_set_callback(BIO *io, long (*callback)(BIO *io, int - cmd, char *argp, int argi, long argl, long ret); - sets - the debug callback. -- BIO_get_callback(BIO *io) - return the assigned function - as mentioned above. -- BIO_set_callback_arg(BIO *io, char *arg) - assign some - data against the BIO. This is normally used by the debug - callback but could in reality be used for anything. To - get an idea of how all this works, have a look at the code - in the default debug callback mentioned above. The - callback can modify the return values. - -Details of the BIO_METHOD structure. -typedef struct bio_method_st - { - int type; - char *name; - int (*bwrite)(); - int (*bread)(); - int (*bputs)(); - int (*bgets)(); - long (*ctrl)(); - int (*create)(); - int (*destroy)(); - } BIO_METHOD; - -The 'type' is the numeric type of the BIO, these are listed in buffer.h; -'Name' is a textual representation of the BIO 'type'. -The 7 function pointers point to the respective function -methods, some of which can be NULL if not implemented. -The BIO structure -typedef struct bio_st - { - BIO_METHOD *method; - long (*callback)(BIO * bio, int mode, char *argp, int - argi, long argl, long ret); - char *cb_arg; /* first argument for the callback */ - int init; - int shutdown; - int flags; /* extra storage */ - int num; - char *ptr; - struct bio_st *next_bio; /* used by filter BIOs */ - int references; - unsigned long num_read; - unsigned long num_write; - } BIO; - -- 'Method' is the BIO method. -- 'callback', when configured, is called before and after - each BIO method is called for that particular BIO. This - is intended primarily for debugging and of informational feedback. -- 'init' is 0 when the BIO can be used for operation. - Often, after a BIO is created, a number of operations may - need to be performed before it is available for use. An - example is for BIO_s_sock(). A socket needs to be - assigned to the BIO before it can be used. -- 'shutdown', this flag indicates if the underlying - comunication primative being used should be closed/freed - when the BIO is closed. -- 'flags' is used to hold extra state. It is primarily used - to hold information about why a non-blocking operation - failed and to record startup protocol information for the - SSL BIO. -- 'num' and 'ptr' are used to hold instance specific state - like file descriptors or local data structures. -- 'next_bio' is used by filter BIOs to hold the pointer of the - next BIO in the chain. written data is sent to this BIO and - data read is taken from it. -- 'references' is used to indicate the number of pointers to - this structure. This needs to be '1' before a call to - BIO_free() is made if the BIO_free() function is to - actually free() the structure, otherwise the reference - count is just decreased. The actual BIO subsystem does - not really use this functionality but it is useful when - used in more advanced applicaion. -- num_read and num_write are the total number of bytes - read/written via the 'read()' and 'write()' methods. - -BIO_ctrl operations. -The following is the list of standard commands passed as the -second parameter to BIO_ctrl() and should be supported by -all BIO as best as possible. Some are optional, some are -manditory, in any case, where is makes sense, a filter BIO -should pass such requests to underlying BIO's. -- BIO_CTRL_RESET - Reset the BIO back to an initial state. -- BIO_CTRL_EOF - return 0 if we are not at the end of input, - non 0 if we are. -- BIO_CTRL_INFO - BIO specific special command, normal - information return. -- BIO_CTRL_SET - set IO specific parameter. -- BIO_CTRL_GET - get IO specific parameter. -- BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one - of BIO_CLOSE or BIO_NOCLOSE. -- BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag. -- BIO_CTRL_PENDING - Return the number of bytes available - for instant reading -- BIO_CTRL_FLUSH - Output pending data, return number of bytes output. -- BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned) - should we 'retry' when IO is possible on the underlying IO object. -- BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on. - -The following command is a special BIO_s_file() specific option. -- BIO_CTRL_SET_FILENAME - specify a file to open for IO. - -The BIO_CTRL_RETRY_TYPE needs a little more explanation. -When performing non-blocking IO, or say reading on a memory -BIO, when no data is present (or cannot be written), -BIO_read() and/or BIO_write() will return -1. -BIO_should_retry(bio) will return true if this is due to an -IO condition rather than an actual error. In the case of -BIO_s_mem(), a read when there is no data will return -1 and -a should retry when there is more 'read' data. -The retry type is deduced from 2 macros -BIO_should_read(bio) and BIO_should_write(bio). -Now while it may appear obvious that a BIO_read() failure -should indicate that a retry should be performed when more -read data is available, this is often not true when using -things like an SSL BIO. During the SSL protocol startup -multiple reads and writes are performed, triggered by any -SSL_read or SSL_write. -So to write code that will transparently handle either a -socket or SSL BIO, - i=BIO_read(bio,..) - if (I == -1) - { - if (BIO_should_retry(bio)) - { - if (BIO_should_read(bio)) - { - /* call us again when BIO can be read */ - } - if (BIO_should_write(bio)) - { - /* call us again when BIO can be written */ - } - } - } - -At this point in time only read and write conditions can be -used but in the future I can see the situation for other -conditions, specifically with SSL there could be a condition -of a X509 certificate lookup taking place and so the non- -blocking BIO_read would require a retry when the certificate -lookup subsystem has finished it's lookup. This is all -makes more sense and is easy to use in a event loop type -setup. -When using the SSL BIO, either SSL_read() or SSL_write()s -can be called during the protocol startup and things will -still work correctly. -The nice aspect of the use of the BIO_should_retry() macro -is that all the errno codes that indicate a non-fatal error -are encapsulated in one place. The Windows specific error -codes and WSAGetLastError() calls are also hidden from the -application. - -Notes on each BIO method. -Normally buffer.h is just required but depending on the -BIO_METHOD, ssl.h or evp.h will also be required. - -BIO_METHOD *BIO_s_mem(void); -- BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) - - set the underlying BUF_MEM structure for the BIO to use. -- BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL, - set it to point to the memory array and return the number - of bytes available. -A read/write BIO. Any data written is appended to the -memory array and any read is read from the front. This BIO -can be used for read/write at the same time. BIO_gets() is -supported in the fgets() sense. -BIO_CTRL_INFO can be used to retrieve pointers to the memory -buffer and it's length. - -BIO_METHOD *BIO_s_file(void); -- BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use. -- BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use. -- BIO_read_filename(BIO *bio, char *name) - read from file. -- BIO_write_filename(BIO *bio, char *name) - write to file. -- BIO_append_filename(BIO *bio, char *name) - append to file. -This BIO sits over the normal system fread()/fgets() type -functions. Gets() is supported. This BIO in theory could be -used for read and write but it is best to think of each BIO -of this type as either a read or a write BIO, not both. - -BIO_METHOD *BIO_s_socket(void); -BIO_METHOD *BIO_s_fd(void); -- BIO_sock_should_retry(int i) - the underlying function - used to determine if a call should be retried; the - argument is the '0' or '-1' returned by the previous BIO - operation. -- BIO_fd_should_retry(int i) - same as the -- BIO_sock_should_retry() except that it is different internally. -- BIO_set_fd(BIO *bio, int fd, int close_flag) - set the - file descriptor to use -- BIO_get_fd(BIO *bio, int *fd) - get the file descriptor. -These two methods are very similar. Gets() is not -supported, if you want this functionality, put a -BIO_f_buffer() onto it. This BIO is bi-directional if the -underlying file descriptor is. This is normally the case -for sockets but not the case for stdio descriptors. - -BIO_METHOD *BIO_s_null(void); -Read and write as much data as you like, it all disappears -into this BIO. - -BIO_METHOD *BIO_f_buffer(void); -- BIO_get_buffer_num_lines(BIO *bio) - return the number of - complete lines in the buffer. -- BIO_set_buffer_size(BIO *bio, long size) - set the size of - the buffers. -This type performs input and output buffering. It performs -both at the same time. The size of the buffer can be set -via the set buffer size option. Data buffered for output is -only written when the buffer fills. - -BIO_METHOD *BIO_f_ssl(void); -- BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL - structure to use. -- BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure - in use. -The SSL bio is a little different from normal BIOs because -the underlying SSL structure is a little different. A SSL -structure performs IO via a read and write BIO. These can -be different and are normally set via the -SSL_set_rbio()/SSL_set_wbio() calls. The SSL_set_fd() calls -are just wrappers that create socket BIOs and then call -SSL_set_bio() where the read and write BIOs are the same. -The BIO_push() operation makes the SSLs IO BIOs the same, so -make sure the BIO pushed is capable of two directional -traffic. If it is not, you will have to install the BIOs -via the more conventional SSL_set_bio() call. BIO_pop() will retrieve -the 'SSL read' BIO. - -BIO_METHOD *BIO_f_md(void); -- BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest - to use. -- BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest - method in use in mdp, return 0 if not set yet. -- BIO_reset() reinitializes the digest (EVP_DigestInit()) - and passes the reset to the underlying BIOs. -All data read or written via BIO_read() or BIO_write() to -this BIO will be added to the calculated digest. This -implies that this BIO is only one directional. If read and -write operations are performed, two separate BIO_f_md() BIOs -are reuqired to generate digests on both the input and the -output. BIO_gets(BIO *bio, char *md, int size) will place the -generated digest into 'md' and return the number of bytes. -The EVP_MAX_MD_SIZE should probably be used to size the 'md' -array. Reading the digest will also reset it. - -BIO_METHOD *BIO_f_cipher(void); -- BIO_reset() reinitializes the cipher. -- BIO_flush() should be called when the last bytes have been - output to flush the final block of block ciphers. -- BIO_get_cipher_status(BIO *b), when called after the last - read from a cipher BIO, returns non-zero if the data - decrypted correctly, otherwise, 0. -- BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key, - unsigned char *iv, int encrypt) This function is used to - setup a cipher BIO. The length of key and iv are - specified by the choice of EVP_CIPHER. Encrypt is 1 to - encrypt and 0 to decrypt. - -BIO_METHOD *BIO_f_base64(void); -- BIO_flush() should be called when the last bytes have been output. -This BIO base64 encodes when writing and base64 decodes when -reading. It will scan the input until a suitable begin line -is found. After reading data, BIO_reset() will reset the -BIO to start scanning again. Do not mix reading and writing -on the same base64 BIO. It is meant as a single stream BIO. - -Directions type -both BIO_s_mem() -one/both BIO_s_file() -both BIO_s_fd() -both BIO_s_socket() -both BIO_s_null() -both BIO_f_buffer() -one BIO_f_md() -one BIO_f_cipher() -one BIO_f_base64() -both BIO_f_ssl() - -It is easy to mix one and two directional BIOs, all one has -to do is to keep two separate BIO pointers for reading and -writing and be careful about usage of underlying BIOs. The -SSL bio by it's very nature has to be two directional but -the BIO_push() command will push the one BIO into the SSL -BIO for both reading and writing. - -The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c. - diff --git a/doc/blowfish.doc b/doc/blowfish.doc deleted file mode 100644 index 8a7f425b32..0000000000 --- a/doc/blowfish.doc +++ /dev/null @@ -1,146 +0,0 @@ -The Blowfish library. - -Blowfish is a block cipher that operates on 64bit (8 byte) quantities. It -uses variable size key, but 128bit (16 byte) key would normally be considered -good. It can be used in all the modes that DES can be used. This -library implements the ecb, cbc, cfb64, ofb64 modes. - -Blowfish is quite a bit faster that DES, and much faster than IDEA or -RC2. It is one of the faster block ciphers. - -For all calls that have an 'input' and 'output' variables, they can be the -same. - -This library requires the inclusion of 'blowfish.h'. - -All of the encryption functions take what is called an BF_KEY as an -argument. An BF_KEY is an expanded form of the Blowfish key. -For all modes of the Blowfish algorithm, the BF_KEY used for -decryption is the same one that was used for encryption. - -The define BF_ENCRYPT is passed to specify encryption for the functions -that require an encryption/decryption flag. BF_DECRYPT is passed to -specify decryption. - -Please note that any of the encryption modes specified in my DES library -could be used with Blowfish. I have only implemented ecb, cbc, cfb64 and -ofb64 for the following reasons. -- ecb is the basic Blowfish encryption. -- cbc is the normal 'chaining' form for block ciphers. -- cfb64 can be used to encrypt single characters, therefore input and output - do not need to be a multiple of 8. -- ofb64 is similar to cfb64 but is more like a stream cipher, not as - secure (not cipher feedback) but it does not have an encrypt/decrypt mode. -- If you want triple Blowfish, thats 384 bits of key and you must be totally - obsessed with security. Still, if you want it, it is simple enough to - copy the function from the DES library and change the des_encrypt to - BF_encrypt; an exercise left for the paranoid reader :-). - -The functions are as follows: - -void BF_set_key( -BF_KEY *ks; -int len; -unsigned char *key; - BF_set_key converts an 'len' byte key into a BF_KEY. - A 'ks' is an expanded form of the 'key' which is used to - perform actual encryption. It can be regenerated from the Blowfish key - so it only needs to be kept when encryption or decryption is about - to occur. Don't save or pass around BF_KEY's since they - are CPU architecture dependent, 'key's are not. Blowfish is an - interesting cipher in that it can be used with a variable length - key. 'len' is the length of 'key' to be used as the key. - A 'len' of 16 is recomended by me, but blowfish can use upto - 72 bytes. As a warning, blowfish has a very very slow set_key - function, it actually runs BF_encrypt 521 times. - -void BF_encrypt(unsigned long *data, BF_KEY *key); -void BF_decrypt(unsigned long *data, BF_KEY *key); - These are the Blowfish encryption function that gets called by just - about every other Blowfish routine in the library. You should not - use this function except to implement 'modes' of Blowfish. - I say this because the - functions that call this routine do the conversion from 'char *' to - long, and this needs to be done to make sure 'non-aligned' memory - access do not occur. - Data is a pointer to 2 unsigned long's and key is the - BF_KEY to use. - -void BF_ecb_encrypt( -unsigned char *in, -unsigned char *out, -BF_KEY *key, -int encrypt); - This is the basic Electronic Code Book form of Blowfish (in DES this - mode is called Electronic Code Book so I'm going to use the term - for blowfish as well. - Input is encrypted into output using the key represented by - key. Depending on the encrypt, encryption or - decryption occurs. Input is 8 bytes long and output is 8 bytes. - -void BF_cbc_encrypt( -unsigned char *in, -unsigned char *out, -long length, -BF_KEY *ks, -unsigned char *ivec, -int encrypt); - This routine implements Blowfish in Cipher Block Chaining mode. - Input, which should be a multiple of 8 bytes is encrypted - (or decrypted) to output which will also be a multiple of 8 bytes. - The number of bytes is in length (and from what I've said above, - should be a multiple of 8). If length is not a multiple of 8, bad - things will probably happen. ivec is the initialisation vector. - This function updates iv after each call so that it can be passed to - the next call to BF_cbc_encrypt(). - -void BF_cfb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -BF_KEY *schedule, -unsigned char *ivec, -int *num, -int encrypt); - This is one of the more useful functions in this Blowfish library, it - implements CFB mode of Blowfish with 64bit feedback. - This allows you to encrypt an arbitrary number of bytes, - you do not require 8 byte padding. Each call to this - routine will encrypt the input bytes to output and then update ivec - and num. Num contains 'how far' we are though ivec. - 'Encrypt' is used to indicate encryption or decryption. - CFB64 mode operates by using the cipher to generate a stream - of bytes which is used to encrypt the plain text. - The cipher text is then encrypted to generate the next 64 bits to - be xored (incrementally) with the next 64 bits of plain - text. As can be seen from this, to encrypt or decrypt, - the same 'cipher stream' needs to be generated but the way the next - block of data is gathered for encryption is different for - encryption and decryption. - -void BF_ofb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -BF_KEY *schedule, -unsigned char *ivec, -int *num); - This functions implements OFB mode of Blowfish with 64bit feedback. - This allows you to encrypt an arbitrary number of bytes, - you do not require 8 byte padding. Each call to this - routine will encrypt the input bytes to output and then update ivec - and num. Num contains 'how far' we are though ivec. - This is in effect a stream cipher, there is no encryption or - decryption mode. - -For reading passwords, I suggest using des_read_pw_string() from my DES library. -To generate a password from a text string, I suggest using MD5 (or MD2) to -produce a 16 byte message digest that can then be passed directly to -BF_set_key(). - -===== -For more information about the specific Blowfish modes in this library -(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the -documentation on my DES library. What is said about DES is directly -applicable for Blowfish. - diff --git a/doc/bn.doc b/doc/bn.doc deleted file mode 100644 index 47be23b6ea..0000000000 --- a/doc/bn.doc +++ /dev/null @@ -1,381 +0,0 @@ -The Big Number library. - -#include "bn.h" when using this library. - -This big number library was written for use in implementing the RSA and DH -public key encryption algorithms. As such, features such as negative -numbers have not been extensively tested but they should work as expected. -This library uses dynamic memory allocation for storing its data structures -and so there are no limit on the size of the numbers manipulated by these -routines but there is always the requirement to check return codes from -functions just in case a memory allocation error has occurred. - -The basic object in this library is a BIGNUM. It is used to hold a single -large integer. This type should be considered opaque and fields should not -be modified or accessed directly. -typedef struct bignum_st - { - int top; /* Index of last used d. */ - BN_ULONG *d; /* Pointer to an array of 'BITS2' bit chunks. */ - int max; /* Size of the d array. */ - int neg; - } BIGNUM; -The big number is stored in a malloced array of BN_ULONG's. A BN_ULONG can -be either 16, 32 or 64 bits in size, depending on the 'number of bits' -specified in bn.h. -The 'd' field is this array. 'max' is the size of the 'd' array that has -been allocated. 'top' is the 'last' entry being used, so for a value of 4, -bn.d[0]=4 and bn.top=1. 'neg' is 1 if the number is negative. -When a BIGNUM is '0', the 'd' field can be NULL and top == 0. - -Various routines in this library require the use of 'temporary' BIGNUM -variables during their execution. Due to the use of dynamic memory -allocation to create BIGNUMs being rather expensive when used in -conjunction with repeated subroutine calls, the BN_CTX structure is -used. This structure contains BN_CTX BIGNUMs. BN_CTX -is the maximum number of temporary BIGNUMs any publicly exported -function will use. - -#define BN_CTX 12 -typedef struct bignum_ctx - { - int tos; /* top of stack */ - BIGNUM *bn[BN_CTX]; /* The variables */ - } BN_CTX; - -The functions that follow have been grouped according to function. Most -arithmetic functions return a result in the first argument, sometimes this -first argument can also be an input parameter, sometimes it cannot. These -restrictions are documented. - -extern BIGNUM *BN_value_one; -There is one variable defined by this library, a BIGNUM which contains the -number 1. This variable is useful for use in comparisons and assignment. - -Get Size functions. - -int BN_num_bits(BIGNUM *a); - This function returns the size of 'a' in bits. - -int BN_num_bytes(BIGNUM *a); - This function (macro) returns the size of 'a' in bytes. - For conversion of BIGNUMs to byte streams, this is the number of - bytes the output string will occupy. If the output byte - format specifies that the 'top' bit indicates if the number is - signed, so an extra '0' byte is required if the top bit on a - positive number is being written, it is upto the application to - make this adjustment. Like I said at the start, I don't - really support negative numbers :-). - -Creation/Destruction routines. - -BIGNUM *BN_new(); - Return a new BIGNUM object. The number initially has a value of 0. If - there is an error, NULL is returned. - -void BN_free(BIGNUM *a); - Free()s a BIGNUM. - -void BN_clear(BIGNUM *a); - Sets 'a' to a value of 0 and also zeros all unused allocated - memory. This function is used to clear a variable of 'sensitive' - data that was held in it. - -void BN_clear_free(BIGNUM *a); - This function zeros the memory used by 'a' and then free()'s it. - This function should be used to BN_free() BIGNUMS that have held - sensitive numeric values like RSA private key values. Both this - function and BN_clear tend to only be used by RSA and DH routines. - -BN_CTX *BN_CTX_new(void); - Returns a new BN_CTX. NULL on error. - -void BN_CTX_free(BN_CTX *c); - Free a BN_CTX structure. The BIGNUMs in 'c' are BN_clear_free()ed. - -BIGNUM *bn_expand(BIGNUM *b, int bits); - This is an internal function that should not normally be used. It - ensures that 'b' has enough room for a 'bits' bit number. It is - mostly used by the various BIGNUM routines. If there is an error, - NULL is returned. if not, 'b' is returned. - -BIGNUM *BN_copy(BIGNUM *to, BIGNUM *from); - The 'from' is copied into 'to'. NULL is returned if there is an - error, otherwise 'to' is returned. - -BIGNUM *BN_dup(BIGNUM *a); - A new BIGNUM is created and returned containing the value of 'a'. - NULL is returned on error. - -Comparison and Test Functions. - -int BN_is_zero(BIGNUM *a) - Return 1 if 'a' is zero, else 0. - -int BN_is_one(a) - Return 1 is 'a' is one, else 0. - -int BN_is_word(a,w) - Return 1 if 'a' == w, else 0. 'w' is a BN_ULONG. - -int BN_cmp(BIGNUM *a, BIGNUM *b); - Return -1 if 'a' is less than 'b', 0 if 'a' and 'b' are the same - and 1 is 'a' is greater than 'b'. This is a signed comparison. - -int BN_ucmp(BIGNUM *a, BIGNUM *b); - This function is the same as BN_cmp except that the comparison - ignores the sign of the numbers. - -Arithmetic Functions -For all of these functions, 0 is returned if there is an error and 1 is -returned for success. The return value should always be checked. eg. -if (!BN_add(r,a,b)) goto err; -Unless explicitly mentioned, the 'return' value can be one of the -'parameters' to the function. - -int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b); - Add 'a' and 'b' and return the result in 'r'. This is r=a+b. - -int BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b); - Subtract 'a' from 'b' and put the result in 'r'. This is r=a-b. - -int BN_lshift(BIGNUM *r, BIGNUM *a, int n); - Shift 'a' left by 'n' bits. This is r=a*(2^n). - -int BN_lshift1(BIGNUM *r, BIGNUM *a); - Shift 'a' left by 1 bit. This form is more efficient than - BN_lshift(r,a,1). This is r=a*2. - -int BN_rshift(BIGNUM *r, BIGNUM *a, int n); - Shift 'a' right by 'n' bits. This is r=int(a/(2^n)). - -int BN_rshift1(BIGNUM *r, BIGNUM *a); - Shift 'a' right by 1 bit. This form is more efficient than - BN_rshift(r,a,1). This is r=int(a/2). - -int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b); - Multiply a by b and return the result in 'r'. 'r' must not be - either 'a' or 'b'. It has to be a different BIGNUM. - This is r=a*b. - -int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); - Multiply a by a and return the result in 'r'. 'r' must not be - 'a'. This function is alot faster than BN_mul(r,a,a). This is r=a*a. - -int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); - Divide 'm' by 'd' and return the result in 'dv' and the remainder - in 'rem'. Either of 'dv' or 'rem' can be NULL in which case that - value is not returned. 'ctx' needs to be passed as a source of - temporary BIGNUM variables. - This is dv=int(m/d), rem=m%d. - -int BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); - Find the remainder of 'm' divided by 'd' and return it in 'rem'. - 'ctx' holds the temporary BIGNUMs required by this function. - This function is more efficient than BN_div(NULL,rem,m,d,ctx); - This is rem=m%d. - -int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BIGNUM *m,BN_CTX *ctx); - Multiply 'a' by 'b' and return the remainder when divided by 'm'. - 'ctx' holds the temporary BIGNUMs required by this function. - This is r=(a*b)%m. - -int BN_mod_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx); - Raise 'a' to the 'p' power and return the remainder when divided by - 'm'. 'ctx' holds the temporary BIGNUMs required by this function. - This is r=(a^p)%m. - -int BN_reciprocal(BIGNUM *r, BIGNUM *m, BN_CTX *ctx); - Return the reciprocal of 'm'. 'ctx' holds the temporary variables - required. This function returns -1 on error, otherwise it returns - the number of bits 'r' is shifted left to make 'r' into an integer. - This number of bits shifted is required in BN_mod_mul_reciprocal(). - This is r=(1/m)<<(BN_num_bits(m)+1). - -int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y, BIGNUM *m, - BIGNUM *i, int nb, BN_CTX *ctx); - This function is used to perform an efficient BN_mod_mul() - operation. If one is going to repeatedly perform BN_mod_mul() with - the same modulus is worth calculating the reciprocal of the modulus - and then using this function. This operation uses the fact that - a/b == a*r where r is the reciprocal of b. On modern computers - multiplication is very fast and big number division is very slow. - 'x' is multiplied by 'y' and then divided by 'm' and the remainder - is returned. 'i' is the reciprocal of 'm' and 'nb' is the number - of bits as returned from BN_reciprocal(). Normal usage is as follows. - bn=BN_reciprocal(i,m); - for (...) - { BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); } - This is r=(x*y)%m. Internally it is approximately - r=(x*y)-m*(x*y/m) or r=(x*y)-m*((x*y*i) >> bn) - This function is used in BN_mod_exp() and BN_is_prime(). - -Assignment Operations - -int BN_one(BIGNUM *a) - Set 'a' to hold the value one. - This is a=1. - -int BN_zero(BIGNUM *a) - Set 'a' to hold the value zero. - This is a=0. - -int BN_set_word(BIGNUM *a, unsigned long w); - Set 'a' to hold the value of 'w'. 'w' is an unsigned long. - This is a=w. - -unsigned long BN_get_word(BIGNUM *a); - Returns 'a' in an unsigned long. Not remarkably, often 'a' will - be biger than a word, in which case 0xffffffffL is returned. - -Word Operations -These functions are much more efficient that the normal bignum arithmetic -operations. - -BN_ULONG BN_mod_word(BIGNUM *a, unsigned long w); - Return the remainder of 'a' divided by 'w'. - This is return(a%w). - -int BN_add_word(BIGNUM *a, unsigned long w); - Add 'w' to 'a'. This function does not take the sign of 'a' into - account. This is a+=w; - -Bit operations. - -int BN_is_bit_set(BIGNUM *a, int n); - This function return 1 if bit 'n' is set in 'a' else 0. - -int BN_set_bit(BIGNUM *a, int n); - This function sets bit 'n' to 1 in 'a'. - This is a&= ~(1<