generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

This commit was manufactured by cvs2svn to create branch 'OpenSSL-engine-

Browse Source 
0_9_6-stable'.
This commit is contained in:
cvs2svn 2001-02-23 21:05:57 +00:00
commit cd9bed6d1d
31 changed files with 2453 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
certs/expired/rsa-ssca.pem Normal file
View File

@ -0,0 +1,19 @@
subject=/C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority
issuer= /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority
notBefore=941109235417Z
notAfter =991231235417Z
-----BEGIN X509 CERTIFICATE-----
MIICKTCCAZYCBQJBAAABMA0GCSqGSIb3DQEBAgUAMF8xCzAJBgNVBAYTAlVTMSAw
HgYDVQQKExdSU0EgRGF0YSBTZWN1cml0eSwgSW5jLjEuMCwGA1UECxMlU2VjdXJl
IFNlcnZlciBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw05NDExMDkyMzU0MTda
Fw05OTEyMzEyMzU0MTdaMF8xCzAJBgNVBAYTAlVTMSAwHgYDVQQKExdSU0EgRGF0
YSBTZWN1cml0eSwgSW5jLjEuMCwGA1UECxMlU2VjdXJlIFNlcnZlciBDZXJ0aWZp
Y2F0aW9uIEF1dGhvcml0eTCBmzANBgkqhkiG9w0BAQEFAAOBiQAwgYUCfgCSznrB
roM+WqqJg1esJQF2DK2ujiw3zus1eGRUA+WEQFHJv48I4oqCCNIWhjdV6bEhAq12
aIGaBaJLyUslZiJWbIgHj/eBWW2EB2VwE3F2Ppt3TONQiVaYSLkdpykaEy5KEVmc
HhXVSVQsczppgrGXOZxtcGdI5d0t1sgeewIDAQABMA0GCSqGSIb3DQEBAgUAA34A
iNHReSHO4ovo+MF9NFM/YYPZtgs4F7boviGNjwC4i1N+RGceIr2XJ+CchcxK9oU7
suK+ktPlDemvXA4MRpX/oRxePug2WHpzpgr4IhFrwwk4fia7c+8AvQKk8xQNMD9h
cHsg/jKjn7P0Z1LctO6EjJY2IN6BCINxIYoPnqk=
-----END X509 CERTIFICATE-----

88
crypto/uid.c Normal file
View File

@ -0,0 +1,88 @@
/* crypto/uid.c */
/* ====================================================================
* Copyright (c) 2001 The OpenSSL Project. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. All advertising materials mentioning features or use of this
* software must display the following acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)"
*
* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
* endorse or promote products derived from this software without
* prior written permission. For written permission, please contact
* licensing@OpenSSL.org.
*
* 5. Products derived from this software may not be called "OpenSSL"
* nor may "OpenSSL" appear in their names without prior written
* permission of the OpenSSL Project.
*
* 6. Redistributions of any form whatsoever must retain the following
* acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)"
*
* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
* ====================================================================
*
* This product includes cryptographic software written by Eric Young
* (eay@cryptsoft.com). This product includes software written by Tim
* Hudson (tjh@cryptsoft.com).
*
*/
#include <openssl/crypto.h>
#if defined(__OpenBSD__) || (defined(__FreeBSD__) && __FreeBSD__ > 2)
#include <unistd.h>
int OPENSSL_issetugid(void)
{
return issetugid();
}
#elif defined(OPENSSL_SYS_WIN32)
int OPENSSL_issetugid(void)
{
return 0;
}
#else
#include <unistd.h>
#include <sys/types.h>
int OPENSSL_issetugid(void)
{
if (getuid() != geteuid()) return 1;
if (getgid() != getegid()) return 1;
return 0;
}
#endif

38
doc/ssl/SSL_CTX_add_extra_chain_cert.pod Normal file
View File

@ -0,0 +1,38 @@
=pod
=head1 NAME
SSL_CTX_add_extra_chain_cert - add certificate to chain
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509)
=head1 DESCRIPTION
SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the certificate
chain presented together with the certificate. Several certificates
can be added one after the other.
=head1 NOTES
When constructing the certificate chain, the chain will be formed from
these certificates explicitly specified. If no chain is specified,
the library will try to complete the chain from the available CA
certificates in the trusted CA storage, see
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
=head1 RETURN VALUES
SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the
error stack to find out the reason for failure otherwise.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
=cut

65
doc/ssl/SSL_CTX_add_session.pod Normal file
View File

@ -0,0 +1,65 @@
=pod
=head1 NAME
SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
=head1 DESCRIPTION
SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The
reference count for session B<c> is incremented by 1. If a session with
the same session id already exists, the old session is removed by calling
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>.
SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>.
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> is called once for B<c>.
SSL_add_session() and SSL_remove_session() are synonyms for their
SSL_CTX_*() counterparts.
=head1 NOTES
When adding a new session to the internal session cache, it is examined
whether a session with the same session id already exists. In this case
it is assumed that both sessions are identical. If the same session is
stored in a different SSL_SESSION object, The old session is
removed and replaced by the new session. If the session is actually
identical (the SSL_SESSION object is identical), SSL_CTX_add_session()
is a no-op, and the return value is 0.
=head1 RETURN VALUES
The following values are returned by all functions:
=over 4
=item 0
The operation failed. In case of the add operation, it was tried to add
the same (identical) session twice. In case of the remove operation, the
session was not found in the cache.
=item 1
The operation succeeded.
=back
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
=cut

49
doc/ssl/SSL_CTX_flush_sessions.pod Normal file
View File

@ -0,0 +1,49 @@
=pod
=head1 NAME
SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm);
void SSL_flush_sessions(SSL_CTX *ctx, long tm);
=head1 DESCRIPTION
SSL_CTX_flush_sessions() causes a run through the session cache of
B<ctx> to remove sessions expired at time B<tm>.
SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions().
=head1 NOTES
If enabled, the internal session cache will collect all sessions established
up to the specified maximum number (see SSL_CTX_sess_set_cache_size()).
As sessions will not be reused ones they are expired, they should be
removed from the cache to save resources. This can either be done
automatically whenever 255 new sessions were established (see
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>)
or manually by calling SSL_CTX_flush_sessions().
The parameter B<tm> specifies the time which should be used for the
expiration test, in most cases the actual time given by time(0)
will be used.
SSL_CTX_flush_sessions() will only check sessions stored in the internal
cache. When a session is found and removed, the remove_session_cb is however
called to synchronize with the external cache (see
L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>).
=head1 RETURN VALUES
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>,
L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>
=cut

53
doc/ssl/SSL_CTX_get_ex_new_index.pod Normal file
View File

@ -0,0 +1,53 @@
=pod
=head1 NAME
SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data - internal application specific data functions
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *arg);
void *SSL_CTX_get_ex_data(SSL_CTX *ctx, int idx);
typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
int idx, long argl, void *argp);
=head1 DESCRIPTION
Several OpenSSL structures can have application specific data attached to them.
These functions are used internally by OpenSSL to manipulate application
specific data attached to a specific structure.
SSL_CTX_get_ex_new_index() is used to register a new index for application
specific data.
SSL_CTX_set_ex_data() is used to store application data at B<arg> for B<idx>
into the B<ctx> object.
SSL_CTX_get_ex_data() is used to retrieve the information for B<idx> from
B<ctx>.
A detailed description for the B<*_get_ex_new_index()> functionality
can be found in L<RSA_get_ex_new_index.pod(3)|RSA_get_ex_new_index.pod(3)>.
The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in
L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
=cut

50
doc/ssl/SSL_CTX_get_verify_mode.pod Normal file
View File

@ -0,0 +1,50 @@
=pod
=head1 NAME
SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_get_verify_mode(SSL_CTX *ctx);
int SSL_get_verify_mode(SSL *ssl);
int SSL_CTX_get_verify_depth(SSL_CTX *ctx);
int SSL_get_verify_depth(SSL *ssl);
int (*SSL_CTX_get_verify_callback(SSL_CTX *ctx))(int, X509_STORE_CTX *);
int (*SSL_get_verify_callback(SSL *ssl))(int, X509_STORE_CTX *);
=head1 DESCRIPTION
SSL_CTX_get_verify_mode() returns the verification mode currently set in
B<ctx>.
SSL_get_verify_mode() returns the verification mode currently set in
B<ssl>.
SSL_CTX_get_verify_depth() returns the verification depth limit currently set
in B<ctx>. If no limit has been explicitly set, -1 is returned and the
default value will be used.
SSL_get_verify_depth() returns the verification depth limit currently set
in B<ssl>. If no limit has been explicitly set, -1 is returned and the
default value will be used.
SSL_CTX_get_verify_callback() returns a function pointer to the verification
callback currently set in B<ctx>. If no callback was explicitly set, the
NULL pointer is returned and the default callback will be used.
SSL_get_verify_callback() returns a function pointer to the verification
callback currently set in B<ssl>. If no callback was explicitly set, the
NULL pointer is returned and the default callback will be used.
=head1 RETURN VALUES
See DESCRIPTION
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
=cut

124
doc/ssl/SSL_CTX_load_verify_locations.pod Normal file
View File

@ -0,0 +1,124 @@
=pod
=head1 NAME
SSL_CTX_load_verify_locations - set default locations for trusted CA
certificates
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
const char *CApath);
=head1 DESCRIPTION
SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at
which CA certificates for verification purposes are located. The certificates
available via B<CAfile> and B<CApath> are trusted.
=head1 NOTES
If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
format. The file can contain several CA certificates identified by
-----BEGIN CERTIFICATE-----
... (CA certificate in base64 encoding) ...
-----END CERTIFICATE-----
sequences. Before, between, and after the certificates text is allowed
which can be used e.g. for descriptions of the certificates.
The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()
function.
If on an TLS/SSL server no special setting is performed using *client_CA_list()
functions, the certificates contained in B<CAfile> are listed to the client
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<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 explicitly 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
ca1.pem ca2.pem ca3.pem:
#!/bin/sh
rm CAfile.pem
for i in ca1.pem ca2.pem ca3.pem ; do
openssl x509 -in $i -text >> CAfile.pem
done
Prepare the directory /some/where/certs containing several CA certificates
for use as B<CApath>:
cd /some/where/certs
c_rehash .
=head1 RETURN VALUES
The following return values can occur:
=over 4
=item 0
The operation failed because B<CAfile> and B<CApath> are NULL or the
processing at one of the locations specified failed. Check the error
stack to find out the reason.
=item 1
The operation succeeded.
=back
=head1 SEE ALSO
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_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

76
doc/ssl/SSL_CTX_sess_number.pod Normal file
View File

@ -0,0 +1,76 @@
=pod
=head1 NAME
SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full - obtain session cache statistics
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_sess_number(SSL_CTX *ctx);
long SSL_CTX_sess_connect(SSL_CTX *ctx);
long SSL_CTX_sess_connect_good(SSL_CTX *ctx);
long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx);
long SSL_CTX_sess_accept(SSL_CTX *ctx);
long SSL_CTX_sess_accept_good(SSL_CTX *ctx);
long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx);
long SSL_CTX_sess_hits(SSL_CTX *ctx);
long SSL_CTX_sess_cb_hits(SSL_CTX *ctx);
long SSL_CTX_sess_misses(SSL_CTX *ctx);
long SSL_CTX_sess_timeouts(SSL_CTX *ctx);
long SSL_CTX_sess_cache_full(SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_CTX_sess_number() returns the current number of sessions in the internal
session cache.
SSL_CTX_sess_connect() returns the number of started SSL/TLS handshakes in
client mode.
SSL_CTX_sess_connect_good() returns the number of successfully established
SSL/TLS sessions in client mode.
SSL_CTX_sess_connect_renegotiate() returns the number of start renegotiations
in client mode.
SSL_CTX_sess_accept() returns the number of started SSL/TLS handshakes in
server mode.
SSL_CTX_sess_accept_good() returns the number of successfully established
SSL/TLS sessions in server mode.
SSL_CTX_sess_accept_renegotiate() returns the number of start renegotiations
in server mode.
SSL_CTX_sess_hits() returns the number of successfully reused sessions.
In client mode a session set with L<SSL_set_session(3)|SSL_set_session(3)>
successfully reused is counted as a hit. In server mode a session successfully
retrieved from internal or external cache is counted as a hit.
SSL_CTX_sess_cb_hits() returns the number of successfully retrieved sessions
from the external session cache in server mode.
SSL_CTX_sess_misses() returns the number of sessions proposed by clients
that were not found in the internal session cache in server mode.
SSL_CTX_sess_timeouts() returns the number of sessions proposed by clients
and either found in the internal or external session cache in server mode,
but that were invalid due to timeout. These sessions are not included in
the SSL_CTX_sess_hits() count.
SSL_CTX_sess_cache_full() returns the number of sessions that were removed
because the maximum session cache size was exceeded.
=head1 RETURN VALUES
The functions return the values indicated in the DESCRIPTION section.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>
=cut

51
doc/ssl/SSL_CTX_sess_set_cache_size.pod Normal file
View File

@ -0,0 +1,51 @@
=pod
=head1 NAME
SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t);
long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_CTX_sess_set_cache_size() sets the size of the internal session cache
of context B<ctx> to B<t>.
SSL_CTX_sess_get_cache_size() returns the currently valid session cache size.
=head1 NOTES
The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT,
currently 1024*20, so that up to 20000 sessions can be held. This size
can be modified using the SSL_CTX_sess_set_cache_size() call. A special
case is the size 0, which is used for unlimited size.
When the maximum number of sessions is reached, no more new sessions are
added to the cache. New space may be added by calling
L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> to remove
expired sessions.
If the size of the session cache is reduced and more sessions are already
in the session cache, old session will be removed at the next time a
session shall be added. This removal is not synchronized with the
expiration of sessions.
=head1 RETURN VALUES
SSL_CTX_sess_set_cache_size() returns the previously valid size.
SSL_CTX_sess_get_cache_size() returns the currently valid size.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)>
=cut

81
doc/ssl/SSL_CTX_sess_set_get_cb.pod Normal file
View File

@ -0,0 +1,81 @@
=pod
=head1 NAME
SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
int (*new_session_cb)(SSL *, SSL_SESSION *));
void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *));
int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess);
void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy);
int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess);
void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data,
int len, int *copy);
=head1 DESCRIPTION
SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically
called whenever a new session was negotiated.
SSL_CTX_sess_set_remove_cb() sets the callback function, which is
automatically called whenever a session is removed by the SSL engine,
because it is considered faulty or the session has become obsolete because
of exceeding the timeout value.
SSL_CTX_sess_set_get_cb() sets the callback function which is called,
whenever a SSL/TLS client proposed to resume a session but the session
could not be found in the internal session cache (see
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>).
(SSL/TLS server only.)
SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the
provided callback functions. If a callback function has not been set,
the NULL pointer is returned.
=head1 NOTES
In order to allow external session caching, synchronization with the internal
session cache is realized via callback functions. Inside these callback
functions, session can be saved to disk or put into a database using the
L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface.
The new_session_cb() is called, whenever a new session has been negotiated
and session caching is enabled (see
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>).
The new_session_cb() is passed the B<ssl> connection and the ssl session
B<sess>. If the callback returns B<0>, the session will be immediately
removed again.
The remove_session_cb() is called, whenever the SSL engine removes a session
from the internal cache. This happens if the session is removed because
it is expired or when a connection was not shutdown cleanly. The
remove_session_cb() is passed the B<ctx> and the ssl session B<sess>.
It does not provide any feedback.
The get_session_cb() is only called on SSL/TLS servers with the session id
proposed by the client. The get_session_cb() is always called, also when
session caching was disabled. The get_session_cb() is passed the
B<ssl> connection, the session id of length B<length> at the memory location
B<data>. With the parameter B<copy> the callback can require the
SSL engine to increment the reference count of the SSL_SESSION object.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)>
=cut

34
doc/ssl/SSL_CTX_sessions.pod Normal file
View File

@ -0,0 +1,34 @@
=pod
=head1 NAME
SSL_CTX_sessions - access internal session cache
=head1 SYNOPSIS
#include <openssl/ssl.h>
struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_CTX_sessions() returns a pointer to the lhash databases containing the
internal session cache for B<ctx>.
=head1 NOTES
The sessions in the internal session cache are kept in an
L<lhash(3)|lhash(3)> type database. It is possible to directly
access this database e.g. for searching. In parallel, the sessions
form a linked list which is maintained separately from the
L<lhash(3)|lhash(3)> operations, so that the database must not be
modified directly but by using the
L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)> family of functions.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<lhash(3)|lhash(3)>,
L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
=cut

90
doc/ssl/SSL_CTX_set_client_CA_list.pod Normal file
View File

@ -0,0 +1,90 @@
=pod
=head1 NAME
SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
SSL_add_client_CA - set list of CAs sent to the client when requesting a
client certificate
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
int SSL_add_client_CA(SSL *ssl, X509 *cacert);
=head1 DESCRIPTION
SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
requesting a client certificate for B<ctx>.
SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
requesting a client certificate for the chosen B<ssl>, overriding the
setting valid for B<ssl>'s SSL_CTX object.
SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
list of CAs sent to the client when requesting a client certificate for
B<ctx>.
SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
list of CAs sent to the client when requesting a client certificate for
the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
=head1 NOTES
When a TLS/SSL server requests a client certificate (see
B<SSL_CTX_set_verify_options()>), it sends a list of CAs, for which
it will accept certificates, to the client. If no special list is provided,
the CAs available using the B<CAfile> option in
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
are sent.
This list can be explicitly set using the SSL_CTX_set_client_CA_list() for
B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
specified overrides the previous setting. The CAs listed do not become
trusted (B<list> only contains the names, not the complete certificates); use
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
to additionally load them for verification.
SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
items the list of client CAs. If no list was specified before using
SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
CA list for B<ctx> or B<ssl> (as appropriate) is opened. The CAs implicitly
specified using
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
are no longer used automatically.
These functions are only useful for TLS/SSL servers.
=head1 RETURN VALUES
SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
diagnostic information.
SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
values:
=over 4
=item 1
The operation succeeded.
=item 0
A failure while manipulating the STACK_OF(X509_NAME) object occurred or
the X509_NAME could not be extracted from B<cacert>. Check the error stack
to find out the reason.
=back
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
=cut

70
doc/ssl/SSL_CTX_set_default_passwd_cb.pod Normal file
View File

@ -0,0 +1,70 @@
=pod
=head1 NAME
SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set passwd callback for encrypted PEM file handling
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb);
void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u);
int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata);
=head1 DESCRIPTION
SSL_CTX_set_default_passwd_cb() sets the default password callback called
when loading/storing a PEM certificate with encryption.
SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to B<userdata> which
will be provided to the password callback on invocation.
The pem_passwd_cb(), which must be provided by the application, hands back the
password to be used during decryption. On invocation a pointer to B<userdata>
is provided. The pem_passwd_cb must write the password into the provided buffer
B<buf> which is of size B<size>. The actual length of the password must
be returned to the calling function. B<rwflag> indicates whether the
callback is used for reading/decryption (rwflag=0) or writing/encryption
(rwflag=1).
=head1 NOTES
When loading or storing private keys, a password might be supplied to
protect the private key. The way this password can be supplied may depend
on the application. If only one private key is handled, it can be practical
to have pem_passwd_cb() handle the password dialog interactively. If several
keys have to be handled, it can be practical to ask for the password once,
then keep it in memory and use it several times. In the last case, the
password could be stored into the B<userdata> storage and the
pem_passwd_cb() only returns the password already stored.
Other items in PEM formatting (certificates) can also be encrypted, it is
however not usual, as certificate information is considered public.
=head1 RETURN VALUES
SSL_CTX_set_default_passwd_cb() and SSL_CTX_set_default_passwd_cb_userdata()
do not provide diagnostic information.
=head1 EXAMPLES
The following example returns the password provided as B<userdata> to the
calling function. The password is considered to be a '\0' terminated
string. If the password does not fit into the buffer, the password is
truncated.
int pem_passwd_cb(char *buf, int size, int rwflag, void *password)
{
strncpy(buf, (char *)(password), size);
buf[size - 1] = '\0';
return(strlen(buf));
}
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>
=cut

78
doc/ssl/SSL_CTX_set_mode.pod Normal file
View File

@ -0,0 +1,78 @@
=pod
=head1 NAME
SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_set_mode(SSL_CTX *ctx, long mode);
long SSL_set_mode(SSL *ssl, long mode);
long SSL_CTX_get_mode(SSL_CTX *ctx);
long SSL_get_mode(SSL *ssl);
=head1 DESCRIPTION
SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>.
Options already set before are not cleared.
SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>.
Options already set before are not cleared.
SSL_CTX_get_mode() returns the mode set for B<ctx>.
SSL_get_mode() returns the mode set for B<ssl>.
=head1 NOTES
The following mode changes are available:
=over 4
=item SSL_MODE_ENABLE_PARTIAL_WRITE
Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success
when just a single record has been written). When not set (the default),
SSL_write() will only report success once the complete chunk was written.
=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
Make it possible to retry SSL_write() with changed buffer location
(the buffer contents must stay the same). This is not the default to avoid
the misconception that non-blocking SSL_write() behaves like
non-blocking write().
=item SSL_MODE_AUTO_RETRY
Never bother the application with retries if the transport is blocking.
If a renegotiation take place during normal operation, a
L<SSL_read(3)|SSL_read(3)> or L<SSL_write(3)|SSL_write(3)> would return
with -1 and indicate the need to retry with SSL_ERROR_WANT_READ.
In a non-blocking environment applications must be prepared to handle
incomplete read/write operations.
In a blocking environment, applications are not always prepared to
deal with read/write operations returning without success report. The
flag SSL_MODE_AUTO_RETRY will cause read/write operations to only
return after the handshake and successful completion.
=back
=head1 RETURN VALUES
SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask
after adding B<mode>.
SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_write(3)|SSL_write(3)>
=head1 HISTORY
SSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6.
=cut

193
doc/ssl/SSL_CTX_set_options.pod Normal file
View File

@ -0,0 +1,193 @@
=pod
=head1 NAME
SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_set_options(SSL_CTX *ctx, long options);
long SSL_set_options(SSL *ssl, long options);
long SSL_CTX_get_options(SSL_CTX *ctx);
long SSL_get_options(SSL *ssl);
=head1 DESCRIPTION
SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
Options already set before are not cleared.
SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
Options already set before are not cleared.
SSL_CTX_get_options() returns the options set for B<ctx>.
SSL_get_options() returns the options set for B<ssl>.
=head1 NOTES
The behaviour of the SSL library can be changed by setting several options.
The options are coded as bitmasks and can be combined by a logical B<or>
operation (|). Options can only be added but can never be reset.
During a handshake, the option settings of the SSL object used. When
a new SSL object is created from a context using SSL_new(), the current
option setting is copied. Changes to B<ctx> do not affect already created
SSL objects. SSL_clear() does not affect the settings.
The following B<bug workaround> options are available:
=over 4
=item SSL_OP_MICROSOFT_SESS_ID_BUG
www.microsoft.com - when talking SSLv2, if session-id reuse is
performed, the session-id passed back in the server-finished message
is different from the one decided upon.
=item SSL_OP_NETSCAPE_CHALLENGE_BUG
Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte
challenge but then appears to only use 16 bytes when generating the
encryption keys. Using 16 bytes is ok but it should be ok to use 32.
According to the SSLv3 spec, one should use 32 bytes for the challenge
when operating in SSLv2/v3 compatibility mode, but as mentioned above,
this breaks this server so 16 bytes is the way to go.
=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
ssl3.netscape.com:443, first a connection is established with RC4-MD5.
If it is then resumed, we end up using DES-CBC3-SHA. It should be
RC4-MD5 according to 7.6.1.3, 'cipher_suite'.
Netscape-Enterprise/2.01 (https://merchant.netscape.com) has this bug.
It only really shows up when connecting via SSLv2/v3 then reconnecting
via SSLv3. The cipher list changes....
NEW INFORMATION. Try connecting with a cipher list of just
DES-CBC-SHA:RC4-MD5. For some weird reason, each new connection uses
RC4-MD5, but a re-connect tries to use DES-CBC-SHA. So netscape, when
doing a re-connect, always takes the first cipher in the cipher list.
=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
...
=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
...
=item SSL_OP_MSIE_SSLV2_RSA_PADDING
...
=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG
...
=item SSL_OP_TLS_D5_BUG
...
=item SSL_OP_TLS_BLOCK_PADDING_BUG
...
=item SSL_OP_TLS_ROLLBACK_BUG
Disable version rollback attack detection.
During the client key exchange, the client must send the same information
about acceptable SSL/TLS protocol levels as during the first hello. Some
clients violate this rule by adapting to the server's answer. (Example:
the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
only understands up to SSLv3. In this case the client must still use the
same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
to the server's answer and violate the version rollback protection.)
=item SSL_OP_ALL
All of the above bug workarounds.
=back
It is save and recommended to use SSL_OP_ALL to enable the bug workaround
options.
The following B<modifying> options are available:
=over 4
=item SSL_OP_SINGLE_DH_USE
Always create a new key when using temporary DH parameters.
=item SSL_OP_EPHEMERAL_RSA
Also use the temporary RSA key when doing RSA operations.
=item SSL_OP_CIPHER_SERVER_PREFERENCE
When choosing a cipher, use the server's preferences instead of the client
preferences. When not set, the SSL server will always follow the clients
preferences. When set, the SSLv3/TLSv1 server will choose following its
own preferences. Because of the different protocol, for SSLv2 the server
will send his list of preferences to the client and the client chooses.
=item SSL_OP_PKCS1_CHECK_1
...
=item SSL_OP_PKCS1_CHECK_2
...
=item SSL_OP_NETSCAPE_CA_DN_BUG
If we accept a netscape connection, demand a client cert, have a
non-self-sighed CA which does not have it's CA in netscape, and the
browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta
=item SSL_OP_NON_EXPORT_FIRST
On servers try to use non-export (stronger) ciphers first. This option does
not work under all circumstances (in the code it is declared "broken").
=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
...
=item SSL_OP_NO_SSLv2
Do not use the SSLv2 protocol.
=item SSL_OP_NO_SSLv3
Do not use the SSLv3 protocol.
=item SSL_OP_NO_TLSv1
Do not use the TLSv1 protocol.
=back
=head1 RETURN VALUES
SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
after adding B<options>.
SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>
=head1 HISTORY
SSL_OP_CIPHER_SERVER_PREFERENCE has been added in OpenSSL 0.9.7.
SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6.
=cut

107
doc/ssl/SSL_CTX_set_session_cache_mode.pod Normal file
View File

@ -0,0 +1,107 @@
=pod
=head1 NAME
SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode);
long SSL_CTX_get_session_cache_mode(SSL_CTX ctx);
=head1 DESCRIPTION
SSL_CTX_set_session_cache_mode() enables/disables session caching
by setting the operational mode for B<ctx> to <mode>.
SSL_CTX_get_session_cache_mode() returns the currently used cache mode.
=head1 NOTES
The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
The sessions can be held in memory for each B<ctx>, if more than one
SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
object.
In order to reuse a session, a client must send the session's id to the
server. It can only send exactly one id. The server then decides whether it
agrees in reusing the session or starts the handshake for a new session.
A server will lookup up the session in its internal session storage. If
the session is not found in internal storage or internal storage is
deactivated, the server will try the external storage if available.
Since a client may try to reuse a session intended for use in a different
context, the session id context must be set by the server (see
L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>).
The following session cache modes and modifiers are available:
=over 4
=item SSL_SESS_CACHE_OFF
No session caching for client or server takes place.
=item SSL_SESS_CACHE_CLIENT
Client sessions are added to the session cache. As there is no reliable way
for the OpenSSL library to know whether a session should be reused or which
session to choose (due to the abstract BIO layer the SSL engine does not
have details about the connection), the application must select the session
to be reused by using the L<SSL_set_session(3)|SSL_set_session(3)>
function. This option is not activated by default.
=item SSL_SESS_CACHE_SERVER
Server sessions are added to the session cache. When a client proposes a
session to be reused, the session is looked up in the internal session cache.
If the session is found, the server will try to reuse the session.
This is the default.
=item SSL_SESS_CACHE_BOTH
Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time.
=item SSL_SESS_CACHE_NO_AUTO_CLEAR
Normally the session cache is checked for expired sessions every
255 connections using the
L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> function. Since
this may lead to a delay which cannot be controlled, the automatic
flushing may be disabled and
L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> can be called
explicitly by the application.
=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
By setting this flag sessions are cached in the internal storage but
they are not looked up automatically. If an external session cache
is enabled, sessions are looked up in the external cache. As automatic
lookup only applies for SSL/TLS servers, the flag has no effect on
clients.
=back
The default mode is SSL_SESS_CACHE_SERVER.
=head1 RETURN VALUES
SSL_CTX_set_session_cache_mode() returns the previously set cache mode.
SSL_CTX_get_session_cache_mode() returns the currently set cache mode.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>,
L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>,
L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>,
L<SSL_CTX_set_timeout.pod(3)|SSL_CTX_set_timeout.pod(3)>,
L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>
=cut

82
doc/ssl/SSL_CTX_set_session_id_context.pod Normal file
View File

@ -0,0 +1,82 @@
=pod
=head1 NAME
SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only)
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx,
unsigned int sid_ctx_len);
int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx,
unsigned int sid_ctx_len);
=head1 DESCRIPTION
SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length
B<sid_ctx_len> within which a session can be reused for the B<ctx> object.
SSL_set_session_id_context() sets the context B<sid_ctx> of length
B<sid_ctx_len> within which a session can be reused for the B<ssl> object.
=head1 NOTES
Sessions are generated within a certain context. When exporting/importing
sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible,
to re-import a session generated from another context (e.g. another
application), which might lead to malfunctions. Therefore each application
must set its own session id context B<sid_ctx> which is used to distinguish
the contexts and is stored in exported sessions. The B<sid_ctx> can be
any kind of binary data with a given length, it is therefore possible
to use e.g. the name of the application and/or the hostname and/or service
name ...
The session id context becomes part of the session. The session id context
is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and
SSL_set_session_id_context() functions are therefore only useful on the
server side.
OpenSSL clients will check the session id context returned by the server
when reusing a session.
The maximum length of the B<sid_ctx> is limited to
B<SSL_MAX_SSL_SESSION_ID_LENGTH>.
=head1 WARNINGS
If the session id context is not set on an SSL/TLS server, stored sessions
will not be reused but a fatal error will be flagged and the handshake
will fail.
If a server returns a different session id context to an OpenSSL client
when reusing a session, an error will be flagged and the handshake will
fail. OpenSSL servers will always return the correct session id context,
as an OpenSSL server checks the session id context itself before reusing
a session as described above.
=head1 RETURN VALUES
SSL_CTX_set_session_id_context() and SSL_set_session_id_context()
return the following values:
=over 4
=item 0
The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded
the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error
is logged to the error stack.
=item 1
The operation succeeded.
=back
=head1 SEE ALSO
L<ssl(3)|ssl(3)>
=cut

55
doc/ssl/SSL_CTX_set_timeout.pod Normal file
View File

@ -0,0 +1,55 @@
=pod
=head1 NAME
SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_set_timeout(SSL_CTX *ctx, long t);
long SSL_CTX_get_timeout(SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_CTX_set_timeout() sets the timeout for newly created sessions for
B<ctx> to B<t>. The timeout value B<t> must be given in seconds.
SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>.
=head1 NOTES
Whenever a new session is created, it is assigned a maximum lifetime. This
lifetime is specified by storing the creation time of the session and the
timeout value valid at this time. If the actual time is later than creation
time plus timeout, the session is not reused.
Due to this realization, all sessions behave according to the timeout value
valid at the time of the session negotiation. Changes of the timeout value
do not affect already established sessions.
The expiration time of a single session can be modified using the
L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)> family of functions.
Expired sessions are removed from the internal session cache, whenever
L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> is called, either
directly by the application or automatically (see
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>)
The default value for session timeout is 300 seconds.
=head1 RETURN VALUES
SSL_CTX_set_timeout() returns the previously set timeout value.
SSL_CTX_get_timeout() returns the currently set timeout value.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>,
L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>
=cut

284
doc/ssl/SSL_CTX_set_verify.pod Normal file
View File

@ -0,0 +1,284 @@
=pod
=head1 NAME
SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
int (*verify_callback)(int, X509_STORE_CTX *));
void SSL_set_verify(SSL *s, int mode,
int (*verify_callback)(int, X509_STORE_CTX *));
void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth);
void SSL_set_verify_depth(SSL *s, int depth);
int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx);
=head1 DESCRIPTION
SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and
specifies the B<verify_callback> function to be used. If no callback function
shall be specified, the NULL pointer can be used for B<verify_callback>.
SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and
specifies the B<verify_callback> function to be used. If no callback function
shall be specified, the NULL pointer can be used for B<verify_callback>. In
this case last B<verify_callback> set specifically for this B<ssl> remains. If
no special B<callback> was set before, the default callback for the underlying
B<ctx> is used, that was valid at the the time B<ssl> was created with
L<SSL_new(3)|SSL_new(3)>.
SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain
verification that shall be allowed for B<ctx>. (See the BUGS section.)
SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
verification that shall be allowed for B<ssl>. (See the BUGS section.)
=head1 NOTES
The verification of certificates can be controlled by a set of logically
or'ed B<mode> flags:
=over 4
=item SSL_VERIFY_NONE
B<Server mode:> the server will not send a client certificate request to the
client, so the client will not send a certificate.
B<Client mode:> if not using an anonymous cipher (by default disabled), the
server will send a certificate which will be checked. The result of the
certificate verification process can be checked after the TLS/SSL handshake
using the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function.
The handshake will be continued regardless of the verification result.
=item SSL_VERIFY_PEER
B<Server mode:> the server sends a client certificate request to the client.
The certificate returned (if any) is checked. If the verification process
fails as indicated by B<verify_callback>, the TLS/SSL handshake is
immediately terminated with an alert message containing the reason for
the verification failure.
The behaviour can be controlled by the additional
SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags.
B<Client mode:> the server certificate is verified. If the verification process
fails as indicated by B<verify_callback>, the TLS/SSL handshake is
immediately terminated with an alert message containing the reason for
the verification failure. If no server certificate is sent, because an
anonymous cipher is used, SSL_VERIFY_PEER is ignored.
=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT
B<Server mode:> if the client did not return a certificate, the TLS/SSL
handshake is immediately terminated with a "handshake failure" alert.
This flag must be used together with SSL_VERIFY_PEER.
B<Client mode:> ignored
=item SSL_VERIFY_CLIENT_ONCE
B<Server mode:> only request a client certificate on the initial TLS/SSL
handshake. Do not ask for a client certificate again in case of a
renegotiation. This flag must be used together with SSL_VERIFY_PEER.
B<Client mode:> ignored
=back
Exactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be
set at any time.
SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up
to which depth certificates in a chain are used during the verification
procedure. If the certificate chain is longer than allowed, the certificates
above the limit are ignored. Error messages are generated as if these
certificates would not be present, most likely a
X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
The depth count is "level 0:peer certificate", "level 1: CA certificate",
"level 2: higher level CA certificate", and so on. Setting the maximum
depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9,
allowing for the peer certificate and additional 9 CA certificates.
The B<verify_callback> function is used to control the behaviour when the
SSL_VERIFY_PEER flag is set. It must be supplied by the application and
receives two arguments: B<preverify_ok> indicates, whether the verification of
the certificate in question was passed (preverify_ok=1) or not
(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used
for the certificate chain verification.
The certificate chain is checked starting with the deepest nesting level
(the root CA certificate) and worked upward to the peer's certificate.
At each level signatures and issuer attributes are checked. Whenever
a verification error is found, the error number is stored in B<x509_ctx>
and B<verify_callback> is called with B<preverify_ok>=0. By applying
X509_CTX_store_* functions B<verify_callback> can locate the certificate
in question and perform additional steps (see EXAMPLES). If no error is
found for a certificate, B<verify_callback> is called with B<preverify_ok>=1
before advancing to the next level.
The return value of B<verify_callback> controls the strategy of the further
verification process. If B<verify_callback> returns 0, the verification
process is immediately stopped with "verification failed" state. If
SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and
the TLS/SSL handshake is terminated. If B<verify_callback> returns 1,
the verification process is continued. If B<verify_callback> always returns
1, the TLS/SSL handshake will never be terminated because of this application
experiencing a verification failure. The calling process can however
retrieve the error code of the last verification error using
L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its
own error storage managed by B<verify_callback>.
If no B<verify_callback> is specified, the default callback will be used.
Its return value is identical to B<preverify_ok>, so that any verification
failure will lead to a termination of the TLS/SSL handshake with an
alert message, if SSL_VERIFY_PEER is set.
=head1 BUGS
In client mode, it is not checked whether the SSL_VERIFY_PEER flag
is set, but whether SSL_VERIFY_NONE is not set. This can lead to
unexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not
used as required (exactly one must be set at any time).
The certificate verification depth set with SSL[_CTX]_verify_depth()
stops the verification at a certain depth. The error message produced
will be that of an incomplete certificate chain and not
X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected.
=head1 RETURN VALUES
The SSL*_set_verify*() functions do not provide diagnostic information.
=head1 EXAMPLES
The following code sequence realizes an example B<verify_callback> function
that will always continue the TLS/SSL handshake regardless of verification
failure, if wished. The callback realizes a verification depth limit with
more informational output.
All verification errors are printed, informations about the certificate chain
are printed on request.
The example is realized for a server that does allow but not require client
certificates.
The example makes use of the ex_data technique to store application data
into/retrieve application data from the SSL structure
(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>,
L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
...
typedef struct {
int verbose_mode;
int verify_depth;
int always_continue;
} mydata_t;
int mydata_index;
...
static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
{
char buf[256];
X509 *err_cert;
int err, depth;
SSL *ssl;
mydata_t *mydata;
err_cert = X509_STORE_CTX_get_current_cert(ctx);
err = X509_STORE_CTX_get_error(ctx);
depth = X509_STORE_CTX_get_error_depth(ctx);
/*
* Retrieve the pointer to the SSL of the connection currently treated
* and the application specific data stored into the SSL object.
*/
ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx());
mydata = SSL_get_ex_data(ssl, mydata_index);
X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256);
/*
* Catch a too long certificate chain. The depth limit set using
* SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so
* that whenever the "depth>verify_depth" condition is met, we
* have violated the limit and want to log this error condition.
* We must do it here, because the CHAIN_TOO_LONG error would not
* be found explicitly; only errors introduced by cutting off the
* additional certificates would be logged.
*/
if (depth > mydata->verify_depth) {
preverify_ok = 0;
err = X509_V_ERR_CERT_CHAIN_TOO_LONG;
X509_STORE_CTX_set_error(ctx, err);
}
if (!preverify_ok) {
printf("verify error:num=%d:%s:depth=%d:%s\n", err,
X509_verify_cert_error_string(err), depth, buf);
}
else if (mydata->verbose_mode)
{
printf("depth=%d:%s\n", depth, buf);
}
/*
* At this point, err contains the last verification error. We can use
* it for something special
*/
if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)
{
X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256);
printf("issuer= %s\n", buf);
}
if (mydata->always_continue)
return 1;
else
return preverify_ok;
}
...
mydata_t mydata;
...
mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL);
...
SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE,
verify_callback);
/*
* Let the verify_callback catch the verify_depth error so that we get
* an appropriate error in the logfile.
*/
SSL_CTX_set_verify_depth(verify_depth + 1);
/*
* Set up the SSL specific data into "mydata" and store it into th SSL
* structure.
*/
mydata.verify_depth = verify_depth; ...
SSL_set_ex_data(ssl, mydata_index, &mydata);
...
SSL_accept(ssl); /* check of success left out for clarity */
if (peer = SSL_get_peer_certificate(ssl))
{
if (SSL_get_verify_result(ssl) == X509_V_OK)
{
/* The client sent a certificate which verified OK */
}
}
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>,
L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>,
L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(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)>
=cut

154
doc/ssl/SSL_CTX_use_certificate.pod Normal file
View File

@ -0,0 +1,154 @@
=pod
=head1 NAME
SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key - load certificate and key data
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);
int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
int SSL_use_certificate(SSL *ssl, X509 *x);
int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);
int SSL_use_certificate_file(SSL *ssl, const char *file, int type);
int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,
long len);
int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);
int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len);
int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);
int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);
int SSL_CTX_check_private_key(SSL_CTX *ctx);
int SSL_check_private_key(SSL *ssl);
=head1 DESCRIPTION
These functions load the certificates and private keys into the SSL_CTX
or SSL object, respectively.
The SSL_CTX_* class of functions loads the certificates and keys into the
SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl>
created from B<ctx> with L<SSL_new(3)|SSL_new(3)> by copying, so that
changes applied to B<ctx> do not propagate to already existing SSL objects.
The SSL_* class of functions only loads certificates and keys into a
specific SSL object. The specific information is kept, when
L<SSL_clear(3)|SSL_clear(3)> is called for this SSL object.
SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>,
SSL_use_certificate() loads B<x> into B<ssl>. The rest of the
certificates needed to form the complete certificate chain can be
specified using the
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
function.
SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from
the memory location B<d> (with length B<len>) into B<ctx>,
SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>.
SSL_CTX_use_certificate_file() loads the first certificate stored in B<file>
into B<ctx>. The formatting B<type> of the certificate must be specified
from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>.
See the NOTES section on why SSL_CTX_use_certificate_chain_file()
should be preferred.
SSL_CTX_use_certificate_chain_file() loads a certificate chain from
B<file> into B<ctx>. The certificates must be in PEM format and must
be sorted starting with the certificate to the highest level (root CA).
There is no corresponding function working on a single SSL object.
SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>.
SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA
to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>;
SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>.
SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk>
stored at memory location B<d> (length B<len>) to B<ctx>.
SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA
stored at memory location B<d> (length B<len>) to B<ctx>.
SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private
key to B<ssl>.
SSL_CTX_use_PrivateKey_file() adds the first private key found in
B<file> to B<ctx>. The formatting B<type> of the certificate must be specified
from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in
B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found
in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private
RSA key found to B<ssl>.
SSL_CTX_check_private_key() checks the consistency of a private key with
the corresponding certificate loaded into B<ctx>. If more than one
key/certificate pair (RSA/DSA) is installed, the last item installed will
be checked. If e.g. the last item was a RSA certificate or key, the RSA
key/certificate pair will be checked. SSL_check_private_key() performs
the same check for B<ssl>. If no key/certificate was explicitly added for
this B<ssl>, the last item added into B<ctx> will be checked.
=head1 NOTES
The internal certificate store of OpenSSL can hold two private key/certificate
pairs at a time: one key/certificate of type RSA and one key/certificate
of type DSA. The certificate used depends on the cipher select, see
also L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>.
When reading certificates and private keys from file, files of type
SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain
one certificate or private key, consequently
SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting.
Files of type SSL_FILETYPE_PEM can contain more than one item.
SSL_CTX_use_certificate_chain_file() adds the first certificate found
in the file to the certificate store. The other certificates are added
to the store of chain certificates using
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>.
There exists only one extra chain store, so that the same chain is appended
to both types of certificates, RSA and DSA! If it is not intended to use
both type of certificate at the same time, it is recommended to use the
SSL_CTX_use_certificate_chain_file() instead of the
SSL_CTX_use_certificate_file() function in order to allow the use of
complete certificate chains even when no trusted CA storage is used or
when the CA issuing the certificate shall not be added to the trusted
CA storage.
If additional certificates are needed to complete the chain during the
TLS negotiation, CA certificates are additionally looked up in the
locations of trusted CA certificates, see
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
The private keys loaded from file can be encrypted. In order to successfully
load encrypted keys, a function returning the passphrase must have been
supplied, see
L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>.
(Certificate files might be encrypted as well from the technical point
of view, it however does not make sense as the data in the certificate
is considered public anyway.)
=head1 RETURN VALUES
On success, the functions return 1.
Otherwise check out the error stack to find out the reason.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,
L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
=cut

61
doc/ssl/SSL_SESSION_get_ex_new_index.pod Normal file
View File

@ -0,0 +1,61 @@
=pod
=head1 NAME
SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data - internal application specific data functions
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_SESSION_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int SSL_SESSION_set_ex_data(SSL_SESSION *session, int idx, void *arg);
void *SSL_SESSION_get_ex_data(SSL_SESSION *session, int idx);
typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
int idx, long argl, void *argp);
=head1 DESCRIPTION
Several OpenSSL structures can have application specific data attached to them.
These functions are used internally by OpenSSL to manipulate application
specific data attached to a specific structure.
SSL_SESSION_get_ex_new_index() is used to register a new index for application
specific data.
SSL_SESSION_set_ex_data() is used to store application data at B<arg> for B<idx>
into the B<session> object.
SSL_SESSION_get_ex_data() is used to retrieve the information for B<idx> from
B<session>.
A detailed description for the B<*_get_ex_new_index()> functionality
can be found in L<RSA_get_ex_new_index.pod(3)|RSA_get_ex_new_index.pod(3)>.
The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in
L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>.
=head1 WARNINGS
The application data is only maintained for sessions held in memory. The
application data is not included when dumping the session with
i2d_SSL_SESSION() (and all functions indirectly calling the dump functions
like PEM_write_SSL_SESSION() and PEM_write_bio_SSL_SESSION()) and can
therefore not be restored.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
=cut

63
doc/ssl/SSL_SESSION_get_time.pod Normal file
View File

@ -0,0 +1,63 @@
=pod
=head1 NAME
SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, SSL_SESSION_get_timeout - retrieve and manipulate session time and timeout settings
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_SESSION_get_time(SSL_SESSION *s);
long SSL_SESSION_set_time(SSL_SESSION *s, long tm);
long SSL_SESSION_get_timeout(SSL_SESSION *s);
long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm);
long SSL_get_time(SSL_SESSION *s);
long SSL_set_time(SSL_SESSION *s, long tm);
long SSL_get_timeout(SSL_SESSION *s);
long SSL_set_timeout(SSL_SESSION *s, long tm);
=head1 DESCRIPTION
SSL_SESSION_get_time() returns the time at which the session B<s> was
established. The time is given in seconds since the Epoch and therefore
compatible to the time delivered by the time() call.
SSL_SESSION_set_time() replaces the creation time of the session B<s> with
the chosen value B<tm>.
SSL_SESSION_get_timeout() returns the timeout value set for session B<s>
in seconds.
SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds
to B<tm>.
The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout()
functions are synonyms for the SSL_SESSION_*() counterparts.
=head1 NOTES
Sessions are expired by examining the creation time and the timeout value.
Both are set at creation time of the session to the actual time and the
default timeout value at creation, respectively, as set by
L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>.
Using these functions it is possible to extend or shorten the lifetime
of the session.
=head1 RETURN VALUES
SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently
valid values.
SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success.
If any of the function is passed the NULL pointer for the session B<s>,
0 is returned.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>
=cut

52
doc/ssl/SSL_get_client_CA_list.pod Normal file
View File

@ -0,0 +1,52 @@
=pod
=head1 NAME
SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs
=head1 SYNOPSIS
#include <openssl/ssl.h>
STACK_OF(X509_NAME) *SSL_get_client_CA_list(SSL *s);
STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
B<ctx> using L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>.
SSL_get_client_CA_list() returns the list of client CAs explicitly
set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, when in
server mode. In client mode, SSL_get_client_CA_list returns the list of
client CAs sent from the server, if any.
=head1 RETURN VALUES
SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
diagnostic information.
SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
values:
=over 4
=item STACK_OF(X509_NAMES)
List of CA names explicitly set (for B<ctx> or in server mode) or send
by the server (client mode).
=item NULL
No client CA list was explicitly set (for B<ctx> or in server mode) or
the server did not send a list of CAs (client mode).
=back
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
=cut

61
doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod Normal file
View File

@ -0,0 +1,61 @@
=pod
=head1 NAME
SSL_get_ex_data_X509_STORE_CTX_idx - get ex_data index to access SSL structure
from X509_STORE_CTX
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_get_ex_data_X509_STORE_CTX_idx(void);
=head1 DESCRIPTION
SSL_get_ex_data_X509_STORE_CTX_idx() returns the index number under which
the pointer to the SSL object is stored into the X509_STORE_CTX object.
=head1 NOTES
Whenever a X509_STORE_CTX object is created for the verification of the
peers certificate during a handshake, a pointer to the SSL object is
stored into the X509_STORE_CTX object to identify the connection affected.
To retrieve this pointer the X509_STORE_CTX_get_ex_data() function can
be used with the correct index. This index is globally the same for all
X509_STORE_CTX objects and can be retrieved using
SSL_get_ex_data_X509_STORE_CTX_idx(). The index value is set when
SSL_get_ex_data_X509_STORE_CTX_idx() is first called either by the application
program directly or indirectly during other SSL setup functions or during
the handshake.
The value depends on other index values defined for X509_STORE_CTX objects
before the SSL index is created.
=head1 RETURN VALUES
=over 4
=item E<gt>=0
The index value to access the pointer.
=item E<lt>0
An error occurred, check the error stack for a detailed error message.
=back
=head1 EXAMPLES
The index returned from SSL_get_ex_data_X509_STORE_CTX_idx() allows to
access the SSL object for the connection to be accessed during the
verify_callback() when checking the peers certificate. Please check
the example in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
=cut

59
doc/ssl/SSL_get_ex_new_index.pod Normal file
View File

@ -0,0 +1,59 @@
=pod
=head1 NAME
SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data - internal application specific data functions
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int SSL_set_ex_data(SSL *ssl, int idx, void *arg);
void *SSL_get_ex_data(SSL *ssl, int idx);
typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
int idx, long argl, void *argp);
=head1 DESCRIPTION
Several OpenSSL structures can have application specific data attached to them.
These functions are used internally by OpenSSL to manipulate application
specific data attached to a specific structure.
SSL_get_ex_new_index() is used to register a new index for application
specific data.
SSL_set_ex_data() is used to store application data at B<arg> for B<idx> into
the B<ssl> object.
SSL_get_ex_data() is used to retrieve the information for B<idx> from
B<ssl>.
A detailed description for the B<*_get_ex_new_index()> functionality
can be found in L<RSA_get_ex_new_index.pod(3)|RSA_get_ex_new_index.pod(3)>.
The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in
L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>.
=head1 EXAMPLES
An example on how to use the functionality is included in the example
verify_callback() in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>,
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
=cut

46
doc/ssl/SSL_get_version.pod Normal file
View File

@ -0,0 +1,46 @@
=pod
=head1 NAME
SSL_get_version - get the protocol version of a connection.
=head1 SYNOPSIS
#include <openssl/ssl.h>
const char *SSL_get_version(SSL *ssl);
=head1 DESCRIPTION
SSL_get_cipher_version() returns the name of the protocol used for the
connection B<ssl>.
=head1 RETURN VALUES
The following strings can occur:
=over 4
=item SSLv2
The connection uses the SSLv2 protocol.
=item SSLv3
The connection uses the SSLv3 protocol.
=item TLSv1
The connection uses the TLSv1 protocol.
=item unknown
This indicates that no version has been set (no connection established).
=back
=head1 SEE ALSO
L<ssl(3)|ssl(3)>
=cut

62
doc/ssl/SSL_load_client_CA_file.pod Normal file
View File

@ -0,0 +1,62 @@
=pod
=head1 NAME
SSL_load_client_CA_file - load certificate names from file
=head1 SYNOPSIS
#include <openssl/ssl.h>
STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
=head1 DESCRIPTION
SSL_load_client_CA_file() reads certificates from B<file> and returns
a STACK_OF(X509_NAME) with the subject names found.
=head1 NOTES
SSL_load_client_CA_file() reads a file of PEM formatted certificates and
extracts the X509_NAMES of the certificates found. While the name suggests
the specific usage as support function for
L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
it is not limited to CA certificates.
=head1 EXAMPLES
Load names of CAs from file and use it as a client CA list:
SSL_CTX *ctx;
STACK_OF(X509_NAME) *cert_names;
...
cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
if (cert_names != NULL)
SSL_CTX_set_client_CA_list(ctx, cert_names);
else
error_handling();
...
=head1 RETURN VALUES
The following return values can occur:
=over 4
=item NULL
The operation failed, check out the error stack for the reason.
=item Pointer to STACK_OF(X509_NAME)
Pointer to the subject names of the successfully read certificates.
=back
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
=cut

68
doc/ssl/SSL_set_shutdown.pod Normal file
View File

@ -0,0 +1,68 @@
=pod
=head1 NAME
SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_set_shutdown(SSL *ssl, int mode);
int SSL_get_shutdown(SSL *ssl);
=head1 DESCRIPTION
SSL_set_shutdown() sets the shutdown state of B<ssl> to B<mode>.
SSL_get_shutdown() returns the shutdown mode of B<ssl>.
=head1 NOTES
The shutdown state of an ssl connection is a bitmask of:
=over 4
=item 0
No shutdown setting, yet.
=item SSL_SENT_SHUTDOWN
A "close notify" shutdown alert was sent to the peer, the connection is being
considered closed and the session is closed and correct.
=item SSL_RECEIVED_SHUTDOWN
A shutdown alert was received form the peer, either a normal "close notify"
or a fatal error.
=back
SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time.
The shutdown state of the connection is used to determine the state of
the ssl session. If the session is still open, when
L<SSL_clear(3)|SSL_clear(3)> or L<SSL_free(3)|SSL_free(3)> is called,
it is considered bad and removed according to RFC2246.
The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN.
SSL_set_shutdown() can be used to set this state without sending a
close alert to the peer (see L<SSL_shutdown(3)|SSL_shutdown(3)>).
If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set,
for setting SSL_SENT_SHUTDOWN the application must however still call
L<SSL_shutdown(3)|SSL_shutdown(3)> or SSL_set_shutdown() itself.
=head1 RETURN VALUES
SSL_set_shutdown() does not return diagnostic information.
SSL_get_shutdown() returns the current setting.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>,
L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
=cut

56
doc/ssl/d2i_SSL_SESSION.pod Normal file
View File

@ -0,0 +1,56 @@
=pod
=head1 NAME
d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation
=head1 SYNOPSIS
#include <openssl/ssl.h>
SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, unsigned char **pp, long length);
int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp);
=head1 DESCRIPTION
d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS
session, stored as binary data at location B<pp> with length B<length>, into
an SSL_SESSION object.
i2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1
representation and stores it into the memory location pointed to by B<pp>.
The length of the resulting ASN1 representation is returned. If B<pp> is
the NULL pointer, only the length is calculated and returned.
=head1 NOTES
The SSL_SESSION object is built from several malloc()ed parts, it can
therefore not be moved, copied or stored directly. In order to store
session data on disk or into a database, it must be transformed into
a binary ASN1 representation.
When using d2i_SSL_SESSION(), the SSL_SESSION object is automatically
allocated.
When using i2d_SSL_SESSION(), the memory location pointed to by B<pp> must be
large enough to hold the binary representation of the session. There is no
known limit on the size of the created ASN1 representation, so the necessary
amount of space should be obtained by first calling i2d_SSL_SESSION() with
B<pp=NULL>, and obtain the size needed, then allocate the memory and
call i2d_SSL_SESSION() again.
=head1 RETURN VALUES
d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION
object. In case of failure the NULL-pointer is returned and the error message
can be retrieved from the error stack.
i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes.
When the session is not valid, B<0> is returned and no operation is performed.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>
=cut

84
test/bctest Executable file
View File

@ -0,0 +1,84 @@
#!/bin/sh
# This script is used by test/Makefile.ssl to check whether a sane 'bc'
# is installed.
# ('make test_bn' should not try to run 'bc' if it does not exist or if
# it is a broken 'bc' version that is known to cause trouble.)
#
# If 'bc' works, we also test if it knows the 'print' command.
#
# In any case, output an appropriate command line for running (or not
# running) bc.
# Test for SunOS 5.[78] bc bug (or missing bc)
if [ 0 != "`bc <<\EOF
obase=16
ibase=16
a=AD88C418F31B3FC712D0425001D522B3AE9134FF3A98C13C1FCC1682211195406C1A6C66C6A\
CEEC1A0EC16950233F77F1C2F2363D56DD71A36C57E0B2511FC4BA8F22D261FE2E9356D99AF57\
10F3817C0E05BF79C423C3F66FDF321BE8D3F18F625D91B670931C1EF25F28E489BDA1C5422D1\
C3F6F7A1AD21585746ECC4F10A14A778AF56F08898E965E9909E965E0CB6F85B514150C644759\
3BE731877B16EA07B552088FF2EA728AC5E0FF3A23EB939304519AB8B60F2C33D6BA0945B66F0\
4FC3CADF855448B24A9D7640BCF473E
b=DCE91E7D120B983EA9A104B5A96D634DD644C37657B1C7860B45E6838999B3DCE5A555583C6\
9209E41F413422954175A06E67FFEF6746DD652F0F48AEFECC3D8CAC13523BDAAD3F5AF4212BD\
8B3CD64126E1A82E190228020C05B91C8B141F1110086FC2A4C6ED631EBA129D04BB9A19FC53D\
3ED0E2017D60A68775B75481449
(a/b)*b + (a%b) - a
EOF`" ]
then
echo "bc does not work. Consider installing GNU bc." >&2
echo "cat >/dev/null"
exit 1
fi
# Test for SCO bc bug.
if [ "0
0" != "`bc <<\EOF
obase=16
ibase=16
-FFDD63BA1A4648F0D804F8A1C66C53F0D2110590E8A3907EC73B4AEC6F15AC177F176F2274D2\
9DC8022EA0D7DD3ABE9746D2D46DD3EA5B5F6F69DF12877E0AC5E7F5ADFACEE54573F5D256A06\
11B5D2BC24947724E22AE4EC3FB0C39D9B4694A01AFE5E43B4D99FB9812A0E4A5773D8B254117\
1239157EC6E3D8D50199 * -FFDD63BA1A4648F0D804F8A1C66C53F0D2110590E8A3907EC73B4\
AEC6F15AC177F176F2274D29DC8022EA0D7DD3ABE9746D2D46DD3EA5B5F6F69DF12877E0AC5E7\
F5ADFACEE54573F5D256A0611B5D2BC24947724E22AE4EC3FB0C39D9B4694A01AFE5E43B4D99F\
B9812A0E4A5773D8B2541171239157EC6E3D8D50199 - FFBACC221682DA464B6D7F123482522\
02EDAEDCA38C3B69E9B7BBCD6165A9CD8716C4903417F23C09A85B851961F92C217258CEEB866\
85EFCC5DD131853A02C07A873B8E2AF2E40C6D5ED598CD0E8F35AD49F3C3A17FDB7653E4E2DC4\
A8D23CC34686EE4AD01F7407A7CD74429AC6D36DBF0CB6A3E302D0E5BDFCD048A3B90C1BE5AA8\
E16C3D5884F9136B43FF7BB443764153D4AEC176C681B078F4CC53D6EB6AB76285537DDEE7C18\
8C72441B52EDBDDBC77E02D34E513F2AABF92F44109CAFE8242BD0ECBAC5604A94B02EA44D43C\
04E9476E6FBC48043916BFA1485C6093603600273C9C33F13114D78064AE42F3DC466C7DA543D\
89C8D71
AD534AFBED2FA39EE9F40E20FCF9E2C861024DB98DDCBA1CD118C49CA55EEBC20D6BA51B2271C\
928B693D6A73F67FEB1B4571448588B46194617D25D910C6A9A130CC963155CF34079CB218A44\
8A1F57E276D92A33386DDCA3D241DB78C8974ABD71DD05B0FA555709C9910D745185E6FE108E3\
37F1907D0C56F8BFBF52B9704 % -E557905B56B13441574CAFCE2BD257A750B1A8B2C88D0E36\
E18EF7C38DAC80D3948E17ED63AFF3B3467866E3B89D09A81B3D16B52F6A3C7134D3C6F5123E9\
F617E3145BBFBE9AFD0D6E437EA4FF6F04BC67C4F1458B4F0F47B64 - 1C2BBBB19B74E86FD32\
9E8DB6A8C3B1B9986D57ED5419C2E855F7D5469E35E76334BB42F4C43E3F3A31B9697C171DAC4\
D97935A7E1A14AD209D6CF811F55C6DB83AA9E6DFECFCD6669DED7171EE22A40C6181615CAF3F\
5296964
EOF`" ]
then
echo "bc does not work. Consider installing GNU bc." >&2
echo "cat >/dev/null"
exit 1
fi
# bc works, good.
# Now check if it knows the 'print' command.
if [ "OK" = "`bc 2>/dev/null <<\EOF
print \"OK\"
EOF`" ]
then
echo "bc"
else
echo "sed 's/print.*//' | bc"
fi
exit 0