abc/GmSSL
1
0
Fork 0
mirror of https://github.com/guanzhi/GmSSL.git synced 2026-08-09 15:33:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

Revert "quantum init"

Browse Source 
This reverts commit 53af3b51ae.
This commit is contained in:
Simon
2018-01-04 14:03:27 +08:00
parent 53af3b51ae
commit 38395c5c80
2361 changed files with 144430 additions and 387427 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
doc/ssl/SSL_CIPHER_get_name.pod
View File

@@ -1,8 +1,14 @@
=pod
=encoding utf8
=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 +18,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 +79,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

54
doc/ssl/SSL_COMP_add_compression_method.pod
View File

@@ -1,16 +1,27 @@
=pod
=encoding utf8
=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 +30,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 +90,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

22
doc/ssl/SSL_CONF_CTX_new.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CONF_CTX_new, SSL_CONF_CTX_free - SSL configuration allocation functions
@@ -17,6 +19,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 +30,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

23
doc/ssl/SSL_CONF_CTX_set1_prefix.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CONF_CTX_set1_prefix - Set configuration context command prefix
@@ -20,7 +22,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 +38,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

28
doc/ssl/SSL_CONF_CTX_set_flags.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CONF_CTX_set_flags, SSL_CONF_CTX_clear_flags - Set of clear SSL configuration context flags
@@ -40,6 +42,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 +64,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

21
doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CONF_CTX_set_ssl_ctx, SSL_CONF_CTX_set_ssl - set context to configure
@@ -34,14 +36,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

198
doc/ssl/SSL_CONF_cmd.pod
View File

@@ -1,7 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_CONF_cmd_value_type, SSL_CONF_finish,
SSL_CONF_cmd - send configuration command
=head1 SYNOPSIS
@@ -101,7 +104,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 +112,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 +177,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 +209,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 +265,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 +354,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 +401,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 +422,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 +458,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 +523,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

23
doc/ssl/SSL_CONF_cmd_argv.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_CONF_cmd_argv - SSL configuration command line processing.
SSL_CONF_cmd_argv - SSL configuration command line processing
=head1 SYNOPSIS
@@ -29,14 +31,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

14
doc/ssl/SSL_CTX_add1_chain_cert.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert,
@@ -138,13 +140,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

41
doc/ssl/SSL_CTX_add_extra_chain_cert.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_add_extra_chain_cert, SSL_CTX_clear_extra_chain_certs - add or clear
@@ -30,7 +32,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 +55,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

23
doc/ssl/SSL_CTX_add_session.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache
@@ -19,10 +21,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 +61,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

13
doc/ssl/SSL_CTX_ctrl.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl - internal handling functions for SSL_CTX and SSL objects
@@ -29,6 +31,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

27
doc/ssl/SSL_CTX_flush_sessions.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions
@@ -25,8 +27,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 +37,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

20
doc/ssl/SSL_CTX_free.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_free - free an allocated SSL_CTX object
@@ -13,13 +15,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 +38,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

13
doc/ssl/SSL_CTX_get0_param.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param -
@@ -46,10 +48,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

13
doc/ssl/SSL_CTX_get_verify_mode.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters
@@ -45,6 +47,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

63
doc/ssl/SSL_CTX_load_verify_locations.pod
View File

@@ -1,9 +1,12 @@
=pod
=encoding utf8
=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 +15,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 +84,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 +121,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 +137,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

200
doc/ssl/SSL_CTX_new.pod
View File

@@ -1,139 +1,134 @@
=pod
=encoding utf8
=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 +141,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 +187,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

19
doc/ssl/SSL_CTX_sess_number.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full - obtain session cache statistics
@@ -45,7 +47,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 +71,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

21
doc/ssl/SSL_CTX_sess_set_cache_size.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size
@@ -29,7 +31,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 +47,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

41
doc/ssl/SSL_CTX_sess_set_get_cb.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching
@@ -9,20 +11,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 +39,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 +52,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 +65,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 +76,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

23
doc/ssl/SSL_CTX_sessions.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_sessions - access internal session cache
@@ -18,17 +20,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

45
doc/ssl/SSL_CTX_set1_curves.pod
View File

@@ -1,10 +1,11 @@
=pod
=encoding utf8
=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 +20,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 +36,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 +50,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 +58,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 +74,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

39
doc/ssl/SSL_CTX_set1_verify_cert_store.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set0_verify_cert_store, SSL_CTX_set1_verify_cert_store,
@@ -54,9 +56,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 +74,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

18
doc/ssl/SSL_CTX_set_alpn_select_cb.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
@@ -11,9 +13,9 @@ protocol negotiation (ALPN)
#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,
@@ -44,7 +46,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
@@ -123,4 +126,13 @@ ALPN protocol not selected.
L<ssl(3)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
L<SSL_CTX_set_tlsext_servername_arg(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_cert_cb.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function
@@ -15,10 +17,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 +29,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 +45,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 +62,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

25
doc/ssl/SSL_CTX_set_cert_store.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_cert_store, SSL_CTX_get_cert_store - manipulate X509 certificate verification storage
@@ -28,17 +30,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 +48,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 +59,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

35
doc/ssl/SSL_CTX_set_cert_verify_callback.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure
@@ -8,13 +10,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 +28,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 +37,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 +56,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

44
doc/ssl/SSL_CTX_set_cipher_list.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs
@@ -15,7 +17,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 +33,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 +59,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

27
doc/ssl/SSL_CTX_set_client_CA_list.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
@@ -9,7 +11,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 +44,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 +84,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

35
doc/ssl/SSL_CTX_set_client_cert_cb.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function
@@ -14,11 +16,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 +31,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 +44,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 +58,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 +74,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 +82,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

133
doc/ssl/SSL_CTX_set_custom_cli_ext.pod
View File

@@ -1,133 +0,0 @@
=pod
=head1 NAME
SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext - 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);
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);
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);
typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type,
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);
=head1 DESCRIPTION
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
with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and
B<parse_cb>.
In both cases the extension type must not be handled by OpenSSL internally
or an error occurs.
SSL_extension_supported() returns 1 if the extension B<ext_type> is handled
internally by OpenSSL and 0 otherwise.
=head1 EXTENSION CALLBACKS
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.
If the application wishes to include the extension B<ext_type> it should
set B<*out> to the extension data, set B<*outlen> to the length of the
extension data and return 1.
If the B<add_cb> does not wish to include the extension it must return 0.
If B<add_cb> returns -1 a fatal handshake error occurs using the TLS
alert value specified in B<*al>.
For clients (but not servers) if B<add_cb> is set to NULL a zero length
extension is added for B<ext_type>.
For clients every registered B<add_cb> is always called to see if the
application wishes to add an extension to ClientHello.
For servers every registered B<add_cb> is called once if and only if the
corresponding extension was received in ClientHello to see if the application
wishes to add the extension to ServerHello. That is, if no corresponding extension
was received in ClientHello then B<add_cb> will not be called.
If an extension is added (that is B<add_cb> returns 1) B<free_cb> is called
(if it is set) with the value of B<out> set by the add callback. It can be
used to free up any dynamic extension data set by B<add_cb>. Since B<out> is
constant (to permit use of constant data in B<add_cb>) applications may need to
cast away const to free the data.
The callback B<parse_cb> receives data for TLS extensions. For TLS clients
the extension data will come from ServerHello and for TLS servers it will
come from ClientHello.
The extension data consists of B<inlen> bytes in the buffer B<in> for the
extension B<extension_type>.
If the B<parse_cb> considers the extension data acceptable it must return
1. If it returns 0 or a negative value a fatal handshake error occurs
using the TLS alert value specified in B<*al>.
The buffer B<in> is a temporary internal buffer which will not be valid after
the callback returns.
=head1 NOTES
The B<add_arg> and B<parse_arg> parameters can be set to arbitrary values
which will be passed to the corresponding callbacks. They can, for example,
be used to store the extension data received in a convenient structure or
pass the extension data to be added or freed when adding extensions.
The B<ext_type> parameter corresponds to the B<extension_type> field of
RFC5246 et al. It is B<not> a NID.
If the same custom extension type is received multiple times a fatal
B<decode_error> alert is sent and the handshake aborts. If a custom extension
is received in ServerHello which was not sent in ClientHello a fatal
B<unsupported_extension> alert is sent and the handshake is aborted. The
ServerHello B<add_cb> callback is only called if the corresponding extension
was received in ClientHello. This is compliant with the TLS specifications.
This behaviour ensures that each callback is called at most once and that
an application can never send unsolicited extensions.
=head1 RETURN VALUES
SSL_CTX_add_client_custom_ext() and SSL_CTX_add_server_custom_ext() return 1 for
success and 0 for failure. A failure can occur if an attempt is made to
add the same B<ext_type> more than once, if an attempt is made to use an
extension type handled internally by OpenSSL or if an internal error occurs
(for example a memory allocation failure).
SSL_extension_supported() returns 1 if the extension B<ext_type> is handled
internally by OpenSSL and 0 otherwise.
=cut

79
doc/ssl/SSL_CTX_set_default_passwd_cb.pod
View File

@@ -1,8 +1,14 @@
=pod
=encoding utf8
=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 +16,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 +76,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

79
doc/ssl/SSL_CTX_set_generate_session_id.pod
View File

@@ -1,8 +1,12 @@
=pod
=encoding utf8
=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 +18,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 +36,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 +54,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 +81,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 +94,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 +127,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

83
doc/ssl/SSL_CTX_set_info_callback.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections
@@ -20,7 +22,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 +95,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 +112,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

21
doc/ssl/SSL_CTX_set_max_cert_list.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=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 +21,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 +43,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 +69,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

29
doc/ssl/SSL_CTX_set_mode.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode
@@ -52,7 +54,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 +66,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 +81,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 +98,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

18
doc/ssl/SSL_CTX_set_msg_callback.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=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 +27,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 +91,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

127
doc/ssl/SSL_CTX_set_options.pod
View File

@@ -1,8 +1,12 @@
=pod
=encoding utf8
=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 +25,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 +42,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 +64,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 +85,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 +127,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 +144,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 +155,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 +195,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 +224,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 +272,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,33 +1,6 @@
=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
=encoding utf8
=head1 NAME
@@ -38,13 +11,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 +32,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 +51,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

31
doc/ssl/SSL_CTX_set_quiet_shutdown.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown, SSL_get_quiet_shutdown - manipulate shutdown behaviour
@@ -18,14 +20,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 +35,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 +58,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

37
doc/ssl/SSL_CTX_set_read_ahead.pod
View File

@@ -1,22 +1,24 @@
=pod
=encoding utf8
=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 +29,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 +37,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

42
doc/ssl/SSL_CTX_set_session_cache_mode.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching
@@ -26,7 +28,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 +39,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 +55,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 +74,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 +96,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 +121,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

13
doc/ssl/SSL_CTX_set_session_id_context.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only)
@@ -78,6 +80,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

25
doc/ssl/SSL_CTX_set_ssl_version.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method
@@ -17,8 +19,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 +31,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 +56,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

29
doc/ssl/SSL_CTX_set_timeout.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching
@@ -30,15 +32,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 +52,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

62
doc/ssl/SSL_CTX_set_tlsext_servername_callback.pod
View File

@@ -1,62 +0,0 @@
=pod
=head1 NAME
SSL_CTX_set_tlsext_servername_callback, SSL_CTX_set_tlsext_servername_arg,
SSL_get_servername_type, SSL_get_servername - handle server name indication
(SNI)
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx,
int (*cb)(SSL *, int *, void *));
long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg);
const char *SSL_get_servername(const SSL *s, const int type);
int SSL_get_servername_type(const SSL *s);
=head1 DESCRIPTION
SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb>
used by a server to perform any actions or configuration required based on
the servername extension received in the incoming connection. When B<cb>
is NULL, SNI is not used. The B<arg> value is a pointer which is passed to
the application callback.
SSL_CTX_set_tlsext_servername_arg() sets a context-specific argument to be
passed into the callback for this B<SSL_CTX>.
SSL_get_servername() returns a servername extension value of the specified
type if provided in the Client Hello or NULL.
SSL_get_servername_type() returns the servername type or -1 if no servername
is present. Currently the only supported type (defined in RFC3546) is
B<TLSEXT_NAMETYPE_host_name>.
=head1 NOTES
The ALPN and SNI callbacks are both executed during Client Hello processing.
The servername callback is executed first, followed by the ALPN callback.
=head1 RETURN VALUES
SSL_CTX_set_tlsext_servername_callback() and
SSL_CTX_set_tlsext_servername_arg() both always return 1 indicating success.
=head1 SEE ALSO
L<ssl(7)>, L<SSL_CTX_set_alpn_select_cb(3)>,
L<SSL_get0_alpn_selected(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

82
doc/ssl/SSL_CTX_set_tlsext_status_cb.pod
View File

@@ -1,10 +1,20 @@
=pod
=encoding utf8
=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 +22,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 +41,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 +97,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

95
doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing
@@ -10,28 +12,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 +39,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 +78,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 +86,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 +107,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 +125,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 +135,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 +148,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 +169,7 @@ Reference Implemention:
return 2;
}
return 1;
}
}
@@ -181,15 +181,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

29
doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_set_tmp_dh - handle DH keys for ephemeral key exchange
@@ -57,18 +59,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 +106,7 @@ partly left out.)
/* Error. */
}
if (dh_2048 == NULL) {
/* Error. */
/* Error. */
}
if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) {
/* Error. */
@@ -122,9 +123,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

76
doc/ssl/SSL_CTX_set_verify.pod
View File

@@ -1,21 +1,24 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters
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);
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,7 +32,7 @@ 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)>.
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.)
@@ -52,7 +55,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,13 +92,12 @@ 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
@@ -138,7 +140,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 +151,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 +173,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<SSL_get_ex_new_index(3)>,
L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
...
typedef struct {
@@ -221,7 +218,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 +234,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 +266,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 +279,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<SSL_get_ex_new_index(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

71
doc/ssl/SSL_CTX_use_certificate.pod
View File

@@ -1,8 +1,20 @@
=pod
=encoding utf8
=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 +28,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 +54,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 +79,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 +94,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 +121,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 +145,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 +162,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,33 +1,6 @@
=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
=encoding utf8
=head1 NAME
@@ -35,7 +8,6 @@ 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 +16,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 +75,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

16
doc/ssl/SSL_CTX_use_serverinfo.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_CTX_use_serverinfo, SSL_CTX_use_serverinfo_file - use serverinfo extension
@@ -20,8 +22,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 +40,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

28
doc/ssl/SSL_SESSION_free.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_SESSION_free - free an allocated SSL_SESSION structure
@@ -15,12 +17,13 @@ SSL_SESSION_free - free an allocated 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,13 +34,13 @@ 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.
@@ -47,9 +50,18 @@ SSL_SESSION_free() does not provide diagnostic information.
=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

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

26
doc/ssl/SSL_SESSION_get_time.pod
View File

@@ -1,8 +1,13 @@
=pod
=encoding utf8
=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 +46,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 +57,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(3)>,
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

23
doc/ssl/SSL_accept.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake
@@ -18,7 +20,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 +66,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

15
doc/ssl/SSL_alert_type_string.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information
@@ -217,7 +219,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 +230,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

15
doc/ssl/SSL_check_chain.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_check_chain - check certificate chain suitability
@@ -79,7 +81,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

37
doc/ssl/SSL_clear.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_clear - reset SSL object to allow another connection
@@ -21,8 +23,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 +32,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 +44,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 +69,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

23
doc/ssl/SSL_connect.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server
@@ -18,7 +20,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 +66,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

21
doc/ssl/SSL_do_handshake.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_do_handshake - perform a TLS/SSL handshake
@@ -15,8 +17,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 +67,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

61
doc/ssl/SSL_export_keying_material.pod
View File

@@ -1,61 +0,0 @@
=pod
=head1 NAME
SSL_export_keying_material - obtain keying material for application use
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen,
const char *label, size_t llen,
const unsigned char *context,
size_t contextlen, int use_context);
=head1 DESCRIPTION
During the creation of a TLS or DTLS connection shared keying material is
established between the two endpoints. The function SSL_export_keying_material()
enables an application to use some of this keying material for its own purposes
in accordance with RFC5705.
An application may need to securely establish the context within which this
keying material will be used. For example this may include identifiers for the
application session, application algorithms or parameters, or the lifetime of
the context. The context value is left to the application but must be the same
on both sides of the communication.
For a given SSL connection B<s>, B<olen> bytes of data will be written to
B<out>. The application specific context should be supplied in the location
pointed to by B<context> and should be B<contextlen> bytes long. Provision of
a context is optional. If the context should be omitted entirely then
B<use_context> should be set to 0. Otherwise it should be any other value. If
B<use_context> is 0 then the values of B<context> and B<contextlen> are ignored.
Note that a zero length context is treated differently to no context at all, and
will result in different keying material being returned.
An application specific label should be provided in the location pointed to by
B<label> and should be B<llen> bytes long. Typically this will be a value from
the IANA Exporter Label Registry
(L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels>).
Alternatively labels beginning with "EXPERIMENTAL" are permitted by the standard
to be used without registration.
Note that this function is only defined for TLSv1.0 and above, and DTLSv1.0 and
above. Attempting to use it in SSLv3 will result in an error.
=head1 RETURN VALUES
SSL_export_keying_material() returns 0 or -1 on failure or 1 on success.
=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

22
doc/ssl/SSL_free.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_free - free an allocated SSL structure
@@ -15,6 +17,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 +31,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 +40,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

15
doc/ssl/SSL_get_SSL_CTX.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_SSL_CTX - get the SSL_CTX from which an SSL is created
@@ -13,7 +15,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 +23,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

54
doc/ssl/SSL_get_ciphers.pod
View File

@@ -1,14 +1,21 @@
=pod
=encoding utf8
=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 +24,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 +50,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

23
doc/ssl/SSL_get_client_CA_list.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs
@@ -9,16 +11,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 +48,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

44
doc/ssl/SSL_get_current_cipher.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=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 +12,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

25
doc/ssl/SSL_get_default_timeout.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_default_timeout - get default session timeout value
@@ -20,11 +22,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 +34,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

37
doc/ssl/SSL_get_error.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_error - obtain result code for TLS/SSL I/O operation
@@ -88,6 +90,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 +127,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

15
doc/ssl/SSL_get_fd.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=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 +41,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

45
doc/ssl/SSL_get_peer_cert_chain.pod
View File

@@ -1,32 +1,49 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_peer_cert_chain - get the X509 certificate chain of the peer
SSL_get_peer_cert_chain, SSL_get0_verified_chain - get the X509 certificate
chain of the peer
=head1 SYNOPSIS
#include <openssl/ssl.h>
STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl);
STACK_OF(X509) *SSL_get0_verified_chain(const SSL *ssl);
=head1 DESCRIPTION
SSL_get_peer_cert_chain() returns a pointer to STACK_OF(X509) certificates
forming the certificate chain of the peer. If called on the client side,
forming the certificate chain sent by the peer. If called on the client side,
the stack also contains the peer's certificate; if called on the server
side, the peer's certificate must be obtained separately using
L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>.
L<SSL_get_peer_certificate(3)>.
If the peer did not present a certificate, NULL is returned.
NB: SSL_get_peer_cert_chain() returns the peer chain as sent by the peer: it
only consists of certificates the peer has sent (in the order the peer
has sent them) it is B<not> a verified chain.
SSL_get0_verified_chain() returns the B<verified> certificate chain
of the peer including the peer's end entity certificate. It must be called
after a session has been successfully established. If peer verification was
not successful (as indicated by SSL_get_verify_result() not returning
X509_V_OK) the chain may be incomplete or invalid.
=head1 NOTES
The peer certificate chain is not necessarily available after reusing
a session, in which case a NULL pointer is returned.
If the session is resumed peers do not send certificates so a NULL pointer
is returned by these functions. Applications can call SSL_session_reused()
to determine whether a session is resumed.
The reference count of the STACK_OF(X509) object is not incremented.
If the corresponding session is freed, the pointer must not be used
any longer.
The reference count of each certificate in the returned STACK_OF(X509) object
is not incremented and the returned stack may be invalidated by renegotiation.
If applications wish to use any certificates in the returned chain
indefinitely they must increase the reference counts using X509_up_ref() or
obtain a copy of the whole chain with X509_chain_up_ref().
=head1 RETURN VALUES
@@ -47,6 +64,16 @@ The return value points to the certificate chain presented by the peer.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>
L<ssl(3)>, L<SSL_get_peer_certificate(3)>, L<X509_up_ref(3)>,
L<X509_chain_up_ref(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_get_peer_certificate.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_peer_certificate - get the X509 certificate of the peer
@@ -20,11 +22,11 @@ peer presented. If the peer did not present a certificate, NULL is returned.
Due to the protocol definition, a TLS/SSL server will always send a
certificate, if present. A client will only send a certificate when
explicitly requested to do so by the server (see
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>). If an anonymous cipher
L<SSL_CTX_set_verify(3)>). If an anonymous cipher
is used, no certificates are sent.
That a certificate is returned does not indicate information about the
verification state, use L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>
verification state, use L<SSL_get_verify_result(3)>
to check the verification state.
The reference count of the X509 object is incremented by one, so that it
@@ -49,7 +51,16 @@ The return value points to the certificate presented by the peer.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
L<ssl(3)>, L<SSL_get_verify_result(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

41
doc/ssl/SSL_get_psk_identity.pod
View File

@@ -1,39 +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
=encoding utf8
=head1 NAME
SSL_get_psk_identity, SSL_get_psk_identity_hint - get PSK client identity and hint
=head1 SYNOPSIS
#include <openssl/ssl.h>
@@ -60,4 +32,15 @@ no PSK identity hint was used during the connection setup.
Note that the return value is valid only during the lifetime of the
SSL object B<ssl>.
=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

15
doc/ssl/SSL_get_rbio.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_rbio - get BIO linked to an SSL object
SSL_get_rbio, SSL_get_wbio - get BIO linked to an SSL object
=head1 SYNOPSIS
@@ -35,6 +37,15 @@ The BIO linked to B<ssl>.
=head1 SEE ALSO
L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
L<SSL_set_bio(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

29
doc/ssl/SSL_get_session.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_session - retrieve TLS/SSL session data
SSL_get_session, SSL_get0_session, SSL_get1_session - retrieve TLS/SSL session data
=head1 SYNOPSIS
@@ -30,16 +32,16 @@ connection without a new handshake.
SSL_get0_session() returns a pointer to the actual session. As the
reference counter is not incremented, the pointer is only valid while
the connection is in use. If L<SSL_clear(3)|SSL_clear(3)> or
L<SSL_free(3)|SSL_free(3)> is called, the session may be removed completely
the connection is in use. If L<SSL_clear(3)> or
L<SSL_free(3)> is called, the session may be removed completely
(if considered bad), and the pointer obtained will become invalid. Even
if the session is valid, it can be removed at any time due to timeout
during L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>.
during L<SSL_CTX_flush_sessions(3)>.
If the data is to be kept, SSL_get1_session() will increment the reference
count, so that the session will not be implicitly removed by other operations
but stays in memory. In order to remove the session
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> must be explicitly called once
L<SSL_SESSION_free(3)> must be explicitly called once
to decrement the reference count again.
SSL_SESSION objects keep internal link information about the session cache
@@ -58,7 +60,7 @@ The following return values can occur:
There is no session available in B<ssl>.
=item Pointer to an SSL
=item Pointer to an SSL_SESSION
The return value points to the data of an SSL session.
@@ -66,8 +68,17 @@ The return value points to the data of an SSL session.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_free(3)|SSL_free(3)>,
L<SSL_clear(3)|SSL_clear(3)>,
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
L<ssl(3)>, L<SSL_free(3)>,
L<SSL_clear(3)>,
L<SSL_SESSION_free(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_verify_result.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_verify_result - get result of peer certificate verification
@@ -30,7 +32,7 @@ when a session is reused.
If no peer certificate was presented, the returned result code is
X509_V_OK. This is because no verification error occurred, it does however
not indicate success. SSL_get_verify_result() is only useful in connection
with L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>.
with L<SSL_get_peer_certificate(3)>.
=head1 RETURN VALUES
@@ -44,14 +46,23 @@ The verification succeeded or no peer certificate was presented.
=item Any other value
Documented in L<verify(1)|verify(1)>.
Documented in L<verify(1)>.
=back
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_set_verify_result(3)|SSL_set_verify_result(3)>,
L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>,
L<verify(1)|verify(1)>
L<ssl(3)>, L<SSL_set_verify_result(3)>,
L<SSL_get_peer_certificate(3)>,
L<verify(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

29
doc/ssl/SSL_get_version.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_get_version - get the protocol version of a connection.
SSL_get_version, SSL_is_dtls - get the protocol information of a connection
=head1 SYNOPSIS
@@ -10,21 +12,21 @@ SSL_get_version - get the protocol version of a connection.
const char *SSL_get_version(const SSL *ssl);
int SSL_is_dtls(const SSL *ssl);
=head1 DESCRIPTION
SSL_get_version() returns the name of the protocol used for the
connection B<ssl>.
SSL_is_dtls() returns one if the connection is using DTLS, zero if not.
=head1 RETURN VALUES
The following strings can be returned:
SSL_get_version() returns one of the following strings:
=over 4
=item SSLv2
The connection uses the SSLv2 protocol.
=item SSLv3
The connection uses the SSLv3 protocol.
@@ -49,6 +51,19 @@ This indicates that no version has been set (no connection established).
=head1 SEE ALSO
L<ssl(3)|ssl(3)>
L<ssl(3)>
=head1 HISTORY
SSL_is_dtls() was added in 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

46
doc/ssl/SSL_library_init.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_library_init, OpenSSL_add_ssl_algorithms, SSLeay_add_ssl_algorithms
SSL_library_init, OpenSSL_add_ssl_algorithms,
- initialize SSL library by registering algorithms
=head1 SYNOPSIS
@@ -10,48 +12,48 @@ SSL_library_init, OpenSSL_add_ssl_algorithms, SSLeay_add_ssl_algorithms
#include <openssl/ssl.h>
int SSL_library_init(void);
#define OpenSSL_add_ssl_algorithms() SSL_library_init()
#define SSLeay_add_ssl_algorithms() SSL_library_init()
int OpenSSL_add_ssl_algorithms(void);
=head1 DESCRIPTION
SSL_library_init() registers the available SSL/TLS ciphers and digests.
OpenSSL_add_ssl_algorithms() and SSLeay_add_ssl_algorithms() are synonyms
for SSL_library_init().
OpenSSL_add_ssl_algorithms() is a synonym for SSL_library_init() and is
implemented as a macro.
=head1 NOTES
SSL_library_init() must be called before any other action takes place.
SSL_library_init() is not reentrant.
SSL_library_init() is not reentrant.
=head1 WARNING
SSL_library_init() adds ciphers and digests used directly and indirectly by
SSL/TLS.
=head1 EXAMPLES
A typical TLS/SSL application will start with the library initialization,
and provide readable error messages.
SSL_load_error_strings(); /* readable error messages */
SSL_library_init(); /* initialize library */
=head1 RETURN VALUES
SSL_library_init() always returns "1", so it is safe to discard the return
value.
=head1 NOTES
OpenSSL 0.9.8o and 1.0.0a and later added SHA2 algorithms to SSL_library_init().
Applications which need to use SHA2 in earlier versions of OpenSSL should call
OpenSSL_add_all_algorithms() as well.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>,
L<RAND_add(3)|RAND_add(3)>
L<ssl(3)>,
L<RAND_add(3)>
=head1 HISTORY
The SSL_library_init() and OpenSSL_add_ssl_algorithms() functions were
deprecated in OpenSSL 1.1.0 by OPENSSL_init_ssl().
=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_load_client_CA_file.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_load_client_CA_file - load certificate names from file
@@ -20,7 +22,7 @@ a STACK_OF(X509_NAME) with the subject names found.
SSL_load_client_CA_file() reads a file of PEM formatted certificates and
extracts the X509_NAMES of the certificates found. While the name suggests
the specific usage as support function for
L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
L<SSL_CTX_set_client_CA_list(3)>,
it is not limited to CA certificates.
=head1 EXAMPLES
@@ -30,7 +32,7 @@ Load names of CAs from file and use it as a client CA list:
SSL_CTX *ctx;
STACK_OF(X509_NAME) *cert_names;
...
...
cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
if (cert_names != NULL)
SSL_CTX_set_client_CA_list(ctx, cert_names);
@@ -56,7 +58,16 @@ Pointer to the subject names of the successfully read certificates.
=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(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

33
doc/ssl/SSL_new.pod
View File

@@ -1,21 +1,29 @@
=pod
=encoding utf8
=head1 NAME
SSL_new - create a new SSL structure for a connection
SSL_new, SSL_up_ref - create a new SSL structure for a connection
=head1 SYNOPSIS
#include <openssl/ssl.h>
SSL *SSL_new(SSL_CTX *ctx);
int SSL_up_ref(SSL *s);
=head1 DESCRIPTION
SSL_new() creates a new B<SSL> structure which is needed to hold the
data for a TLS/SSL connection. The new structure inherits the settings
of the underlying context B<ctx>: connection method (SSLv2/v3/TLSv1),
options, verification settings, timeout settings.
of the underlying context B<ctx>: connection method,
options, verification settings, timeout settings. An B<SSL> structure is
reference counted. Creating an B<SSL> structure for the first time increments
the reference count. Freeing it (using SSL_free) decrements it. When the
reference count drops to zero, any memory or resources allocated to the B<SSL>
structure are freed. SSL_up_ref() increments the reference count for an
existing B<SSL> structure.
=head1 RETURN VALUES
@@ -32,13 +40,24 @@ find out the reason.
The return value points to an allocated SSL structure.
SSL_up_ref() returns 1 for success and 0 for failure.
=back
=head1 SEE ALSO
L<SSL_free(3)|SSL_free(3)>, L<SSL_clear(3)|SSL_clear(3)>,
L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>,
L<ssl(3)|ssl(3)>
L<SSL_free(3)>, L<SSL_clear(3)>,
L<SSL_CTX_set_options(3)>,
L<SSL_get_SSL_CTX(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

69
doc/ssl/SSL_pending.pod
View File

@@ -1,45 +1,70 @@
=pod
=encoding utf8
=head1 NAME
SSL_pending - obtain number of readable bytes buffered in an SSL object
SSL_pending, SSL_has_pending - check for readable bytes buffered in an
SSL object
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_pending(const SSL *ssl);
int SSL_has_pending(const SSL *s);
=head1 DESCRIPTION
SSL_pending() returns the number of bytes which are available inside
B<ssl> for immediate read.
Data is received in whole blocks known as records from the peer. A whole record
is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
read by the application via a call to L<SSL_read(3)>.
=head1 NOTES
SSL_pending() returns the number of bytes which have been processed, buffered
and are available inside B<ssl> for immediate read.
Data are received in blocks from the peer. Therefore data can be buffered
inside B<ssl> and are ready for immediate retrieval with
L<SSL_read(3)|SSL_read(3)>.
If the B<SSL> object's I<read_ahead> flag is set (see
L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current
record) may have been read containing more TLS/SSL records. This also applies to
DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
additional bytes will be buffered by OpenSSL but will remain unprocessed until
they are needed. As these bytes are still in an unprocessed state SSL_pending()
will ignore them. Therefore it is possible for no more bytes to be readable from
the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
to return 0, even though readable application data bytes are available (because
the data is in unprocessed buffered records).
SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or
unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to
return 1, and then a subsequent call to SSL_read() to return no data because the
unprocessed buffered data when processed yielded no application data (for
example this can happen during renegotiation). It is also possible in this
scenario for SSL_has_pending() to continue to return 1 even after an SSL_read()
call because the buffered and unprocessed data is not yet processable (e.g.
because OpenSSL has only received a partial record so far).
=head1 RETURN VALUES
The number of bytes pending is returned.
=head1 BUGS
SSL_pending() takes into account only bytes from the TLS/SSL record
that is currently being processed (if any). If the B<SSL> object's
I<read_ahead> flag is set (see
L<SSL_CTX_set_read_ahead(3)|SSL_CTX_set_read_ahead(3)>), additional protocol
bytes may have been read containing more TLS/SSL records; these are ignored by
SSL_pending().
Up to OpenSSL 0.9.6, SSL_pending() does not check if the record type
of pending data is application data.
SSL_pending() returns the number of buffered and processed application data
bytes that are pending and are available for immediate read. SSL_has_pending()
returns 1 if there is buffered record data in the SSL object and 0 otherwise.
=head1 SEE ALSO
L<SSL_read(3)|SSL_read(3)>,
L<SSL_CTX_set_read_ahead(3)|SSL_CTX_set_read_ahead(3)>, L<ssl(3)|ssl(3)>
L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(3)>
=head1 HISTORY
The SSL_has_pending() function 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

53
doc/ssl/SSL_read.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_read - read bytes from a TLS/SSL connection.
SSL_read - read bytes from a TLS/SSL connection
=head1 SYNOPSIS
@@ -18,16 +20,16 @@ buffer B<buf>.
=head1 NOTES
If necessary, SSL_read() will negotiate a TLS/SSL session, if
not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or
L<SSL_accept(3)|SSL_accept(3)>. If the
not already explicitly performed by L<SSL_connect(3)> or
L<SSL_accept(3)>. If the
peer requests a re-negotiation, it will be performed transparently during
the SSL_read() operation. The behaviour of SSL_read() depends on the
underlying BIO.
underlying BIO.
For the transparent negotiation to succeed, the B<ssl> must have been
initialized to client or server mode. This is being done by calling
L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state()
before the first call to an SSL_read() or L<SSL_write(3)|SSL_write(3)>
L<SSL_set_connect_state(3)> or SSL_set_accept_state()
before the first call to an SSL_read() or L<SSL_write(3)>
function.
SSL_read() works based on the SSL/TLS records. The data are received in
@@ -47,14 +49,14 @@ record is complete and SSL_read() can succeed.
If the underlying BIO is B<blocking>, SSL_read() will only return, once the
read operation has been finished or an error occurred, except when a
renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call.
L<SSL_CTX_set_mode(3)> call.
If the underlying BIO is B<non-blocking>, SSL_read() will also return
when the underlying BIO could not satisfy the needs of SSL_read()
to continue the operation. In this case a call to
L<SSL_get_error(3)|SSL_get_error(3)> with the
L<SSL_get_error(3)> with the
return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or
B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
call to SSL_read() can also cause write operations! The calling process
@@ -64,7 +66,7 @@ non-blocking socket, nothing is to be done, but select() can be used to check
for the required condition. When using a buffering BIO, like a BIO pair, data
must be written into or retrieved out of the BIO before being able to continue.
L<SSL_pending(3)|SSL_pending(3)> can be used to find out whether there
L<SSL_pending(3)> can be used to find out whether there
are buffered bytes available for immediate retrieval. In this case
SSL_read() can be called without blocking or actually receiving new
data from the underlying socket.
@@ -89,18 +91,10 @@ connection.
=item Z<><= 0
=item E<lt>0
The read operation was not successful, because either the connection was closed,
an error occurred or action must be taken by the calling process.
Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason.
SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
only be detected, whether the underlying connection was closed. It cannot
be checked, whether the closure was initiated by the peer or by something
else.
Old documentation indicated a difference between 0 and -1, and that -1 was
retryable.
You should instead call SSL_get_error() to find out if it's retryable.
@@ -109,12 +103,21 @@ You should instead call SSL_get_error() to find out if it's retryable.
=head1 SEE ALSO
L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>,
L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>
L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
L<SSL_pending(3)|SSL_pending(3)>,
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
L<SSL_get_error(3)>, L<SSL_write(3)>,
L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
L<SSL_connect(3)>, L<SSL_accept(3)>
L<SSL_set_connect_state(3)>,
L<SSL_pending(3)>,
L<SSL_shutdown(3)>, L<SSL_set_shutdown(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

13
doc/ssl/SSL_rstate_string.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_rstate_string, SSL_rstate_string_long - get textual description of state of an SSL object during read operation
@@ -54,6 +56,15 @@ The read state is unknown. This should never happen.
=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

15
doc/ssl/SSL_session_reused.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_session_reused - query whether a reused session was negotiated during handshake
@@ -39,7 +41,16 @@ A session was reused.
=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(3)>, L<SSL_set_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

98
doc/ssl/SSL_set_bio.pod
View File

@@ -1,34 +1,110 @@
=pod
=encoding utf8
=head1 NAME
SSL_set_bio - connect the SSL object with a BIO
SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio - connect the SSL object with a BIO
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);
void SSL_set0_rbio(SSL *s, BIO *rbio);
void SSL_set0_wbio(SSL *s, BIO *wbio);
=head1 DESCRIPTION
SSL_set_bio() connects the BIOs B<rbio> and B<wbio> for the read and write
operations of the TLS/SSL (encrypted) side of B<ssl>.
SSL_set0_rbio() connects the BIO B<rbio> for the read operations of the B<ssl>
object. The SSL engine inherits the behaviour of B<rbio>. If the BIO is
non-blocking then the B<ssl> object will also have non-blocking behaviour. This
function transfers ownership of B<rbio> to B<ssl>. It will be automatically
freed using L<BIO_free_all(3)> when the B<ssl> is freed. On calling this
function, any existing B<rbio> that was previously set will also be freed via a
call to L<BIO_free_all(3)> (this includes the case where the B<rbio> is set to
the same value as previously).
The SSL engine inherits the behaviour of B<rbio> and B<wbio>, respectively.
If a BIO is non-blocking, the B<ssl> will also have non-blocking behaviour.
SSL_set0_wbio() works in the same as SSL_set0_rbio() except that it connects
the BIO B<wbio> for the write operations of the B<ssl> object. Note that if the
rbio and wbio are the same then SSL_set0_rbio() and SSL_set0_wbio() each take
ownership of one reference. Therefore it may be necessary to increment the
number of references available using L<BIO_up_ref(3)> before calling the set0
functions.
If there was already a BIO connected to B<ssl>, BIO_free() will be called
(for both the reading and writing side, if different).
SSL_set_bio() does a similar job as SSL_set0_rbio() and SSL_set0_wbio() except
that it connects both the B<rbio> and the B<wbio> at the same time. This
function transfers the ownership of B<rbio> and B<wbio> to B<ssl> except that
the rules for this are much more complex. For this reason this function is
considered a legacy function and SSL_set0_rbio() and SSL_set0_wbio() should be
used in preference. The ownership rules are as follows:
=over 4
=item
If neither the rbio or wbio have changed from their previous values then nothing
is done.
=item
If the rbio and wbio parameters are different and both are different to their
previously set values then one reference is consumed for the rbio and one
reference is consumed for the wbio.
=item
If the rbio and wbio parameters are the same and the rbio is not the same as the
previously set value then one reference is consumed.
=item
If the rbio and wbio parameters are the same and the rbio is the same as the
previously set value, then no additional references are consumed.
=item
If the rbio and wbio parameters are different and the rbio is the same as the
previously set value then one reference is consumbed for the wbio and no
references are consumed for the rbio.
=item
If the rbio and wbio parameters are different and the wbio is the same as the
previously set value and the old rbio and wbio values were the same as each
other then one reference is consumed for the rbio and no references are consumed
for the wbio.
=item
If the rbio and wbio parameters are different and the wbio is the same as the
previously set value and the old rbio and wbio values were different to each
other then one reference is consumed for the rbio and one reference is consumed
for the wbio.
=back
=head1 RETURN VALUES
SSL_set_bio() cannot fail.
SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail.
=head1 SEE ALSO
L<SSL_get_rbio(3)|SSL_get_rbio(3)>,
L<SSL_connect(3)|SSL_connect(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_get_rbio(3)>,
L<SSL_connect(3)>, L<SSL_accept(3)>,
L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>
=head1 HISTORY
SSL_set0_rbio() and SSL_set0_wbio() were 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

35
doc/ssl/SSL_set_connect_state.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_set_connect_state, SSL_get_accept_state - prepare SSL object to work in client or server mode
SSL_set_connect_state, SSL_set_accept_state - prepare SSL object to work in client or server mode
=head1 SYNOPSIS
@@ -20,22 +22,22 @@ SSL_set_accept_state() sets B<ssl> to work in server mode.
=head1 NOTES
When the SSL_CTX object was created with L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
When the SSL_CTX object was created with L<SSL_CTX_new(3)>,
it was either assigned a dedicated client method, a dedicated server
method, or a generic method, that can be used for both client and
server connections. (The method might have been changed with
L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)> or
SSL_set_ssl_method(3).)
L<SSL_CTX_set_ssl_version(3)> or
SSL_set_ssl_method().)
When beginning a new handshake, the SSL engine must know whether it must
call the connect (client) or accept (server) routines. Even though it may
be clear from the method chosen, whether client or server mode was
requested, the handshake routines must be explicitly set.
When using the L<SSL_connect(3)|SSL_connect(3)> or
L<SSL_accept(3)|SSL_accept(3)> routines, the correct handshake
When using the L<SSL_connect(3)> or
L<SSL_accept(3)> routines, the correct handshake
routines are automatically set. When performing a transparent negotiation
using L<SSL_write(3)|SSL_write(3)> or L<SSL_read(3)|SSL_read(3)>, the
using L<SSL_write(3)> or L<SSL_read(3)>, the
handshake routines must be explicitly set in advance using either
SSL_set_connect_state() or SSL_set_accept_state().
@@ -46,10 +48,19 @@ information.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>,
L<SSL_write(3)|SSL_write(3)>, L<SSL_read(3)|SSL_read(3)>,
L<SSL_do_handshake(3)|SSL_do_handshake(3)>,
L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>
L<ssl(3)>, L<SSL_new(3)>, L<SSL_CTX_new(3)>,
LL<SSL_connect(3)>, L<SSL_accept(3)>,
L<SSL_write(3)>, L<SSL_read(3)>,
L<SSL_do_handshake(3)>,
L<SSL_CTX_set_ssl_version(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_set_fd.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_set_fd - connect the SSL object with a file descriptor
SSL_set_fd, SSL_set_rfd, SSL_set_wfd - connect the SSL object with a file descriptor
=head1 SYNOPSIS
@@ -47,8 +49,17 @@ The operation succeeded.
=head1 SEE ALSO
L<SSL_get_fd(3)|SSL_get_fd(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>,
L<SSL_connect(3)|SSL_connect(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_get_fd(3)>, L<SSL_set_bio(3)>,
L<SSL_connect(3)>, L<SSL_accept(3)>,
L<SSL_shutdown(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

27
doc/ssl/SSL_set_session.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect
@@ -17,11 +19,15 @@ is to be established. SSL_set_session() is only useful for TLS/SSL clients.
When the session is set, the reference count of B<session> is incremented
by 1. If the session is not reused, the reference count is decremented
again during SSL_connect(). Whether the session was reused can be queried
with the L<SSL_session_reused(3)|SSL_session_reused(3)> call.
with the L<SSL_session_reused(3)> call.
If there is already a session set inside B<ssl> (because it was set with
SSL_set_session() before or because the same B<ssl> was already used for
a connection), SSL_SESSION_free() will be called for that session.
a connection), SSL_SESSION_free() will be called for that session. If that old
session is still B<open>, it is considered bad and will be removed from the
session cache (if used). A session is considered open, 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).
=head1 NOTES
@@ -49,9 +55,18 @@ The operation succeeded.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
L<SSL_get_session(3)|SSL_get_session(3)>,
L<SSL_session_reused(3)|SSL_session_reused(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
L<ssl(3)>, L<SSL_SESSION_free(3)>,
L<SSL_get_session(3)>,
L<SSL_session_reused(3)>,
L<SSL_CTX_set_session_cache_mode(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_set_shutdown.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection
@@ -44,18 +46,18 @@ SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time.
The shutdown state of the connection is used to determine the state of
the ssl session. If the session is still open, when
L<SSL_clear(3)|SSL_clear(3)> or L<SSL_free(3)|SSL_free(3)> is called,
L<SSL_clear(3)> or L<SSL_free(3)> is called,
it is considered bad and removed according to RFC2246.
The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN
(according to the TLS RFC, it is acceptable to only send the "close notify"
alert but to not wait for the peer's answer, when the underlying connection
is closed).
SSL_set_shutdown() can be used to set this state without sending a
close alert to the peer (see L<SSL_shutdown(3)|SSL_shutdown(3)>).
close alert to the peer (see L<SSL_shutdown(3)>).
If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set,
for setting SSL_SENT_SHUTDOWN the application must however still call
L<SSL_shutdown(3)|SSL_shutdown(3)> or SSL_set_shutdown() itself.
L<SSL_shutdown(3)> or SSL_set_shutdown() itself.
=head1 RETURN VALUES
@@ -65,8 +67,17 @@ SSL_get_shutdown() returns the current setting.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>,
L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>,
L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
L<ssl(3)>, L<SSL_shutdown(3)>,
L<SSL_CTX_set_quiet_shutdown(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

19
doc/ssl/SSL_set_verify_result.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_set_verify_result - override result of peer certificate verification
@@ -23,7 +25,7 @@ the verification result of the B<ssl> object. It does not become part of the
established session, so if the session is to be reused later, the original
value will reappear.
The valid codes for B<verify_result> are documented in L<verify(1)|verify(1)>.
The valid codes for B<verify_result> are documented in L<verify(1)>.
=head1 RETURN VALUES
@@ -31,8 +33,17 @@ SSL_set_verify_result() does not provide a return value.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>,
L<verify(1)|verify(1)>
L<ssl(3)>, L<SSL_get_verify_result(3)>,
L<SSL_get_peer_certificate(3)>,
L<verify(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

39
doc/ssl/SSL_shutdown.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_shutdown - shut down a TLS/SSL connection
@@ -12,7 +14,7 @@ SSL_shutdown - shut down a TLS/SSL connection
=head1 DESCRIPTION
SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
"close notify" shutdown alert to the peer.
=head1 NOTES
@@ -50,21 +52,19 @@ with 1.
=item If the peer already sent the "close notify" alert B<and> it was
already processed implicitly inside another function
(L<SSL_read(3)|SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set.
(L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set.
SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN
flag and will immediately return with 1.
Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
SSL_get_shutdown() (see also L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> call.
SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call.
=back
It is therefore recommended, to check the return value of SSL_shutdown()
and call SSL_shutdown() again, if the bidirectional shutdown is not yet
complete (return value of the first call is 0). As the shutdown is not
specially handled in the SSLv2 protocol, SSL_shutdown() will succeed on
the first call.
complete (return value of the first call is 0).
The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
handshake step has been finished or an error occurred.
@@ -82,7 +82,7 @@ into or retrieved out of the BIO before being able to continue.
SSL_shutdown() can be modified to only set the connection to "shutdown"
state but not actually send the "close notify" alert messages,
see L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>.
see L<SSL_CTX_set_quiet_shutdown(3)>.
When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
and return 1.
@@ -96,7 +96,7 @@ The following return values can occur:
The shutdown is not yet finished. Call SSL_shutdown() for a second time,
if a bidirectional shutdown shall be performed.
The output of L<SSL_get_error(3)|SSL_get_error(3)> may be misleading, as an
The output of L<SSL_get_error(3)> may be misleading, as an
erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred.
=item Z<>1
@@ -109,17 +109,26 @@ and the peer's "close notify" alert was received.
The shutdown was not successful because a fatal error occurred either
at the protocol level or a connection failure occurred. It can also occur if
action is need to continue the operation for non-blocking BIOs.
Call L<SSL_get_error(3)|SSL_get_error(3)> with the return value B<ret>
Call L<SSL_get_error(3)> with the return value B<ret>
to find out the reason.
=back
=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_set_shutdown(3)|SSL_set_shutdown(3)>,
L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>,
L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>,
L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
L<SSL_get_error(3)>, L<SSL_connect(3)>,
L<SSL_accept(3)>, L<SSL_set_shutdown(3)>,
L<SSL_CTX_set_quiet_shutdown(3)>,
L<SSL_clear(3)>, L<SSL_free(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

13
doc/ssl/SSL_state_string.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
SSL_state_string, SSL_state_string_long - get textual description of state of an SSL object
@@ -40,6 +42,15 @@ Detailed description of possible states to be included later.
=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

50
doc/ssl/SSL_want.pod
View File

@@ -1,8 +1,12 @@
=pod
=encoding utf8
=head1 NAME
SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup - obtain state information TLS/SSL I/O operation
SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup,
SSL_want_async, SSL_want_async_job - obtain state information TLS/SSL I/O
operation
=head1 SYNOPSIS
@@ -13,6 +17,8 @@ SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup
int SSL_want_read(const SSL *ssl);
int SSL_want_write(const SSL *ssl);
int SSL_want_x509_lookup(const SSL *ssl);
int SSL_want_async(const SSL *ssl);
int SSL_want_async_job(const SSL *ssl);
=head1 DESCRIPTION
@@ -24,15 +30,15 @@ by SSL_want().
=head1 NOTES
SSL_want() examines the internal state information of the SSL object. Its
return values are similar to that of L<SSL_get_error(3)|SSL_get_error(3)>.
Unlike L<SSL_get_error(3)|SSL_get_error(3)>, which also evaluates the
return values are similar to that of L<SSL_get_error(3)>.
Unlike L<SSL_get_error(3)>, which also evaluates the
error queue, the results are obtained by examining an internal state flag
only. The information must therefore only be used for normal operation under
non-blocking I/O. Error conditions are not handled and must be treated
using L<SSL_get_error(3)|SSL_get_error(3)>.
using L<SSL_get_error(3)>.
The result returned by SSL_want() should always be consistent with
the result of L<SSL_get_error(3)|SSL_get_error(3)>.
the result of L<SSL_get_error(3)>.
=head1 RETURN VALUES
@@ -48,30 +54,52 @@ There is no data to be written or to be read.
There are data in the SSL buffer that must be written to the underlying
B<BIO> layer in order to complete the actual SSL_*() operation.
A call to L<SSL_get_error(3)|SSL_get_error(3)> should return
A call to L<SSL_get_error(3)> should return
SSL_ERROR_WANT_WRITE.
=item SSL_READING
More data must be read from the underlying B<BIO> layer in order to
complete the actual SSL_*() operation.
A call to L<SSL_get_error(3)|SSL_get_error(3)> should return
A call to L<SSL_get_error(3)> should return
SSL_ERROR_WANT_READ.
=item SSL_X509_LOOKUP
The operation did not complete because an application callback set by
SSL_CTX_set_client_cert_cb() has asked to be called again.
A call to L<SSL_get_error(3)|SSL_get_error(3)> should return
A call to L<SSL_get_error(3)> should return
SSL_ERROR_WANT_X509_LOOKUP.
=item SSL_ASYNC_PAUSED
An asynchronous operation partially completed and was then paused. See
L<SSL_get_all_async_fds(3)>. A call to L<SSL_get_error(3)> should return
SSL_ERROR_WANT_ASYNC.
=item SSL_ASYNC_NO_JOBS
The asynchronous job could not be started because there were no async jobs
available in the pool (see ASYNC_init_thread(3)). A call to L<SSL_get_error(3)>
should return SSL_ERROR_WANT_ASYNC_JOB.
=back
SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup()
return 1, when the corresponding condition is true or 0 otherwise.
SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup(),
SSL_want_async() and SSL_want_async_job() return 1, when the corresponding
condition is true or 0 otherwise.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<err(3)|err(3)>, L<SSL_get_error(3)|SSL_get_error(3)>
L<ssl(3)>, L<err(3)>, L<SSL_get_error(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

45
doc/ssl/SSL_write.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
SSL_write - write bytes to a TLS/SSL connection.
SSL_write - write bytes to a TLS/SSL connection
=head1 SYNOPSIS
@@ -18,27 +20,27 @@ B<ssl> connection.
=head1 NOTES
If necessary, SSL_write() will negotiate a TLS/SSL session, if
not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or
L<SSL_accept(3)|SSL_accept(3)>. If the
not already explicitly performed by L<SSL_connect(3)> or
L<SSL_accept(3)>. If the
peer requests a re-negotiation, it will be performed transparently during
the SSL_write() operation. The behaviour of SSL_write() depends on the
underlying BIO.
underlying BIO.
For the transparent negotiation to succeed, the B<ssl> must have been
initialized to client or server mode. This is being done by calling
L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state()
before the first call to an L<SSL_read(3)|SSL_read(3)> or SSL_write() function.
L<SSL_set_connect_state(3)> or SSL_set_accept_state()
before the first call to an L<SSL_read(3)> or SSL_write() function.
If the underlying BIO is B<blocking>, SSL_write() will only return, once the
write operation has been finished or an error occurred, except when a
renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call.
L<SSL_CTX_set_mode(3)> call.
If the underlying BIO is B<non-blocking>, SSL_write() will also return,
when the underlying BIO could not satisfy the needs of SSL_write()
to continue the operation. In this case a call to
L<SSL_get_error(3)|SSL_get_error(3)> with the
L<SSL_get_error(3)> with the
return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or
B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
call to SSL_write() can also cause read operations! The calling process
@@ -51,7 +53,7 @@ must be written into or retrieved out of the BIO before being able to continue.
SSL_write() will only return with success, when the complete contents
of B<buf> of length B<num> has been written. This default behaviour
can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of
L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>. When this flag is set,
L<SSL_CTX_set_mode(3)>. When this flag is set,
SSL_write() will also return with success, when a partial write has been
successfully completed. In this case the SSL_write() operation is considered
completed. The bytes are sent and a new SSL_write() operation with a new
@@ -85,10 +87,6 @@ The write operation was not successful, because either the connection was
closed, an error occurred or action must be taken by the calling process.
Call SSL_get_error() with the return value B<ret> to find out the reason.
SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
only be detected, whether the underlying connection was closed. It cannot
be checked, why the closure happened.
Old documentation indicated a difference between 0 and -1, and that -1 was
retryable.
You should instead call SSL_get_error() to find out if it's retryable.
@@ -97,10 +95,19 @@ You should instead call SSL_get_error() to find out if it's retryable.
=head1 SEE ALSO
L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>,
L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>
L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
L<SSL_get_error(3)>, L<SSL_read(3)>,
L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
L<SSL_connect(3)>, L<SSL_accept(3)>
L<SSL_set_connect_state(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