ssleay.txt

mediastreamer2是开源的网络传输媒体流的库

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.


==== blowfish.doc ========================================================

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.


==== bn.doc ========================================================

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 h