Backport documentation added for 0.9.7.
This commit is contained in:
Lutz Jänicke
parent
943f8a46a4
commit
c032563a0a
7 changed files with 183 additions and 62 deletions
|
|
@ -2,8 +2,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
|
||||
|
||||
|
|
@ -29,9 +28,10 @@ SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -40,11 +40,66 @@ 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.
|
||||
|
||||
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
|
||||
|
|
@ -52,6 +107,6 @@ 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
|
||||
|
|
|
|||
|
|
@ -40,15 +40,43 @@ as available CAs during the TLS/SSL handshake.
|
|||
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
|
||||
|
|
@ -88,6 +116,9 @@ The operation succeeded.
|
|||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -33,9 +33,9 @@ understand SSLv2 client hello messages.
|
|||
=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().
|
||||
|
||||
|
|
@ -46,7 +46,8 @@ TLSv1 protocol. A client will send out TLSv1 client hello messages
|
|||
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)
|
||||
|
||||
|
|
|
|||
|
|
@ -2,8 +2,7 @@
|
|||
|
||||
=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
|
||||
|
||||
|
|
@ -47,6 +46,7 @@ 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<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
|
||||
L<ciphers(1)|ciphers(1)>
|
||||
|
||||
=cut
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ The TLS/SSL handshake was not successful but was shut down controlled and
|
|||
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
|
||||
|
|
@ -64,6 +64,6 @@ to find out the reason.
|
|||
=head1 SEE ALSO
|
||||
|
||||
L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>,
|
||||
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
|
||||
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
|
||||
|
||||
=cut
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
=head1 NAME
|
||||
|
||||
SSL_read - write bytes to a TLS/SSL connection.
|
||||
SSL_write - write bytes to a TLS/SSL connection.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
|
|
@ -31,7 +31,7 @@ when the underlying BIO could not satisfy the needs of SSL_write()
|
|||
to continue the operation. In this case a call to SSL_get_error() with the
|
||||
return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or
|
||||
B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
|
||||
call to SSL_write() can also cause write operations! The calling process
|
||||
call to SSL_write() can also cause read operations! The calling process
|
||||
then must repeat the call after taking appropriate action to satisfy the
|
||||
needs of SSL_write(). The action depends on the underlying BIO. When using a
|
||||
non-blocking socket, nothing is to be done, but select() can be used to check
|
||||
|
|
@ -62,7 +62,7 @@ value B<ret> to find out, whether an error occurred.
|
|||
|
||||
=item E<lt>0
|
||||
|
||||
The read operation was not successful, because either an error occurred
|
||||
The write operation was not successful, because either an error occurred
|
||||
or action must be taken by the calling process. Call SSL_get_error() with the
|
||||
return value B<ret> to find out the reason.
|
||||
|
||||
|
|
|
|||
120
doc/ssl/ssl.pod
120
doc/ssl/ssl.pod
|
|
@ -13,6 +13,69 @@ The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and
|
|||
Transport Layer Security (TLS v1) protocols. It provides a rich API which is
|
||||
documented here.
|
||||
|
||||
At first the library must be initialized; see
|
||||
L<SSL_library_init(3)|SSL_library_init(3)>.
|
||||
|
||||
Then an B<SSL_CTX> object is created as a framework to establish
|
||||
TLS/SSL enabled connections (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>).
|
||||
Various options regarding certificates, algorithms etc. can be set
|
||||
in this object.
|
||||
|
||||
When a network connection has been created, it can be assigned to an
|
||||
B<SSL> object. After the B<SSL> object has been created using
|
||||
L<SSL_new(3)|SSL_new(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)> or
|
||||
L<SSL_set_bio(3)|SSL_set_bio(3)> can be used to associate the network
|
||||
connection with the object.
|
||||
|
||||
Then the TLS/SSL handshake is performed using
|
||||
L<SSL_accept(3)|SSL_accept(3)> or L<SSL_connect(3)|SSL_connect(3)>
|
||||
respectively.
|
||||
L<SSL_read(3)|SSL_read(3)> and L<SSL_write(3)|SSL_write(3)> are used
|
||||
to read and write data on the TLS/SSL connection.
|
||||
L<SSL_shutdown(3)|SSL_shutdown(3)> can be used to shut down the
|
||||
TLS/SSL connection.
|
||||
|
||||
=head1 DATA STRUCTURES
|
||||
|
||||
Currently the OpenSSL B<ssl> library functions deals with the following data
|
||||
structures:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<SSL_METHOD> (SSL Method)
|
||||
|
||||
That's a dispatch structure describing the internal B<ssl> library
|
||||
methods/functions which implement the various protocol versions (SSLv1, SSLv2
|
||||
and TLSv1). It's needed to create an B<SSL_CTX>.
|
||||
|
||||
=item B<SSL_CIPHER> (SSL Cipher)
|
||||
|
||||
This structure holds the algorithm information for a particular cipher which
|
||||
are a core part of the SSL/TLS protocol. The available ciphers are configured
|
||||
on a B<SSL_CTX> basis and the actually used ones are then part of the
|
||||
B<SSL_SESSION>.
|
||||
|
||||
=item B<SSL_CTX> (SSL Context)
|
||||
|
||||
That's the global context structure which is created by a server or client
|
||||
once per program life-time and which holds mainly default values for the
|
||||
B<SSL> structures which are later created for the connections.
|
||||
|
||||
=item B<SSL_SESSION> (SSL Session)
|
||||
|
||||
This is a structure containing the current TLS/SSL session details for a
|
||||
connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
|
||||
|
||||
=item B<SSL> (SSL Connection)
|
||||
|
||||
That's the main SSL/TLS structure which is created by a server or client per
|
||||
established connection. This actually is the core structure in the SSL API.
|
||||
Under run-time the application usually deals with this structure which has
|
||||
links to mostly all other structures.
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 HEADER FILES
|
||||
|
||||
Currently the OpenSSL B<ssl> library provides the following C header files
|
||||
|
|
@ -55,46 +118,6 @@ it's already included by ssl.h>.
|
|||
|
||||
=back
|
||||
|
||||
=head1 DATA STRUCTURES
|
||||
|
||||
Currently the OpenSSL B<ssl> library functions deals with the following data
|
||||
structures:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<SSL_METHOD> (SSL Method)
|
||||
|
||||
That's a dispatch structure describing the internal B<ssl> library
|
||||
methods/functions which implement the various protocol versions (SSLv1, SSLv2
|
||||
and TLSv1). It's needed to create an B<SSL_CTX>.
|
||||
|
||||
=item B<SSL_CIPHER> (SSL Cipher)
|
||||
|
||||
This structure holds the algorithm information for a particular cipher which
|
||||
are a core part of the SSL/TLS protocol. The available ciphers are configured
|
||||
on a B<SSL_CTX> basis and the actually used ones are then part of the
|
||||
B<SSL_SESSION>.
|
||||
|
||||
=item B<SSL_CTX> (SSL Context)
|
||||
|
||||
That's the global context structure which is created by a server or client
|
||||
once per program life-time and which holds mainly default values for the
|
||||
B<SSL> structures which are later created for the connections.
|
||||
|
||||
=item B<SSL_SESSION> (SSL Session)
|
||||
|
||||
This is a structure containing the current TLS/SSL session details for a
|
||||
connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
|
||||
|
||||
=item B<SSL> (SSL Connection)
|
||||
|
||||
That's the main SSL/TLS structure which is created by a server or client per
|
||||
established connection. This actually is the core structure in the SSL API.
|
||||
Under run-time the application usually deals with this structure which has
|
||||
links to mostly all other structures.
|
||||
|
||||
=back
|
||||
|
||||
=head1 API FUNCTIONS
|
||||
|
||||
Currently the OpenSSL B<ssl> library exports 214 API functions.
|
||||
|
|
@ -626,13 +649,23 @@ connection defined in the B<SSL> structure.
|
|||
L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>,
|
||||
L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>,
|
||||
L<SSL_connect(3)|SSL_connect(3)>,
|
||||
L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>,
|
||||
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
|
||||
L<SSL_CTX_get_ex_new_index(3)|SSL_CTX_get_ex_new_index(3)>,
|
||||
L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>,
|
||||
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
|
||||
L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
|
||||
L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
|
||||
L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
|
||||
L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,
|
||||
L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>,
|
||||
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
|
||||
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
|
||||
L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,
|
||||
L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
|
||||
L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_get_fd(3)|SSL_get_fd(3)>,
|
||||
L<SSL_get_error(3)|SSL_get_error(3)>,
|
||||
L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
|
||||
L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>,
|
||||
L<SSL_get_fd(3)|SSL_get_fd(3)>,
|
||||
L<SSL_get_peer_cert_chain(3)|SSL_get_peer_cert_chain(3)>,
|
||||
L<SSL_get_rbio(3)|SSL_get_rbio(3)>,
|
||||
L<SSL_get_session(3)|SSL_get_session(3)>,
|
||||
|
|
@ -644,7 +677,8 @@ L<SSL_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>,
|
|||
L<SSL_set_fd(3)|SSL_set_fd(3)>, L<SSL_pending(3)|SSL_pending(3)>,
|
||||
L<SSL_set_session(3)|SSL_set_session(3)>,
|
||||
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_write(3)|SSL_write(3)>,
|
||||
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
|
||||
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
|
||||
L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue