ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import OpenSSL 1.1.0f

Browse Source
This commit is contained in:
Steve Dower
2017-09-07 16:27:43 -07:00
committed by Steve Dower
parent ccd3ab4aff
commit f4b81cb7c9
3340 changed files with 325158 additions and 557542 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
doc/ssl/DTLSv1_listen.pod Normal file
View File

@@ -0,0 +1,102 @@
=pod
=head1 NAME
DTLSv1_listen - listen for incoming DTLS connections
=head1 SYNOPSIS
#include <openssl/ssl.h>
int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer);
=head1 DESCRIPTION
DTLSv1_listen() listens for new incoming DTLS connections. If a ClientHello is
received that does not contain a cookie, then DTLSv1_listen() responds with a
HelloVerifyRequest. If a ClientHello is received with a cookie that is verified
then control is returned to user code to enable the handshake to be completed
(for example by using SSL_accept()).
=head1 NOTES
Datagram based protocols can be susceptible to Denial of Service attacks. A
DTLS attacker could, for example, submit a series of handshake initiation
requests that cause the server to allocate state (and possibly perform
cryptographic operations) thus consuming server resources. The attacker could
also (with UDP) quite simply forge the source IP address in such an attack.
As a counter measure to that DTLS includes a stateless cookie mechanism. The
idea is that when a client attempts to connect to a server it sends a
ClientHello message. The server responds with a HelloVerifyRequest which
contains a unique cookie. The client then resends the ClientHello, but this time
includes the cookie in the message thus proving that the client is capable of
receiving messages sent to that address. All of this can be done by the server
without allocating any state, and thus without consuming expensive resources.
OpenSSL implements this capability via the DTLSv1_listen() function. The B<ssl>
parameter should be a newly allocated SSL object with its read and write BIOs
set, in the same way as might be done for a call to SSL_accept(). Typically the
read BIO will be in an "unconnected" state and thus capable of receiving
messages from any peer.
When a ClientHello is received that contains a cookie that has been verified,
then DTLSv1_listen() will return with the B<ssl> parameter updated into a state
where the handshake can be continued by a call to (for example) SSL_accept().
Additionally the B<BIO_ADDR> pointed to by B<peer> will be filled in with
details of the peer that sent the ClientHello. If the underlying BIO is unable
to obtain the B<BIO_ADDR> of the peer (for example because the BIO does not
support this), then B<*peer> will be cleared and the family set to AF_UNSPEC.
Typically user code is expected to "connect" the underlying socket to the peer
and continue the handshake in a connected state.
Prior to calling DTLSv1_listen() user code must ensure that cookie generation
and verification callbacks have been set up using
SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb()
respectively.
Since DTLSv1_listen() operates entirely statelessly whilst processing incoming
ClientHellos it is unable to process fragmented messages (since this would
require the allocation of state). An implication of this is that DTLSv1_listen()
B<only> supports ClientHellos that fit inside a single datagram.
=head1 RETURN VALUES
From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance
the B<peer> value will be filled in and the B<ssl> object set up ready to
continue the handshake.
A return value of 0 indicates a non-fatal error. This could (for
example) be because of non-blocking IO, or some invalid message having been
received from a peer. Errors may be placed on the OpenSSL error queue with
further information if appropriate. Typically user code is expected to retry the
call to DTLSv1_listen() in the event of a non-fatal error. Any old errors on the
error queue will be cleared in the subsequent call.
A return value of <0 indicates a fatal error. This could (for example) be
because of a failure to allocate sufficient memory for the operation.
Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return codes
<= 0 (in typical implementations user code treats all errors as non-fatal),
whilst return codes >0 indicate success.
=head1 SEE ALSO
L<SSL_get_error(3)>, L<SSL_accept(3)>,
L<ssl(3)>, L<bio(3)>
=head1 HISTORY
DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of "peer"
also changed in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

84
doc/ssl/OPENSSL_init_ssl.pod Normal file
View File

@@ -0,0 +1,84 @@
=pod
=head1 NAME
OPENSSL_init_ssl - OpenSSL (libssl and libcrypto) initialisation
=head1 SYNOPSIS
#include <openssl/ssl.h>
int OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
=head1 DESCRIPTION
During normal operation OpenSSL (libssl and libcrypto) will allocate various
resources at start up that must, subsequently, be freed on close down of the
library. Additionally some resources are allocated on a per thread basis (if the
application is multi-threaded), and these resources must be freed prior to the
thread closing.
As of version 1.1.0 OpenSSL will automatically allocate all resources that it
needs so no explicit initialisation is required. Similarly it will also
automatically deinitialise as required.
However, there may be situations when explicit initialisation is desirable or
needed, for example when some non-default initialisation is required. The
function OPENSSL_init_ssl() can be used for this purpose. Calling
this function will explicitly initialise BOTH libcrypto and libssl. To
explicitly initialise ONLY libcrypto see the
L<OPENSSL_init_crypto(3)> function.
Numerous internal OpenSSL functions call OPENSSL_init_ssl().
Therefore, in order to perform non-default initialisation,
OPENSSL_init_ssl() MUST be called by application code prior to
any other OpenSSL function calls.
The B<opts> parameter specifies which aspects of libssl and libcrypto should be
initialised. Valid options for libcrypto are described on the
L<OPENSSL_init_crypto(3)> page. In addition to any libcrypto
specific option the following libssl options can also be used:
=over 4
=item OPENSSL_INIT_NO_LOAD_SSL_STRINGS
Suppress automatic loading of the libssl error strings. This option is
not a default option. Once selected subsequent calls to
OPENSSL_init_ssl() with the option
B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored.
=item OPENSSL_INIT_LOAD_SSL_STRINGS
Automatic loading of the libssl error strings. This option is a
default option. Once selected subsequent calls to
OPENSSL_init_ssl() with the option
B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored.
=back
OPENSSL_init_ssl() takes a B<settings> parameter which can be used to
set parameter values. See L<OPENSSL_init_crypto(3)> for details.
=head1 RETURN VALUES
The function OPENSSL_init_ssl() returns 1 on success or 0 on error.
=head1 SEE ALSO
L<OPENSSL_init_crypto(3)>
=head1 HISTORY
The OPENSSL_init_ssl() function was added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

144
doc/ssl/SSL_CIPHER_get_name.pod
View File

@@ -2,7 +2,11 @@
=head1 NAME
SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties
SSL_CIPHER_get_cipher_nid, SSL_CIPHER_get_digest_nid, SSL_CIPHER_get_kx_nid,
SSL_CIPHER_get_auth_nid, SSL_CIPHER_is_aead,
SSL_CIPHER_get_name, SSL_CIPHER_get_bits,
SSL_CIPHER_get_version, SSL_CIPHER_description
- get SSL_CIPHER properties
=head1 SYNOPSIS
@@ -12,41 +16,58 @@ SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_des
int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);
int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
=head1 DESCRIPTION
SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the
argument is the NULL pointer, a pointer to the constant value "NONE" is
returned.
B<cipher> is NULL, it returns "(NONE)".
SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If
B<alg_bits> is not NULL, it contains the number of bits processed by the
chosen algorithm. If B<cipher> is NULL, 0 is returned.
SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>.
If B<cipher> is NULL, 0 is returned.
SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol
version that first defined the cipher.
This is currently B<SSLv2> or B<TLSv1/SSLv3>.
In some cases it should possibly return "TLSv1.2" but does not;
use SSL_CIPHER_description() instead.
If B<cipher> is NULL, "(NONE)" is returned.
version that first defined the cipher. It returns "(NONE)" if B<cipher> is NULL.
SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>.
If there is no cipher (e.g. for ciphersuites with no encryption) then
B<NID_undef> is returned.
SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC
used by B<c>. If there is no digest (e.g. for AEAD ciphersuites) then
B<NID_undef> is returned.
SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method
used by B<c>. If there is no key exchange, then B<NID_undef> is returned. Examples (not comprehensive):
NID_kx_rsa
NID_kx_ecdhe
NID_kx_dhe
NID_kx_psk
SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method
used by B<c>. If there is no authentication, then B<NID_undef> is returned.
Examples (not comprehensive):
NID_auth_rsa
NID_auth_ecdsa
NID_auth_psk
SSL_CIPHER_is_aead() returns 1 if the cipher B<c> is AEAD (e.g. GCM or
ChaCha20/Poly1305), and 0 if it is not AEAD.
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 a pointer to 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.
into the buffer B<buf> of length B<len> provided. If B<buf> is provided, it
must be at least 128 bytes, otherwise a buffer will be allocated using
OPENSSL_malloc(). If the provided buffer is too small, or the allocation fails,
B<NULL> is returned.
=head1 NOTES
The number of bits processed can be different from the secret bits. An
export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm
does use the full 128 bits (which would be returned for B<alg_bits>), of
which however 88bits are fixed. The search space is hence only 40 bits.
The string returned by SSL_CIPHER_description() in case of success consists
of cleartext information separated by one or more blanks in the following
sequence:
The string returned by SSL_CIPHER_description() consists of several fields
separated by whitespace:
=over 4
@@ -56,77 +77,52 @@ Textual representation of the cipher name.
=item <protocol version>
Protocol version: B<SSLv2>, B<SSLv3>, B<TLSv1.2>. The TLSv1.0 ciphers are
flagged with SSLv3. No new ciphers were added by TLSv1.1.
Protocol version, such as B<TLSv1.2>, when the cipher was first defined.
=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>.
Key exchange method such as B<RSA>, B<ECDHE>, etc.
=item Au=<authentication>
Authentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the
Authentication method such as B<RSA>, B<None>, etc.. None is the
representation of anonymous ciphers.
=item Enc=<symmetric 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>.
Encryption method, with number of secret bits, such as B<AESGCM(128)>.
=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.
Message digest, such as B<SHA256>.
=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
ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384
A comp[lete list can be retrieved by invoking the following command:
=head1 HISTORY
openssl ciphers -v ALL
SSL_CIPHER_get_version() was updated to always return the correct protocol
string in OpenSSL 1.1.
=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.
The standard terminology for ephemeral Diffie-Hellman schemes is DHE
(finite field) or ECDHE (elliptic curve). This version of OpenSSL
idiosyncratically reports these schemes as EDH and EECDH, even though
it also accepts the standard terminology.
It is recommended to use the standard terminology (DHE and ECDHE)
during configuration (e.g. via SSL_CTX_set_cipher_list) for clarity of
configuration. OpenSSL versions after 1.0.2 will report the standard
terms via SSL_CIPHER_get_name and SSL_CIPHER_description.
=head1 RETURN VALUES
See DESCRIPTION
SSL_CIPHER_description() was changed to return B<NULL> on error,
rather than a fixed string, in OpenSSL 1.1
=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<ciphers(1)|ciphers(1)>,
L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>
L<ssl(3)>, L<SSL_get_current_cipher(3)>,
L<SSL_get_ciphers(3)>, L<ciphers(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

52
doc/ssl/SSL_COMP_add_compression_method.pod
View File

@@ -2,15 +2,24 @@
=head1 NAME
SSL_COMP_add_compression_method, SSL_COMP_free_compression_methods - handle SSL/TLS integrated compression methods
SSL_COMP_add_compression_method, SSL_COMP_get_compression_methods,
SSL_COMP_get0_name, SSL_COMP_get_id, SSL_COMP_free_compression_methods
- handle SSL/TLS integrated compression methods
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm);
STACK_OF(SSL_COMP) *SSL_COMP_get_compression_methods(void);
const char *SSL_COMP_get0_name(const SSL_COMP *comp);
int SSL_COMP_get_id(const SSL_COMP *comp);
+void SSL_COMP_free_compression_methods(void);
Deprecated:
#if OPENSSL_API_COMPAT < 0x10100000L
void SSL_COMP_free_compression_methods(void)
#endif
=head1 DESCRIPTION
@@ -19,9 +28,19 @@ the identifier B<id> to the list of available compression methods. This
list is globally maintained for all SSL operations within this application.
It cannot be set for specific SSL_CTX or SSL objects.
SSL_COMP_free_compression_methods() frees the internal table of
compression methods that were built internally, and possibly
augmented by adding SSL_COMP_add_compression_method().
SSL_COMP_get_compression_methods() returns a stack of all of the available
compression methods or NULL on error.
SSL_COMP_get0_name() returns the name of the compression method B<comp>.
SSL_COMP_get_id() returns the id of the compression method B<comp>.
In versions of OpenSSL prior to 1.1.0 SSL_COMP_free_compression_methods() freed
the internal table of compression methods that were built internally, and
possibly augmented by adding SSL_COMP_add_compression_method(). However this is
now unnecessary from version 1.1.0. No explicit initialisation or
de-initialisation is necessary. See L<OPENSSL_init_crypto(3)> and
L<OPENSSL_init_ssl(3)>. From OpenSSL 1.1.0 calling this function does nothing.
=head1 NOTES
@@ -69,8 +88,29 @@ The operation failed. Check the error queue to find out the reason.
=back
SSL_COMP_get_compression_methods() returns the stack of compressions methods or
NULL on error.
SSL_COMP_get0_name() returns the name of the compression method or NULL on error.
SSL_COMP_get_id() returns the name of the compression method or -1 on error.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>
L<ssl(3)>
=head1 HISTORY
SSL_COMP_free_compression_methods() was deprecated in OpenSSL 1.1.0.
SSL_COMP_get0_name() and SSL_comp_get_id() were added in OpenSSL 1.1.0d.
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

20
doc/ssl/SSL_CONF_CTX_new.pod
View File

@@ -17,6 +17,7 @@ The function SSL_CONF_CTX_new() allocates and initialises an B<SSL_CONF_CTX>
structure for use with the SSL_CONF functions.
The function SSL_CONF_CTX_free() frees up the context B<cctx>.
If B<cctx> is NULL nothing is done.
=head1 RETURN VALUES
@@ -27,14 +28,23 @@ SSL_CONF_CTX_free() does not return a value.
=head1 SEE ALSO
L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)>,
L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)>
L<SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_cmd(3)>,
L<SSL_CONF_cmd_argv(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.2
=head1 COPYRIGHT
Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/ssl/SSL_CONF_CTX_set1_prefix.pod
View File

@@ -20,7 +20,7 @@ to B<prefix>. If B<prefix> is B<NULL> it is restored to the default value.
Command prefixes alter the commands recognised by subsequent SSL_CTX_cmd()
calls. For example for files, if the prefix "SSL" is set then command names
such as "SSLProtocol", "SSLOptions" etc. are recognised instead of "Protocol"
and "Options". Similarly for command lines if the prefix is "--ssl-" then
and "Options". Similarly for command lines if the prefix is "--ssl-" then
"--ssl-no_tls1_2" is recognised instead of "-no_tls1_2".
If the B<SSL_CONF_FLAG_CMDLINE> flag is set then prefix checks are case
@@ -36,14 +36,23 @@ SSL_CONF_CTX_set1_prefix() returns 1 for success and 0 for failure.
=head1 SEE ALSO
L<SSL_CONF_CTX_new(3)|SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)>,
L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)>
L<SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_cmd(3)>,
L<SSL_CONF_cmd_argv(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.2
=head1 COPYRIGHT
Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

26
doc/ssl/SSL_CONF_CTX_set_flags.pod
View File

@@ -40,6 +40,13 @@ both of these flags must be set.
recognise certificate and private key options.
=item SSL_CONF_FLAG_REQUIRE_PRIVATE
If this option is set then if a private key is not specified for a certificate
it will attempt to load a private key from the certificate file when
SSL_CONF_CTX_finish() is called. If a key cannot be loaded from the certificate
file an error occurs.
=item SSL_CONF_FLAG_SHOW_ERRORS
indicate errors relating to unrecognised options or missing arguments in
@@ -55,14 +62,23 @@ value after setting or clearing flags.
=head1 SEE ALSO
L<SSL_CONF_CTX_new(3)|SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)>,
L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)>
L<SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_cmd(3)>,
L<SSL_CONF_cmd_argv(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.2
=head1 COPYRIGHT
Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

19
doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod
View File

@@ -34,14 +34,23 @@ SSL_CONF_CTX_set_ssl_ctx() and SSL_CTX_set_ssl() do not return a value.
=head1 SEE ALSO
L<SSL_CONF_CTX_new(3)|SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)>,
L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)>
L<SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_cmd(3)>,
L<SSL_CONF_cmd_argv(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.2
=head1 COPYRIGHT
Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

196
doc/ssl/SSL_CONF_cmd.pod
View File

@@ -2,6 +2,7 @@
=head1 NAME
SSL_CONF_cmd_value_type, SSL_CONF_finish,
SSL_CONF_cmd - send configuration command
=head1 SYNOPSIS
@@ -101,7 +102,7 @@ are permitted.
Attempts to use the file B<value> as the private key for the appropriate
context. This option is only supported if certificate operations
are permitted. Note: if no B<-key> option is set then a private key is
not loaded: it does not currently use the B<-cert> file.
not loaded unless the flag B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
=item B<-dhparam>
@@ -109,19 +110,40 @@ Attempts to use the file B<value> as the set of temporary DH parameters for
the appropriate context. This option is only supported if certificate
operations are permitted.
=item B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
=item B<-min_protocol>, B<-max_protocol>
Disables protocol support for SSLv2, SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2
by setting the corresponding options B<SSL_OP_NO_SSLv2>, B<SSL_OP_NO_SSLv3>,
B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> and B<SSL_OP_NO_TLSv1_2> respectively.
Sets the minimum and maximum supported protocol.
Currently supported protocol values are B<SSLv3>, B<TLSv1>,
B<TLSv1.1>, B<TLSv1.2> for TLS and B<DTLSv1>, B<DTLSv1.2> for DTLS,
and B<None> for no limit.
If the either bound is not specified then only the other bound applies,
if specified.
To restrict the supported protocol versions use these commands rather
than the deprecated alternative commands below.
=item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
Disables protocol support for SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2 by setting the
corresponding options B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>
and B<SSL_OP_NO_TLSv1_2> respectively.
These options are deprecated, instead use B<-min_protocol> and B<-max_protocol>.
=item B<-bugs>
Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
=item B<-comp>
Enables support for SSL/TLS compression, same as clearing
B<SSL_OP_NO_COMPRESSION>.
This command was introduced in OpenSSL 1.1.0.
As of OpenSSL 1.1.0, compression is off by default.
=item B<-no_comp>
Disables support for SSL/TLS compression, same as setting B<SSL_OP_NO_COMPRESS>.
Disables support for SSL/TLS compression, same as setting
B<SSL_OP_NO_COMPRESSION>.
As of OpenSSL 1.1.0, compression is off by default.
=item B<-no_ticket>
@@ -153,20 +175,13 @@ Set by default.
enables strict mode protocol handling. Equivalent to setting
B<SSL_CERT_FLAG_TLS_STRICT>.
=item B<-debug_broken_protocol>
disables various checks and permits several kinds of broken protocol behaviour
for testing purposes: it should B<NEVER> be used in anything other than a test
environment. Only supported if OpenSSL is configured with
B<-DOPENSSL_SSL_DEBUG_BROKEN_PROTOCOL>.
=back
=head1 SUPPORTED CONFIGURATION FILE COMMANDS
Currently supported B<cmd> names for configuration files (i.e. when the
flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file
B<cmd> names and are case insensitive so B<signaturealgorithms> is recognised
B<cmd> names are case insensitive so B<signaturealgorithms> is recognised
as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names
are also case insensitive.
@@ -192,8 +207,14 @@ are permitted.
Attempts to use the file B<value> as the private key for the appropriate
context. This option is only supported if certificate operations
are permitted. Note: if no B<-key> option is set then a private key is
not loaded: it does not currently use the B<Certificate> file.
are permitted. Note: if no B<PrivateKey> option is set then a private key is
not loaded unless the B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
=item B<ChainCAFile>, B<ChainCAPath>, B<VerifyCAFile>, B<VerifyCAPath>
These options indicate a file or directory used for building certificate
chains or verifying certificate chains. These options are only supported
if certificate operations are permitted.
=item B<ServerInfoFile>
@@ -242,33 +263,57 @@ The B<value> argument is a colon separated list of curves. The curve can be
either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
B<prime256v1>). Curve names are case sensitive.
=item B<ECDHParameters>
=item B<MinProtocol>
This sets the temporary curve used for ephemeral ECDH modes. Only used by
servers
This sets the minimum supported SSL, TLS or DTLS version.
The B<value> argument is a curve name or the special value B<Automatic> which
picks an appropriate curve based on client and server preferences. The curve
can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
(e.g B<prime256v1>). Curve names are case sensitive.
Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
The value B<None> will disable the limit.
=item B<MaxProtocol>
This sets the maximum supported SSL, TLS or DTLS version.
Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
The value B<None> will disable the limit.
=item B<Protocol>
The supported versions of the SSL or TLS protocol.
This can be used to enable or disable certain versions of the SSL,
TLS or DTLS protocol.
The B<value> argument is a comma separated list of supported protocols to
enable or disable. If an protocol is preceded by B<-> that version is disabled.
Currently supported protocol values are B<SSLv2>, B<SSLv3>, B<TLSv1>,
B<TLSv1.1> and B<TLSv1.2>.
All protocol versions other than B<SSLv2> are enabled by default.
To avoid inadvertent enabling of B<SSLv2>, when SSLv2 is disabled, it is not
possible to enable it via the B<Protocol> command.
The B<value> argument is a comma separated list of supported protocols
to enable or disable.
If a protocol is preceded by B<-> that version is disabled.
All protocol versions are enabled by default.
You need to disable at least one protocol version for this setting have any
effect.
Only enabling some protocol versions does not disable the other protocol
versions.
Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
The special value B<ALL> refers to all supported versions.
This can't enable protocols that are disabled using B<MinProtocol>
or B<MaxProtocol>, but can disable protocols that are still allowed
by them.
The B<Protocol> command is fragile and deprecated; do not use it.
Use B<MinProtocol> and B<MaxProtocol> instead.
If you do use B<Protocol>, make sure that the resulting range of enabled
protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make
sure to also leave TLS 1.1 enabled.
=item B<Options>
The B<value> argument is a comma separated list of various flags to set.
If a flag string is preceded B<-> it is disabled. See the
B<SSL_CTX_set_options> function for more details of individual options.
If a flag string is preceded B<-> it is disabled.
See the L<SSL_CTX_set_options(3)> function for more details of
individual options.
Each option is listed below. Where an operation is enabled by default
the B<-flag> syntax is needed to disable it.
@@ -307,6 +352,27 @@ B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation
for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
Set by default.
=item B<VerifyMode>
The B<value> argument is a comma separated list of flags to set.
B<Peer> enables peer verification: for clients only.
B<Request> requests but does not require a certificate from the client.
Servers only.
B<Require> requests and requires a certificate from the client: an error
occurs if the client does not present a certificate. Servers only.
B<Once> requests a certificate from a client only on the initial connection:
not when renegotiating. Servers only.
=item B<ClientCAFile>, B<ClientCAPath>
A file or directory of certificates in PEM format whose names are used as the
set of acceptable names for client CAs. Servers only. This option is only
supported if certificate operations are permitted.
=back
=head1 SUPPORTED COMMAND TYPES
@@ -333,6 +399,11 @@ The value is a file name.
The value is a directory name.
=item B<SSL_CONF_TYPE_NONE>
The value string is not used e.g. a command line option which doesn't take an
argument.
=back
=head1 NOTES
@@ -349,7 +420,7 @@ however the call sequence is:
SSL_CONF_cmd(ctx, userparam, uservalue);
SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
then SSLv3 is B<always> disabled and attempt to override this by the user are
SSLv3 is B<always> disabled and attempt to override this by the user are
ignored.
By checking the return code of SSL_CTX_cmd() it is possible to query if a
@@ -385,18 +456,42 @@ Set supported signature algorithms:
SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
Enable all protocols except SSLv3 and SSLv2:
There are various ways to select the supported protocols.
SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2");
This set the minimum protocol version to TLSv1, and so disables SSLv3.
This is the recommended way to disable protocols.
SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1");
The following also disables SSLv3:
SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
The following will first enable all protocols, and then disable
SSLv3.
If no protocol versions were disabled before this has the same effect as
"-SSLv3", but if some versions were disables this will re-enable them before
disabling SSLv3.
SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3");
Only enable TLSv1.2:
SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2");
SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2");
This also only enables TLSv1.2:
SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
Disable TLS session tickets:
SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
Enable compression:
SSL_CONF_cmd(ctx, "Options", "Compression");
Set supported curves to P-256, P-384:
SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
@@ -426,14 +521,33 @@ SSL_CONF_finish() returns 1 for success and 0 for failure.
=head1 SEE ALSO
L<SSL_CONF_CTX_new(3)|SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)>
L<SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_cmd_argv(3)>,
L<SSL_CTX_set_options(3)>
=head1 HISTORY
SSL_CONF_cmd() was first added to OpenSSL 1.0.2
B<SSL_OP_NO_SSL2> doesn't have effect since 1.1.0, but the macro is retained
for backwards compatibility.
B<SSL_CONF_TYPE_NONE> was first added to OpenSSL 1.1.0. In earlier versions of
OpenSSL passing a command which didn't take an argument would return
B<SSL_CONF_TYPE_UNKNOWN>.
B<MinProtocol> and B<MaxProtocol> where added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/ssl/SSL_CONF_cmd_argv.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
SSL_CONF_cmd_argv - SSL configuration command line processing.
SSL_CONF_cmd_argv - SSL configuration command line processing
=head1 SYNOPSIS
@@ -29,14 +29,23 @@ to an error: for example a syntax error in the argument.
=head1 SEE ALSO
L<SSL_CONF_CTX_new(3)|SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)>
L<SSL_CONF_CTX_new(3)>,
L<SSL_CONF_CTX_set_flags(3)>,
L<SSL_CONF_CTX_set1_prefix(3)>,
L<SSL_CONF_CTX_set_ssl_ctx(3)>,
L<SSL_CONF_cmd(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.2
=head1 COPYRIGHT
Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

12
doc/ssl/SSL_CTX_add1_chain_cert.pod
View File

@@ -138,13 +138,21 @@ a verification error occurs then 2 is returned.
All other functions return 1 for success and 0 for failure.
=head1 SEE ALSO
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
L<SSL_CTX_add_extra_chain_cert(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.2.
=head1 COPYRIGHT
Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

39
doc/ssl/SSL_CTX_add_extra_chain_cert.pod
View File

@@ -30,7 +30,7 @@ following the end entity certificate.
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)>.
L<SSL_CTX_load_verify_locations(3)>.
The B<x509> certificate provided to SSL_CTX_add_extra_chain_cert() will be
freed by the library when the B<SSL_CTX> is destroyed. An application
@@ -53,19 +53,28 @@ reason for failure.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>,
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
L<SSL_CTX_set0_chain(3)|SSL_CTX_set0_chain(3)>
L<SSL_CTX_set1_chain(3)|SSL_CTX_set1_chain(3)>
L<SSL_CTX_add0_chain_cert(3)|SSL_CTX_add0_chain_cert(3)>
L<SSL_CTX_add1_chain_cert(3)|SSL_CTX_add1_chain_cert(3)>
L<SSL_set0_chain(3)|SSL_set0_chain(3)>
L<SSL_set1_chain(3)|SSL_set1_chain(3)>
L<SSL_add0_chain_cert(3)|SSL_add0_chain_cert(3)>
L<SSL_add1_chain_cert(3)|SSL_add1_chain_cert(3)>
L<SSL_CTX_build_cert_chain(3)|SSL_CTX_build_cert_chain(3)>
L<SSL_build_cert_chain(3)|SSL_build_cert_chain(3)>
L<ssl(3)>,
L<SSL_CTX_use_certificate(3)>,
L<SSL_CTX_set_client_cert_cb(3)>,
L<SSL_CTX_load_verify_locations(3)>
L<SSL_CTX_set0_chain(3)>
L<SSL_CTX_set1_chain(3)>
L<SSL_CTX_add0_chain_cert(3)>
L<SSL_CTX_add1_chain_cert(3)>
L<SSL_set0_chain(3)>
L<SSL_set1_chain(3)>
L<SSL_add0_chain_cert(3)>
L<SSL_add1_chain_cert(3)>
L<SSL_CTX_build_cert_chain(3)>
L<SSL_build_cert_chain(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/ssl/SSL_CTX_add_session.pod
View File

@@ -19,10 +19,10 @@ SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session
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)>.
L<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>.
L<SSL_SESSION_free(3)> is called once for B<c>.
SSL_add_session() and SSL_remove_session() are synonyms for their
SSL_CTX_*() counterparts.
@@ -59,15 +59,24 @@ The following values are returned by all functions:
session was not found in the cache.
=item Z<>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)>
L<ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)>,
L<SSL_SESSION_free(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

93
doc/ssl/SSL_CTX_config.pod Normal file
View File

@@ -0,0 +1,93 @@
=pod
=head1 NAME
SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_config(SSL_CTX *ctx, const char *name);
int SSL_config(SSL *s, const char *name);
=head1 DESCRIPTION
The functions SSL_CTX_config() and SSL_config() configure an B<SSL_CTX> or
B<SSL> structure using the configuration B<name>.
=head1 NOTES
By calling SSL_CTX_config() or SSL_config() an application can perform many
complex tasks based on the contents of the configuration file: greatly
simplifying application configuration code. A degree of future proofing
can also be achieved: an application can support configuration features
in newer versions of OpenSSL automatically.
A configuration file must have been previously loaded, for example using
CONF_modules_load_file(). See L<config(3)> for details of the configuration
file syntax.
=head1 RETURN VALUES
SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error
occurred.
=head1 EXAMPLE
If the file "config.cnf" contains the following:
testapp = test_sect
[test_sect]
# list of confuration modules
ssl_conf = ssl_sect
[ssl_sect]
server = server_section
[server_section]
RSA.Certificate = server-rsa.pem
ECDSA.Certificate = server-ecdsa.pem
Ciphers = ALL:!RC4
An application could call:
if (CONF_modules_load_file("config.cnf", "testapp", 0) <= 0) {
fprintf(stderr, "Error processing config file\n");
goto err;
}
ctx = SSL_CTX_new(TLS_server_method());
if (SSL_CTX_config(ctx, "server") == 0) {
fprintf(stderr, "Error configuring server.\n");
goto err;
}
In this example two certificates and the cipher list are configured without
the need for any additional application code.
=head1 SEE ALSO
L<config(3)>,
L<SSL_CONF_cmd(3)>,
L<CONF_modules_load_file(3)>
=head1 HISTORY
SSL_CTX_config() and SSL_config() were first added to OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

11
doc/ssl/SSL_CTX_ctrl.pod
View File

@@ -29,6 +29,15 @@ supplied via the B<cmd> parameter.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>
L<ssl(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

382
doc/ssl/SSL_CTX_dane_enable.pod Normal file
View File

@@ -0,0 +1,382 @@
=pod
=head1 NAME
SSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable,
SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa
SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags,
SSL_dane_set_flags, SSL_dane_clear_flags -
enable DANE TLS authentication of the remote TLS server in the local
TLS client
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_dane_enable(SSL_CTX *ctx);
int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md,
uint8_t mtype, uint8_t ord);
int SSL_dane_enable(SSL *s, const char *basedomain);
int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector,
uint8_t mtype, unsigned char *data, size_t dlen);
int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki);
int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector,
uint8_t *mtype, unsigned const char **data,
size_t *dlen);
unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags);
unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags);
unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags);
unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags);
=head1 DESCRIPTION
These functions implement support for DANE TLSA (RFC6698 and RFC7671)
peer authentication.
SSL_CTX_dane_enable() must be called first to initialize the shared state
required for DANE support.
Individual connections associated with the context can then enable
per-connection DANE support as appropriate.
DANE authentication is implemented in the L<X509_verify_cert(3)> function, and
applications that override L<X509_verify_cert(3)> via
L<SSL_CTX_set_cert_verify_callback(3)> are responsible to authenticate the peer
chain in whatever manner they see fit.
SSL_CTX_dane_mtype_set() may then be called zero or more times to adjust the
supported digest algorithms.
This must be done before any SSL handles are created for the context.
The B<mtype> argument specifies a DANE TLSA matching type and the B<md>
argument specifies the associated digest algorithm handle.
The B<ord> argument specifies a strength ordinal.
Algorithms with a larger strength ordinal are considered more secure.
Strength ordinals are used to implement RFC7671 digest algorithm agility.
Specifying a B<NULL> digest algorithm for a matching type disables
support for that matching type.
Matching type Full(0) cannot be modified or disabled.
By default, matching type C<SHA2-256(1)> (see RFC7218 for definitions
of the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()>
with a strength ordinal of C<1> and matching type C<SHA2-512(2)>
is mapped to C<EVP_sha512()> with a strength ordinal of C<2>.
SSL_dane_enable() must be called before the SSL handshake is initiated with
L<SSL_connect(3)> if (and only if) you want to enable DANE for that connection.
(The connection must be associated with a DANE-enabled SSL context).
The B<basedomain> argument specifies the RFC7671 TLSA base domain,
which will be the primary peer reference identifier for certificate
name checks.
Additional server names can be specified via L<SSL_add1_host(3)>.
The B<basedomain> is used as the default SNI hint if none has yet been
specified via L<SSL_set_tlsext_host_name(3)>.
SSL_dane_tlsa_add() may then be called one or more times, to load each of the
TLSA records that apply to the remote TLS peer.
(This too must be done prior to the beginning of the SSL handshake).
The arguments specify the fields of the TLSA record.
The B<data> field is provided in binary (wire RDATA) form, not the hexadecimal
ASCII presentation form, with an explicit length passed via B<dlen>.
A return value of 0 indicates that "unusable" TLSA records (with invalid or
unsupported parameters) were provided.
A negative return value indicates an internal error in processing the record.
The caller is expected to check the return value of each SSL_dane_tlsa_add()
call and take appropriate action if none are usable or an internal error
is encountered in processing some records.
If no TLSA records are added successfully, DANE authentication is not enabled,
and authentication will be based on any configured traditional trust-anchors;
authentication success in this case does not mean that the peer was
DANE-authenticated.
SSL_get0_dane_authority() can be used to get more detailed information about
the matched DANE trust-anchor after successful connection completion.
The return value is negative if DANE verification failed (or was not enabled),
0 if an EE TLSA record directly matched the leaf certificate, or a positive
number indicating the depth at which a TA record matched an issuer certificate.
The complete verified chain can be retrieved via L<SSL_get0_verified_chain(3)>.
The return value is an index into this verified chain, rather than the list of
certificates sent by the peer as returned by L<SSL_get_peer_cert_chain(3)>.
If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain
certificate, a pointer to the matching certificate is returned via B<mcert>.
The returned address is a short-term internal reference to the certificate and
must not be freed by the application.
Applications that want to retain access to the certificate can call
L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via
L<X509_free(3)> once no longer needed.
If no TLSA records directly matched any elements of the certificate chain, but
a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an
element of the chain, then that key is returned via B<mspki> argument (if not
NULL).
In this case the return value is the depth of the top-most element of the
validated certificate chain.
As with B<mcert> this is a short-term internal reference, and
L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and
release long-term references respectively.
SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that
matched the peer certificate chain.
The return value indicates the match depth or failure to match just as with
SSL_get0_dane_authority().
When the return value is non-negative, the storage pointed to by the B<usage>,
B<selector>, B<mtype> and B<data> parameters is updated to the corresponding
TLSA record fields.
The B<data> field is in binary wire form, and is therefore not NUL-terminated,
its length is returned via the B<dlen> parameter.
If any of these parameters is NULL, the corresponding field is not returned.
The B<data> parameter is set to a short-term internal-copy of the associated
data field and must not be freed by the application.
Applications that need long-term access to this field need to copy the content.
SSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable
optional DANE verification features.
SSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable
the same features.
The B<flags> argument is a bitmask of the features to enable or disable.
The B<flags> set for an B<SSL_CTX> context are copied to each B<SSL> handle
associated with that context at the time the handle is created.
Subsequent changes in the context's B<flags> have no effect on the B<flags> set
for the handle.
At present, the only available option is B<DANE_FLAG_NO_DANE_EE_NAMECHECKS>
which can be used to disable server name checks when authenticating via
DANE-EE(3) TLSA records.
For some applications, primarily web browsers, it is not safe to disable name
checks due to "unknown key share" attacks, in which a malicious server can
convince a client that a connection to a victim server is instead a secure
connection to the malicious server.
The malicious server may then be able to violate cross-origin scripting
restrictions.
Thus, despite the text of RFC7671, name checks are by default enabled for
DANE-EE(3) TLSA records, and can be disabled in applications where it is safe
to do so.
In particular, SMTP and XMPP clients should set this option as SRV and MX
records already make it possible for a remote domain to redirect client
connections to any server of its choice, and in any case SMTP and XMPP clients
do not execute scripts downloaded from remote servers.
=head1 RETURN VALUES
The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(),
SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success.
Negative return values indicate resource problems (out of memory, etc.) in the
SSL library, while a return value of B<0> indicates incorrect usage or invalid
input, such as an unsupported TLSA record certificate usage, selector or
matching type.
Invalid input also includes malformed data, either a digest length that does
not match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form)
certificate or a public key that fails to parse.
The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a
negative value when DANE authentication failed or was not enabled, a
non-negative value indicates the chain depth at which the TLSA record matched a
chain certificate, or the depth of the top-most certificate, when the TLSA
record is a full public key that is its signer.
The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(),
SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect
before they were called.
=head1 EXAMPLE
Suppose "smtp.example.com" is the MX host of the domain "example.com", and has
DNSSEC-validated TLSA records.
The calls below will perform DANE authentication and arrange to match either
the MX hostname or the destination domain name in the SMTP server certificate.
Wildcards are supported, but must match the entire label.
The actual name matched in the certificate (which might be a wildcard) is
retrieved, and must be copied by the application if it is to be retained beyond
the lifetime of the SSL connection.
SSL_CTX *ctx;
SSL *ssl;
int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL;
int num_usable = 0;
const char *nexthop_domain = "example.com";
const char *dane_tlsa_domain = "smtp.example.com";
uint8_t usage, selector, mtype;
if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL)
/* handle error */
if (SSL_CTX_dane_enable(ctx) <= 0)
/* handle error */
if ((ssl = SSL_new(ctx)) == NULL)
/* handle error */
if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0)
/* handle error */
/*
* For many applications it is safe to skip DANE-EE(3) namechecks. Do not
* disable the checks unless "unknown key share" attacks pose no risk for
* your application.
*/
SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS);
if (!SSL_add1_host(ssl, nexthop_domain))
/* handle error */
SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
for (... each TLSA record ...) {
unsigned char *data;
size_t len;
int ret;
/* set usage, selector, mtype, data, len */
/*
* Opportunistic DANE TLS clients support only DANE-TA(2) or DANE-EE(3).
* They treat all other certificate usages, and in particular PKIX-TA(0)
* and PKIX-EE(1), as unusable.
*/
switch (usage) {
default:
case 0: /* PKIX-TA(0) */
case 1: /* PKIX-EE(1) */
continue;
case 2: /* DANE-TA(2) */
case 3: /* DANE-EE(3) */
break;
}
ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len);
/* free data as appropriate */
if (ret < 0)
/* handle SSL library internal error */
else if (ret == 0)
/* handle unusable TLSA record */
else
++num_usable;
}
/*
* At this point, the verification mode is still the default SSL_VERIFY_NONE.
* Opportunistic DANE clients use unauthenticated TLS when all TLSA records
* are unusable, so continue the handshake even if authentication fails.
*/
if (num_usable == 0) {
/* Log all records unusable? */
/* Optionally set verify_cb to a suitable non-NULL callback. */
SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb);
} else {
/* At least one usable record. We expect to verify the peer */
/* Optionally set verify_cb to a suitable non-NULL callback. */
/*
* Below we elect to fail the handshake when peer verification fails.
* Alternatively, use the permissive SSL_VERIFY_NONE verification mode,
* complete the handshake, check the verification status, and if not
* verified disconnect gracefully at the application layer, especially if
* application protocol supports informing the server that authentication
* failed.
*/
SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb);
}
/*
* Load any saved session for resumption, making sure that the previous
* session applied the same security and authentication requirements that
* would be expected of a fresh connection.
*/
/* Perform SSL_connect() handshake and handle errors here */
if (SSL_session_reused(ssl)) {
if (SSL_get_verify_result(ssl) == X509_V_OK) {
/*
* Resumed session was originally verified, this connection is
* authenticated.
*/
} else {
/*
* Resumed session was not originally verified, this connection is not
* authenticated.
*/
}
} else if (SSL_get_verify_result(ssl) == X509_V_OK) {
const char *peername = SSL_get0_peername(ssl);
EVP_PKEY *mspki = NULL;
int depth = SSL_get0_dane_authority(ssl, NULL, &mspki);
if (depth >= 0) {
(void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL);
printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype,
(mspki != NULL) ? "TA public key verified certificate" :
depth ? "matched TA certificate" : "matched EE certificate",
depth);
}
if (peername != NULL) {
/* Name checks were in scope and matched the peername */
printf("Verified peername: %s\n", peername);
}
} else {
/*
* Not authenticated, presumably all TLSA rrs unusable, but possibly a
* callback suppressed connection termination despite the presence of
* usable TLSA RRs none of which matched. Do whatever is appropriate for
* fresh unauthenticated connections.
*/
}
=head1 NOTES
It is expected that the majority of clients employing DANE TLS will be doing
"opportunistic DANE TLS" in the sense of RFC7672 and RFC7435.
That is, they will use DANE authentication when DNSSEC-validated TLSA records
are published for a given peer, and otherwise will use unauthenticated TLS or
even cleartext.
Such applications should generally treat any TLSA records published by the peer
with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include
them among the TLSA records used to authenticate peer connections.
In addition, some TLSA records with supported usages may be "unusable" as a
result of invalid or unsupported parameters.
When a peer has TLSA records, but none are "usable", an opportunistic
application must avoid cleartext, but cannot authenticate the peer,
and so should generally proceed with an unauthenticated connection.
Opportunistic applications need to note the return value of each
call to SSL_dane_tlsa_add(), and if all return 0 (due to invalid
or unsupported parameters) disable peer authentication by calling
L<SSL_set_verify(3)> with B<mode> equal to B<SSL_VERIFY_NONE>.
=head1 SEE ALSO
L<SSL_new(3)>,
L<SSL_add1_host(3)>,
L<SSL_set_hostflags(3)>,
L<SSL_set_tlsext_host_name(3)>,
L<SSL_set_verify(3)>,
L<SSL_CTX_set_cert_verify_callback(3)>,
L<SSL_get0_verified_chain(3)>,
L<SSL_get_peer_cert_chain(3)>,
L<SSL_get_verify_result(3)>,
L<SSL_connect(3)>,
L<SSL_get0_peername(3)>,
L<X509_verify_cert(3)>,
L<X509_up_ref(3)>,
L<X509_free(3)>,
L<EVP_get_digestbyname(3)>,
L<EVP_PKEY_up_ref(3)>,
L<EVP_PKEY_free(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

25
doc/ssl/SSL_CTX_flush_sessions.pod
View File

@@ -25,8 +25,8 @@ 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().
L<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)
@@ -35,15 +35,22 @@ 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
L<SSL_CTX_sess_set_get_cb(3)>).
=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)>
L<ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_set_timeout(3)>,
L<SSL_CTX_sess_set_get_cb(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

18
doc/ssl/SSL_CTX_free.pod
View File

@@ -13,13 +13,14 @@ SSL_CTX_free - free an allocated SSL_CTX object
=head1 DESCRIPTION
SSL_CTX_free() decrements the reference count of B<ctx>, and removes the
SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the
the reference count has reached 0.
SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the reference count has reached 0.
It also calls the free()ing procedures for indirectly affected items, if
applicable: the session cache, the list of ciphers, the list of Client CAs,
the certificates and keys.
If B<ctx> is NULL nothing is done.
=head1 WARNINGS
If a session-remove callback is set (SSL_CTX_sess_set_remove_cb()), this
@@ -35,7 +36,16 @@ SSL_CTX_free() does not provide diagnostic information.
=head1 SEE ALSO
L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<ssl(3)|ssl(3)>,
L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>
L<SSL_CTX_new(3)>, L<ssl(3)>,
L<SSL_CTX_sess_set_get_cb(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

11
doc/ssl/SSL_CTX_get0_param.pod
View File

@@ -46,10 +46,19 @@ for failure.
=head1 SEE ALSO
L<X509_VERIFY_PARAM_set_flags(3)|X509_VERIFY_PARAM_set_flags(3)>
L<X509_VERIFY_PARAM_set_flags(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.2.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

53
doc/ssl/SSL_CTX_get_ex_new_index.pod
View File

@@ -1,53 +0,0 @@
=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(const 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(3)|RSA_get_ex_new_index(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

11
doc/ssl/SSL_CTX_get_verify_mode.pod
View File

@@ -45,6 +45,15 @@ See DESCRIPTION
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
L<ssl(3)>, L<SSL_CTX_set_verify(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

37
doc/ssl/SSL_CTX_has_client_custom_ext.pod Normal file
View File

@@ -0,0 +1,37 @@
=pod
=head1 NAME
SSL_CTX_has_client_custom_ext - check whether a handler exists for a particular
client extension type
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_has_client_custom_ext(const SSL_CTX *ctx, unsigned int ext_type);
=head1 DESCRIPTION
SSL_CTX_has_client_custom_ext() checks whether a handler has been set for a
client extension of type B<ext_type> using SSL_CTX_add_client_custom_ext().
=head1 RETURN VALUES
Returns 1 if a handler has been set, 0 otherwise.
=head1 SEE ALSO
L<ssl(3)>,
L<SSL_CTX_add_client_custom_ext(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

61
doc/ssl/SSL_CTX_load_verify_locations.pod
View File

@@ -2,8 +2,9 @@
=head1 NAME
SSL_CTX_load_verify_locations - set default locations for trusted CA
certificates
SSL_CTX_load_verify_locations, SSL_CTX_set_default_verify_paths,
SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file - set
default locations for trusted CA certificates
=head1 SYNOPSIS
@@ -12,12 +13,34 @@ certificates
int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
const char *CApath);
int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);
int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx);
int SSL_CTX_set_default_verify_file(SSL_CTX *ctx);
=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.
SSL_CTX_set_default_verify_paths() specifies that the default locations from
which CA certificates are loaded should be used. There is one default directory
and one default file. The default CA certificates directory is called "certs" in
the default OpenSSL directory. Alternatively the SSL_CERT_DIR environment
variable can be defined to override this location. The default CA certificates
file is called "cert.pem" in the default OpenSSL directory. Alternatively the
SSL_CERT_FILE environment variable can be defined to override this location.
SSL_CTX_set_default_verify_dir() is similar to
SSL_CTX_set_default_verify_paths() except that just the default directory is
used.
SSL_CTX_set_default_verify_file() is similar to
SSL_CTX_set_default_verify_paths() except that just the default file is
used.
=head1 NOTES
If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
@@ -59,14 +82,14 @@ In server mode, when requesting a client certificate, the server must send
the list of CAs of which it will accept client certificates. This list
is not influenced by the contents of B<CAfile> or B<CApath> and must
explicitly be set using the
L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
L<SSL_CTX_set_client_CA_list(3)>
family of functions.
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)>.
L<SSL_CTX_add_extra_chain_cert(3)>,
L<SSL_CTX_use_certificate(3)>.
=head1 WARNINGS
@@ -96,7 +119,7 @@ for use as B<CApath>:
=head1 RETURN VALUES
The following return values can occur:
For SSL_CTX_load_verify_locations the following return values can occur:
=over 4
@@ -112,13 +135,27 @@ The operation succeeded.
=back
SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and
SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A
missing default location is still treated as a success.
=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)>,
L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>
L<ssl(3)>,
L<SSL_CTX_set_client_CA_list(3)>,
L<SSL_get_client_CA_list(3)>,
L<SSL_CTX_use_certificate(3)>,
L<SSL_CTX_add_extra_chain_cert(3)>,
L<SSL_CTX_set_cert_store(3)>,
L<SSL_CTX_set_client_CA_list(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

198
doc/ssl/SSL_CTX_new.pod
View File

@@ -2,138 +2,131 @@
=head1 NAME
SSL_CTX_new,
SSLv23_method, SSLv23_server_method, SSLv23_client_method,
TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method,
TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method,
TLSv1_method, TLSv1_server_method, TLSv1_client_method,
SSLv3_method, SSLv3_server_method, SSLv3_client_method,
SSLv2_method, SSLv2_server_method, SSLv2_client_method,
DTLS_method, DTLS_server_method, DTLS_client_method,
DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method,
DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method -
create a new SSL_CTX object as framework for TLS/SSL enabled functions
SSL_CTX_new, SSL_CTX_up_ref, SSLv3_method, SSLv3_server_method,
SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method,
TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method,
TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method,
SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method,
DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method,
DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method
- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled
functions
=head1 SYNOPSIS
#include <openssl/ssl.h>
SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
int SSL_CTX_up_ref(SSL_CTX *ctx);
const SSL_METHOD *TLS_method(void);
const SSL_METHOD *TLS_server_method(void);
const SSL_METHOD *TLS_client_method(void);
const SSL_METHOD *SSLv23_method(void);
const SSL_METHOD *SSLv23_server_method(void);
const SSL_METHOD *SSLv23_client_method(void);
const SSL_METHOD *TLSv1_2_method(void);
const SSL_METHOD *TLSv1_2_server_method(void);
const SSL_METHOD *TLSv1_2_client_method(void);
const SSL_METHOD *TLSv1_1_method(void);
const SSL_METHOD *TLSv1_1_server_method(void);
const SSL_METHOD *TLSv1_1_client_method(void);
const SSL_METHOD *TLSv1_method(void);
const SSL_METHOD *TLSv1_server_method(void);
const SSL_METHOD *TLSv1_client_method(void);
#ifndef OPENSSL_NO_SSL3_METHOD
const SSL_METHOD *SSLv3_method(void);
const SSL_METHOD *SSLv3_server_method(void);
const SSL_METHOD *SSLv3_client_method(void);
#endif
#ifndef OPENSSL_NO_SSL2
const SSL_METHOD *SSLv2_method(void);
const SSL_METHOD *SSLv2_server_method(void);
const SSL_METHOD *SSLv2_client_method(void);
#ifndef OPENSSL_NO_TLS1_METHOD
const SSL_METHOD *TLSv1_method(void);
const SSL_METHOD *TLSv1_server_method(void);
const SSL_METHOD *TLSv1_client_method(void);
#endif
#ifndef OPENSSL_NO_TLS1_1_METHOD
const SSL_METHOD *TLSv1_1_method(void);
const SSL_METHOD *TLSv1_1_server_method(void);
const SSL_METHOD *TLSv1_1_client_method(void);
#endif
#ifndef OPENSSL_NO_TLS1_2_METHOD
const SSL_METHOD *TLSv1_2_method(void);
const SSL_METHOD *TLSv1_2_server_method(void);
const SSL_METHOD *TLSv1_2_client_method(void);
#endif
const SSL_METHOD *DTLS_method(void);
const SSL_METHOD *DTLS_server_method(void);
const SSL_METHOD *DTLS_client_method(void);
const SSL_METHOD *DTLSv1_2_method(void);
const SSL_METHOD *DTLSv1_2_server_method(void);
const SSL_METHOD *DTLSv1_2_client_method(void);
#ifndef OPENSSL_NO_DTLS1_METHOD
const SSL_METHOD *DTLSv1_method(void);
const SSL_METHOD *DTLSv1_server_method(void);
const SSL_METHOD *DTLSv1_client_method(void);
#endif
#ifndef OPENSSL_NO_DTLS1_2_METHOD
const SSL_METHOD *DTLSv1_2_method(void);
const SSL_METHOD *DTLSv1_2_server_method(void);
const SSL_METHOD *DTLSv1_2_client_method(void);
#endif
=head1 DESCRIPTION
SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish
TLS/SSL enabled connections.
SSL_CTX_new() creates a new B<SSL_CTX> object as framework to
establish TLS/SSL or DTLS enabled connections. An B<SSL_CTX> object is
reference counted. Creating an B<SSL_CTX> object for the first time increments
the reference count. Freeing it (using SSL_CTX_free) decrements it. When the
reference count drops to zero, any memory or resources allocated to the
B<SSL_CTX> object are freed. SSL_CTX_up_ref() increments the reference count for
an existing B<SSL_CTX> structure.
=head1 NOTES
The SSL_CTX object uses B<method> as connection method. The methods exist
in a generic type (for client and server use), a server only type, and a
client only type. B<method> can be of the following types:
The SSL_CTX object uses B<method> as connection method.
The methods exist in a generic type (for client and server use), a server only
type, and a client only type.
B<method> can be of the following types:
=over 4
=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
=item TLS_method(), TLS_server_method(), TLS_client_method()
These are the general-purpose I<version-flexible> SSL/TLS methods.
The actual protocol version used will be negotiated to the highest version
mutually supported by the client and the server.
The supported protocols are SSLv2, SSLv3, TLSv1, TLSv1.1 and TLSv1.2.
Most applications should use these method, and avoid the version specific
The supported protocols are SSLv3, TLSv1, TLSv1.1 and TLSv1.2.
Applications should use these methods, and avoid the version-specific
methods described below.
The list of protocols available can be further limited using the
B<SSL_OP_NO_SSLv2>, B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>,
B<SSL_OP_NO_TLSv1_1> and B<SSL_OP_NO_TLSv1_2> options of the
L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions.
Clients should avoid creating "holes" in the set of protocols they support,
when disabling a protocol, make sure that you also disable either all previous
or all subsequent protocol versions.
In clients, when a protocol version is disabled without disabling I<all>
previous protocol versions, the effect is to also disable all subsequent
protocol versions.
=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
The SSLv2 and SSLv3 protocols are deprecated and should generally not be used.
Applications should typically use L<SSL_CTX_set_options(3)> in combination with
the B<SSL_OP_NO_SSLv3> flag to disable negotiation of SSLv3 via the above
I<version-flexible> SSL/TLS methods.
The B<SSL_OP_NO_SSLv2> option is set by default, and would need to be cleared
via L<SSL_CTX_clear_options(3)> in order to enable negotiation of SSLv2.
Use of these functions is deprecated. They have been replaced with the above
TLS_method(), TLS_server_method() and TLS_client_method() respectively. New
code should use those functions instead.
=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
A TLS/SSL connection established with these methods will only understand the
TLSv1.2 protocol. A client will send out TLSv1.2 client hello messages and
will also indicate that it only understand TLSv1.2. A server will only
understand TLSv1.2 client hello messages.
TLSv1.2 protocol.
=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
A TLS/SSL connection established with these methods will only understand the
TLSv1.1 protocol. A client will send out TLSv1.1 client hello messages and
will also indicate that it only understand TLSv1.1. A server will only
understand TLSv1.1 client hello messages.
TLSv1.1 protocol.
=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
A TLS/SSL connection established with these methods will only understand the
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.
TLSv1 protocol.
=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
A TLS/SSL connection established with these methods will only understand the
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. The SSLv3 protocol is deprecated and should not be
used.
=item SSLv2_method(), SSLv2_server_method(), SSLv2_client_method()
A TLS/SSL connection established with these methods will only understand the
SSLv2 protocol. A client will send out SSLv2 client hello messages and will
also indicate that it only understand SSLv2. A server will only understand
SSLv2 client hello messages. The SSLv2 protocol offers little to no security
and should not be used.
As of OpenSSL 1.0.2g, EXPORT ciphers and 56-bit DES are no longer available
with SSLv2.
SSLv3 protocol.
The SSLv3 protocol is deprecated and should not be used.
=item DTLS_method(), DTLS_server_method(), DTLS_client_method()
These are the version-flexible DTLS methods.
Currently supported protocols are DTLS 1.0 and DTLS 1.2.
=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
@@ -146,7 +139,36 @@ These are the version-specific methods for DTLSv1.
=back
SSL_CTX_new() initializes the list of ciphers, the session cache setting, the
callbacks, the keys and certificates and the options to its default values.
callbacks, the keys and certificates and the options to their default values.
TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(),
DTLS_server_method() and DTLS_client_method() are the I<version-flexible>
methods.
All other methods only support one specific protocol version.
Use the I<version-flexible> methods instead of the version specific methods.
If you want to limit the supported protocols for the version flexible
methods you can use L<SSL_CTX_set_min_proto_version(3)>,
L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and
L<SSL_set_max_proto_version(3)> functions.
Using these functions it is possible to choose e.g. TLS_server_method()
and be able to negotiate with all possible clients, but to only
allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2.
The list of protocols available can also be limited using the
B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> and
B<SSL_OP_NO_TLSv1_2> options of the L<SSL_CTX_set_options(3)> or
L<SSL_set_options(3)> functions, but this approach is not recommended.
Clients should avoid creating "holes" in the set of protocols they support.
When disabling a protocol, make sure that you also disable either all previous
or all subsequent protocol versions.
In clients, when a protocol version is disabled without disabling I<all>
previous protocol versions, the effect is to also disable all subsequent
protocol versions.
The SSLv3 protocol is deprecated and should generally not be used.
Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set
the minimum protocol to at least B<TLS1_VERSION>.
=head1 RETURN VALUES
@@ -163,12 +185,34 @@ the reason.
The return value points to an allocated SSL_CTX object.
SSL_CTX_up_ref() returns 1 for success and 0 for failure.
=back
=head1 HISTORY
Support for SSLv2 and the corresponding SSLv2_method(),
SSLv2_server_method() and SSLv2_client_method() functions where
removed in OpenSSL 1.1.0.
SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
were deprecated and the preferred TLS_method(), TLS_server_method()
and TLS_client_method() functions were introduced in OpenSSL 1.1.0.
All version-specific methods were deprecated in OpenSSL 1.1.0.
=head1 SEE ALSO
L<SSL_CTX_set_options(3)>, L<SSL_CTX_clear_options(3)>, L<SSL_set_options(3)>,
L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>,
L<ssl(3)|ssl(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
L<SSL_CTX_set_min_proto_version(3)>, L<ssl(3)>, L<SSL_set_connect_state(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

17
doc/ssl/SSL_CTX_sess_number.pod
View File

@@ -45,7 +45,7 @@ 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)>
In client mode a session set with L<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.
@@ -69,8 +69,17 @@ 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)>
L<ssl(3)>, L<SSL_set_session(3)>,
L<SSL_CTX_set_session_cache_mode(3)>
L<SSL_CTX_sess_set_cache_size(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

19
doc/ssl/SSL_CTX_sess_set_cache_size.pod
View File

@@ -29,7 +29,7 @@ case is the size 0, which is used for unlimited size.
If adding the session makes the cache exceed its size, then unused
sessions are dropped from the end of the cache.
Cache space may also be reclaimed by calling
L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> to remove
L<SSL_CTX_flush_sessions(3)> to remove
expired sessions.
If the size of the session cache is reduced and more sessions are already
@@ -45,9 +45,18 @@ 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)>
L<ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_sess_number(3)>,
L<SSL_CTX_flush_sessions(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

39
doc/ssl/SSL_CTX_sess_set_get_cb.pod
View File

@@ -9,20 +9,20 @@ SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SS
#include <openssl/ssl.h>
void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
int (*new_session_cb)(SSL *, SSL_SESSION *));
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 (*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 *));
SSL_SESSION (*get_session_cb)(SSL *, const 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);
SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, const 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);
int len, int *copy);
=head1 DESCRIPTION
@@ -37,7 +37,7 @@ 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)>).
L<SSL_CTX_set_session_cache_mode(3)>).
(SSL/TLS server only.)
SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
@@ -50,11 +50,11 @@ the NULL pointer is returned.
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.
L<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)>).
L<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.
@@ -63,7 +63,7 @@ The remove_session_cb() is called, whenever the SSL engine removes a session
from the internal cache. This happens when the session is removed because
it is expired or when a connection was not shutdown cleanly. It also happens
for all sessions in the internal session cache when
L<SSL_CTX_free(3)|SSL_CTX_free(3)> is called. The remove_session_cb() is passed
L<SSL_CTX_free(3)> is called. 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
@@ -74,14 +74,23 @@ B<data>. With the parameter B<copy> the callback can require the
SSL engine to increment the reference count of the SSL_SESSION object,
Normally the reference count is not incremented and therefore the
session must not be explicitly freed with
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>.
L<SSL_SESSION_free(3)>.
=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)>,
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
L<SSL_CTX_free(3)|SSL_CTX_free(3)>
L<ssl(3)>, L<d2i_SSL_SESSION(3)>,
L<SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_flush_sessions(3)>,
L<SSL_SESSION_free(3)>,
L<SSL_CTX_free(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/ssl/SSL_CTX_sessions.pod
View File

@@ -18,17 +18,26 @@ 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
L<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
L<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.
L<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)>
L<ssl(3)>, L<lhash(3)>,
L<SSL_CTX_add_session(3)>,
L<SSL_CTX_set_session_cache_mode(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

43
doc/ssl/SSL_CTX_set1_curves.pod
View File

@@ -3,8 +3,7 @@
=head1 NAME
SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves,
SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve,
SSL_CTX_set_ecdh_auto, SSL_set_ecdh_auto - EC supported curve functions
SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve - EC supported curve functions
=head1 SYNOPSIS
@@ -19,15 +18,12 @@ SSL_CTX_set_ecdh_auto, SSL_set_ecdh_auto - EC supported curve functions
int SSL_get1_curves(SSL *ssl, int *curves);
int SSL_get_shared_curve(SSL *s, int n);
int SSL_CTX_set_ecdh_auto(SSL_CTX *ctx, int onoff);
int SSL_set_ecdh_auto(SSL *s, int onoff);
=head1 DESCRIPTION
SSL_CTX_set1_curves() sets the supported curves for B<ctx> to B<clistlen>
curves in the array B<clist>. The array consist of all NIDs of curves in
preference order. For a TLS client the curves are used directly in the
supported curves extension. For a TLS server the curves are used to
supported curves extension. For a TLS server the curves are used to
determine the set of shared curves.
SSL_CTX_set1_curves_list() sets the supported curves for B<ctx> to
@@ -38,7 +34,7 @@ SSL_set1_curves() and SSL_set1_curves_list() are similar except they set
supported curves for the SSL structure B<ssl>.
SSL_get1_curves() returns the set of supported curves sent by a client
in the supported curves extension. It returns the total number of
in the supported curves extension. It returns the total number of
supported curves. The B<curves> parameter can be B<NULL> to simply
return the number of curves for memory allocation purposes. The
B<curves> array is in the form of a set of curve NIDs in preference
@@ -52,11 +48,6 @@ most applications will only be interested in the first shared curve
so B<n> is normally set to zero. If the value B<n> is out of range,
NID_undef is returned.
SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() set automatic curve
selection for server B<ctx> or B<ssl> to B<onoff>. If B<onoff> is 1 then
the highest preference curve is automatically used for ECDH temporary
keys used during key exchange.
All these functions are implemented as macros.
=head1 NOTES
@@ -65,23 +56,10 @@ If an application wishes to make use of several of these functions for
configuration purposes either on a command line or in a file it should
consider using the SSL_CONF interface instead of manually parsing options.
The functions SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() can be used to
make a server always choose the most appropriate curve for a client. If set
it will override any temporary ECDH parameters set by a server. Previous
versions of OpenSSL could effectively only use a single ECDH curve set
using a function such as SSL_CTX_set_ecdh_tmp(). Newer applications should
just call:
SSL_CTX_set_ecdh_auto(ctx, 1);
and they will automatically support ECDH using the most appropriate shared
curve.
=head1 RETURN VALUES
SSL_CTX_set1_curves(), SSL_CTX_set1_curves_list(), SSL_set1_curves(),
SSL_set1_curves_list(), SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto()
return 1 for success and 0 for failure.
SSL_CTX_set1_curves(), SSL_CTX_set1_curves_list(), SSL_set1_curves() and
SSL_set1_curves_list(), return 1 for success and 0 for failure.
SSL_get1_curves() returns the number of curves, which may be zero.
@@ -94,10 +72,19 @@ returns -1.
=head1 SEE ALSO
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
L<SSL_CTX_add_extra_chain_cert(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.2.
=head1 COPYRIGHT
Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

113
doc/ssl/SSL_CTX_set1_sigalgs.pod Normal file
View File

@@ -0,0 +1,113 @@
=pod
=head1 NAME
SSL_CTX_set1_sigalgs, SSL_set1_sigalgs, SSL_CTX_set1_sigalgs_list,
SSL_set1_sigalgs_list, SSL_CTX_set1_client_sigalgs,
SSL_set1_client_sigalgs, SSL_CTX_set1_client_sigalgs_list,
SSL_set1_client_sigalgs_list - set supported signature algorithms
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_set1_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen);
long SSL_set1_sigalgs(SSL *ssl, const int *slist, long slistlen);
long SSL_CTX_set1_sigalgs_list(SSL_CTX *ctx, const char *str);
long SSL_set1_sigalgs_list(SSL *ssl, const char *str);
long SSL_CTX_set1_client_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen);
long SSL_set1_client_sigalgs(SSL *ssl, const int *slist, long slistlen);
long SSL_CTX_set1_client_sigalgs_list(SSL_CTX *ctx, const char *str);
long SSL_set1_client_sigalgs_list(SSL *ssl, const char *str);
=head1 DESCRIPTION
SSL_CTX_set1_sigalgs() and SSL_set1_sigalgs() set the supported signature
algorithms for B<ctx> or B<ssl>. The array B<slist> of length B<slistlen>
must consist of pairs of NIDs corresponding to digest and public key
algorithms.
SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list() set the supported
signature algorithms for B<ctx> or B<ssl>. The B<str> parameter
must be a null terminated string consisting or a colon separated list of
public key algorithms and digests separated by B<+>.
SSL_CTX_set1_client_sigalgs(), SSL_set1_client_sigalgs(),
SSL_CTX_set1_client_sigalgs_list() and SSL_set1_client_sigalgs_list() set
signature algorithms related to client authentication, otherwise they are
identical to SSL_CTX_set1_sigalgs(), SSL_set1_sigalgs(),
SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list().
All these functions are implemented as macros. The signature algorithm
parameter (integer array or string) is not freed: the application should
free it, if necessary.
=head1 NOTES
If an application wishes to allow the setting of signature algorithms
as one of many user configurable options it should consider using the more
flexible SSL_CONF API instead.
The signature algorithms set by a client are used directly in the supported
signature algorithm in the client hello message.
The supported signature algorithms set by a server are not sent to the
client but are used to determine the set of shared signature algorithms
and (if server preferences are set with SSL_OP_CIPHER_SERVER_PREFERENCE)
their order.
The client authentication signature algorithms set by a server are sent
in a certificate request message if client authentication is enabled,
otherwise they are unused.
Similarly client authentication signature algorithms set by a client are
used to determined the set of client authentication shared signature
algorithms.
Signature algorithms will neither be advertised nor used if the security level
prohibits them (for example SHA1 if the security level is 4 or more).
Currently the NID_md5, NID_sha1, NID_sha224, NID_sha256, NID_sha384 and
NID_sha512 digest NIDs are supported and the public key algorithm NIDs
EVP_PKEY_RSA, EVP_PKEY_DSA and EVP_PKEY_EC.
The short or long name values for digests can be used in a string (for
example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and
the public key algorithm strings "RSA", "DSA" or "ECDSA".
The use of MD5 as a digest is strongly discouraged due to security weaknesses.
=head1 EXAMPLES
Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA
using an array:
const int slist[] = {NID_sha256, EVP_PKEY_EC, NID_sha256, EVP_PKEY_RSA};
SSL_CTX_set1_sigalgs(ctx, slist, 4);
Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA
using a string:
SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256");
=head1 RETURN VALUES
All these functions return 1 for success and 0 for failure.
=head1 SEE ALSO
L<ssl(3)>, L<SSL_get_shared_sigalgs(3)>,
L<SSL_CONF_CTX_new(3)>
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

37
doc/ssl/SSL_CTX_set1_verify_cert_store.pod
View File

@@ -54,9 +54,9 @@ any client certificate chain.
The chain store is used to build the certificate chain.
If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set or a certificate chain is
configured already (for example using the functions such as
L<SSL_CTX_add1_chain_cert(3)|SSL_CTX_add1_chain_cert(3)> or
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>) then
configured already (for example using the functions such as
L<SSL_CTX_add1_chain_cert(3)> or
L<SSL_CTX_add_extra_chain_cert(3)>) then
automatic chain building is disabled.
If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set then automatic chain building
@@ -72,20 +72,29 @@ All these functions return 1 for success and 0 for failure.
=head1 SEE ALSO
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
L<SSL_CTX_set0_chain(3)|SSL_CTX_set0_chain(3)>
L<SSL_CTX_set1_chain(3)|SSL_CTX_set1_chain(3)>
L<SSL_CTX_add0_chain_cert(3)|SSL_CTX_add0_chain_cert(3)>
L<SSL_CTX_add1_chain_cert(3)|SSL_CTX_add1_chain_cert(3)>
L<SSL_set0_chain(3)|SSL_set0_chain(3)>
L<SSL_set1_chain(3)|SSL_set1_chain(3)>
L<SSL_add0_chain_cert(3)|SSL_add0_chain_cert(3)>
L<SSL_add1_chain_cert(3)|SSL_add1_chain_cert(3)>
L<SSL_CTX_build_cert_chain(3)|SSL_CTX_build_cert_chain(3)>
L<SSL_build_cert_chain(3)|SSL_build_cert_chain(3)>
L<SSL_CTX_add_extra_chain_cert(3)>
L<SSL_CTX_set0_chain(3)>
L<SSL_CTX_set1_chain(3)>
L<SSL_CTX_add0_chain_cert(3)>
L<SSL_CTX_add1_chain_cert(3)>
L<SSL_set0_chain(3)>
L<SSL_set1_chain(3)>
L<SSL_add0_chain_cert(3)>
L<SSL_add1_chain_cert(3)>
L<SSL_CTX_build_cert_chain(3)>
L<SSL_build_cert_chain(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.2.
=head1 COPYRIGHT
Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

89
doc/ssl/SSL_CTX_set_alpn_select_cb.pod
View File

@@ -3,17 +3,18 @@
=head1 NAME
SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
SSL_select_next_proto, SSL_get0_alpn_selected - handle application layer
protocol negotiation (ALPN)
SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb,
SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated
- handle application layer protocol negotiation (ALPN)
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
unsigned protos_len);
unsigned int protos_len);
int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
unsigned protos_len);
unsigned int protos_len);
void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
int (*cb) (SSL *ssl,
const unsigned char **out,
@@ -21,13 +22,30 @@ protocol negotiation (ALPN)
const unsigned char *in,
unsigned int inlen,
void *arg), void *arg);
void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
unsigned int *len);
void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx,
int (*cb)(SSL *ssl,
const unsigned char **out,
unsigned int *outlen,
void *arg),
void *arg);
void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx,
int (*cb)(SSL *s,
unsigned char **out,
unsigned char *outlen,
const unsigned char *in,
unsigned int inlen,
void *arg),
void *arg);
int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
const unsigned char *server,
unsigned int server_len,
const unsigned char *client,
unsigned int client_len)
void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
unsigned int *len);
void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data,
unsigned *len);
=head1 DESCRIPTION
@@ -44,7 +62,8 @@ the application callback.
B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
vector in protocol-list format. The value of the B<out>, B<outlen> vector
should be set to the value of a single protocol selected from the B<in>,
B<inlen> vector. The B<arg> parameter is the pointer set via
B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a
buffer that outlives the handshake. The B<arg> parameter is the pointer set via
SSL_CTX_set_alpn_select_cb().
SSL_select_next_proto() is a helper function used to select protocols. It
@@ -58,10 +77,40 @@ B<client>, so it should be copied immediately. If no match is found, the first
item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This
function can also be used in the NPN callback.
SSL_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a
client needs to select a protocol from the server's provided list, and a
user-defined pointer argument B<arg> which will be passed to this callback.
For the callback itself, B<out>
must be set to point to the selected protocol (which may be within B<in>).
The length of the protocol name must be written into B<outlen>. The
server's advertised protocols are provided in B<in> and B<inlen>. The
callback can assume that B<in> is syntactically valid. The client must
select a protocol. It is fatal to the connection if this callback returns
a value other than B<SSL_TLSEXT_ERR_OK>. The B<arg> parameter is the pointer
set via SSL_CTX_set_next_proto_select_cb().
SSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called
when a TLS server needs a list of supported protocols for Next Protocol
Negotiation. The returned list must be in protocol-list format, described
below. The list is
returned by setting B<out> to point to it and B<outlen> to its length. This
memory will not be modified, but the B<SSL> does keep a
reference to it. The callback should return B<SSL_TLSEXT_ERR_OK> if it
wishes to advertise. Otherwise, no such extension will be included in the
ServerHello.
SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data>
with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len>
is set to 0 if no protocol has been selected. B<data> must not be freed.
SSL_get0_next_proto_negotiated() sets B<data> and B<len> to point to the
client's requested protocol for this connection. If the client did not
request any protocol or NPN is not enabled, then B<data> is set to NULL and
B<len> to 0. Note that
the client can request any protocol it chooses. The value returned from
this function need not be a member of the list of supported protocols
provided by the callback.
=head1 NOTES
The protocol-lists must be in wire-format, which is defined as a vector of
@@ -112,15 +161,37 @@ The ALPN select callback B<cb>, must return one of the following:
ALPN protocol selected.
=item SSL_TLSEXT_ERR_ALERT_FATAL
There was no overlap between the client's supplied list and the server
configuration.
=item SSL_TLSEXT_ERR_NOACK
ALPN protocol not selected.
ALPN protocol not selected, e.g., because no ALPN protocols are configured for
this connection.
=back
The callback set using SSL_CTX_set_next_proto_select_cb() should return
B<SSL_TLSEXT_ERR_OK> if successful. Any other value is fatal to the connection.
The callback set using SSL_CTX_set_next_protos_advertised_cb() should return
B<SSL_TLSEXT_ERR_OK> if it wishes to advertise. Otherwise, no such extension
will be included in the ServerHello.
=head1 SEE ALSO
L<ssl(3)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
L<SSL_CTX_set_tlsext_servername_arg(3)>
=head1 COPYRIGHT
Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

25
doc/ssl/SSL_CTX_set_cert_cb.pod
View File

@@ -15,10 +15,10 @@ SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function
=head1 DESCRIPTION
SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the B<cert_cb()> callback,
SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the cert_cb() callback,
B<arg> value is pointer which is passed to the application callback.
When B<cert_cb()> is NULL, no callback function is used.
When cert_cb() is NULL, no callback function is used.
cert_cb() is the application defined callback. It is called before a
certificate will be used by a client or server. The callback can then inspect
@@ -27,7 +27,7 @@ the callback is successful it B<MUST> return 1 even if no certificates have
been set. A zero is returned on error which will abort the handshake with a
fatal internal error alert. A negative return value will suspend the handshake
and the handshake function will return immediately.
L<SSL_get_error(3)|SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to
L<SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to
indicate, that the handshake was suspended. The next call to the handshake
function will again lead to the call of cert_cb(). It is the job of the
cert_cb() to store information about the state of the last call,
@@ -43,7 +43,7 @@ SSL_add1_chain_cert().
It might also call SSL_certs_clear() to delete any certificates associated
with the B<SSL> object.
The certificate callback functionality supercedes the (largely broken)
The certificate callback functionality supersedes the (largely broken)
functionality provided by the old client certificate callback interface.
It is B<always> called even is a certificate is already set so the callback
can modify or delete the existing certificate.
@@ -60,9 +60,18 @@ support it will B<not> be used.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_use_certificate(3)|SSL_use_certificate(3)>,
L<SSL_add1_chain_cert(3)|SSL_add1_chain_cert(3)>,
L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
L<ssl(3)>, L<SSL_use_certificate(3)>,
L<SSL_add1_chain_cert(3)>,
L<SSL_get_client_CA_list(3)>,
L<SSL_clear(3)>, L<SSL_free(3)>
=head1 COPYRIGHT
Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

23
doc/ssl/SSL_CTX_set_cert_store.pod
View File

@@ -28,17 +28,17 @@ via lookup methods, handled inside the X509_STORE. From the X509_STORE
the X509_STORE_CTX used when verifying certificates is created.
Typically the trusted certificate store is handled indirectly via using
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
L<SSL_CTX_load_verify_locations(3)>.
Using the SSL_CTX_set_cert_store() and SSL_CTX_get_cert_store() functions
it is possible to manipulate the X509_STORE object beyond the
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
L<SSL_CTX_load_verify_locations(3)>
call.
Currently no detailed documentation on how to use the X509_STORE
object is available. Not all members of the X509_STORE are used when
the verification takes place. So will e.g. the verify_callback() be
overridden with the verify_callback() set via the
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> family of functions.
L<SSL_CTX_set_verify(3)> family of functions.
This document must therefore be updated when documentation about the
X509_STORE object and its handling becomes available.
@@ -46,7 +46,7 @@ X509_STORE object and its handling becomes available.
The X509_STORE structure used by an SSL_CTX is used for verifying peer
certificates and building certificate chains, it is also shared by
every child SSL structure. Applications wanting finer control can use
every child SSL structure. Applications wanting finer control can use
functions such as SSL_CTX_set1_verify_cert_store() instead.
=head1 RETURN VALUES
@@ -57,8 +57,17 @@ SSL_CTX_get_cert_store() returns the current setting.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
L<ssl(3)>,
L<SSL_CTX_load_verify_locations(3)>,
L<SSL_CTX_set_verify(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

33
doc/ssl/SSL_CTX_set_cert_verify_callback.pod
View File

@@ -8,13 +8,13 @@ SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure
#include <openssl/ssl.h>
void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *,void *), void *arg);
void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *, void *), void *arg);
=head1 DESCRIPTION
SSL_CTX_set_cert_verify_callback() sets the verification callback function for
I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at
the time when L<SSL_new(3)|SSL_new(3)> is called.
the time when L<SSL_new(3)> is called.
=head1 NOTES
@@ -26,7 +26,7 @@ SSL_CTX_set_cert_verify_callback(), the supplied callback function is called
instead. By setting I<callback> to NULL, the default behaviour is restored.
When the verification must be performed, I<callback> will be called with
the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The
the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The
argument I<arg> is specified by the application when setting I<callback>.
I<callback> should return 1 to indicate verification success and 0 to
@@ -35,16 +35,16 @@ returns 0, the handshake will fail. As the verification procedure may
allow to continue the connection in case of failure (by always returning 1)
the verification result must be set in any case using the B<error>
member of I<x509_store_ctx> so that the calling application will be informed
about the detailed result of the verification procedure!
about the detailed result of the verification procedure!
Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback>
function set using L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>.
function set using L<SSL_CTX_set_verify(3)>.
=head1 WARNINGS
Do not mix the verification callback described in this function with the
B<verify_callback> function called during the verification process. The
latter is set using the L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
latter is set using the L<SSL_CTX_set_verify(3)>
family of functions.
Providing a complete verification procedure including certificate purpose
@@ -54,22 +54,21 @@ the B<verify_callback> function.
=head1 BUGS
=head1 RETURN VALUES
SSL_CTX_set_cert_verify_callback() does not provide diagnostic information.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(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(3)>, L<SSL_CTX_set_verify(3)>,
L<SSL_get_verify_result(3)>,
L<SSL_CTX_load_verify_locations(3)>
=head1 HISTORY
=head1 COPYRIGHT
Previous to OpenSSL 0.9.7, the I<arg> argument to B<SSL_CTX_set_cert_verify_callback>
was ignored, and I<callback> was called simply as
int (*callback)(X509_STORE_CTX *)
To compile software written for previous versions of OpenSSL, a dummy
argument will have to be added to I<callback>.
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

42
doc/ssl/SSL_CTX_set_cipher_list.pod
View File

@@ -15,7 +15,7 @@ SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPH
SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx>
using the control string B<str>. The format of the string is described
in L<ciphers(1)|ciphers(1)>. The list of ciphers is inherited by all
in L<ciphers(1)>. The list of ciphers is inherited by all
B<ssl> objects created from B<ctx>.
SSL_set_cipher_list() sets the list of ciphers only for B<ssl>.
@@ -31,33 +31,25 @@ at all.
It should be noted, that inclusion of a cipher to be used into the list is
a necessary condition. On the client side, the inclusion into the list is
also sufficient. On the server side, additional restrictions apply. All ciphers
have additional requirements. ADH ciphers don't need a certificate, but
DH-parameters must have been set. All other ciphers need a corresponding
certificate and key.
also sufficient unless the security level excludes it. On the server side,
additional restrictions apply. All ciphers have additional requirements.
ADH ciphers don't need a certificate, but DH-parameters must have been set.
All other ciphers need a corresponding certificate and key.
A RSA cipher can only be chosen, when a RSA certificate is available.
RSA export ciphers with a keylength of 512 bits for the RSA key require
a temporary 512 bit RSA key, as typically the supplied key has a length
of 1024 bit (see
L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>).
RSA ciphers using DHE need a certificate and key and additional DH-parameters
(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
(see L<SSL_CTX_set_tmp_dh_callback(3)>).
A DSA cipher can only be chosen, when a DSA certificate is available.
DSA ciphers always use DH key exchange and therefore need DH-parameters
(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
(see L<SSL_CTX_set_tmp_dh_callback(3)>).
When these conditions are not met for any cipher in the list (e.g. a
client only supports export RSA ciphers with a asymmetric key length
client only supports export RSA ciphers with an asymmetric key length
of 512 bits and the server is not configured to use temporary RSA
keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated
and the handshake will fail.
If the cipher list does not contain any SSLv2 cipher suites (this is the
default) then SSLv2 is effectively disabled and neither clients nor servers
will attempt to use SSLv2.
=head1 RETURN VALUES
SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
@@ -65,10 +57,18 @@ 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<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
L<ciphers(1)|ciphers(1)>
L<ssl(3)>, L<SSL_get_ciphers(3)>,
L<SSL_CTX_use_certificate(3)>,
L<SSL_CTX_set_tmp_dh_callback(3)>,
L<ciphers(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

25
doc/ssl/SSL_CTX_set_client_CA_list.pod
View File

@@ -9,7 +9,7 @@ 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);
@@ -42,11 +42,11 @@ This list must explicitly be set using 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)>
L<SSL_CTX_load_verify_locations(3)>
to additionally load them for verification.
If the list of acceptable CAs is compiled in a file, the
L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>
L<SSL_load_client_CA_file(3)>
function can be used to help importing the necessary data.
SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
@@ -82,13 +82,22 @@ The operation succeeded.
Scan all certificates in B<CAfile> and list them as acceptable CAs:
SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile));
SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
=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)>
L<ssl(3)>,
L<SSL_get_client_CA_list(3)>,
L<SSL_load_client_CA_file(3)>,
L<SSL_CTX_load_verify_locations(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

33
doc/ssl/SSL_CTX_set_client_cert_cb.pod
View File

@@ -14,11 +14,11 @@ SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certifica
=head1 DESCRIPTION
SSL_CTX_set_client_cert_cb() sets the B<client_cert_cb()> callback, that is
SSL_CTX_set_client_cert_cb() sets the client_cert_cb() callback, that is
called when a client certificate is requested by a server and no certificate
was yet set for the SSL object.
When B<client_cert_cb()> is NULL, no callback function is used.
When client_cert_cb() is NULL, no callback function is used.
SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback
function.
@@ -29,7 +29,7 @@ using the B<x509> and B<pkey> arguments and "1" must be returned. The
certificate will be installed into B<ssl>, see the NOTES and BUGS sections.
If no certificate should be set, "0" has to be returned and no certificate
will be sent. A negative return value will suspend the handshake and the
handshake function will return immediately. L<SSL_get_error(3)|SSL_get_error(3)>
handshake function will return immediately. L<SSL_get_error(3)>
will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was
suspended. The next call to the handshake function will again lead to the call
of client_cert_cb(). It is the job of the client_cert_cb() to store information
@@ -42,7 +42,7 @@ from the client. A client certificate must only be sent, when the server
did send the request.
When a certificate was set using the
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions,
L<SSL_CTX_use_certificate(3)> family of functions,
it will be sent to the server. The TLS standard requires that only a
certificate is sent, if it matches the list of acceptable CAs sent by the
server. This constraint is violated by the default behavior of the OpenSSL
@@ -56,7 +56,7 @@ If the callback function returns a certificate, the OpenSSL library
will try to load the private key and certificate data into the SSL
object using the SSL_use_certificate() and SSL_use_private_key() functions.
Thus it will permanently install the certificate and key for this SSL
object. It will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>.
object. It will not be reset by calling L<SSL_clear(3)>.
If the callback returns no certificate, the OpenSSL library will not send
a certificate.
@@ -72,7 +72,7 @@ either adding the intermediate CA certificates into the trusted
certificate store for the SSL_CTX object (resulting in having to add
CA certificates that otherwise maybe would not be trusted), or by adding
the chain certificates using the
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
L<SSL_CTX_add_extra_chain_cert(3)>
function, which is only available for the SSL_CTX object as a whole and that
therefore probably can only apply for one client certificate, making
the concept of the callback function (to allow the choice from several
@@ -80,15 +80,24 @@ certificates) questionable.
Once the SSL object has been used in conjunction with the callback function,
the certificate will be set for the SSL object and will not be cleared
even when L<SSL_clear(3)|SSL_clear(3)> is being called. It is therefore
mandatory to destroy the SSL object using L<SSL_free(3)|SSL_free(3)>
even when L<SSL_clear(3)> is being called. It is therefore
mandatory to destroy the SSL object using L<SSL_free(3)>
and create a new one to return to the previous state.
=head1 SEE ALSO
L<ssl(3)|ssl(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)>,
L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
L<ssl(3)>, L<SSL_CTX_use_certificate(3)>,
L<SSL_CTX_add_extra_chain_cert(3)>,
L<SSL_get_client_CA_list(3)>,
L<SSL_clear(3)>, L<SSL_free(3)>
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

145
doc/ssl/SSL_CTX_set_ct_validation_callback.pod Normal file
View File

@@ -0,0 +1,145 @@
=pod
=head1 NAME
ssl_ct_validation_cb,
SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct,
SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback,
SSL_ct_is_enabled, SSL_CTX_ct_is_enabled -
control Certificate Transparency policy
=head1 SYNOPSIS
#include <openssl/ssl.h>
typedef int (*ssl_ct_validation_cb)(const CT_POLICY_EVAL_CTX *ctx,
const STACK_OF(SCT) *scts, void *arg);
int SSL_enable_ct(SSL *s, int validation_mode);
int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode);
int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback,
void *arg);
int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx,
ssl_ct_validation_cb callback,
void *arg);
void SSL_disable_ct(SSL *s);
void SSL_CTX_disable_ct(SSL_CTX *ctx);
int SSL_ct_is_enabled(const SSL *s);
int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_enable_ct() and SSL_CTX_enable_ct() enable the processing of signed
certificate timestamps (SCTs) either for a given SSL connection or for all
connections that share the given SSL context, respectively.
This is accomplished by setting a built-in CT validation callback.
The behaviour of the callback is determined by the B<validation_mode> argument,
which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or
B<SSL_CT_VALIDATION_STRICT> as described below.
If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full
TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer
presents no valid SCTs the handshake will be aborted.
If the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue
despite lack of valid SCTs.
However, in that case if the verification status before the built-in callback
was B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the
callback.
Applications can call L<SSL_get_verify_result(3)> to check the status at
handshake completion, even after session resumption since the verification
status is part of the saved session state.
See L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>.
If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the
handshake continues, and the verification status is not modified, regardless of
the validation status of any SCTs.
The application can still inspect the validation status of the SCTs at
handshake completion.
Note that with session resumption there will not be any SCTs presented during
the handshake.
Therefore, in applications that delay SCT policy enforcement until after
handshake completion, such delayed SCT checks should only be performed when the
session is not resumed.
SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback()
register a custom callback that may implement a different policy than either of
the above.
This callback can examine the peer's SCTs and determine whether they are
sufficient to allow the connection to continue.
The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE>
and the callback returns a non-positive result.
An arbitrary callback context argument, B<arg>, can be passed in when setting
the callback.
This will be passed to the callback whenever it is invoked.
Ownership of this context remains with the caller.
If no callback is set, SCTs will not be requested and Certificate Transparency
validation will not occur.
No callback will be invoked when the peer presents no certificate, e.g. by
employing an anonymous (aNULL) ciphersuite.
In that case the handshake continues as it would had no callback been
requested.
Callbacks are also not invoked when the peer certificate chain is invalid or
validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509
PKI, or no X.509 PKI at all, respectively.
Clients that require SCTs are expected to not have enabled any aNULL ciphers
nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA
records.
SSL_disable_ct() and SSL_CTX_disable_ct() turn off CT processing, whether
enabled via the built-in or the custom callbacks, by setting a NULL callback.
These may be implemented as macros.
SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is
enabled via either SSL_enable_ct() or a non-null custom callback, and 0
otherwise.
=head1 NOTES
When SCT processing is enabled, OCSP stapling will be enabled. This is because
one possible source of SCTs is the OCSP response from a server.
The time returned by SSL_SESSION_get_time() will be used to evaluate whether any
presented SCTs have timestamps that are in the future (and therefore invalid).
=head1 RESTRICTIONS
Certificate Transparency validation cannot be enabled and so a callback cannot
be set if a custom client extension handler has been registered to handle SCT
extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>).
=head1 RETURN VALUES
SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and
SSL_set_ct_validation_callback() return 1 if the B<callback> is successfully
set.
They return 0 if an error occurs, e.g. a custom client extension handler has
been setup to handle SCTs.
SSL_disable_ct() and SSL_CTX_disable_ct() do not return a result.
SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT
validation callback is set, or 0 if no callback (or equivalently a NULL
callback) is set.
=head1 SEE ALSO
L<ssl(7)>,
<SSL_get_verify_result(3)>,
L<SSL_session_reused(3)>,
L<SSL_set_verify(3)>,
L<SSL_CTX_set_verify(3)>,
L<SSL_SESSION_get_time(3)>
=head1 COPYRIGHT
Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,53 @@
=pod
=head1 NAME
SSL_CTX_set_default_ctlog_list_file, SSL_CTX_set_ctlog_list_file -
load a Certificate Transparency log list from a file
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_set_default_ctlog_list_file(SSL_CTX *ctx);
int SSL_CTX_set_ctlog_list_file(SSL_CTX *ctx, const char *path);
=head1 DESCRIPTION
SSL_CTX_set_default_ctlog_list_file() loads a list of Certificate Transparency
(CT) logs from the default file location, "ct_log_list.cnf", found in the
directory where OpenSSL is installed.
SSL_CTX_set_ctlog_list_file() loads a list of CT logs from a specific path.
See L<CTLOG_STORE_new(3)> for the file format.
=head1 NOTES
These functions will not clear the existing CT log list - it will be appended
to. To replace the existing list, use L<SSL_CTX_set0_ctlog_store> first.
If an error occurs whilst parsing a particular log entry in the file, that log
entry will be skipped.
=head1 RETURN VALUES
SSL_CTX_set_default_ctlog_list_file() and SSL_CTX_set_ctlog_list_file()
return 1 if the log list is successfully loaded, and 0 if an error occurs. In
the case of an error, the log list may have been partially loaded.
=head1 SEE ALSO
L<ssl(3)>,
L<SSL_CTX_set_ct_validation_callback(3)>,
L<CTLOG_STORE_new(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

77
doc/ssl/SSL_CTX_set_default_passwd_cb.pod
View File

@@ -2,7 +2,11 @@
=head1 NAME
SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set passwd callback for encrypted PEM file handling
SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata,
SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata,
SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata,
SSL_get_default_passwd_cb, SSL_get_default_passwd_cb_userdata - set or
get passwd callback for encrypted PEM file handling
=head1 SYNOPSIS
@@ -10,37 +14,56 @@ SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set pass
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);
pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx);
void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx);
int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata);
void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb);
void SSL_set_default_passwd_cb_userdata(SSL *s, void *u);
pem_password_cb *SSL_get_default_passwd_cb(SSL *s);
void *SSL_get_default_passwd_cb_userdata(SSL *s);
=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.
SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to userdata, B<u>,
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
SSL_CTX_get_default_passwd_cb() returns a function pointer to the password
callback currently set in B<ctx>. If no callback was explicitly set, the
NULL pointer is returned.
SSL_CTX_get_default_passwd_cb_userdata() returns a pointer to the userdata
currently set in B<ctx>. If no userdata was explicitly set, the NULL pointer
is returned.
SSL_set_default_passwd_cb(), SSL_set_default_passwd_cb_userdata(),
SSL_get_default_passwd_cb() and SSL_get_default_passwd_cb_userdata() perform
the same function as their SSL_CTX counterparts, but using an SSL object.
The password callback, which must be provided by the application, hands back the
password to be used during decryption.
On invocation a pointer to userdata
is provided. The function must store 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).
For more details, see L<pem_password_cb(3)>.
=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
to have the callback 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.
password could be stored into the userdata storage and the
callback only returns the password already stored.
When asking for the password interactively, pem_passwd_cb() can use
When asking for the password interactively, the callback can use
B<rwflag> to check, whether an item shall be encrypted (rwflag=1).
In this case the password dialog may ask for the same password twice
for comparison in order to catch typos, that would make decryption
@@ -51,26 +74,40 @@ 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.
These functions do not provide diagnostic information.
=head1 EXAMPLES
The following example returns the password provided as B<userdata> to the
The following example returns the password provided as 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)
int my_cb(char *buf, int size, int rwflag, void *u)
{
strncpy(buf, (char *)(password), size);
buf[size - 1] = '\0';
return(strlen(buf));
strncpy(buf, (char *)u, size);
buf[size - 1] = '\0';
return strlen(buf);
}
=head1 HISTORY
SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(),
SSL_set_default_passwd_cb() and SSL_set_default_passwd_cb_userdata() were
first added to OpenSSL 1.1.0
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>
L<ssl(3)>,
L<SSL_CTX_use_certificate(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,52 @@
=pod
=head1 NAME
SSL_CTX_get_ex_data, SSL_CTX_set_ex_data,
SSL_get_ex_data, SSL_set_ex_data
- Store and retrieve extra data from the SSL_CTX, SSL or SSL_SESSION
=head1 SYNOPSIS
#include <openssl/ssl.h>
void *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx);
int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, void *arg);
void *SSL_get_ex_data(const SSL *s, int idx);
int SSL_set_ex_data(SSL *s, int idx, void *arg);
=head1 DESCRIPTION
SSL*_set_ex_data() functions can be used to store arbitrary user data into the
B<SSL_CTX>, or B<SSL> object. The user must supply a unique index
which they can subsequently use to retrieve the data using SSL*_get_ex_data().
For more detailed information see L<CRYPTO_get_ex_data(3)> and
L<CRYPTO_set_ex_data(3)> which implement these functions and
L<CRYPTO_get_ex_new_index(3)> for generating a unique index.
=head1 RETURN VALUES
The SSL*_set_ex_data() functions return 1 if the item is successfully stored
and 0 if it is not.
The SSL*_get_ex_data() functions return the ex_data pointer if successful,
otherwise NULL.
=head1 SEE ALSO
L<CRYPTO_get_ex_data(3)>, L<CRYPTO_set_ex_data(3)>,
L<CRYPTO_get_ex_new_index(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

77
doc/ssl/SSL_CTX_set_generate_session_id.pod
View File

@@ -2,7 +2,9 @@
=head1 NAME
SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, SSL_has_matching_session_id - manipulate generation of SSL session IDs (server only)
SSL_CTX_set_generate_session_id, SSL_set_generate_session_id,
SSL_has_matching_session_id, GEN_SESSION_CB
- manipulate generation of SSL session IDs (server only)
=head1 SYNOPSIS
@@ -14,7 +16,7 @@ SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, SSL_has_matching_s
int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb);
int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb);
int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id,
unsigned int id_len);
unsigned int id_len);
=head1 DESCRIPTION
@@ -32,9 +34,8 @@ of the parent context of B<ssl>.
When a new session is established between client and server, the server
generates a session id. The session id is an arbitrary sequence of bytes.
The length of the session id is 16 bytes for SSLv2 sessions and between
1 and 32 bytes for SSLv3/TLSv1. The session id is not security critical
but must be unique for the server. Additionally, the session id is
The length of the session id is between 1 and 32 bytes. The session id is not
security critical but must be unique for the server. Additionally, the session id is
transmitted in the clear when reusing the session so it must not contain
sensitive information.
@@ -51,21 +52,14 @@ The callback is only allowed to generate a shorter id and reduce B<id_len>;
the callback B<must never> increase B<id_len> or write to the location
B<id> exceeding the given limit.
If a SSLv2 session id is generated and B<id_len> is reduced, it will be
restored after the callback has finished and the session id will be padded
with 0x00. It is not recommended to change the B<id_len> for SSLv2 sessions.
The callback can use the L<SSL_get_version(3)|SSL_get_version(3)> function
to check, whether the session is of type SSLv2.
The location B<id> is filled with 0x00 before the callback is called, so the
callback may only fill part of the possible length and leave B<id_len>
untouched while maintaining reproducibility.
Since the sessions must be distinguished, session ids must be unique.
Without the callback a random number is used, so that the probability
of generating the same session id is extremely small (2^128 possible ids
for an SSLv2 session, 2^256 for SSLv3/TLSv1). In order to assure the
uniqueness of the generated session id, the callback must call
of generating the same session id is extremely small (2^256 for SSLv3/TLSv1).
In order to assure the uniqueness of the generated session id, the callback must call
SSL_has_matching_session_id() and generate another id if a conflict occurs.
If an id conflict is not resolved, the handshake will fail.
If the application codes e.g. a unique host id, a unique process number, and
@@ -85,10 +79,6 @@ Collisions can also occur when using an external session cache, since
the external cache is not tested with SSL_has_matching_session_id()
and the same race condition applies.
When calling SSL_has_matching_session_id() for an SSLv2 session with
reduced B<id_len>, the match operation will be performed using the
fixed length required and with a 0x00 padded id.
The callback must return 0 if it cannot generate a session id for whatever
reason and return 1 on success.
@@ -102,31 +92,27 @@ server id given, and will fill the rest with pseudo random bytes:
#define MAX_SESSION_ID_ATTEMPTS 10
static int generate_session_id(const SSL *ssl, unsigned char *id,
unsigned int *id_len)
{
{
unsigned int count = 0;
const char *version;
version = SSL_get_version(ssl);
if (!strcmp(version, "SSLv2"))
/* we must not change id_len */;
do {
RAND_pseudo_bytes(id, *id_len);
/* Prefix the session_id with the required prefix. NB: If our
* prefix is too long, clip it - but there will be worse effects
* anyway, eg. the server could only possibly create 1 session
* ID (ie. the prefix!) so all future session negotiations will
* fail due to conflicts. */
memcpy(id, session_id_prefix,
(strlen(session_id_prefix) < *id_len) ?
strlen(session_id_prefix) : *id_len);
}
while(SSL_has_matching_session_id(ssl, id, *id_len) &&
do {
RAND_pseudo_bytes(id, *id_len);
/*
* Prefix the session_id with the required prefix. NB: If our
* prefix is too long, clip it - but there will be worse effects
* anyway, eg. the server could only possibly create 1 session
* ID (ie. the prefix!) so all future session negotiations will
* fail due to conflicts.
*/
memcpy(id, session_id_prefix,
(strlen(session_id_prefix) < *id_len) ?
strlen(session_id_prefix) : *id_len);
}
while (SSL_has_matching_session_id(ssl, id, *id_len) &&
(++count < MAX_SESSION_ID_ATTEMPTS));
if(count >= MAX_SESSION_ID_ATTEMPTS)
if (count >= MAX_SESSION_ID_ATTEMPTS)
return 0;
return 1;
}
}
=head1 RETURN VALUES
@@ -139,12 +125,15 @@ same id is already in the cache.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_get_version(3)|SSL_get_version(3)>
L<ssl(7)>, L<SSL_get_version(3)>
=head1 HISTORY
=head1 COPYRIGHT
SSL_CTX_set_generate_session_id(), SSL_set_generate_session_id()
and SSL_has_matching_session_id() have been introduced in
OpenSSL 0.9.7.
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

81
doc/ssl/SSL_CTX_set_info_callback.pod
View File

@@ -20,7 +20,7 @@ SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to
obtain state information for SSL objects created from B<ctx> during connection
setup and use. The setting for B<ctx> is overridden from the setting for
a specific SSL object, if specified.
When B<callback> is NULL, not callback function is used.
When B<callback> is NULL, no callback function is used.
SSL_set_info_callback() sets the B<callback> function, that can be used to
obtain state information for B<ssl> during connection setup and use.
@@ -93,10 +93,10 @@ Callback has been called because a handshake is finished.
=back
The current state information can be obtained using the
L<SSL_state_string(3)|SSL_state_string(3)> family of functions.
L<SSL_state_string(3)> family of functions.
The B<ret> information can be evaluated using the
L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> family of functions.
L<SSL_alert_type_string(3)> family of functions.
=head1 RETURN VALUES
@@ -110,44 +110,53 @@ The following example callback function prints state strings, information
about alerts being handled and error messages to the B<bio_err> BIO.
void apps_ssl_info_callback(SSL *s, int where, int ret)
{
const char *str;
int w;
{
const char *str;
int w;
w=where& ~SSL_ST_MASK;
w = where & ~SSL_ST_MASK;
if (w & SSL_ST_CONNECT) str="SSL_connect";
else if (w & SSL_ST_ACCEPT) str="SSL_accept";
else str="undefined";
if (w & SSL_ST_CONNECT) str = "SSL_connect";
else if (w & SSL_ST_ACCEPT) str = "SSL_accept";
else str = "undefined";
if (where & SSL_CB_LOOP)
{
BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s));
}
else if (where & SSL_CB_ALERT)
{
str=(where & SSL_CB_READ)?"read":"write";
BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n",
str,
SSL_alert_type_string_long(ret),
SSL_alert_desc_string_long(ret));
}
else if (where & SSL_CB_EXIT)
{
if (ret == 0)
BIO_printf(bio_err,"%s:failed in %s\n",
str,SSL_state_string_long(s));
else if (ret < 0)
{
BIO_printf(bio_err,"%s:error in %s\n",
str,SSL_state_string_long(s));
}
}
}
if (where & SSL_CB_LOOP)
{
BIO_printf(bio_err, "%s:%s\n", str, SSL_state_string_long(s));
}
else if (where & SSL_CB_ALERT)
{
str = (where & SSL_CB_READ) ? "read" : "write";
BIO_printf(bio_err, "SSL3 alert %s:%s:%s\n",
str,
SSL_alert_type_string_long(ret),
SSL_alert_desc_string_long(ret));
}
else if (where & SSL_CB_EXIT)
{
if (ret == 0)
BIO_printf(bio_err, "%s:failed in %s\n",
str, SSL_state_string_long(s));
else if (ret < 0)
{
BIO_printf(bio_err, "%s:error in %s\n",
str, SSL_state_string_long(s));
}
}
}
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>,
L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>
L<ssl(3)>, L<SSL_state_string(3)>,
L<SSL_alert_type_string(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

19
doc/ssl/SSL_CTX_set_max_cert_list.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL_get_max_cert_list, - manipulate allowed for the peer's certificate chain
SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL_get_max_cert_list - manipulate allowed size for the peer's certificate chain
=head1 SYNOPSIS
@@ -19,7 +19,7 @@ SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL
SSL_CTX_set_max_cert_list() sets the maximum size allowed for the peer's
certificate chain for all SSL objects created from B<ctx> to be <size> bytes.
The SSL objects inherit the setting valid for B<ctx> at the time
L<SSL_new(3)|SSL_new(3)> is being called.
L<SSL_new(3)> is being called.
SSL_CTX_get_max_cert_list() returns the currently set maximum size for B<ctx>.
@@ -41,7 +41,7 @@ chain is set.
The default value for the maximum certificate chain size is 100kB (30kB
on the 16bit DOS platform). This should be sufficient for usual certificate
chains (OpenSSL's default maximum chain length is 10, see
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, and certificates
L<SSL_CTX_set_verify(3)>, and certificates
without special extensions have a typical size of 1-2kB).
For special applications it can be necessary to extend the maximum certificate
@@ -67,11 +67,16 @@ set value.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>,
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
L<ssl(3)>, L<SSL_new(3)>,
L<SSL_CTX_set_verify(3)>
=head1 HISTORY
=head1 COPYRIGHT
SSL*_set/get_max_cert_list() have been introduced in OpenSSL 0.9.7.
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

60
doc/ssl/SSL_CTX_set_min_proto_version.pod Normal file
View File

@@ -0,0 +1,60 @@
=pod
=head1 NAME
SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version,
SSL_set_min_proto_version, SSL_set_max_proto_version - Set minimum
and maximum supported protocol version
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version);
int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version);
int SSL_set_min_proto_version(SSL *ssl, int version);
int SSL_set_max_proto_version(SSL *ssl, int version);
=head1 DESCRIPTION
The functions set the minimum and maximum supported protocol versions
for the B<ctx> or B<ssl>.
This works in combination with the options set via
L<SSL_CTX_set_options(3)> that also make it possible to disable
specific protocol versions.
Use these functions instead of disabling specific protocol versions.
Setting the minimum or maximum version to 0, will enable protocol
versions down to the lowest version, or up to the highest version
supported by the library, respectively.
Currently supported versions are B<SSL3_VERSION>, B<TLS1_VERSION>,
B<TLS1_1_VERSION>, B<TLS1_2_VERSION> for TLS and B<DTLS1_VERSION>,
B<DTLS1_2_VERSION> for DTLS.
=head1 RETURN VALUES
These functions return 1 on success and 0 on failure.
=head1 NOTES
All these functions are implemented using macros.
=head1 HISTORY
The functions were added in OpenSSL 1.1.0
=head1 SEE ALSO
L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

27
doc/ssl/SSL_CTX_set_mode.pod
View File

@@ -52,7 +52,7 @@ non-blocking write().
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
L<SSL_read(3)> or L<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.
@@ -64,10 +64,8 @@ return after the handshake and successful completion.
=item SSL_MODE_RELEASE_BUFFERS
When we no longer need a read buffer or a write buffer for a given SSL,
then release the memory we were using to hold it. Released memory is
either appended to a list of unused RAM chunks on the SSL_CTX, or simply
freed if the list of unused chunks would become longer than
SSL_CTX->freelist_max_len, which defaults to 32. Using this flag can
then release the memory we were using to hold it.
Using this flag can
save around 34k per idle SSL connection.
This flag has no effect on SSL v2 connections, or on DTLS connections.
@@ -81,6 +79,12 @@ DO NOT ENABLE THIS if your application attempts a normal handshake.
Only use this in explicit fallback retries, following the guidance
in draft-ietf-tls-downgrade-scsv-00.
=item SSL_MODE_ASYNC
Enable asynchronous processing. TLS I/O operations may indicate a retry with
SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is
used to perform cryptographic operations. See L<SSL_get_error(3)>.
=back
=head1 RETURN VALUES
@@ -92,10 +96,19 @@ 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)>
L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)>, L<SSL_get_error(3)>
=head1 HISTORY
SSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6.
SSL_MODE_ASYNC was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

16
doc/ssl/SSL_CTX_set_msg_callback.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_get_msg_callback_arg - install callback for observing protocol messages
SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_set_msg_callback_arg - install callback for observing protocol messages
=head1 SYNOPSIS
@@ -25,7 +25,7 @@ available for arbitrary application use.
SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify
default settings that will be copied to new B<SSL> objects by
L<SSL_new(3)|SSL_new(3)>. SSL_set_msg_callback() and
L<SSL_new(3)>. SSL_set_msg_callback() and
SSL_set_msg_callback_arg() modify the actual settings of an B<SSL>
object. Using a B<0> pointer for I<cb> disables the message callback.
@@ -89,11 +89,15 @@ I<version> will be B<SSL3_VERSION>.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>
L<ssl(3)>, L<SSL_new(3)>
=head1 HISTORY
=head1 COPYRIGHT
SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(),
SSL_set_msg_callback() and SSL_get_msg_callback_arg() were added in OpenSSL 0.9.7.
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

125
doc/ssl/SSL_CTX_set_options.pod
View File

@@ -2,7 +2,9 @@
=head1 NAME
SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options, SSL_CTX_get_options, SSL_get_options, SSL_get_secure_renegotiation_support - manipulate SSL options
SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options,
SSL_clear_options, SSL_CTX_get_options, SSL_get_options,
SSL_get_secure_renegotiation_support - manipulate SSL options
=head1 SYNOPSIS
@@ -21,8 +23,6 @@ SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options,
=head1 DESCRIPTION
Note: all these functions are implemented using macros.
SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
Options already set before are not cleared!
@@ -40,17 +40,18 @@ SSL_get_options() returns the options set for B<ssl>.
SSL_get_secure_renegotiation_support() indicates whether the peer supports
secure renegotiation.
Note, this is implemented via a macro.
=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>
The options are coded as bitmasks and can be combined by a bitwise B<or>
operation (|).
SSL_CTX_set_options() and SSL_set_options() affect the (external)
protocol behaviour of the SSL library. The (internal) behaviour of
the API can be changed by using the similar
L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions.
L<SSL_CTX_set_mode(3)> and SSL_set_mode() functions.
During a handshake, the option settings of the SSL object are used. When
a new SSL object is created from a context using SSL_new(), the current
@@ -61,25 +62,6 @@ 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
As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect.
=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
...
@@ -101,10 +83,6 @@ OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.
...
=item SSL_OP_TLS_BLOCK_PADDING_BUG
...
=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
@@ -147,10 +125,10 @@ to the server's answer and violate the version rollback protection.)
=item SSL_OP_SINGLE_DH_USE
Always create a new key when using temporary/ephemeral DH parameters
(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
(see L<SSL_CTX_set_tmp_dh_callback(3)>).
This option must be used to prevent small subgroup attacks, when
the DH parameters were not generated using "strong" primes
(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>).
(e.g. when using DSA-parameters, see L<dhparam(1)>).
If "strong" primes were used, it is not strictly necessary to generate
a new DH key during each handshake but it is also recommended.
B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever
@@ -164,9 +142,8 @@ This option is no longer implemented and is treated as no op.
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 its list of preferences to the client and the client chooses.
preferences. When set, the SSL/TLS server will choose following its
own preferences.
=item SSL_OP_PKCS1_CHECK_1
@@ -176,37 +153,16 @@ will send its list of preferences to the client and the client chooses.
...
=item SSL_OP_NETSCAPE_CA_DN_BUG
If we accept a netscape connection, demand a client cert, have a
non-self-signed CA which does not have its CA in netscape, and the
browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta
=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1,
SSL_OP_NO_TLSv1_2, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2
=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
...
=item SSL_OP_NO_SSLv2
Do not use the SSLv2 protocol.
As of OpenSSL 1.0.2g the B<SSL_OP_NO_SSLv2> option is set by default.
=item SSL_OP_NO_SSLv3
Do not use the SSLv3 protocol.
It is recommended that applications should set this option.
=item SSL_OP_NO_TLSv1
Do not use the TLSv1 protocol.
=item SSL_OP_NO_TLSv1_1
Do not use the TLSv1.1 protocol.
=item SSL_OP_NO_TLSv1_2
Do not use the TLSv1.2 protocol.
These options turn off the SSLv3, TLSv1, TLSv1.1 or TLSv1.2 protocol
versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
respectively.
As of OpenSSL 1.1.0, these options are deprecated, use
L<SSL_CTX_set_min_proto_version(3)> and
L<SSL_CTX_set_max_proto_version(3)> instead.
=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
@@ -237,13 +193,10 @@ B<SECURE RENEGOTIATION> section for more details.
=head1 SECURE RENEGOTIATION
OpenSSL 0.9.8m and later always attempts to use secure renegotiation as
OpenSSL always attempts to use secure renegotiation as
described in RFC5746. This counters the prefix attack described in
CVE-2009-3555 and elsewhere.
The deprecated and highly broken SSLv2 protocol does not support
renegotiation at all: its use is B<strongly> discouraged.
This attack has far reaching consequences which application writers should be
aware of. In the description below an implementation supporting secure
renegotiation is referred to as I<patched>. A server not supporting secure
@@ -269,14 +222,6 @@ unaware of the unpatched nature of the client.
If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
renegotiation B<always> succeeds.
B<NB:> a bug in OpenSSL clients earlier than 0.9.8m (all of which are
unpatched) will result in the connection hanging if it receives a
B<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard
a B<no_renegotiation> alert as fatal and respond with a fatal
B<handshake_failure> alert. This is because the OpenSSL API currently has
no provision to indicate to an application that a renegotiation attempt
was refused.
=head2 Patched OpenSSL client and unpatched server.
If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
@@ -325,31 +270,23 @@ secure renegotiation and 0 if it does not.
=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_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
L<dhparam(1)|dhparam(1)>
L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>,
L<SSL_CTX_set_tmp_dh_callback(3)>,
L<SSL_CTX_set_min_proto_version(3)>,
L<dhparam(1)>
=head1 HISTORY
B<SSL_OP_CIPHER_SERVER_PREFERENCE> and
B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in
OpenSSL 0.9.7.
The attempt to always try to use secure renegotiation was added in
Openssl 0.9.8m.
B<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically
enabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL>
and must be explicitly set.
=head1 COPYRIGHT
B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e.
Versions up to OpenSSL 0.9.6c do not include the countermeasure that
can be disabled with this option (in OpenSSL 0.9.6d, it was always
enabled).
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL
0.9.8m.
B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT>
and the function SSL_get_secure_renegotiation_support() were first added in
OpenSSL 0.9.8m.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

54
doc/ssl/SSL_CTX_set_psk_client_callback.pod
View File

@@ -1,34 +1,5 @@
=pod
=begin comment
Copyright 2005 Nokia. All rights reserved.
The portions of the attached software ("Contribution") is developed by
Nokia Corporation and is licensed pursuant to the OpenSSL open source
license.
The Contribution, originally written by Mika Kousa and Pasi Eronen of
Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites
support (see RFC 4279) to OpenSSL.
No patent licenses or other rights except those expressly stated in
the OpenSSL open source license shall be deemed granted or received
expressly, by implication, estoppel, or otherwise.
No assurances are provided by Nokia that the Contribution does not
infringe the patent or other intellectual property rights of any third
party or that the license provides you with all the necessary rights
to make use of the Contribution.
THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN
ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA
SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY
OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR
OTHERWISE.
=end comment
=head1 NAME
SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client callback
@@ -38,13 +9,13 @@ SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client ca
#include <openssl/ssl.h>
void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx,
unsigned int (*callback)(SSL *ssl, const char *hint,
char *identity, unsigned int max_identity_len,
unsigned char *psk, unsigned int max_psk_len));
unsigned int (*callback)(SSL *ssl, const char *hint,
char *identity, unsigned int max_identity_len,
unsigned char *psk, unsigned int max_psk_len));
void SSL_set_psk_client_callback(SSL *ssl,
unsigned int (*callback)(SSL *ssl, const char *hint,
char *identity, unsigned int max_identity_len,
unsigned char *psk, unsigned int max_psk_len));
unsigned int (*callback)(SSL *ssl, const char *hint,
char *identity, unsigned int max_identity_len,
unsigned char *psk, unsigned int max_psk_len));
=head1 DESCRIPTION
@@ -59,7 +30,7 @@ The callback is set using functions SSL_CTX_set_psk_client_callback()
or SSL_set_psk_client_callback(). The callback function is given the
connection in parameter B<ssl>, a B<NULL>-terminated PSK identity hint
sent by the server in parameter B<hint>, a buffer B<identity> of
length B<max_identity_len> bytes where the the resulting
length B<max_identity_len> bytes where the resulting
B<NULL>-terminated identity is to be stored, and a buffer B<psk> of
length B<max_psk_len> bytes where the resulting pre-shared key is to
be stored.
@@ -78,4 +49,15 @@ the length (> 0) of B<psk> in bytes is returned.
Otherwise or on errors callback should return 0. In this case
the connection setup fails.
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
Copyright 2005 Nokia.
=cut

29
doc/ssl/SSL_CTX_set_quiet_shutdown.pod
View File

@@ -18,14 +18,14 @@ SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown,
SSL_CTX_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ctx> to be
B<mode>. SSL objects created from B<ctx> inherit the B<mode> valid at the time
L<SSL_new(3)|SSL_new(3)> is called. B<mode> may be 0 or 1.
L<SSL_new(3)> is called. B<mode> may be 0 or 1.
SSL_CTX_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ctx>.
SSL_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ssl> to be
B<mode>. The setting stays valid until B<ssl> is removed with
L<SSL_free(3)|SSL_free(3)> or SSL_set_quiet_shutdown() is called again.
It is not changed when L<SSL_clear(3)|SSL_clear(3)> is called.
L<SSL_free(3)> or SSL_set_quiet_shutdown() is called again.
It is not changed when L<SSL_clear(3)> is called.
B<mode> may be 0 or 1.
SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ssl>.
@@ -33,13 +33,13 @@ SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ssl>.
=head1 NOTES
Normally when a SSL connection is finished, the parties must send out
"close notify" alert messages using L<SSL_shutdown(3)|SSL_shutdown(3)>
"close notify" alert messages using L<SSL_shutdown(3)>
for a clean shutdown.
When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)|SSL_shutdown(3)>
When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)>
will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.
(L<SSL_shutdown(3)|SSL_shutdown(3)> then behaves like
L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> called with
(L<SSL_shutdown(3)> then behaves like
L<SSL_set_shutdown(3)> called with
SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.)
The session is thus considered to be shutdown, but no "close notify" alert
is sent to the peer. This behaviour violates the TLS standard.
@@ -56,8 +56,17 @@ setting.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>,
L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, L<SSL_new(3)|SSL_new(3)>,
L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
L<ssl(3)>, L<SSL_shutdown(3)>,
L<SSL_set_shutdown(3)>, L<SSL_new(3)>,
L<SSL_clear(3)>, L<SSL_free(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

35
doc/ssl/SSL_CTX_set_read_ahead.pod
View File

@@ -2,21 +2,21 @@
=head1 NAME
SSL_CTX_set_read_ahead, SSL_CTX_set_default_read_ahead, SSL_CTX_get_read_ahead,
SSL_CTX_get_default_read_ahead, SSL_set_read_ahead, SSL_get_read_ahead
SSL_CTX_set_read_ahead, SSL_CTX_get_read_ahead,
SSL_set_read_ahead, SSL_get_read_ahead,
SSL_CTX_get_default_read_ahead
- manage whether to read as many input bytes as possible
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_get_read_ahead(const SSL *s);
void SSL_set_read_ahead(SSL *s, int yes);
int SSL_get_read_ahead(const SSL *s);
#define SSL_CTX_get_default_read_ahead(ctx)
#define SSL_CTX_set_default_read_ahead(ctx,m)
#define SSL_CTX_get_read_ahead(ctx)
#define SSL_CTX_set_read_ahead(ctx,m)
SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes);
long SSL_CTX_get_read_ahead(SSL_CTX *ctx);
long SSL_CTX_get_default_read_ahead(SSL_CTX *ctx);
=head1 DESCRIPTION
@@ -27,9 +27,7 @@ the underlying BIO (where B<y> > B<x>), then OpenSSL will read all B<y> bytes
into its buffer (providing that the buffer is large enough) if reading ahead is
on, or B<x> bytes otherwise. The parameter B<yes> or B<m> should be 0 to ensure
reading ahead is off, or non zero otherwise.
SSL_CTX_set_default_read_ahead is a synonym for SSL_CTX_set_read_ahead, and
SSL_CTX_get_default_read_ahead is a synonym for SSL_CTX_get_read_ahead.
SSL_CTX_set_default_read_ahead() is identical to SSL_CTX_set_read_ahead().
SSL_CTX_get_read_ahead() and SSL_get_read_ahead() indicate whether reading
ahead has been set or not.
@@ -37,15 +35,26 @@ ahead has been set or not.
=head1 NOTES
These functions have no impact when used with DTLS. The return values for
SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS.
SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS. Setting
B<read_ahead> can impact the behaviour of the SSL_pending() function
(see L<SSL_pending(3)>).
=head1 RETURN VALUES
SSL_get_read_ahead and SSL_CTX_get_read_ahead return 0 if reading ahead is off,
SSL_get_read_ahead() and SSL_CTX_get_read_ahead() return 0 if reading ahead is off,
and non zero otherwise.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>
L<ssl(3)>, L<SSL_pending(3)>
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

169
doc/ssl/SSL_CTX_set_security_level.pod Normal file
View File

@@ -0,0 +1,169 @@
=pod
=head1 NAME
SSL_CTX_set_security_level, SSL_set_security_level, SSL_CTX_get_security_level, SSL_get_security_level, SSL_CTX_set_security_callback, SSL_set_security_callback, SSL_CTX_get_security_callback, SSL_get_security_callback, SSL_CTX_set0_security_ex_data, SSL_set0_security_ex_data, SSL_CTX_get0_security_ex_data, SSL_get0_security_ex_data - SSL/TLS security framework
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_set_security_level(SSL_CTX *ctx, int level);
void SSL_set_security_level(SSL *s, int level);
int SSL_CTX_get_security_level(const SSL_CTX *ctx);
int SSL_get_security_level(const SSL *s);
void SSL_CTX_set_security_callback(SSL_CTX *ctx,
int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid,
void *other, void *ex));
void SSL_set_security_callback(SSL *s,
int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid,
void *other, void *ex));
int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex);
int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex);
void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex);
void SSL_set0_security_ex_data(SSL *s, void *ex);
void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx);
void *SSL_get0_security_ex_data(const SSL *s);
=head1 DESCRIPTION
The functions SSL_CTX_set_security_level() and SSL_set_security_level() set
the security level to B<level>. If not set the library default security level
is used.
The functions SSL_CTX_get_security_level() and SSL_get_security_level()
retrieve the current security level.
SSL_CTX_set_security_callback(), SSL_set_security_callback(),
SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set
the security callback associated with B<ctx> or B<s>. If not set a default
security callback is used. The meaning of the parameters and the behaviour
of the default callbacks is described below.
SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(),
SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the
extra data pointer passed to the B<ex> parameter of the callback. This
value is passed to the callback verbatim and can be set to any convenient
application specific value.
=head1 DEFAULT CALLBACK BEHAVIOUR
If an application doesn't set its own security callback the default
callback is used. It is intended to provide sane defaults. The meaning
of each level is described below.
=over 4
=item B<Level 0>
Everything is permitted. This retains compatibility with previous versions of
OpenSSL.
=item B<Level 1>
The security level corresponds to a minimum of 80 bits of security. Any
parameters offering below 80 bits of security are excluded. As a result RSA,
DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits
are prohibited. All export ciphersuites are prohibited since they all offer
less than 80 bits of security. SSL version 2 is prohibited. Any ciphersuite
using MD5 for the MAC is also prohibited.
=item B<Level 2>
Security level set to 112 bits of security. As a result RSA, DSA and DH keys
shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited.
In addition to the level 1 exclusions any ciphersuite using RC4 is also
prohibited. SSL version 3 is also not allowed. Compression is disabled.
=item B<Level 3>
Security level set to 128 bits of security. As a result RSA, DSA and DH keys
shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited.
In addition to the level 2 exclusions ciphersuites not offering forward
secrecy are prohibited. TLS versions below 1.1 are not permitted. Session
tickets are disabled.
=item B<Level 4>
Security level set to 192 bits of security. As a result RSA, DSA and DH keys
shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited.
Ciphersuites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are
not permitted.
=item B<Level 5>
Security level set to 256 bits of security. As a result RSA, DSA and DH keys
shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited.
=back
=head1 APPLICATION DEFINED SECURITY CALLBACKS
I<Documentation to be provided.>
=head1 NOTES
B<WARNING> at this time setting the security level higher than 1 for
general internet use is likely to cause B<considerable> interoperability
issues and is not recommended. This is because the B<SHA1> algorithm
is very widely used in certificates and will be rejected at levels
higher than 1 because it only offers 80 bits of security.
The default security level can be configured when OpenSSL is compiled by
setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 1 is used.
The security framework disables or reject parameters inconsistent with the
set security level. In the past this was difficult as applications had to set
a number of distinct parameters (supported ciphers, supported curves supported
signature algorithms) to achieve this end and some cases (DH parameter size
for example) could not be checked at all.
By setting an appropriate security level much of this complexity can be
avoided.
The bits of security limits affect all relevant parameters including
ciphersuite encryption algorithms, supported ECC curves, supported
signature algorithms, DH parameter sizes, certificate key sizes and
signature algorithms. This limit applies no matter what other custom
settings an application has set: so if the ciphersuite is set to B<ALL>
then only ciphersuites consistent with the security level are permissible.
See SP800-57 for how the security limits are related to individual
algorithms.
Some security levels require large key sizes for non-ECC public key
algorithms which can severely degrade performance. For example 256 bits
of security requires the use of RSA keys of at least 15360 bits in size.
Some restrictions can be gracefully handled: for example ciphersuites
offering insufficient security are not sent by the client and will not
be selected by the server. Other restrictions such as the peer certificate
key size or the DH parameter size will abort the handshake with a fatal
alert.
Attempts to set certificates or parameters with insufficient security are
also blocked. For example trying to set a certificate using a 512 bit RSA
key using SSL_CTX_use_certificate() at level 1. Applications which do not
check the return values for errors will misbehave: for example it might
appear that a certificate is not set at all because it had been rejected.
=head1 HISTORY
These functions were first added to OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

40
doc/ssl/SSL_CTX_set_session_cache_mode.pod
View File

@@ -26,7 +26,7 @@ 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 either
server. It can only send exactly one id. The server then either
agrees to reuse the session or it starts a full handshake (to create a new
session).
@@ -37,7 +37,7 @@ 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)>).
L<SSL_CTX_set_session_id_context(3)>).
The following session cache modes and modifiers are available:
@@ -53,7 +53,7 @@ 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)>
to be reused by using the L<SSL_set_session(3)>
function. This option is not activated by default.
=item SSL_SESS_CACHE_SERVER
@@ -72,10 +72,10 @@ Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time.
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
L<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
L<SSL_CTX_flush_sessions(3)> can be called
explicitly by the application.
=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
@@ -94,7 +94,7 @@ sessions negotiated in an SSL/TLS handshake may be cached for possible reuse.
Normally a new session is added to the internal cache as well as any external
session caching (callback) that is configured for the SSL_CTX. This flag will
prevent sessions being stored in the internal cache (though the application can
add them manually using L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>). Note:
add them manually using L<SSL_CTX_add_session(3)>). Note:
in any SSL/TLS servers where external caching is configured, any successful
session lookups in the external cache (ie. for session-resume requests) would
normally be copied into the local cache before processing continues - this flag
@@ -119,19 +119,23 @@ 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_session_reused(3)|SSL_session_reused(3)>,
L<SSL_CTX_add_session(3)|SSL_CTX_add_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(3)|SSL_CTX_set_timeout(3)>,
L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>
L<ssl(3)>, L<SSL_set_session(3)>,
L<SSL_session_reused(3)>,
L<SSL_CTX_add_session(3)>,
L<SSL_CTX_sess_number(3)>,
L<SSL_CTX_sess_set_cache_size(3)>,
L<SSL_CTX_sess_set_get_cb(3)>,
L<SSL_CTX_set_session_id_context(3)>,
L<SSL_CTX_set_timeout(3)>,
L<SSL_CTX_flush_sessions(3)>
=head1 HISTORY
=head1 COPYRIGHT
SSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL
were introduced in OpenSSL 0.9.6h.
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

11
doc/ssl/SSL_CTX_set_session_id_context.pod
View File

@@ -78,6 +78,15 @@ The operation succeeded.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>
L<ssl(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

132
doc/ssl/SSL_CTX_set_split_send_fragment.pod Normal file
View File

@@ -0,0 +1,132 @@
=pod
=head1 NAME
SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment,
SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment,
SSL_CTX_set_max_pipelines, SSL_set_max_pipelines,
SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len - Control
fragment sizes and pipelining operations
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
long SSL_set_max_send_fragment(SSL *ssl, long m);
long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
long SSL_set_max_pipelines(SSL_CTX *ssl, long m);
long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
long SSL_set_split_send_fragment(SSL *ssl, long m);
void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
void SSL_set_default_read_buffer_len(SSL *s, size_t len);
=head1 DESCRIPTION
Some engines are able to process multiple simultaneous crypto operations. This
capability could be utilised to parallelise the processing of a single
connection. For example a single write can be split into multiple records and
each one encrypted independently and in parallel. Note: this will only work in
TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
capability is known as "pipelining" within OpenSSL.
In order to benefit from the pipelining capability. You need to have an engine
that provides ciphers that support this. The OpenSSL "dasync" engine provides
AES128-SHA based ciphers that have this capability. However these are for
development and test purposes only.
SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This
value restricts the amount of plaintext bytes that will be sent in any one
SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These
functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH.
SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number
of pipelines that will be used at any one time. This value applies to both
"read" pipelining and "write" pipelining. By default only one pipeline will be
used (i.e. normal non-parallel operation). The number of pipelines set must be
in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also
automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is
explained further below. OpenSSL will only every use more than one pipeline if
a ciphersuite is negotiated that uses a pipeline capable cipher provided by an
engine.
Pipelining operates slightly differently for reading encrypted data compared to
writing encrypted data. SSL_CTX_set_split_send_fragment() and
SSL_set_split_send_fragment() define how data is split up into pipelines when
writing encrypted data. The number of pipelines used will be determined by the
amount of data provided to the SSL_write() call divided by
B<split_send_fragment>.
For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4
then:
SSL_write called with 0-2000 bytes == 1 pipeline used
SSL_write called with 2001-4000 bytes == 2 pipelines used
SSL_write called with 4001-6000 bytes == 3 pipelines used
SSL_write called with 6001+ bytes == 4 pipelines used
B<split_send_fragment> must always be less than or equal to
B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.
This will mean that the same number of records will always be created as would
have been created in the non-parallel case, although the data will be
apportioned differently. In the parallel case data will be spread equally
between the pipelines.
Read pipelining is controlled in a slightly different way than with write
pipelining. While reading we are constrained by the number of records that the
peer (and the network) can provide to us in one go. The more records we can get
in one go the more opportunity we have to parallelise the processing. As noted
above when setting B<max_pipelines> to a value greater than one, B<read_ahead>
is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to
read as much data into the read buffer as the network can provide and will fit
into the buffer. Without this set data is read into the read buffer one record
at a time. The more data that can be read, the more opportunity there is for
parallelising the processing at the cost of increased memory overhead per
connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
function (see L<SSL_pending(3)>).
The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
functions control the size of the read buffer that will be used. The B<len>
parameter sets the size of the buffer. The value will only be used if it is
greater than the default that would have been used anyway. The normal default
value depends on a number of factors but it will be at least
SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.
=head1 RETURN VALUES
All non-void functions return 1 on success and 0 on failure.
=head1 NOTES
With the exception of SSL_CTX_set_default_read_buffer_len() and
SSL_set_default_read_buffer_len() all these functions are implemented using
macros.
=head1 HISTORY
The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(),
SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
functions were added in OpenSSL 1.1.0.
=head1 SEE ALSO
L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

23
doc/ssl/SSL_CTX_set_ssl_version.pod
View File

@@ -17,8 +17,8 @@ SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method
SSL_CTX_set_ssl_version() sets a new default TLS/SSL B<method> for SSL objects
newly created from this B<ctx>. SSL objects already created with
L<SSL_new(3)|SSL_new(3)> are not affected, except when
L<SSL_clear(3)|SSL_clear(3)> is being called.
L<SSL_new(3)> are not affected, except when
L<SSL_clear(3)> is being called.
SSL_set_ssl_method() sets a new TLS/SSL B<method> for a particular B<ssl>
object. It may be reset, when SSL_clear() is called.
@@ -29,9 +29,9 @@ set in B<ssl>.
=head1 NOTES
The available B<method> choices are described in
L<SSL_CTX_new(3)|SSL_CTX_new(3)>.
L<SSL_CTX_new(3)>.
When L<SSL_clear(3)|SSL_clear(3)> is called and no session is connected to
When L<SSL_clear(3)> is called and no session is connected to
an SSL object, the method of the SSL object is reset to the method currently
set in the corresponding SSL_CTX object.
@@ -54,8 +54,17 @@ The operation succeeded.
=head1 SEE ALSO
L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<SSL_new(3)|SSL_new(3)>,
L<SSL_clear(3)|SSL_clear(3)>, L<ssl(3)|ssl(3)>,
L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
L<SSL_CTX_new(3)>, L<SSL_new(3)>,
L<SSL_clear(3)>, L<ssl(3)>,
L<SSL_set_connect_state(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

27
doc/ssl/SSL_CTX_set_timeout.pod
View File

@@ -30,15 +30,15 @@ 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.
L<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
L<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)>)
L<SSL_CTX_set_session_cache_mode(3)>)
The default value for session timeout is decided on a per protocol
basis, see L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>.
basis, see L<SSL_get_default_timeout(3)>.
All currently supported protocols have the same default timeout value
of 300 seconds.
@@ -50,10 +50,19 @@ 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)>,
L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>
L<ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)>,
L<SSL_SESSION_get_time(3)>,
L<SSL_CTX_flush_sessions(3)>,
L<SSL_get_default_timeout(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

80
doc/ssl/SSL_CTX_set_tlsext_status_cb.pod
View File

@@ -2,9 +2,17 @@
=head1 NAME
SSL_CTX_set_tlsext_status_cb, SSL_CTX_set_tlsext_status_arg,
SSL_set_tlsext_status_type, SSL_get_tlsext_status_ocsp_resp,
SSL_set_tlsext_status_ocsp_resp - OCSP Certificate Status Request functions
SSL_CTX_set_tlsext_status_cb,
SSL_CTX_get_tlsext_status_cb,
SSL_CTX_set_tlsext_status_arg,
SSL_CTX_get_tlsext_status_arg,
SSL_CTX_set_tlsext_status_type,
SSL_CTX_get_tlsext_status_type,
SSL_set_tlsext_status_type,
SSL_get_tlsext_status_type,
SSL_get_tlsext_status_ocsp_resp,
SSL_set_tlsext_status_ocsp_resp
- OCSP Certificate Status Request functions
=head1 SYNOPSIS
@@ -12,9 +20,17 @@ SSL_set_tlsext_status_ocsp_resp - OCSP Certificate Status Request functions
long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx,
int (*callback)(SSL *, void *));
long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx,
int (**callback)(SSL *, void *));
long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg);
long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg);
long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type);
long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx);
long SSL_set_tlsext_status_type(SSL *s, int type);
long SSL_get_tlsext_status_type(SSL *s);
long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp);
long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len);
@@ -23,16 +39,31 @@ SSL_set_tlsext_status_ocsp_resp - OCSP Certificate Status Request functions
A client application may request that a server send back an OCSP status response
(also known as OCSP stapling). To do so the client should call the
SSL_set_tlsext_status_type() function prior to the start of the handshake.
SSL_CTX_set_tlsext_status_type() function prior to the creation of any SSL
objects. Alternatively an application can call the SSL_set_tlsext_status_type()
function on an individual SSL object prior to the start of the handshake.
Currently the only supported type is B<TLSEXT_STATUSTYPE_ocsp>. This value
should be passed in the B<type> argument. The client should additionally provide
a callback function to decide what to do with the returned OCSP response by
calling SSL_CTX_set_tlsext_status_cb(). The callback function should determine
whether the returned OCSP response is acceptable or not. The callback will be
passed as an argument the value previously set via a call to
SSL_CTX_set_tlsext_status_arg(). Note that the callback will not be called in
the event of a handshake where session resumption occurs (because there are no
Certificates exchanged in such a handshake).
should be passed in the B<type> argument. Calling
SSL_CTX_get_tlsext_status_type() will return the type B<TLSEXT_STATUSTYPE_ocsp>
previously set via SSL_CTX_set_tlsext_status_type() or -1 if not set.
The client should additionally provide a callback function to decide what to do
with the returned OCSP response by calling SSL_CTX_set_tlsext_status_cb(). The
callback function should determine whether the returned OCSP response is
acceptable or not. The callback will be passed as an argument the value
previously set via a call to SSL_CTX_set_tlsext_status_arg(). Note that the
callback will not be called in the event of a handshake where session resumption
occurs (because there are no Certificates exchanged in such a handshake).
The callback previously set via SSL_CTX_set_tlsext_status_cb() can be retrieved
by calling SSL_CTX_get_tlsext_status_cb(), and the argument by calling
SSL_CTX_get_tlsext_status_arg().
On the client side SSL_get_tlsext_status_type() can be used to determine whether
the client has previously called SSL_set_tlsext_status_type(). It will return
B<TLSEXT_STATUSTYPE_ocsp> if it has been called or -1 otherwise. On the server
side SSL_get_tlsext_status_type() can be used to determine whether the client
requested OCSP stapling. If the client requested it then this function will
return B<TLSEXT_STATUSTYPE_ocsp>, or -1 otherwise.
The response returned by the server can be obtained via a call to
SSL_get_tlsext_status_ocsp_resp(). The value B<*resp> will be updated to point
@@ -64,10 +95,31 @@ returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has
occurred).
SSL_CTX_set_tlsext_status_cb(), SSL_CTX_set_tlsext_status_arg(),
SSL_set_tlsext_status_type() and SSL_set_tlsext_status_ocsp_resp() return 0 on
error or 1 on success.
SSL_CTX_set_tlsext_status_type(), SSL_set_tlsext_status_type() and
SSL_set_tlsext_status_ocsp_resp() return 0 on error or 1 on success.
SSL_CTX_get_tlsext_status_type() returns the value previously set by
SSL_CTX_set_tlsext_status_type(), or -1 if not set.
SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data
or -1 if there is no OCSP response data.
SSL_get_tlsext_status_type() returns B<TLSEXT_STATUSTYPE_ocsp> on the client
side if SSL_set_tlsext_status_type() was previously called, or on the server
side if the client requested OCSP stapling. Otherwise -1 is returned.
=head1 HISTORY
SSL_get_tlsext_status_type(), SSL_CTX_get_tlsext_status_type() and
SSL_CTX_set_tlsext_status_type() were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

93
doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod
View File

@@ -10,28 +10,25 @@ SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing
long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
int (*cb)(SSL *s, unsigned char key_name[16],
unsigned char iv[EVP_MAX_IV_LENGTH],
EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
unsigned char iv[EVP_MAX_IV_LENGTH],
EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
=head1 DESCRIPTION
SSL_CTX_set_tlsext_ticket_key_cb() sets a callback fuction I<cb> for handling
session tickets for the ssl context I<sslctx>. Session tickets, defined in
SSL_CTX_set_tlsext_ticket_key_cb() sets a callback function I<cb> for handling
session tickets for the ssl context I<sslctx>. Session tickets, defined in
RFC5077 provide an enhanced session resumption capability where the server
implementation is not required to maintain per session state. It only applies
to TLS and there is no SSLv3 implementation.
The callback is available when the OpenSSL library was built without
I<OPENSSL_NO_TLSEXT> being defined.
The callback function I<cb> will be called for every client instigated TLS
session when session ticket extension is presented in the TLS hello
message. It is the responsibility of this function to create or retrieve the
cryptographic parameters and to maintain their state.
The OpenSSL library uses your callback function to help implement a common TLS
The OpenSSL library uses your callback function to help implement a common TLS
ticket construction state according to RFC5077 Section 4 such that per session
state is unnecessary and a small set of cryptographic variables needs to be
state is unnecessary and a small set of cryptographic variables needs to be
maintained by the callback function implementation.
In order to reuse a session, a TLS client must send the a session ticket
@@ -40,36 +37,37 @@ The server, through the callback function, either agrees to reuse the session
ticket information or it starts a full TLS handshake to create a new session
ticket.
Before the callback function is started I<ctx> and I<hctx> have been
Before the callback function is started I<ctx> and I<hctx> have been
initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively.
For new sessions tickets, when the client doesn't present a session ticket, or
an attempted retreival of the ticket failed, or a renew option was indicated,
an attempted retrieval of the ticket failed, or a renew option was indicated,
the callback function will be called with I<enc> equal to 1. The OpenSSL
library expects that the function will set an arbitary I<name>, initialize
library expects that the function will set an arbitrary I<name>, initialize
I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>.
The I<name> is 16 characters long and is used as a key identifier.
The I<iv> length is the length of the IV of the corresponding cipher. The
maximum IV length is L<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>.
maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>.
The initialization vector I<iv> should be a random value. The cipher context
I<ctx> should use the initialisation vector I<iv>. The cipher context can be
set using L<EVP_EncryptInit_ex>. The hmac context can be set using L<HMAC_Init_ex>.
The initialization vector I<iv> should be a random value. The cipher context
I<ctx> should use the initialisation vector I<iv>. The cipher context can be
set using L<EVP_EncryptInit_ex(3)>. The hmac context can be set using
L<HMAC_Init_ex(3)>.
When the client presents a session ticket, the callback function with be called
with I<enc> set to 0 indicating that the I<cb> function should retreive a set
When the client presents a session ticket, the callback function with be called
with I<enc> set to 0 indicating that the I<cb> function should retrieve a set
of parameters. In this case I<name> and I<iv> have already been parsed out of
the session ticket. The OpenSSL library expects that the I<name> will be used
to retrieve a cryptographic parameters and that the cryptographic context
I<ctx> will be set with the retreived parameters and the initialization vector
I<iv>. using a function like L<EVP_DecryptInit_ex>. The I<hctx> needs to be set
using L<HMAC_Init_ex>.
I<ctx> will be set with the retrieved parameters and the initialization vector
I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The I<hctx> needs to be
set using L<HMAC_Init_ex(3)>.
If the I<name> is still valid but a renewal of the ticket is required the
callback function should return 2. The library will call the callback again
with an arguement of enc equal to 1 to set the new ticket.
with an argument of enc equal to 1 to set the new ticket.
The return value of the I<cb> function is used by OpenSSL to determine what
further processing will occur. The following return values have meaning:
@@ -78,7 +76,7 @@ further processing will occur. The following return values have meaning:
=item Z<>2
This indicates that the I<ctx> and I<hctx> have been set and the session can
This indicates that the I<ctx> and I<hctx> have been set and the session can
continue on those parameters. Additionally it indicates that the session
ticket is in a renewal period and should be replaced. The OpenSSL library will
call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077
@@ -86,13 +84,13 @@ call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077
=item Z<>1
This indicates that the I<ctx> and I<hctx> have been set and the session can
This indicates that the I<ctx> and I<hctx> have been set and the session can
continue on those parameters.
=item Z<>0
This indicates that it was not possible to set/retrieve a session ticket and
the SSL/TLS session will continue by by negiotationing a set of cryptographic
This indicates that it was not possible to set/retrieve a session ticket and
the SSL/TLS session will continue by negotiating a set of cryptographic
parameters or using the alternate SSL/TLS resumption mechanism, session ids.
If called with enc equal to 0 the library will call the I<cb> again to get
@@ -107,10 +105,10 @@ This indicates an error.
=head1 NOTES
Session resumption shortcuts the TLS so that the client certificate
negiotation don't occur. It makes up for this by storing client certificate
negotiation don't occur. It makes up for this by storing client certificate
an all other negotiated state information encrypted within the ticket. In a
resumed session the applications will have all this state information available
exactly as if a full negiotation had occured.
exactly as if a full negotiation had occurred.
If an attacker can obtain the key used to encrypt a session ticket, they can
obtain the master secret for any ticket using that key and decrypt any traffic
@@ -125,8 +123,8 @@ enable an attacker to obtain the session keys.
=head1 EXAMPLES
Reference Implemention:
SSL_CTX_set_tlsext_ticket_key_cb(SSL,ssl_tlsext_ticket_key_cb);
Reference Implementation:
SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb);
....
static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)
@@ -135,7 +133,7 @@ Reference Implemention:
if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) {
return -1; /* insufficient random */
}
key = currentkey(); /* something that you need to implement */
if ( !key ) {
/* current key doesn't exist or isn't valid */
@@ -148,19 +146,19 @@ Reference Implemention:
}
}
memcpy(key_name, key->name, 16);
EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
return 1;
} else { /* retrieve session */
key = findkey(name);
if (!key || key->expire < now() ) {
return 0;
}
HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv );
@@ -169,7 +167,7 @@ Reference Implemention:
return 2;
}
return 1;
}
}
@@ -181,15 +179,20 @@ returns 0 to indicate the callback function was set.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
L<SSL_session_reused(3)|SSL_session_reused(3)>,
L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>,
L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(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(3)>, L<SSL_set_session(3)>,
L<SSL_session_reused(3)>,
L<SSL_CTX_add_session(3)>,
L<SSL_CTX_sess_number(3)>,
L<SSL_CTX_sess_set_get_cb(3)>,
L<SSL_CTX_set_session_id_context(3)>,
=head1 HISTORY
=head1 COPYRIGHT
This function was introduced in OpenSSL 0.9.8h
Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

27
doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
View File

@@ -57,18 +57,17 @@ DH parameters can be reused, as the actual key is newly generated during
the negotiation. The risk in reusing DH parameters is that an attacker
may specialize on a very often used DH group. Applications should therefore
generate their own DH parameters during the installation process using the
openssl L<dhparam(1)|dhparam(1)> application. This application
openssl L<dhparam(1)> application. This application
guarantees that "strong" primes are used.
Files dh2048.pem, and dh4096.pem in the 'apps' directory of the current
version of the OpenSSL distribution contain the 'SKIP' DH parameters,
which use safe primes and were generated verifiably pseudo-randomly.
These files can be converted into C code using the B<-C> option of the
L<dhparam(1)|dhparam(1)> application. Generation of custom DH
L<dhparam(1)> application. Generation of custom DH
parameters during installation should still be preferred to stop an
attacker from specializing on a commonly used group. Files dh1024.pem
and dh512.pem contain old parameters that must not be used by
applications.
attacker from specializing on a commonly used group. File dh1024.pem
contains old parameters that must not be used by applications.
An application may either directly specify the DH parameters or
can supply the DH parameters via a callback function.
@@ -105,7 +104,7 @@ partly left out.)
/* Error. */
}
if (dh_2048 == NULL) {
/* Error. */
/* Error. */
}
if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) {
/* Error. */
@@ -122,9 +121,17 @@ on failure. Check the error queue to find out the reason of failure.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)>
L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>,
L<SSL_CTX_set_options(3)>,
L<ciphers(1)>, L<dhparam(1)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

159
doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod
View File

@@ -1,159 +0,0 @@
=pod
=head1 NAME
SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa - handle RSA keys for ephemeral key exchange
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx,
RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa);
long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx);
void SSL_set_tmp_rsa_callback(SSL_CTX *ctx,
RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa)
long SSL_need_tmp_rsa(SSL *ssl)
RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength);
=head1 DESCRIPTION
SSL_CTX_set_tmp_rsa_callback() sets the callback function for B<ctx> to be
used when a temporary/ephemeral RSA key is required to B<tmp_rsa_callback>.
The callback is inherited by all SSL objects newly created from B<ctx>
with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected.
SSL_CTX_set_tmp_rsa() sets the temporary/ephemeral RSA key to be used to be
B<rsa>. The key is inherited by all SSL objects newly created from B<ctx>
with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected.
SSL_CTX_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed
for RSA-based strength-limited 'exportable' ciphersuites because a RSA key
with a keysize larger than 512 bits is installed.
SSL_set_tmp_rsa_callback() sets the callback only for B<ssl>.
SSL_set_tmp_rsa() sets the key only for B<ssl>.
SSL_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed,
for RSA-based strength-limited 'exportable' ciphersuites because a RSA key
with a keysize larger than 512 bits is installed.
These functions apply to SSL/TLS servers only.
=head1 NOTES
When using a cipher with RSA authentication, an ephemeral RSA key exchange
can take place. In this case the session data are negotiated using the
ephemeral/temporary RSA key and the RSA key supplied and certified
by the certificate chain is only used for signing.
Under previous export restrictions, ciphers with RSA keys shorter (512 bits)
than the usual key length of 1024 bits were created. To use these ciphers
with RSA keys of usual length, an ephemeral key exchange must be performed,
as the normal (certified) key cannot be directly used.
Using ephemeral RSA key exchange yields forward secrecy, as the connection
can only be decrypted, when the RSA key is known. By generating a temporary
RSA key inside the server application that is lost when the application
is left, it becomes impossible for an attacker to decrypt past sessions,
even if he gets hold of the normal (certified) RSA key, as this key was
used for signing only. The downside is that creating a RSA key is
computationally expensive.
Additionally, the use of ephemeral RSA key exchange is only allowed in
the TLS standard, when the RSA key can be used for signing only, that is
for export ciphers. Using ephemeral RSA key exchange for other purposes
violates the standard and can break interoperability with clients.
It is therefore strongly recommended to not use ephemeral RSA key
exchange and use DHE (Ephemeral Diffie-Hellman) key exchange instead
in order to achieve forward secrecy (see
L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
An application may either directly specify the key or can supply the key via a
callback function. The callback approach has the advantage, that the callback
may generate the key only in case it is actually needed. As the generation of a
RSA key is however costly, it will lead to a significant delay in the handshake
procedure. Another advantage of the callback function is that it can supply
keys of different size while the explicit setting of the key is only useful for
key size of 512 bits to satisfy the export restricted ciphers and does give
away key length if a longer key would be allowed.
The B<tmp_rsa_callback> is called with the B<keylength> needed and
the B<is_export> information. The B<is_export> flag is set, when the
ephemeral RSA key exchange is performed with an export cipher.
=head1 EXAMPLES
Generate temporary RSA keys to prepare ephemeral RSA key exchange. As the
generation of a RSA key costs a lot of computer time, they saved for later
reuse. For demonstration purposes, two keys for 512 bits and 1024 bits
respectively are generated.
...
/* Set up ephemeral RSA stuff */
RSA *rsa_512 = NULL;
RSA *rsa_1024 = NULL;
rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL);
if (rsa_512 == NULL)
evaluate_error_queue();
rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL);
if (rsa_1024 == NULL)
evaluate_error_queue();
...
RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength)
{
RSA *rsa_tmp=NULL;
switch (keylength) {
case 512:
if (rsa_512)
rsa_tmp = rsa_512;
else { /* generate on the fly, should not happen in this example */
rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL);
rsa_512 = rsa_tmp; /* Remember for later reuse */
}
break;
case 1024:
if (rsa_1024)
rsa_tmp=rsa_1024;
else
should_not_happen_in_this_example();
break;
default:
/* Generating a key on the fly is very costly, so use what is there */
if (rsa_1024)
rsa_tmp=rsa_1024;
else
rsa_tmp=rsa_512; /* Use at least a shorter key */
}
return(rsa_tmp);
}
=head1 RETURN VALUES
SSL_CTX_set_tmp_rsa_callback() and SSL_set_tmp_rsa_callback() do not return
diagnostic output.
SSL_CTX_set_tmp_rsa() and SSL_set_tmp_rsa() do return 1 on success and 0
on failure. Check the error queue to find out the reason of failure.
SSL_CTX_need_tmp_rsa() and SSL_need_tmp_rsa() return 1 if a temporary
RSA key is needed and 0 otherwise.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
L<SSL_new(3)|SSL_new(3)>, L<ciphers(1)|ciphers(1)>
=cut

103
doc/ssl/SSL_CTX_set_verify.pod
View File

@@ -2,20 +2,25 @@
=head1 NAME
SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters
SSL_get_ex_data_X509_STORE_CTX_idx,
SSL_CTX_set_verify, SSL_set_verify,
SSL_CTX_set_verify_depth, SSL_set_verify_depth,
SSL_verify_cb
- 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_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback);
void SSL_set_verify(SSL *s, int mode, SSL_verify_cb verify_callback);
SSL_get_ex_data_X509_STORE_CTX_idx(void);
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);
typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx);
=head1 DESCRIPTION
@@ -29,13 +34,15 @@ 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 time B<ssl> was created with
L<SSL_new(3)|SSL_new(3)>.
L<SSL_new(3)>. Within the callback function,
B<SSL_get_ex_data_X509_STORE_CTX_idx> can be called to get the data index
of the current SSL object that is doing the verification.
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.)
verification that shall be allowed for B<ctx>.
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.)
verification that shall be allowed for B<ssl>.
=head1 NOTES
@@ -52,7 +59,7 @@ 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.
using the L<SSL_get_verify_result(3)> function.
The handshake will be continued regardless of the verification result.
=item SSL_VERIFY_PEER
@@ -89,28 +96,30 @@ 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.
If the B<mode> is SSL_VERIFY_NONE none of the other flags may be set.
The actual verification procedure is performed either using the built-in
verification procedure or using another application provided verification
function set with
L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>.
L<SSL_CTX_set_cert_verify_callback(3)>.
The following descriptions apply in the case of the built-in procedure. An
application provided procedure also has access to the verify depth information
and the verify_callback() function, but the way this information is used
may be different.
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.
SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set a limit on the
number of certificates between the end-entity and trust-anchor certificates.
Neither the
end-entity nor the trust-anchor certificates count against B<depth>. If the
certificate chain needed to reach a trusted issuer is longer than B<depth+2>,
X509_V_ERR_CERT_CHAIN_TOO_LONG 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 100,
allowing for the peer certificate and additional 100 CA certificates.
depth to 2 allows the levels 0, 1, 2 and 3 (0 being the end-entity and 3 the
trust-anchor).
The default depth limit is 100,
allowing for the peer certificate, at most 100 intermediate CA certificates and
a final trust anchor certificate.
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
@@ -138,7 +147,7 @@ the verification process is continued. If B<verify_callback> always returns
1, the TLS/SSL handshake will not be terminated with respect to verification
failures and the connection will be established. 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
L<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.
@@ -149,14 +158,9 @@ 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.
is set, but whether any flags are set. This can lead to
unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as
required.
=head1 RETURN VALUES
@@ -176,8 +180,8 @@ 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)>).
(see L<CRYPTO_get_ex_new_index(3)>,
L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
...
typedef struct {
@@ -221,7 +225,7 @@ L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
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);
@@ -237,7 +241,7 @@ L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
*/
if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT))
{
X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256);
X509_NAME_oneline(X509_get_issuer_name(err_cert), buf, 256);
printf("issuer= %s\n", buf);
}
@@ -269,9 +273,9 @@ L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
*/
mydata.verify_depth = verify_depth; ...
SSL_set_ex_data(ssl, mydata_index, &mydata);
...
SSL_accept(ssl); /* check of success left out for clarity */
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)
@@ -282,13 +286,22 @@ L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
=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_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(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(7)>, L<SSL_new(3)>,
L<SSL_CTX_get_verify_mode(3)>,
L<SSL_get_verify_result(3)>,
L<SSL_CTX_load_verify_locations(3)>,
L<SSL_get_peer_certificate(3)>,
L<SSL_CTX_set_cert_verify_callback(3)>,
L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
L<CRYPTO_get_ex_new_index(3)>
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

69
doc/ssl/SSL_CTX_use_certificate.pod
View File

@@ -2,7 +2,17 @@
=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
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_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
@@ -16,16 +26,17 @@ SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_f
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_use_certificate_chain_file(SSL *ssl, 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);
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_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);
@@ -41,18 +52,18 @@ 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
created from B<ctx> with L<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.
L<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)>
L<SSL_CTX_add_extra_chain_cert(3)>
function.
SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from
@@ -66,12 +77,12 @@ 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
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 subject's certificate (actual client or server
certificate), followed by intermediate CA certificates if applicable, and
ending at the highest level (root) CA.
There is no corresponding function working on a single SSL object.
ending at the highest level (root) CA. SSL_use_certificate_chain_file() is
similar except it loads the certificate chain into B<ssl>.
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
@@ -81,7 +92,7 @@ If a certificate has already been set and the private does not belong
to the certificate an error is returned. To change a certificate, private
key pair the new certificate needs to be set with SSL_use_certificate()
or SSL_CTX_use_certificate() before setting the private key with
SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey().
SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey().
SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk>
@@ -108,22 +119,22 @@ 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 several private
key/certificate pairs at a time. The certificate used depends on the
cipher selected, see also L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>.
cipher selected, see also L<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
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_add1_chain_cert(3)|SSL_CTX_add1_chain_cert(3)>. Note: versions of OpenSSL before 1.0.2 only had a single
to the store of chain certificates using L<SSL_CTX_add1_chain_cert(3)>. Note: versions of OpenSSL before 1.0.2 only had a single
certificate chain store for all certificate types, OpenSSL 1.0.2 and later
have a separate chain store for each type. SSL_CTX_use_certificate_chain_file()
have a separate chain store for each type. SSL_CTX_use_certificate_chain_file()
should be used 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
@@ -132,12 +143,12 @@ 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)>.
L<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)>.
L<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.)
@@ -149,17 +160,21 @@ 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_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>,
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>,
L<SSL_CTX_load_verify_locations(3)>,
L<SSL_CTX_set_default_passwd_cb(3)>,
L<SSL_CTX_set_cipher_list(3)>,
L<SSL_CTX_set_client_CA_list(3)>,
L<SSL_CTX_set_client_cert_cb(3)>,
L<SSL_CTX_add_extra_chain_cert(3)>
=head1 HISTORY
=head1 COPYRIGHT
Support for DER encoded private keys (SSL_FILETYPE_ASN1) in
SSL_CTX_use_PrivateKey_file() and SSL_use_PrivateKey_file() was added
in 0.9.8 .
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

49
doc/ssl/SSL_CTX_use_psk_identity_hint.pod
View File

@@ -1,41 +1,11 @@
=pod
=begin comment
Copyright 2005 Nokia. All rights reserved.
The portions of the attached software ("Contribution") is developed by
Nokia Corporation and is licensed pursuant to the OpenSSL open source
license.
The Contribution, originally written by Mika Kousa and Pasi Eronen of
Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites
support (see RFC 4279) to OpenSSL.
No patent licenses or other rights except those expressly stated in
the OpenSSL open source license shall be deemed granted or received
expressly, by implication, estoppel, or otherwise.
No assurances are provided by Nokia that the Contribution does not
infringe the patent or other intellectual property rights of any third
party or that the license provides you with all the necessary rights
to make use of the Contribution.
THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN
ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA
SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY
OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR
OTHERWISE.
=end comment
=head1 NAME
SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint,
SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK
identity hint to use
=head1 SYNOPSIS
#include <openssl/ssl.h>
@@ -44,11 +14,11 @@ identity hint to use
int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx,
unsigned int (*callback)(SSL *ssl, const char *identity,
unsigned char *psk, int max_psk_len));
unsigned int (*callback)(SSL *ssl, const char *identity,
unsigned char *psk, int max_psk_len));
void SSL_set_psk_server_callback(SSL *ssl,
unsigned int (*callback)(SSL *ssl, const char *identity,
unsigned char *psk, int max_psk_len));
unsigned int (*callback)(SSL *ssl, const char *identity,
unsigned char *psk, int max_psk_len));
=head1 DESCRIPTION
@@ -103,4 +73,15 @@ completely.
=back
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
Copyright 2005 Nokia.
=cut

14
doc/ssl/SSL_CTX_use_serverinfo.pod
View File

@@ -20,8 +20,8 @@ A "serverinfo" extension is returned in response to an empty ClientHello
Extension.
SSL_CTX_use_serverinfo() loads one or more serverinfo extensions from
a byte array into B<ctx>. The extensions must be concatenated into a
sequence of bytes. Each extension must consist of a 2-byte Extension Type,
a byte array into B<ctx>. The extensions must be concatenated into a
sequence of bytes. Each extension must consist of a 2-byte Extension Type,
a 2-byte length, and then length bytes of extension_data.
SSL_CTX_use_serverinfo_file() loads one or more serverinfo extensions from
@@ -38,17 +38,19 @@ use the serverinfo extension for multiple certificates,
SSL_CTX_use_serverinfo() needs to be called multiple times, once B<after>
each time a certificate is loaded.
=head1 NOTES
=head1 RETURN VALUES
On success, the functions return 1.
On failure, the functions return 0. Check out the error stack to find out
the reason.
=head1 SEE ALSO
=head1 COPYRIGHT
=head1 HISTORY
Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

43
doc/ssl/SSL_SESSION_free.pod
View File

@@ -2,25 +2,36 @@
=head1 NAME
SSL_SESSION_free - free an allocated SSL_SESSION structure
SSL_SESSION_new,
SSL_SESSION_up_ref,
SSL_SESSION_free - create, free and manage SSL_SESSION structures
=head1 SYNOPSIS
#include <openssl/ssl.h>
SSL_SESSION *SSL_SESSION_new(void);
int SSL_SESSION_up_ref(SSL_SESSION *ses);
void SSL_SESSION_free(SSL_SESSION *session);
=head1 DESCRIPTION
SSL_SESSION_new() creates a new SSL_SESSION structure and returns a pointer to
it.
SSL_SESSION_up_ref() increments the reference count on the given SSL_SESSION
structure.
SSL_SESSION_free() decrements the reference count of B<session> and removes
the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated
memory, if the reference count has reached 0.
If B<session> is NULL nothing is done.
=head1 NOTES
SSL_SESSION objects are allocated, when a TLS/SSL handshake operation
is successfully completed. Depending on the settings, see
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_set_session_cache_mode(3)>,
the SSL_SESSION objects are internally referenced by the SSL_CTX and
linked into its session cache. SSL objects may be using the SSL_SESSION object;
as a session may be reused, several SSL objects may be using one SSL_SESSION
@@ -31,25 +42,37 @@ dangling pointers. These failures may also appear delayed, e.g.
when an SSL_SESSION object was completely freed as the reference count
incorrectly became 0, but it is still referenced in the internal
session cache and the cache list is processed during a
L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> operation.
L<SSL_CTX_flush_sessions(3)> operation.
SSL_SESSION_free() must only be called for SSL_SESSION objects, for
which the reference count was explicitly incremented (e.g.
by calling SSL_get1_session(), see L<SSL_get_session(3)|SSL_get_session(3)>)
by calling SSL_get1_session(), see L<SSL_get_session(3)>)
or when the SSL_SESSION object was generated outside a TLS handshake
operation, e.g. by using L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>.
operation, e.g. by using L<d2i_SSL_SESSION(3)>.
It must not be called on other SSL_SESSION objects, as this would cause
incorrect reference counts and therefore program failures.
=head1 RETURN VALUES
SSL_SESSION_free() does not provide diagnostic information.
SSL_SESSION_new returns a pointer to the newly allocated SSL_SESSION structure
or NULL on error.
SSL_SESSION_up_ref returns 1 on success or 0 on error.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_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)>,
L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>
L<ssl(3)>, L<SSL_get_session(3)>,
L<SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_flush_sessions(3)>,
L<d2i_SSL_SESSION(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

42
doc/ssl/SSL_SESSION_get0_cipher.pod Normal file
View File

@@ -0,0 +1,42 @@
=pod
=head1 NAME
SSL_SESSION_get0_cipher - retrieve the SSL cipher associated with a session
=head1 SYNOPSIS
#include <openssl/ssl.h>
const SSL_CIPHER *SSL_SESSION_get0_cipher(const SSL_SESSSION *s);
=head1 DESCRIPTION
SSL_SESSION_get0_cipher() retrieves the cipher that was used by the
connection when the session was created, or NULL if it cannot be determined.
The value returned is a pointer to an object maintained within B<s> and
should not be released.
=head1 SEE ALSO
L<ssl(3)>,
L<d2i_SSL_SESSION(3)>,
L<SSL_SESSION_get_time(3)>,
L<SSL_SESSION_get0_hostname(3)>,
L<SSL_SESSION_free(3)>
=head1 HISTORY
SSL_SESSION_get0_cipher() was first added to OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

37
doc/ssl/SSL_SESSION_get0_hostname.pod Normal file
View File

@@ -0,0 +1,37 @@
=pod
=head1 NAME
SSL_SESSION_get0_hostname - retrieve the SNI hostname associated with a session
=head1 SYNOPSIS
#include <openssl/ssl.h>
const char *SSL_SESSION_get0_hostname(const SSL_SESSSION *s);
=head1 DESCRIPTION
SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the
client when the session was created, or NULL if no value was sent.
The value returned is a pointer to memory maintained within B<s> and
should not be free'd.
=head1 SEE ALSO
L<ssl(3)>,
L<d2i_SSL_SESSION(3)>,
L<SSL_SESSION_get_time(3)>,
L<SSL_SESSION_free(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,56 @@
=pod
=head1 NAME
SSL_SESSION_get0_id_context,
SSL_SESSION_set1_id_context
- get and set the SSL ID context associated with a session
=head1 SYNOPSIS
#include <openssl/ssl.h>
const unsigned char *SSL_SESSION_get0_id_context(const SSL_SESSION *s,
unsigned int *len)
int SSL_SESSION_set1_id_context(SSL_SESSION *s, const unsigned char *sid_ctx,
unsigned int sid_ctx_len);
=head1 DESCRIPTION
See L<SSL_CTX_set_session_id_context(3)> for further details on session ID
contexts.
SSL_SESSION_get0_id_context() returns the ID context associated with
the SSL/TLS session B<s>. The length of the ID context is written to
B<*len> if B<len> is not NULL.
The value returned is a pointer to an object maintained within B<s> and
should not be released.
SSL_SESSION_set1_id_context() takes a copy of the provided ID context given in
B<sid_ctx> and associates it with the session B<s>. The length of the ID context
is given by B<sid_ctx_len> which must not exceed SSL_MAX_SID_CTX_LENGTH bytes.
=head1 RETURN VALUES
SSL_SESSION_set1_id_context() returns 1 on success or 0 on error.
=head1 SEE ALSO
L<ssl(3)>,
L<SSL_set_session_id_context(3)>
=head1 HISTORY
SSL_SESSION_get0_id_context() was first added to OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,38 @@
=pod
=head1 NAME
SSL_SESSION_get0_peer
- get details about peer's certificate for a session
=head1 SYNOPSIS
#include <openssl/ssl.h>
X509 *SSL_SESSION_get0_peer(SSL_SESSION *s);
=head1 DESCRIPTION
SSL_SESSION_get0_peer() returns the peer certificate associated with the session
B<s> or NULL if no peer certificate is available. The caller should not free the
returned value (unless L<X509_up_ref(3)> has also been called).
=head1 RETURN VALUES
SSL_SESSION_get0_peer() returns a pointer to the peer certificate or NULL if
no peer certificate is available.
=head1 SEE ALSO
L<ssl(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

39
doc/ssl/SSL_SESSION_get_compress_id.pod Normal file
View File

@@ -0,0 +1,39 @@
=pod
=head1 NAME
SSL_SESSION_get_compress_id
- get details about the compression associated with a session
=head1 SYNOPSIS
#include <openssl/ssl.h>
unsigned int SSL_SESSION_get_compress_id(const SSL_SESSION *s);
=head1 DESCRIPTION
If compression has been negotiated for an ssl session then
SSL_SESSION_get_compress_id() will return the id for the compression method or
0 otherwise. The only built-in supported compression method is zlib which has an
id of 1.
=head1 RETURN VALUES
SSL_SESSION_get_compress_id() returns the id of the compression method or 0 if
none.
=head1 SEE ALSO
L<ssl(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

47
doc/ssl/SSL_SESSION_get_ex_data.pod Normal file
View File

@@ -0,0 +1,47 @@
=pod
=head1 NAME
SSL_SESSION_set_ex_data,
SSL_SESSION_get_ex_data
- get and set application specific data on a session
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_SESSION_set_ex_data(SSL_SESSION *ss, int idx, void *data);
void *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx);
=head1 DESCRIPTION
SSL_SESSION_set_ex_data() enables an application to store arbitrary application
specific data B<data> in an SSL_SESSION structure B<ss>. The index B<idx> should
be a value previously returned from a call to L<CRYPTO_get_ex_new_index(3)>.
SSL_SESSION_get_ex_data() retrieves application specific data previously stored
in an SSL_SESSION structure B<s>. The B<idx> value should be the same as that
used when originally storing the data.
=head1 RETURN VALUES
SSL_SESSION_set_ex_data() returns 1 for success or 0 for failure.
SSL_SESSION_get_ex_data() returns the previously stored value or NULL on
failure. NULL may also be a valid value.
=head1 SEE ALSO
L<ssl(3)>,
L<CRYPTO_get_ex_new_index(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

61
doc/ssl/SSL_SESSION_get_ex_new_index.pod
View File

@@ -1,61 +0,0 @@
=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(const 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(3)|RSA_get_ex_new_index(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

44
doc/ssl/SSL_SESSION_get_protocol_version.pod Normal file
View File

@@ -0,0 +1,44 @@
=pod
=head1 NAME
SSL_SESSION_get_protocol_version - retrieve session protocol version
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_SESSION_get_protocol_version(const SSL_SESSION *s);
=head1 DESCRIPTION
SSL_SESSION_get_protocol_version() returns the protocol version number used
by session B<s>.
=head1 RETURN VALUES
SSL_SESSION_get_protocol_version() returns a number indicating the protocol
version used for the session; this number matches the constants I<e.g.>
B<TLS1_VERSION> or B<TLS1_2_VERSION>.
Note that the SSL_SESSION_get_protocol_version() function
does B<not> perform a null check on the provided session B<s> pointer.
=head1 SEE ALSO
L<ssl(3)>
=head1 HISTORY
SSL_SESSION_get_protocol_version() was first added to OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

24
doc/ssl/SSL_SESSION_get_time.pod
View File

@@ -2,7 +2,10 @@
=head1 NAME
SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, SSL_SESSION_set_timeout - retrieve and manipulate session time and timeout settings
SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout,
SSL_SESSION_set_timeout,
SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_set_timeout
- retrieve and manipulate session time and timeout settings
=head1 SYNOPSIS
@@ -41,7 +44,7 @@ functions are synonyms for the SSL_SESSION_*() counterparts.
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)>.
L<SSL_CTX_set_timeout(3)>.
Using these functions it is possible to extend or shorten the lifetime
of the session.
@@ -52,13 +55,22 @@ 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>,
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)>,
L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>
L<ssl(7)>,
L<SSL_CTX_set_timeout(3)>,
L<SSL_get_default_timeout(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,53 @@
=pod
=head1 NAME
SSL_SESSION_get0_ticket,
SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint
- get details about the ticket associated with a session
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_SESSION_has_ticket(const SSL_SESSION *s);
unsigned long SSL_SESSION_get_ticket_lifetime_hint(const SSL_SESSION *s);
void SSL_SESSION_get0_ticket(const SSL_SESSION *s, const unsigned char **tick,
size_t *len);
=head1 DESCRIPTION
SSL_SESSION_has_ticket() returns 1 if there is a Session Ticket associated with
this session, and 0 otherwise.
SSL_SESSION_get_ticket_lifetime_hint returns the lifetime hint in seconds
associated with the session ticket.
SSL_SESSION_get0_ticket obtains a pointer to the ticket associated with a
session. The length of the ticket is written to B<*len>. If B<tick> is non
NULL then a pointer to the ticket is written to B<*tick>. The pointer is only
valid while the connection is in use. The session (and hence the ticket pointer)
may also become invalid as a result of a call to SSL_CTX_flush_sessions().
=head1 SEE ALSO
L<ssl(7)>,
L<d2i_SSL_SESSION(3)>,
L<SSL_SESSION_get_time(3)>,
L<SSL_SESSION_free(3)>
=head1 HISTORY
SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint and
SSL_SESSION_get0_ticket were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

47
doc/ssl/SSL_SESSION_print.pod Normal file
View File

@@ -0,0 +1,47 @@
=pod
=head1 NAME
SSL_SESSION_print,
SSL_SESSION_print_fp,
SSL_SESSION_print_keylog
- printf information about a session
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_SESSION_print(BIO *fp, const SSL_SESSION *ses);
int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *ses);
int SSL_SESSION_print_keylog(BIO *bp, const SSL_SESSION *x);
=head1 DESCRIPTION
SSL_SESSION_print() prints summary information about the session provided in
B<ses> to the BIO B<fp>.
SSL_SESSION_print_fp() does the same as SSL_SESSION_print() except it prints it
to the FILE B<fp>.
SSL_SESSION_print_keylog() prints session information to the provided BIO <bp>
in NSS keylog format.
=head1 RETURN VALUES
SSL_SESSION_print(), SSL_SESSION_print_fp() and SSL_SESSION_print_keylog return
1 on success or 0 on error.
=head1 SEE ALSO
L<ssl(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,50 @@
=pod
=head1 NAME
SSL_SESSION_get_id,
SSL_SESSION_set1_id
- get and set the SSL session ID
=head1 SYNOPSIS
#include <openssl/ssl.h>
const unsigned char *SSL_SESSION_get_id(const SSL_SESSION *s,
unsigned int *len)
int SSL_SESSION_set1_id(SSL_SESSION *s, const unsigned char *sid,
unsigned int sid_len);
=head1 DESCRIPTION
SSL_SESSION_get_id() returns a pointer to the internal session id value for the
session B<s>. The length of the id in bytes is stored in B<*len>. The length may
be 0. The caller should not free the returned pointer directly.
SSL_SESSION_set1_id() sets the the session ID for the B<ssl> SSL/TLS session
to B<sid> of length B<sid_len>.
=head1 RETURN VALUES
SSL_SESSION_get_id() returns a pointer to the session id value.
SSL_SESSION_set1_id() returns 1 for success and 0 for failure, for example
if the supplied session ID length exceeds B<SSL_MAX_SSL_SESSION_ID_LENGTH>.
=head1 SEE ALSO
L<ssl(3)>
=head1 HISTORY
SSL_SESSION_set1_id() was first added to OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/ssl/SSL_accept.pod
View File

@@ -18,7 +18,7 @@ B<ssl> by setting an underlying B<BIO>.
=head1 NOTES
The behaviour of SSL_accept() depends on the underlying BIO.
The behaviour of SSL_accept() depends on the underlying BIO.
If the underlying BIO is B<blocking>, SSL_accept() will only return once the
handshake has been finished or an error occurred.
@@ -64,10 +64,19 @@ to find out the reason.
=head1 SEE ALSO
L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>,
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
L<SSL_do_handshake(3)|SSL_do_handshake(3)>,
L<SSL_CTX_new(3)|SSL_CTX_new(3)>
L<SSL_get_error(3)>, L<SSL_connect(3)>,
L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>,
L<SSL_set_connect_state(3)>,
L<SSL_do_handshake(3)>,
L<SSL_CTX_new(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/ssl/SSL_alert_type_string.pod
View File

@@ -217,7 +217,7 @@ point. This message is always a warning.
=item "UP"/"unknown PSK identity"
Sent by the server to indicate that it does not recognize a PSK
identity or an SRP identity.
identity or an SRP identity.
=item "UK"/"unknown"
@@ -228,6 +228,15 @@ Probably B<value> does not contain a correct alert message.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>
L<ssl(3)>, L<SSL_CTX_set_info_callback(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/ssl/SSL_check_chain.pod
View File

@@ -79,7 +79,16 @@ for earlier versions of TLS or DTLS.
=head1 SEE ALSO
L<SSL_CTX_set_cert_cb(3)|SSL_CTX_set_cert_cb(3)>,
L<ssl(3)|ssl(3)>
L<SSL_CTX_set_cert_cb(3)>,
L<ssl(3)>
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

35
doc/ssl/SSL_clear.pod
View File

@@ -21,8 +21,8 @@ SSL_clear is used to prepare an SSL object for a new connection. While all
settings are kept, a side effect is the handling of the current SSL session.
If a session is still B<open>, it is considered bad and will be removed
from the session cache, as required by RFC2246. A session is considered open,
if L<SSL_shutdown(3)|SSL_shutdown(3)> was not called for the connection
or at least L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> was used to
if L<SSL_shutdown(3)> was not called for the connection
or at least L<SSL_set_shutdown(3)> was used to
set the SSL_SENT_SHUTDOWN state.
If a session was closed cleanly, the session object will be kept and all
@@ -30,8 +30,8 @@ settings corresponding. This explicitly means, that e.g. the special method
used during the session will be kept for the next handshake. So if the
session was a TLSv1 session, a SSL client object will use a TLSv1 client
method for the next handshake and a SSL server object will use a TLSv1
server method, even if SSLv23_*_methods were chosen on startup. This
will might lead to connection failures (see L<SSL_new(3)|SSL_new(3)>)
server method, even if TLS_*_methods were chosen on startup. This
will might lead to connection failures (see L<SSL_new(3)>)
for a description of the method's properties.
=head1 WARNINGS
@@ -42,12 +42,12 @@ reset operation however keeps several settings of the last sessions
handshake). It only makes sense for a new connection with the exact
same peer that shares these settings, and may fail if that peer
changes its settings between connections. Use the sequence
L<SSL_get_session(3)|SSL_get_session(3)>;
L<SSL_new(3)|SSL_new(3)>;
L<SSL_set_session(3)|SSL_set_session(3)>;
L<SSL_free(3)|SSL_free(3)>
L<SSL_get_session(3)>;
L<SSL_new(3)>;
L<SSL_set_session(3)>;
L<SSL_free(3)>
instead to avoid such failures
(or simply L<SSL_free(3)|SSL_free(3)>; L<SSL_new(3)|SSL_new(3)>
(or simply L<SSL_free(3)>; L<SSL_new(3)>
if session reuse is not desired).
=head1 RETURN VALUES
@@ -67,9 +67,18 @@ The SSL_clear() operation was successful.
=back
L<SSL_new(3)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>,
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>
L<SSL_new(3)>, L<SSL_free(3)>,
L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
L<SSL_CTX_set_options(3)>, L<ssl(3)>,
L<SSL_CTX_set_client_cert_cb(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/ssl/SSL_connect.pod
View File

@@ -18,7 +18,7 @@ underlying B<BIO>.
=head1 NOTES
The behaviour of SSL_connect() depends on the underlying BIO.
The behaviour of SSL_connect() depends on the underlying BIO.
If the underlying BIO is B<blocking>, SSL_connect() will only return once the
handshake has been finished or an error occurred.
@@ -64,10 +64,19 @@ 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_set_connect_state(3)|SSL_set_connect_state(3)>,
L<SSL_do_handshake(3)|SSL_do_handshake(3)>,
L<SSL_CTX_new(3)|SSL_CTX_new(3)>
L<SSL_get_error(3)>, L<SSL_accept(3)>,
L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>,
L<SSL_set_connect_state(3)>,
L<SSL_do_handshake(3)>,
L<SSL_CTX_new(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

19
doc/ssl/SSL_do_handshake.pod
View File

@@ -15,8 +15,8 @@ SSL_do_handshake - perform a TLS/SSL handshake
SSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the
connection is in client mode, the handshake will be started. The handshake
routines may have to be explicitly set in advance using either
L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or
L<SSL_set_accept_state(3)|SSL_set_accept_state(3)>.
L<SSL_set_connect_state(3)> or
L<SSL_set_accept_state(3)>.
=head1 NOTES
@@ -65,8 +65,17 @@ to find out the reason.
=head1 SEE ALSO
L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>,
L<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
L<SSL_get_error(3)>, L<SSL_connect(3)>,
L<SSL_accept(3)>, L<ssl(3)>, L<bio(3)>,
L<SSL_set_connect_state(3)>
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

52
doc/ssl/SSL_CTX_set_custom_cli_ext.pod → doc/ssl/SSL_extension_supported.pod
View File

@@ -2,48 +2,51 @@
=head1 NAME
SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext - custom TLS extension handling
SSL_extension_supported,
SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext,
custom_ext_add_cb, custom_ext_free_cb, custom_ext_parse_cb
- custom TLS extension handling
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
custom_ext_add_cb add_cb,
custom_ext_free_cb free_cb, void *add_arg,
custom_ext_parse_cb parse_cb,
void *parse_arg);
custom_ext_add_cb add_cb,
custom_ext_free_cb free_cb, void *add_arg,
custom_ext_parse_cb parse_cb,
void *parse_arg);
int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
custom_ext_add_cb add_cb,
custom_ext_free_cb free_cb, void *add_arg,
custom_ext_parse_cb parse_cb,
void *parse_arg);
custom_ext_add_cb add_cb,
custom_ext_free_cb free_cb, void *add_arg,
custom_ext_parse_cb parse_cb,
void *parse_arg);
int SSL_extension_supported(unsigned int ext_type);
typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type,
const unsigned char **out,
size_t *outlen, int *al,
void *add_arg);
const unsigned char **out,
size_t *outlen, int *al,
void *add_arg);
typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type,
const unsigned char *out,
void *add_arg);
const unsigned char *out,
void *add_arg);
typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type,
const unsigned char *in,
size_t inlen, int *al,
void *parse_arg);
const unsigned char *in,
size_t inlen, int *al,
void *parse_arg);
=head1 DESCRIPTION
SSL_CTX_add_client_custom_ext() adds a custom extension for a TLS client
SSL_CTX_add_client_custom_ext() adds a custom extension for a TLS client
with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and
B<parse_cb>.
SSL_CTX_add_server_custom_ext() adds a custom extension for a TLS server
SSL_CTX_add_server_custom_ext() adds a custom extension for a TLS server
with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and
B<parse_cb>.
@@ -55,7 +58,7 @@ internally by OpenSSL and 0 otherwise.
=head1 EXTENSION CALLBACKS
The callback B<add_cb> is called to send custom extension data to be
The callback B<add_cb> is called to send custom extension data to be
included in ClientHello for TLS clients or ServerHello for servers. The
B<ext_type> parameter is set to the extension type which will be added and
B<add_arg> to the value set when the extension handler was added.
@@ -130,4 +133,13 @@ extension type handled internally by OpenSSL or if an internal error occurs
SSL_extension_supported() returns 1 if the extension B<ext_type> is handled
internally by OpenSSL and 0 otherwise.
=head1 COPYRIGHT
Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

20
doc/ssl/SSL_free.pod
View File

@@ -15,6 +15,7 @@ SSL_free - free an allocated SSL structure
SSL_free() decrements the reference count of B<ssl>, and removes the SSL
structure pointed to by B<ssl> and frees up the allocated memory if the
reference count has reached 0.
If B<ssl> is NULL nothing is done.
=head1 NOTES
@@ -28,8 +29,8 @@ failure.
The ssl session has reference counts from two users: the SSL object, for
which the reference count is removed by SSL_free() and the internal
session cache. If the session is considered bad, because
L<SSL_shutdown(3)|SSL_shutdown(3)> was not called for the connection
and L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> was not used to set the
L<SSL_shutdown(3)> was not called for the connection
and L<SSL_set_shutdown(3)> was not used to set the
SSL_SENT_SHUTDOWN state, the session will also be removed
from the session cache as required by RFC2246.
@@ -37,8 +38,17 @@ from the session cache as required by RFC2246.
SSL_free() does not provide diagnostic information.
L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
L<ssl(3)|ssl(3)>
L<SSL_new(3)>, L<SSL_clear(3)>,
L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
L<ssl(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

45
doc/ssl/SSL_get0_peer_scts.pod Normal file
View File

@@ -0,0 +1,45 @@
=pod
=head1 NAME
SSL_get0_peer_scts - get SCTs received
=head1 SYNOPSIS
#include <openssl/ssl.h>
const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s);
=head1 DESCRIPTION
SSL_get0_peer_scts() returns the signed certificate timestamps (SCTs) that have
been received. If this is the first time that this function has been called for
a given B<SSL> instance, it will examine the TLS extensions, OCSP response and
the peer's certificate for SCTs. Future calls will return the same SCTs.
=head1 RESTRICTIONS
If no Certificate Transparency validation callback has been set (using
B<SSL_CTX_set_ct_validation_callback> or B<SSL_set_ct_validation_callback>),
this function is not guaranteed to return all of the SCTs that the peer is
capable of sending.
=head1 RETURN VALUES
SSL_get0_peer_scts() returns a list of SCTs found, or NULL if an error occurs.
=head1 SEE ALSO
L<ssl(3)>,
L<SSL_CTX_set_ct_validation_callback(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/ssl/SSL_get_SSL_CTX.pod
View File

@@ -13,7 +13,7 @@ SSL_get_SSL_CTX - get the SSL_CTX from which an SSL is created
=head1 DESCRIPTION
SSL_get_SSL_CTX() returns a pointer to the SSL_CTX object, from which
B<ssl> was created with L<SSL_new(3)|SSL_new(3)>.
B<ssl> was created with L<SSL_new(3)>.
=head1 RETURN VALUES
@@ -21,6 +21,15 @@ The pointer to the SSL_CTX object is returned.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>
L<ssl(3)>, L<SSL_new(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

88
doc/ssl/SSL_get_all_async_fds.pod Normal file
View File

@@ -0,0 +1,88 @@
=pod
=head1 NAME
SSL_waiting_for_async,
SSL_get_all_async_fds,
SSL_get_changed_async_fds
- manage asynchronous operations
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/async.h>
#include <openssl/ssl.h>
int SSL_waiting_for_async(SSL *s);
int SSL_get_all_async_fds(SSL *s, OSSL_ASYNC_FD *fd, size_t *numfds);
int SSL_get_changed_async_fds(SSL *s, OSSL_ASYNC_FD *addfd, size_t *numaddfds,
OSSL_ASYNC_FD *delfd, size_t *numdelfds);
=head1 DESCRIPTION
SSL_waiting_for_async() determines whether an SSL connection is currently
waiting for asynchronous operations to complete (see the SSL_MODE_ASYNC mode in
L<SSL_CTX_set_mode(3)>).
SSL_get_all_async_fds() returns a list of file descriptor which can be used in a
call to select() or poll() to determine whether the current asynchronous
operation has completed or not. A completed operation will result in data
appearing as "read ready" on the file descriptor (no actual data should be read
from the file descriptor). This function should only be called if the SSL object
is currently waiting for asynchronous work to complete (i.e.
SSL_ERROR_WANT_ASYNC has been received - see L<SSL_get_error(3)>). Typically the
list will only contain one file descriptor. However if multiple asynchronous
capable engines are in use then more than one is possible. The number of file
descriptors returned is stored in B<*numfds> and the file descriptors themselves
are in B<*fds>. The B<fds> parameter may be NULL in which case no file
descriptors are returned but B<*numfds> is still populated. It is the callers
responsibility to ensure sufficient memory is allocated at B<*fds> so typically
this function is called twice (once with a NULL B<fds> parameter and once
without).
SSL_get_changed_async_fds() returns a list of the asynchronous file descriptors
that have been added and a list that have been deleted since the last
SSL_ERROR_WANT_ASYNC was received (or since the SSL object was created if no
SSL_ERROR_WANT_ASYNC has been received). Similar to SSL_get_all_async_fds() it
is the callers responsibility to ensure that B<*addfd> and B<*delfd> have
sufficient memory allocated, although they may be NULL. The number of added fds
and the number of deleted fds are stored in B<*numaddfds> and B<*numdelfds>
respectively.
=head1 RETURN VALUES
SSL_waiting_for_async() will return 1 if the current SSL operation is waiting
for an async operation to complete and 0 otherwise.
SSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or
0 on error.
=head1 NOTES
On Windows platforms the openssl/async.h header is dependent on some
of the types customarily made available by including windows.h. The
application developer is likely to require control over when the latter
is included, commonly as one of the first included headers. Therefore
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
=head1 SEE ALSO
L<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)>
=head1 HISTORY
SSL_waiting_for_async(), SSL_get_all_async_fds() and SSL_get_changed_async_fds()
were first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

52
doc/ssl/SSL_get_ciphers.pod
View File

@@ -2,13 +2,18 @@
=head1 NAME
SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs
SSL_get1_supported_ciphers, SSL_get_client_ciphers,
SSL_get_ciphers, SSL_CTX_get_ciphers, SSL_get_cipher_list
- get list of available SSL_CIPHERs
=head1 SYNOPSIS
#include <openssl/ssl.h>
STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl);
STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx);
STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s);
STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl);
const char *SSL_get_cipher_list(const SSL *ssl, int priority);
=head1 DESCRIPTION
@@ -17,6 +22,25 @@ SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>,
sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL
is returned.
SSL_CTX_get_ciphers() returns the stack of available SSL_CIPHERs for B<ctx>.
SSL_get1_supported_ciphers() returns the stack of enabled SSL_CIPHERs for
B<ssl>, sorted by preference.
The list depends on settings like the cipher list, the supported protocol
versions, the security level, and the enabled signature algorithms.
SRP and PSK ciphers are only enabled if the appropriate callbacks or settings
have been applied.
This is the list that will be sent by the client to the server.
The list supported by the server might include more ciphers in case there is a
hole in the list of supported protocols.
The server will also not use ciphers from this list depending on the
configured certificates and DH parameters.
If B<ssl> is NULL or no ciphers are available, NULL is returned.
SSL_get_client_ciphers() returns the stack of available SSL_CIPHERs matching the
list received from the client on B<ssl>. If B<ssl> is NULL, no ciphers are
available, or B<ssl> is not operating in server mode, NULL is returned.
SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER
listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are
available, or there are less ciphers than B<priority> available, NULL
@@ -24,19 +48,37 @@ is returned.
=head1 NOTES
The details of the ciphers obtained by SSL_get_ciphers() can be obtained using
the L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> family of functions.
The details of the ciphers obtained by SSL_get_ciphers(), SSL_CTX_get_ciphers()
SSL_get1_supported_ciphers() and SSL_get_client_ciphers() can be obtained using
the L<SSL_CIPHER_get_name(3)> family of functions.
Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the
sorted list of available ciphers, until NULL is returned.
Note: SSL_get_ciphers(), SSL_CTX_get_ciphers() and SSL_get_client_ciphers()
return a pointer to an internal cipher stack, which will be freed later on when
the SSL or SSL_SESSION object is freed. Therefore, the calling code B<MUST NOT>
free the return value itself.
The stack returned by SSL_get1_supported_ciphers() should be freed using
sk_SSL_CIPHER_free().
=head1 RETURN VALUES
See DESCRIPTION
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>
L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>,
L<SSL_CIPHER_get_name(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/ssl/SSL_get_client_CA_list.pod
View File

@@ -9,16 +9,16 @@ SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs
#include <openssl/ssl.h>
STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const 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)>.
B<ctx> using L<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
L<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.
@@ -46,8 +46,17 @@ the server did not send a list of CAs (client mode).
=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_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>
L<ssl(3)>,
L<SSL_CTX_set_client_CA_list(3)>,
L<SSL_CTX_set_client_cert_cb(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

88
doc/ssl/SSL_get_client_random.pod Normal file
View File

@@ -0,0 +1,88 @@
=pod
=head1 NAME
SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key - retrieve internal TLS/SSL random values and master key
=head1 SYNOPSIS
#include <openssl/ssl.h>
size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen);
size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen);
size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, unsigned char *out, size_t outlen);
=head1 DESCRIPTION
SSL_get_client_random() extracts the random value sent from the client
to the server during the initial SSL/TLS handshake. It copies as many
bytes as it can of this value into the buffer provided in B<out>,
which must have at least B<outlen> bytes available. It returns the
total number of bytes that were actually copied. If B<outlen> is
zero, SSL_get_client_random() copies nothing, and returns the
total size of the client_random value.
SSL_get_server_random() behaves the same, but extracts the random value
sent from the server to the client during the initial SSL/TLS handshake.
SSL_SESSION_get_master_key() behaves the same, but extracts the master
secret used to guarantee the security of the SSL/TLS session. This one
can be dangerous if misused; see NOTES below.
=head1 NOTES
You probably shouldn't use these functions.
These functions expose internal values from the TLS handshake, for
use in low-level protocols. You probably should not use them, unless
you are implementing something that needs access to the internal protocol
details.
Despite the names of SSL_get_client_random() and SSL_get_server_random(), they
ARE NOT random number generators. Instead, they return the mostly-random values that
were already generated and used in the TLS protocol. Using them
in place of RAND_bytes() would be grossly foolish.
The security of your TLS session depends on keeping the master key secret:
do not expose it, or any information about it, to anybody.
If you need to calculate another secret value that depends on the master
secret, you should probably use SSL_export_keying_material() instead, and
forget that you ever saw these functions.
In current versions of the TLS protocols, the length of client_random
(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for
other outlen arguments to the SSL_get_*_random() functions is provided
in case of the unlikely event that a future version or variant of TLS
uses some other length there.
Finally, though the "client_random" and "server_random" values are called
"random", many TLS implementations will generate four bytes of those
values based on their view of the current time.
=head1 RETURN VALUES
If B<outlen> is greater than 0, these functions return the number of bytes
actually copied, which will be less than or equal to B<outlen>.
If B<outlen> is 0, these functions return the maximum number
of bytes they would copy--that is, the length of the underlying field.
=head1 SEE ALSO
L<ssl(3)>,
L<RAND_bytes(3)>,
L<SSL_export_keying_material(3)>
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

42
doc/ssl/SSL_get_current_cipher.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name,
SSL_get_current_cipher, SSL_get_cipher_name, SSL_get_cipher,
SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection
=head1 SYNOPSIS
@@ -10,34 +10,46 @@ SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection
#include <openssl/ssl.h>
SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl);
#define SSL_get_cipher(s) \
SSL_CIPHER_get_name(SSL_get_current_cipher(s))
#define SSL_get_cipher_name(s) \
SSL_CIPHER_get_name(SSL_get_current_cipher(s))
#define SSL_get_cipher_bits(s,np) \
SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np)
#define SSL_get_cipher_version(s) \
SSL_CIPHER_get_version(SSL_get_current_cipher(s))
const char *SSL_get_cipher_name(const SSL *s);
const char *SSL_get_cipher(const SSL *s);
int SSL_get_cipher_bits(const SSL *s, int *np) \
const char *SSL_get_cipher_version(const SSL *s);
=head1 DESCRIPTION
SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing
the description of the actually used cipher of a connection established with
the B<ssl> object.
See L<SSL_CIPHER_get_name(3)> for more details.
SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the
name of the currently used cipher. SSL_get_cipher_bits() is a
macro to obtain the number of secret/algorithm bits used and
SSL_get_cipher_name() obtains the
name of the currently used cipher.
SSL_get_cipher() is identical to SSL_get_cipher_name().
SSL_get_cipher_bits() is a
macro to obtain the number of secret/algorithm bits used and
SSL_get_cipher_version() returns the protocol name.
See L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> for more details.
=head1 RETURN VALUES
SSL_get_current_cipher() returns the cipher actually used or NULL, when
SSL_get_current_cipher() returns the cipher actually used, or NULL if
no session has been established.
=head1 NOTES
These are implemented as macros.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>
L<ssl(3)>, L<SSL_CIPHER_get_name(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

23
doc/ssl/SSL_get_default_timeout.pod
View File

@@ -20,11 +20,11 @@ SSL_SESSION objects negotiated for the protocol valid for B<ssl>.
Whenever a new session is negotiated, it is assigned a timeout value,
after which it will not be accepted for session reuse. If the timeout
value was not explicitly set using
L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, the hardcoded default
L<SSL_CTX_set_timeout(3)>, the hardcoded default
timeout for the protocol will be used.
SSL_get_default_timeout() return this hardcoded value, which is 300 seconds
for all currently supported protocols (SSLv2, SSLv3, and TLSv1).
for all currently supported protocols.
=head1 RETURN VALUES
@@ -32,10 +32,19 @@ See description.
=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)>,
L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>
L<ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)>,
L<SSL_SESSION_get_time(3)>,
L<SSL_CTX_flush_sessions(3)>,
L<SSL_get_default_timeout(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

35
doc/ssl/SSL_get_error.pod
View File

@@ -88,6 +88,28 @@ SSL_CTX_set_client_cert_cb() has asked to be called again.
The TLS/SSL I/O function should be called again later.
Details depend on the application.
=item SSL_ERROR_WANT_ASYNC
The operation did not complete because an asynchronous engine is still
processing data. This will only occur if the mode has been set to SSL_MODE_ASYNC
using L<SSL_CTX_set_mode(3)> or L<SSL_set_mode(3)> and an asynchronous capable
engine is being used. An application can determine whether the engine has
completed its processing using select() or poll() on the asynchronous wait file
descriptor. This file descriptor is available by calling
L<SSL_get_all_async_fds(3)> or L<SSL_get_changed_async_fds(3)>. The TLS/SSL I/O
function should be called again later. The function B<must> be called from the
same thread that the original call was made from.
=item SSL_ERROR_WANT_ASYNC_JOB
The asynchronous job could not be started because there were no async jobs
available in the pool (see ASYNC_init_thread(3)). This will only occur if the
mode has been set to SSL_MODE_ASYNC using L<SSL_CTX_set_mode(3)> or
L<SSL_set_mode(3)> and a maximum limit has been set on the async job pool
through a call to L<ASYNC_init_thread(3)>. The application should retry the
operation after a currently executing asynchronous operation for the current
thread has completed.
=item SSL_ERROR_SYSCALL
Some non-recoverable I/O error occurred.
@@ -103,10 +125,19 @@ OpenSSL error queue contains more information on the error.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<err(3)|err(3)>
L<ssl(3)>, L<err(3)>
=head1 HISTORY
SSL_get_error() was added in SSLeay 0.8.
SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

61
doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod
View File

@@ -1,61 +0,0 @@
=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
View File

@@ -1,59 +0,0 @@
=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(const 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(3)|RSA_get_ex_new_index(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

40
doc/ssl/SSL_get_extms_support.pod Normal file
View File

@@ -0,0 +1,40 @@
=pod
=head1 NAME
SSL_get_extms_support - extended master secret support
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_get_extms_support(SSL *ssl);
=head1 DESCRIPTION
SSL_get_extms_support() indicates whether the current session used extended
master secret.
This function is implemented as a macro.
=head1 RETURN VALUES
SSL_get_extms_support() returns 1 if the current session used extended
master secret, 0 if it did not and -1 if a handshake is currently in
progress i.e. it is not possible to determine if extended master secret
was used.
=head1 SEE ALSO
L<ssl(3)>
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/ssl/SSL_get_fd.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
SSL_get_fd - get file descriptor linked to an SSL object
SSL_get_fd, SSL_get_rfd, SSL_get_wfd - get file descriptor linked to an SSL object
=head1 SYNOPSIS
@@ -39,6 +39,15 @@ The file descriptor linked to B<ssl>.
=head1 SEE ALSO
L<SSL_set_fd(3)|SSL_set_fd(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
L<SSL_set_fd(3)>, L<ssl(3)> , L<bio(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

Some files were not shown because too many files have changed in this diff Show More