Backport documentation added for 0.9.7.

=head1 NAME

SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version,

SSL_CIPHER_description - get SSL_CIPHER properties

SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties

=head1 SYNOPSIS

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.

128 bytes, otherwise a pointer to the 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, a pointer to the string

"OPENSSL_malloc Error" is returned.

=head1 NOTES

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.

The string returned by SSL_CIPHER_description() in case of success consists

of cleartext information seperated by one or more blanks in the following

sequence:

=over 4

=item <ciphername>

Textual representation of the cipher name.

=item <protocol version>

Protocol version: B<SSLv2>, B<SSLv3>. The TLSv1 ciphers are flagged with SSLv3.

=item Kx=<key exchange>

Key exchange method: B<RSA> (for export ciphers as B<RSA(512)> or

B<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>),

B<DH/RSA>, B<DH/DSS>, B<Fortezza>.

=item Au=<authentication>

Authentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the

representation of anonymous ciphers.

=item Enc=<symmectric encryption method>

Encryption method with number of secret bits: B<DES(40)>, B<DES(56)>,

B<3DES(168)>, B<RC4(40)>, B<RC4(56)>, B<RC4(64)>, B<RC4(128)>,

B<RC2(40)>, B<RC2(56)>, B<RC2(128)>, B<IDEA(128)>, B<Fortezza>, B<None>.

=item Mac=<message authentication code>

Message digest: B<MD5>, B<SHA1>.

=item <export flag>

If the cipher is flagged exportable with respect to old US crypto

regulations, the word "B<export>" is printed.

=back

=head1 EXAMPLES

Some examples for the output of SSL_CIPHER_description():

 EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1

 EDH-DSS-DES-CBC3-SHA    SSLv3 Kx=DH       Au=DSS  Enc=3DES(168) Mac=SHA1

 RC4-MD5                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5

 EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export

=head1 BUGS

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

library crashes.

If SSL_CIPHER_description() cannot handle a built-in cipher, the according

description of the cipher property is B<unknown>. This case should not

occur.

=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)>

L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)>

=cut

If B<CApath> is not NULL, it points to a directory containing CA certificates

in PEM format. The files each contain one CA certificate. The files are

looked up by the CA subject name hash value, which must hence be available.

If more than one CA certificate with the same name hash value exist, the

extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search

is performed in the ordering of the extension number, regardless of other

properties of the certificates.

Use the B<c_rehash> utility to create the necessary links.

The certificates in B<CAfile> are only looked up when required, e.g. when

The certificates in B<CApath> are only looked up when required, e.g. when

building the certificate chain or when actually performing the verification

of a peer certificate.

On a server, the certificates in B<CApath> are not listed as available

CA certificates to a client during a TLS/SSL handshake.

When looking up CA certificates, the OpenSSL library will first search the

certificates in B<CAfile>, then those in B<CApath>. Certificate matching

is done based on the subject name, the key identifier (if present), and the

serial number as taken from the certificate to be verified. If these data

do not match, the next certificate will be tried. If a first certificate

matching the parameters is found, the verification process will be performed;

no other certificates for the same parameters will be searched in case of

failure.

When building its own certificate chain, an OpenSSL client/server will

try to fill in missing certificates from B<CAfile>/B<CApath>, if the

certificate chain was not explicitely specified (see

L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,

L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>.

=head1 WARNINGS

If several CA certificates matching the name, key identifier, and serial

number condition are available, only the first one will be examined. This

may lead to unexpected results if the same CA certificate is available

with different expiration dates. If a "certificate expired" verification

error occurs, no other certificate will be searched. Make sure to not

have expired certificates mixed with valid ones.

=head1 EXAMPLES

Generate a CA certificate file with descriptive text from the CA certificates

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

L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,

L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>

L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,

L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,

L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>

=cut

=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void)

A TLS/SSL connection established with these methods will only understand the

SSLv3 and TLSv1 protocol. A client will send out SSLv3 client hello messages

and will indicate that it also understands TLSv1. A server will only understand

SSLv3 and TLSv1 client hello messages. This especially means, that it will

SSLv3 protocol. A client will send out SSLv3 client hello messages

and will indicate that it only understands SSLv3. A server will only understand

SSLv3 client hello messages. This especially means, that it will

not understand SSLv2 client hello messages which are widely used for

compatibility reasons, see SSLv23_*_method().

and will indicate that it only understands TLSv1. A server will only understand

TLSv1 client hello messages. This especially means, that it will

not understand SSLv2 client hello messages which are widely used for

compatibility reasons, see SSLv23_*_method().

compatibility reasons, see SSLv23_*_method(). It will also not understand

SSLv3 client hello messages.

=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)

=head1 NAME

SSL_CTX_set_cipher_list, SSL_set_cipher_list 

- choose list of available SSL_CIPHERs

SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs

=head1 SYNOPSIS

=head1 SEE ALSO

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

L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,

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

=cut

by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the

return value B<ret> to find out the reason.

=item -1

=item E<lt>0

The TLS/SSL handshake was not successful, because a fatal error occurred either

at the protocol level or a connection failure occurred. The shutdown was