From d02b48c63a58ea4367a0e905979f140b7d090f86 Mon Sep 17 00:00:00 2001 From: "Ralf S. Engelschall" Date: Mon, 21 Dec 1998 10:52:47 +0000 Subject: Import of old SSLeay release: SSLeay 0.8.1b --- doc/API.doc | 24 +++ doc/a_verify.doc | 85 ++++++++++ doc/apps.doc | 53 ++++++ doc/asn1.doc | 401 +++++++++++++++++++++++++++++++++++++++++++ doc/bio.doc | 423 ++++++++++++++++++++++++++++++++++++++++++++++ doc/blowfish.doc | 149 ++++++++++++++++ doc/bn.doc | 379 +++++++++++++++++++++++++++++++++++++++++ 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 | 133 +++++++++++++++ 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/ssluse.doc | 45 +++++ doc/stack.doc | 96 +++++++++++ doc/threads.doc | 90 ++++++++++ doc/txt_db.doc | 4 + doc/verify | 22 +++ doc/why.doc | 79 +++++++++ 49 files changed, 6476 insertions(+) create mode 100644 doc/API.doc create mode 100644 doc/a_verify.doc create mode 100644 doc/apps.doc create mode 100644 doc/asn1.doc create mode 100644 doc/bio.doc create mode 100644 doc/blowfish.doc create mode 100644 doc/bn.doc create mode 100644 doc/ca.1 create mode 100644 doc/callback.doc create mode 100644 doc/cipher.doc create mode 100644 doc/cipher.m create mode 100644 doc/conf.doc create mode 100644 doc/danger create mode 100644 doc/des.doc create mode 100644 doc/digest.doc create mode 100644 doc/encode.doc create mode 100644 doc/envelope.doc create mode 100644 doc/error.doc create mode 100644 doc/idea.doc create mode 100644 doc/legal.doc create mode 100644 doc/lhash.doc create mode 100644 doc/md2.doc create mode 100644 doc/md5.doc create mode 100644 doc/memory.doc create mode 100644 doc/ms3-ca.doc create mode 100644 doc/ns-ca.doc create mode 100644 doc/obj.doc create mode 100644 doc/rand.doc create mode 100644 doc/rc2.doc create mode 100644 doc/rc4.doc create mode 100644 doc/readme create mode 100644 doc/ref.doc create mode 100644 doc/req.1 create mode 100644 doc/rsa.doc create mode 100644 doc/rsaref.doc create mode 100644 doc/s_mult.doc create mode 100644 doc/session.doc create mode 100644 doc/sha.doc create mode 100644 doc/speed.doc create mode 100644 doc/ssl-ciph.doc create mode 100644 doc/ssl.doc create mode 100644 doc/ssl_ctx.doc create mode 100644 doc/ssleay.doc create mode 100644 doc/ssluse.doc create mode 100644 doc/stack.doc create mode 100644 doc/threads.doc create mode 100644 doc/txt_db.doc create mode 100644 doc/verify create mode 100644 doc/why.doc (limited to 'doc') diff --git a/doc/API.doc b/doc/API.doc new file mode 100644 index 0000000000..fe2820259a --- /dev/null +++ b/doc/API.doc @@ -0,0 +1,24 @@ +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/a_verify.doc b/doc/a_verify.doc new file mode 100644 index 0000000000..06eec17c2b --- /dev/null +++ b/doc/a_verify.doc @@ -0,0 +1,85 @@ +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 new file mode 100644 index 0000000000..3a7291f371 --- /dev/null +++ b/doc/blowfish.doc @@ -0,0 +1,149 @@ +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, +int encrypt); + This is 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. Encryption or decryption is indicated by 'encrypt'. + which can have the values BF_ENCRYPT or BF_DECRYPT. + +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 new file mode 100644 index 0000000000..2358c20f45 --- /dev/null +++ b/doc/bn.doc @@ -0,0 +1,379 @@ +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'. Return 0 if less than + 'n' bits in 'a', else 1. This is a&= ~(1<