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

6 files changed, 315 insertions, 0 deletions

diff --git a/doc/crypto/BIO_f_buffer.pod b/doc/crypto/BIO_f_buffer.pod
new file mode 100644
index 0000000000..c9093c6a57
--- /dev/null
+++ b/doc/crypto/BIO_f_buffer.pod
@@ -0,0 +1,69 @@
+=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
diff --git a/doc/ssl/SSL_CIPHER_get_name.pod b/doc/ssl/SSL_CIPHER_get_name.pod
new file mode 100644
index 0000000000..7fea14ee68
--- /dev/null
+++ b/doc/ssl/SSL_CIPHER_get_name.pod
@@ -0,0 +1,57 @@
+=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
diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod
new file mode 100644
index 0000000000..272d6b3de2
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_cipher_list.pod
@@ -0,0 +1,52 @@
+=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
diff --git a/doc/ssl/SSL_get_ciphers.pod b/doc/ssl/SSL_get_ciphers.pod
new file mode 100644
index 0000000000..2a57455c23
--- /dev/null
+++ b/doc/ssl/SSL_get_ciphers.pod
@@ -0,0 +1,42 @@
+=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
diff --git a/doc/ssl/SSL_get_current_cipher.pod b/doc/ssl/SSL_get_current_cipher.pod
new file mode 100644
index 0000000000..2dd7261d89
--- /dev/null
+++ b/doc/ssl/SSL_get_current_cipher.pod
@@ -0,0 +1,43 @@
+=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
diff --git a/doc/ssl/SSL_library_init.pod b/doc/ssl/SSL_library_init.pod
new file mode 100644
index 0000000000..bf2a94c760
--- /dev/null
+++ b/doc/ssl/SSL_library_init.pod
@@ -0,0 +1,52 @@
+=pod
+
+=head1 NAME
+
+SSL_library_init, OpenSSL_add_ssl_algorithms, SSLeay_add_ssl_algorithms
+- initialize SSL library by registering algorithms
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_library_init(void);
+ #define OpenSSL_add_ssl_algorithms()    SSL_library_init()
+ #define SSLeay_add_ssl_algorithms()     SSL_library_init()
+
+=head1 DESCRIPTION
+
+SSL_library_init() registers the available ciphers and digests.
+
+OpenSSL_add_ssl_algorithms() and SSLeay_add_ssl_algorithms() are synonyms
+for SSL_library_init().
+
+=head1 NOTES
+
+SSL_library_init() must be called before any other action takes place.
+
+=head1 IMPORTANT
+
+SSL_library_init() only registers ciphers. Another important initialization
+is the seeding of the PRNG (Pseudo Random Number Generator), which has to
+be performed separately.
+
+=head1 EXAMPLES
+
+A typical TLS/SSL application will start with the library initialization,
+will provide readable error messages and will seed the PRNG.
+
+ SSL_load_error_strings();                /* readable error messages */
+ SSL_library_init();                      /* initialize library */
+ actions_to_seed_PRNG(); 
+
+=head1 RETURN VALUES
+
+SSL_library_init() always returns "1", so it is safe to discard the return
+value.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>,
+L<RAND_add(3)|RAND_add(3)>
+
+=cut