This commit was manufactured by cvs2svn to create branch 'BRANCH_engine'.

=pod

=head1 NAME

BIO_f_buffer - buffering BIO

=head1 SYNOPSIS

 #include <openssl/bio.h>

 BIO_METHOD * BIO_f_buffer(void);

 #define BIO_get_buffer_num_lines(b)	BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL)

 #define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0)

 #define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1)

 #define BIO_set_buffer_size(b,size)	BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL)

 #define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf)

=head1 DESCRIPTION

BIO_f_buffer() returns the buffering BIO method.

Data written to a buffering BIO is buffered and periodically written

to the next BIO in the chain. Data read from a buffering BIO comes from

an internal buffer which is filled from the next BIO in the chain.

Both BIO_gets() and BIO_puts() are supported.

Calling BIO_reset() on a buffering BIO clears any buffered data.

BIO_get_buffer_num_lines() returns the number of lines currently buffered.

BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()

set the read, write or both read and write buffer sizes to B<size>. The initial

buffer size is DEFAULT_BUFFER_SIZE, currently 1024. Any attempt to reduce the

buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared

when the buffer is resized.

BIO_set_buffer_read_data() clears the read buffer and fills it with B<num>

bytes of B<buf>. If B<num> is larger than the current buffer size the buffer

is expanded.

=head1 NOTES

Buffering BIOs implement BIO_gets() by using BIO_read() operations on the

next BIO in the chain. By prepending a buffering BIO to a chain it is therefore

possible to provide BIO_gets() functionality if the following BIOs do not

support it (for example SSL BIOs).

Data is only written to the next BIO in the chain when the write buffer fills

or when BIO_flush() is called. It is therefore important to call BIO_flush()

whenever any pending data should be written such as when removing a buffering

BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate

source/sink BIO is non blocking.

=head1 RETURN VALUES

BIO_f_buffer() returns the buffering BIO method.

BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0).

BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()

return 1 if the buffer was successfully resized or 0 for failure.

BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if

there was an error.

=head1 SEE ALSO

TBA

=pod

=head1 NAME

SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version,

SSL_CIPHER_description - get SSL_CIPHER properties

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 const char *SSL_CIPHER_get_name(SSL_CIPHER *cipher);

 int SSL_CIPHER_get_bits(SSL_CIPHER *cipher, int *alg_bits);

 char *SSL_CIPHER_get_version(SSL_CIPHER *cipher);

 char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int size);

=head1 DESCRIPTION

SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the

argument is the NULL pointer, a pointer to the constant value "NONE" is

returned.

SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If

B<alg_bits> is not NULL, it contains the number of bits processed by the

chosen algorithm. If B<cipher> is NULL, 0 is returned.

SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently

"SSLv2", "SSLv3", or "TLSv1". If B<cipher> is NULL, "(NONE)" is returned.

SSL_CIPHER_description() returns a textual description of the cipher used

into the buffer B<buf> of length B<len> provided. B<len> must be at least

128 bytes, otherwise the string "Buffer too small" is returned. If B<buf>

is NULL, a buffer of 128 bytes is allocated using OPENSSL_malloc(). If the

allocation fails, the string "OPENSSL_malloc Error" is returned.

=head1 NOTES

The number of bits processed can be different from the secret bits. An

export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm

does use the full 128 bits (which would be returned for B<alg_bits>), of

which however 88bits are fixed. The search space is hence only 40 bits.

=head1 BUGS

If SSL_CIPHER_description() is called with B<cipher> being NULL, the

library crashes.

=head1 RETURN VALUES

See DESCRIPTION

=head1 SEE ALSO

L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>,

L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>

=cut

=pod

=head1 NAME

SSL_CTX_set_cipher_list, SSL_set_cipher_list 

- choose list of available SSL_CIPHERs

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);

 int SSL_set_cipher_list(SSL *ssl, const char *str);

=head1 DESCRIPTION

SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx>

using the control string B<str>. The format of the string is described

in L<ciphers(1)|ciphers(1)>. The list of ciphers is inherited by all

B<ssl> objects created from B<ctx>.

SSL_set_cipher_list() sets the list of ciphers only for B<ssl>.

=head1 NOTES

The control string B<str> should be universally usable and not depend

on details of the library configuration (ciphers compiled in). Thus no

syntax checking takes place. Items that are not recognized, because the

corresponding ciphers are not compiled in or because they are mistyped,

are simply ignored. Failure is only flagged if no ciphers could be collected

at all.

It should be noted, that inclusion of a cipher to be used into the list is

a necessary condition. On the client side, the inclusion into the list is

also sufficient. On the server side, additional restrictions apply. All ciphers

have additional requirements. ADH ciphers don't need a certificate, but

DH-parameters must have been set. All other ciphers need a corresponding

certificate and key. A RSA cipher can only be chosen, when a RSA certificate is

available, the respective is valid for DSA ciphers. Ciphers using EDH need

a certificate and key and DH-parameters.

=head1 RETURN VALUES

SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher

could be selected and 0 on complete failure.

=head1 SEE ALSO

L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,

L<ciphers(1)|ciphers(1)>

=cut

=pod

=head1 NAME

SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 STACK_OF(SSL_CIPHER) *SSL_get_ciphers(SSL *ssl);

 const char *SSL_get_cipher_list(SSL *ssl, int priority);

=head1 DESCRIPTION

SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>,

sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL

is returned.

SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER

listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are

available, or there are less ciphers than B<priority> available, NULL

is returned.

=head1 NOTES

The details of the ciphers obtained by SSL_get_ciphers() can be obtained using

the L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> family of functions.

Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the

sorted list of available ciphers, until NULL is returned.

=head1 RETURN VALUES

See DESCRIPTION

=head1 SEE ALSO

L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,

L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>

=cut

=pod

=head1 NAME

SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name,

SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 SSL_CIPHER *SSL_get_current_cipher(SSL *ssl);

 #define SSL_get_cipher(s) \

                SSL_CIPHER_get_name(SSL_get_current_cipher(s))

 #define SSL_get_cipher_name(s) \

                SSL_CIPHER_get_name(SSL_get_current_cipher(s))

 #define SSL_get_cipher_bits(s,np) \

                SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np)

 #define SSL_get_cipher_version(s) \

                SSL_CIPHER_get_version(SSL_get_current_cipher(s))

=head1 DESCRIPTION

SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing

the description of the actually used cipher of a connection established with

the B<ssl> object.

SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the

name of the currently used cipher. SSL_get_cipher_bits() is a

macro to obtain the number of secret/algorithm bits used and 

SSL_get_cipher_version() returns the protocol name.

See L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> for more details.

=head1 RETURN VALUES

SSL_get_current_cipher() returns the cipher actually used or NULL, when

no session has been established.

=head1 SEE ALSO

L<ssl(3)|ssl(3)>, L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>

=cut