diff options
author | Rich Salz <rsalz@openssl.org> | 2016-10-26 13:56:48 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2016-10-26 13:59:52 -0400 |
commit | 99d63d4662e16afbeff49f29b48f1c87d5558ed0 (patch) | |
tree | 6512ff02cd93985526080f05ab2b5408235b19a9 /doc/ssl | |
parent | 4f3015bb30b7d95bb97408776b70e6a35fb91e8a (diff) | |
download | openssl-99d63d4662e16afbeff49f29b48f1c87d5558ed0.tar.gz |
Move manpages to man[1357] structure.
Move manpages to manX directories
Add Windows/VMS install fix from Richard Levitte
Update README
Fix typo's
Remove some duplicates
Reviewed-by: Richard Levitte <levitte@openssl.org>
Diffstat (limited to 'doc/ssl')
118 files changed, 0 insertions, 12064 deletions
diff --git a/doc/ssl/DTLSv1_listen.pod b/doc/ssl/DTLSv1_listen.pod deleted file mode 100644 index a839d9fec1..0000000000 --- a/doc/ssl/DTLSv1_listen.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -DTLSv1_listen - listen for incoming DTLS connections - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer); - -=head1 DESCRIPTION - -DTLSv1_listen() listens for new incoming DTLS connections. If a ClientHello is -received that does not contain a cookie, then DTLSv1_listen() responds with a -HelloVerifyRequest. If a ClientHello is received with a cookie that is verified -then control is returned to user code to enable the handshake to be completed -(for example by using SSL_accept()). - -=head1 NOTES - -Datagram based protocols can be susceptible to Denial of Service attacks. A -DTLS attacker could, for example, submit a series of handshake initiation -requests that cause the server to allocate state (and possibly perform -cryptographic operations) thus consuming server resources. The attacker could -also (with UDP) quite simply forge the source IP address in such an attack. - -As a counter measure to that DTLS includes a stateless cookie mechanism. The -idea is that when a client attempts to connect to a server it sends a -ClientHello message. The server responds with a HelloVerifyRequest which -contains a unique cookie. The client then resends the ClientHello, but this time -includes the cookie in the message thus proving that the client is capable of -receiving messages sent to that address. All of this can be done by the server -without allocating any state, and thus without consuming expensive resources. - -OpenSSL implements this capability via the DTLSv1_listen() function. The B<ssl> -parameter should be a newly allocated SSL object with its read and write BIOs -set, in the same way as might be done for a call to SSL_accept(). Typically the -read BIO will be in an "unconnected" state and thus capable of receiving -messages from any peer. - -When a ClientHello is received that contains a cookie that has been verified, -then DTLSv1_listen() will return with the B<ssl> parameter updated into a state -where the handshake can be continued by a call to (for example) SSL_accept(). -Additionally the B<BIO_ADDR> pointed to by B<peer> will be filled in with -details of the peer that sent the ClientHello. If the underlying BIO is unable -to obtain the B<BIO_ADDR> of the peer (for example because the BIO does not -support this), then B<*peer> will be cleared and the family set to AF_UNSPEC. -Typically user code is expected to "connect" the underlying socket to the peer -and continue the handshake in a connected state. - -Prior to calling DTLSv1_listen() user code must ensure that cookie generation -and verification callbacks have been set up using -SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb() -respectively. - -Since DTLSv1_listen() operates entirely statelessly whilst processing incoming -ClientHellos it is unable to process fragmented messages (since this would -require the allocation of state). An implication of this is that DTLSv1_listen() -B<only> supports ClientHellos that fit inside a single datagram. - -=head1 RETURN VALUES - -From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance -the B<peer> value will be filled in and the B<ssl> object set up ready to -continue the handshake. - -A return value of 0 indicates a non-fatal error. This could (for -example) be because of non-blocking IO, or some invalid message having been -received from a peer. Errors may be placed on the OpenSSL error queue with -further information if appropriate. Typically user code is expected to retry the -call to DTLSv1_listen() in the event of a non-fatal error. Any old errors on the -error queue will be cleared in the subsequent call. - -A return value of <0 indicates a fatal error. This could (for example) be -because of a failure to allocate sufficient memory for the operation. - -Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return codes -<= 0 (in typical implementations user code treats all errors as non-fatal), -whilst return codes >0 indicate success. - -=head1 SEE ALSO - -L<SSL_get_error(3)>, L<SSL_accept(3)>, -L<ssl(3)>, L<bio(3)> - -=head1 HISTORY - -DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of "peer" -also changed in OpenSSL 1.1.0. - -=head1 COPYRIGHT - -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/OPENSSL_init_ssl.pod b/doc/ssl/OPENSSL_init_ssl.pod deleted file mode 100644 index b963e5e7a9..0000000000 --- a/doc/ssl/OPENSSL_init_ssl.pod +++ /dev/null @@ -1,84 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_init_ssl - OpenSSL (libssl and libcrypto) initialisation - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); - -=head1 DESCRIPTION - -During normal operation OpenSSL (libssl and libcrypto) will allocate various -resources at start up that must, subsequently, be freed on close down of the -library. Additionally some resources are allocated on a per thread basis (if the -application is multi-threaded), and these resources must be freed prior to the -thread closing. - -As of version 1.1.0 OpenSSL will automatically allocate all resources that it -needs so no explicit initialisation is required. Similarly it will also -automatically deinitialise as required. - -However, there may be situations when explicit initialisation is desirable or -needed, for example when some non-default initialisation is required. The -function OPENSSL_init_ssl() can be used for this purpose. Calling -this function will explicitly initialise BOTH libcrypto and libssl. To -explicitly initialise ONLY libcrypto see the -L<OPENSSL_init_crypto(3)> function. - -Numerous internal OpenSSL functions call OPENSSL_init_ssl(). -Therefore, in order to perform non-default initialisation, -OPENSSL_init_ssl() MUST be called by application code prior to -any other OpenSSL function calls. - -The B<opts> parameter specifies which aspects of libssl and libcrypto should be -initialised. Valid options for libcrypto are described on the -L<OPENSSL_init_crypto(3)> page. In addition to any libcrypto -specific option the following libssl options can also be used: - -=over 4 - -=item OPENSSL_INIT_NO_LOAD_SSL_STRINGS - -Suppress automatic loading of the libssl error strings. This option is -not a default option. Once selected subsequent calls to -OPENSSL_init_ssl() with the option -B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored. - -=item OPENSSL_INIT_LOAD_SSL_STRINGS - -Automatic loading of the libssl error strings. This option is a -default option. Once selected subsequent calls to -OPENSSL_init_ssl() with the option -B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored. - -=back - -OPENSSL_init_ssl() takes a B<settings> parameter which can be used to -set parameter values. See L<OPENSSL_init_crypto(3)> for details. - -=head1 RETURN VALUES - -The function OPENSSL_init_ssl() returns 1 on success or 0 on error. - -=head1 SEE ALSO - -L<OPENSSL_init_crypto(3)> - -=head1 HISTORY - -The OPENSSL_init_ssl() function was added in OpenSSL 1.1.0. - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_CIPHER_get_name.pod b/doc/ssl/SSL_CIPHER_get_name.pod deleted file mode 100644 index b7ee3c84f5..0000000000 --- a/doc/ssl/SSL_CIPHER_get_name.pod +++ /dev/null @@ -1,128 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/ssl.h> - - const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); - 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 -B<cipher> is NULL, it returns "(NONE)". - -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. 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. 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. - -The string returned by SSL_CIPHER_description() consists of several fields -separated by whitespace: - -=over 4 - -=item <ciphername> - -Textual representation of the cipher name. - -=item <protocol version> - -Protocol version, such as B<TLSv1.2>, when the cipher was first defined. - -=item Kx=<key exchange> - -Key exchange method such as B<RSA>, B<ECDHE>, etc. - -=item Au=<authentication> - -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, such as B<AESGCM(128)>. - -=item Mac=<message authentication code> - -Message digest, such as B<SHA256>. - -=back - -Some examples for the output of SSL_CIPHER_description(): - - 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 - -=head1 HISTORY - -SSL_CIPHER_get_version() was updated to always return the correct protocol -string in OpenSSL 1.1. - -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)>, 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 diff --git a/doc/ssl/SSL_COMP_add_compression_method.pod b/doc/ssl/SSL_COMP_add_compression_method.pod deleted file mode 100644 index c455832078..0000000000 --- a/doc/ssl/SSL_COMP_add_compression_method.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - -SSL_COMP_add_compression_method, 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); - -Deprecated: - - #if OPENSSL_API_COMPAT < 0x10100000L - void SSL_COMP_free_compression_methods(void) - #endif - -=head1 DESCRIPTION - -SSL_COMP_add_compression_method() adds the compression method B<cm> with -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. - -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 - -The TLS standard (or SSLv3) allows the integration of compression methods -into the communication. The TLS RFC does however not specify compression -methods or their corresponding identifiers, so there is currently no compatible -way to integrate compression with unknown peers. It is therefore currently not -recommended to integrate compression into applications. Applications for -non-public use may agree on certain compression methods. Using different -compression methods with the same identifier will lead to connection failure. - -An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1) -will unconditionally send the list of all compression methods enabled with -SSL_COMP_add_compression_method() to the server during the handshake. -Unlike the mechanisms to set a cipher list, there is no method available to -restrict the list of compression method on a per connection basis. - -An OpenSSL server will match the identifiers listed by a client against -its own compression methods and will unconditionally activate compression -when a matching identifier is found. There is no way to restrict the list -of compression methods supported on a per connection basis. - -If enabled during compilation, the OpenSSL library will have the -COMP_zlib() compression method available. - -=head1 WARNINGS - -Once the identities of the compression methods for the TLS protocol have -been standardized, the compression API will most likely be changed. Using -it in the current state is not recommended. - -=head1 RETURN VALUES - -SSL_COMP_add_compression_method() may return the following values: - -=over 4 - -=item Z<>0 - -The operation succeeded. - -=item Z<>1 - -The operation failed. Check the error queue to find out the reason. - -=back - -=head1 SEE ALSO - -L<ssl(3)> - -=head1 HISTORY - -SSL_COMP_free_compression_methods() was deprecated 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 diff --git a/doc/ssl/SSL_CONF_CTX_new.pod b/doc/ssl/SSL_CONF_CTX_new.pod deleted file mode 100644 index 79f0bbc7dd..0000000000 --- a/doc/ssl/SSL_CONF_CTX_new.pod +++ /dev/null @@ -1,50 +0,0 @@ -=pod - -=head1 NAME - -SSL_CONF_CTX_new, SSL_CONF_CTX_free - SSL configuration allocation functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL_CONF_CTX *SSL_CONF_CTX_new(void); - void SSL_CONF_CTX_free(SSL_CONF_CTX *cctx); - -=head1 DESCRIPTION - -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 - -SSL_CONF_CTX_new() returns either the newly allocated B<SSL_CONF_CTX> structure -or B<NULL> if an error occurs. - -SSL_CONF_CTX_free() does not return a value. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CONF_CTX_set1_prefix.pod b/doc/ssl/SSL_CONF_CTX_set1_prefix.pod deleted file mode 100644 index da9e580244..0000000000 --- a/doc/ssl/SSL_CONF_CTX_set1_prefix.pod +++ /dev/null @@ -1,58 +0,0 @@ -=pod - -=head1 NAME - -SSL_CONF_CTX_set1_prefix - Set configuration context command prefix - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - unsigned int SSL_CONF_CTX_set1_prefix(SSL_CONF_CTX *cctx, const char *prefix); - -=head1 DESCRIPTION - -The function SSL_CONF_CTX_set1_prefix() sets the command prefix of B<cctx> -to B<prefix>. If B<prefix> is B<NULL> it is restored to the default value. - -=head1 NOTES - -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 -"--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 -sensitive and "-" is the default. In the unlikely even an application -explicitly wants to set no prefix it must be explicitly set to "". - -If the B<SSL_CONF_FLAG_FILE> flag is set then prefix checks are case -insensitive and no prefix is the default. - -=head1 RETURN VALUES - -SSL_CONF_CTX_set1_prefix() returns 1 for success and 0 for failure. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CONF_CTX_set_flags.pod b/doc/ssl/SSL_CONF_CTX_set_flags.pod deleted file mode 100644 index efd8da3bc6..0000000000 --- a/doc/ssl/SSL_CONF_CTX_set_flags.pod +++ /dev/null @@ -1,84 +0,0 @@ -=pod - -=head1 NAME - -SSL_CONF_CTX_set_flags, SSL_CONF_CTX_clear_flags - Set of clear SSL configuration context flags - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - unsigned int SSL_CONF_CTX_set_flags(SSL_CONF_CTX *cctx, unsigned int flags); - unsigned int SSL_CONF_CTX_clear_flags(SSL_CONF_CTX *cctx, unsigned int flags); - -=head1 DESCRIPTION - -The function SSL_CONF_CTX_set_flags() sets B<flags> in the context B<cctx>. - -The function SSL_CONF_CTX_clear_flags() clears B<flags> in the context B<cctx>. - -=head1 NOTES - -The flags set affect how subsequent calls to SSL_CONF_cmd() or -SSL_CONF_argv() behave. - -Currently the following B<flags> values are recognised: - -=over 4 - -=item SSL_CONF_FLAG_CMDLINE, SSL_CONF_FLAG_FILE - -recognise options intended for command line or configuration file use. At -least one of these flags must be set. - -=item SSL_CONF_FLAG_CLIENT, SSL_CONF_FLAG_SERVER - -recognise options intended for use in SSL/TLS clients or servers. One or -both of these flags must be set. - -=item SSL_CONF_FLAG_CERTIFICATE - -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 -the error queue. If this option isn't set such errors are only reflected -in the return values of SSL_CONF_set_cmd() or SSL_CONF_set_argv() - -=back - -=head1 RETURN VALUES - -SSL_CONF_CTX_set_flags() and SSL_CONF_CTX_clear_flags() returns the new flags -value after setting or clearing flags. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod b/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod deleted file mode 100644 index 7e4120f7ce..0000000000 --- a/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - -SSL_CONF_CTX_set_ssl_ctx, SSL_CONF_CTX_set_ssl - set context to configure - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CONF_CTX_set_ssl_ctx(SSL_CONF_CTX *cctx, SSL_CTX *ctx); - void SSL_CONF_CTX_set_ssl(SSL_CONF_CTX *cctx, SSL *ssl); - -=head1 DESCRIPTION - -SSL_CONF_CTX_set_ssl_ctx() sets the context associated with B<cctx> to the -B<SSL_CTX> structure B<ctx>. Any previous B<SSL> or B<SSL_CTX> associated with -B<cctx> is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to -B<ctx>. - -SSL_CONF_CTX_set_ssl() sets the context associated with B<cctx> to the -B<SSL> structure B<ssl>. Any previous B<SSL> or B<SSL_CTX> associated with -B<cctx> is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to -B<ssl>. - -=head1 NOTES - -The context need not be set or it can be set to B<NULL> in which case only -syntax checking of commands is performed, where possible. - -=head1 RETURN VALUES - -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)>, -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 diff --git a/doc/ssl/SSL_CONF_cmd.pod b/doc/ssl/SSL_CONF_cmd.pod deleted file mode 100644 index d8c0e9b95d..0000000000 --- a/doc/ssl/SSL_CONF_cmd.pod +++ /dev/null @@ -1,553 +0,0 @@ -=pod - -=head1 NAME - -SSL_CONF_cmd_value_type, SSL_CONF_finish, -SSL_CONF_cmd - send configuration command - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value); - int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd); - int SSL_CONF_finish(SSL_CONF_CTX *cctx); - -=head1 DESCRIPTION - -The function SSL_CONF_cmd() performs configuration operation B<cmd> with -optional parameter B<value> on B<ctx>. Its purpose is to simplify application -configuration of B<SSL_CTX> or B<SSL> structures by providing a common -framework for command line options or configuration files. - -SSL_CONF_cmd_value_type() returns the type of value that B<cmd> refers to. - -The function SSL_CONF_finish() must be called after all configuration -operations have been completed. It is used to finalise any operations -or to process defaults. - -=head1 SUPPORTED COMMAND LINE COMMANDS - -Currently supported B<cmd> names for command lines (i.e. when the -flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<cmd> names -are case sensitive. Unless otherwise stated commands can be used by -both clients and servers and the B<value> parameter is not used. The default -prefix for command line commands is B<-> and that is reflected below. - -=over 4 - -=item B<-sigalgs> - -This sets the supported signature algorithms for TLS v1.2. For clients this -value is used directly for the supported signature algorithms extension. For -servers it is used to determine which signature algorithms to support. - -The B<value> argument should be a colon separated list of signature algorithms -in order of decreasing preference of the form B<algorithm+hash>. B<algorithm> -is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm -OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>. -Note: algorithm and hash names are case sensitive. - -If this option is not set then all signature algorithms supported by the -OpenSSL library are permissible. - -=item B<-client_sigalgs> - -This sets the supported signature algorithms associated with client -authentication for TLS v1.2. For servers the value is used in the supported -signature algorithms field of a certificate request. For clients it is -used to determine which signature algorithm to with the client certificate. -If a server does not request a certificate this option has no effect. - -The syntax of B<value> is identical to B<-sigalgs>. If not set then -the value set for B<-sigalgs> will be used instead. - -=item B<-curves> - -This sets the supported elliptic curves. For clients the curves are -sent using the supported curves extension. For servers it is used -to determine which curve to use. This setting affects curves used for both -signatures and key exchange, if applicable. - -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<-named_curve> - -This sets the temporary curve used for ephemeral ECDH modes. Only used by -servers - -The B<value> argument is a curve name or the special value B<auto> 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. - -=item B<-cipher> - -Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is -currently not performed unless a B<SSL> or B<SSL_CTX> structure is -associated with B<cctx>. - -=item B<-cert> - -Attempts to use the file B<value> as the certificate for the appropriate -context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX> -structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL> -structure is set. This option is only supported if certificate operations -are permitted. - -=item B<-key> - -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 unless the flag B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set. - -=item B<-dhparam> - -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<-min_protocol>, B<-max_protocol> - -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_COMPRESSION>. -As of OpenSSL 1.1.0, compression is off by default. - -=item B<-no_ticket> - -Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>. - -=item B<-serverpref> - -Use server and not client preference order when determining which cipher suite, -signature algorithm or elliptic curve to use for an incoming connection. -Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers. - -=item B<-no_resumption_on_reneg> - -set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers. - -=item B<-legacyrenegotiation> - -permits the use of unsafe legacy renegotiation. Equivalent to setting -B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>. - -=item B<-legacy_server_connect>, B<-no_legacy_server_connect> - -permits or prohibits the use of unsafe legacy renegotiation for OpenSSL -clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>. -Set by default. - -=item B<-strict> - -enables strict mode protocol handling. Equivalent to setting -B<SSL_CERT_FLAG_TLS_STRICT>. - -=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 are case insensitive so B<signaturealgorithms> is recognised -as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names -are also case insensitive. - -Note: the command prefix (if set) alters the recognised B<cmd> values. - -=over 4 - -=item B<CipherString> - -Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is -currently not performed unless an B<SSL> or B<SSL_CTX> structure is -associated with B<cctx>. - -=item B<Certificate> - -Attempts to use the file B<value> as the certificate for the appropriate -context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX> -structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL> -structure is set. This option is only supported if certificate operations -are permitted. - -=item B<PrivateKey> - -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<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> - -Attempts to use the file B<value> in the "serverinfo" extension using the -function SSL_CTX_use_serverinfo_file. - -=item B<DHParameters> - -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<SignatureAlgorithms> - -This sets the supported signature algorithms for TLS v1.2. For clients this -value is used directly for the supported signature algorithms extension. For -servers it is used to determine which signature algorithms to support. - -The B<value> argument should be a colon separated list of signature algorithms -in order of decreasing preference of the form B<algorithm+hash>. B<algorithm> -is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm -OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>. -Note: algorithm and hash names are case sensitive. - -If this option is not set then all signature algorithms supported by the -OpenSSL library are permissible. - -=item B<ClientSignatureAlgorithms> - -This sets the supported signature algorithms associated with client -authentication for TLS v1.2. For servers the value is used in the supported -signature algorithms field of a certificate request. For clients it is -used to determine which signature algorithm to with the client certificate. - -The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then -the value set for B<SignatureAlgorithms> will be used instead. - -=item B<Curves> - -This sets the supported elliptic curves. For clients the curves are -sent using the supported curves extension. For servers it is used -to determine which curve to use. This setting affects curves used for both -signatures and key exchange, if applicable. - -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<MinProtocol> - -This sets the minimum 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<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> - -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 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 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. - -B<SessionTicket>: session ticket support, enabled by default. Inverse of -B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting -B<SSL_OP_NO_TICKET>. - -B<Compression>: SSL/TLS compression support, enabled by default. Inverse -of B<SSL_OP_NO_COMPRESSION>. - -B<EmptyFragments>: use empty fragments as a countermeasure against a -SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It -is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>. - -B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>. - -B<DHSingle>: enable single use DH keys, set by default. Inverse of -B<SSL_OP_DH_SINGLE>. Only used by servers. - -B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of -B<SSL_OP_ECDH_SINGLE>. Only used by servers. - -B<ServerPreference> use server and not client preference order when -determining which cipher suite, signature algorithm or elliptic curve -to use for an incoming connection. Equivalent to -B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers. - -B<NoResumptionOnRenegotiation> set -B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers. - -B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation. -Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>. - -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 - -The function SSL_CONF_cmd_value_type() currently returns one of the following -types: - -=over 4 - -=item B<SSL_CONF_TYPE_UNKNOWN> - -The B<cmd> string is unrecognised, this return value can be use to flag -syntax errors. - -=item B<SSL_CONF_TYPE_STRING> - -The value is a string without any specific structure. - -=item B<SSL_CONF_TYPE_FILE> - -The value is a file name. - -=item B<SSL_CONF_TYPE_DIR> - -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 - -The order of operations is significant. This can be used to set either defaults -or values which cannot be overridden. For example if an application calls: - - SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); - SSL_CONF_cmd(ctx, userparam, uservalue); - -it will disable SSLv3 support by default but the user can override it. If -however the call sequence is: - - SSL_CONF_cmd(ctx, userparam, uservalue); - SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); - -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 -given B<cmd> is recognised, this is useful is SSL_CTX_cmd() values are -mixed with additional application specific operations. - -For example an application might call SSL_CTX_cmd() and if it returns --2 (unrecognised command) continue with processing of application specific -commands. - -Applications can also use SSL_CTX_cmd() to process command lines though the -utility function SSL_CTX_cmd_argv() is normally used instead. One way -to do this is to set the prefix to an appropriate value using -SSL_CONF_CTX_set1_prefix(), pass the current argument to B<cmd> and the -following argument to B<value> (which may be NULL). - -In this case if the return value is positive then it is used to skip that -number of arguments as they have been processed by SSL_CTX_cmd(). If -2 is -returned then B<cmd> is not recognised and application specific arguments -can be checked instead. If -3 is returned a required argument is missing -and an error is indicated. If 0 is returned some other error occurred and -this can be reported back to the user. - -The function SSL_CONF_cmd_value_type() can be used by applications to -check for the existence of a command or to perform additional syntax -checking or translation of the command value. For example if the return -value is B<SSL_CONF_TYPE_FILE> an application could translate a relative -pathname to an absolute pathname. - -=head1 EXAMPLES - -Set supported signature algorithms: - - SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256"); - -There are various ways to select the supported protocols. - -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"); - -Set automatic support for any elliptic curve for key exchange: - - SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic"); - -=head1 RETURN VALUES - -SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is -B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it -returns the number of arguments processed. This is useful when processing -command lines. - -A return value of -2 means B<cmd> is not recognised. - -A return value of -3 means B<cmd> is recognised and the command requires a -value but B<value> is NULL. - -A return code of 0 indicates that both B<cmd> and B<value> are valid but an -error occurred attempting to perform the operation: for example due to an -error in the syntax of B<value> in this case the error queue may provide -additional information. - -SSL_CONF_finish() returns 1 for success and 0 for failure. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CONF_cmd_argv.pod b/doc/ssl/SSL_CONF_cmd_argv.pod deleted file mode 100644 index 15529a5973..0000000000 --- a/doc/ssl/SSL_CONF_cmd_argv.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -SSL_CONF_cmd_argv - SSL configuration command line processing - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CONF_cmd_argv(SSL_CONF_CTX *cctx, int *pargc, char ***pargv); - -=head1 DESCRIPTION - -The function SSL_CONF_cmd_argv() processes at most two command line -arguments from B<pargv> and B<pargc>. The values of B<pargv> and B<pargc> -are updated to reflect the number of command options processed. The B<pargc> -argument can be set to B<NULL> is it is not used. - -=head1 RETURN VALUES - -SSL_CONF_cmd_argv() returns the number of command arguments processed: 0, 1, 2 -or a negative error code. - -If -2 is returned then an argument for a command is missing. - -If -1 is returned the command is recognised but couldn't be processed due -to an error: for example a syntax error in the argument. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_add1_chain_cert.pod b/doc/ssl/SSL_CTX_add1_chain_cert.pod deleted file mode 100644 index 1f0418b249..0000000000 --- a/doc/ssl/SSL_CTX_add1_chain_cert.pod +++ /dev/null @@ -1,158 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert, -SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs, -SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert, -SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain, -SSL_build_cert_chain, SSL_CTX_select_current_cert, -SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert - extra -chain certificate processing - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); - int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); - int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509); - int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509); - int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk); - int SSL_CTX_clear_chain_certs(SSL_CTX *ctx); - - int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk); - int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk); - int SSL_add0_chain_cert(SSL *ssl, X509 *x509); - int SSL_add1_chain_cert(SSL *ssl, X509 *x509); - int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk); - int SSL_clear_chain_certs(SSL *ssl); - - int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags); - int SSL_build_cert_chain(SSL *ssl, flags); - - int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509); - int SSL_select_current_cert(SSL *ssl, X509 *x509); - int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op); - int SSL_set_current_cert(SSL *ssl, long op); - -=head1 DESCRIPTION - -SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain -associated with the current certificate of B<ctx> to B<sk>. - -SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single -certificate B<x509> to the chain associated with the current certificate of -B<ctx>. - -SSL_CTX_get0_chain_certs() retrieves the chain associated with the current -certificate of B<ctx>. - -SSL_CTX_clear_chain_certs() clears any existing chain associated with the -current certificate of B<ctx>. (This is implemented by calling -SSL_CTX_set0_chain() with B<sk> set to B<NULL>). - -SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx> normally -this uses the chain store or the verify store if the chain store is not set. -If the function is successful the built chain will replace any existing chain. -The B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_UNTRUSTED> to use -existing chain certificates as untrusted CAs, B<SSL_BUILD_CHAIN_FLAG_NO_ROOT> -to omit the root CA from the built chain, B<SSL_BUILD_CHAIN_FLAG_CHECK> to -use all existing chain certificates only to build the chain (effectively -sanity checking and rearranging them if necessary), the flag -B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> ignores any errors during verification: -if flag B<SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR> is also set verification errors -are cleared from the error queue. - -Each of these functions operates on the I<current> end entity -(i.e. server or client) certificate. This is the last certificate loaded or -selected on the corresponding B<ctx> structure. - -SSL_CTX_select_current_cert() selects B<x509> as the current end entity -certificate, but only if B<x509> has already been loaded into B<ctx> using a -function such as SSL_CTX_use_certificate(). - -SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(), -SSL_add1_chain_cert(), SSL_get0_chain_certs(), SSL_clear_chain_certs(), -SSL_build_cert_chain(), SSL_select_current_cert() and SSL_set_current_cert() -are similar except they apply to SSL structure B<ssl>. - -SSL_CTX_set_current_cert() changes the current certificate to a value based -on the B<op> argument. Currently B<op> can be B<SSL_CERT_SET_FIRST> to use -the first valid certificate or B<SSL_CERT_SET_NEXT> to set the next valid -certificate after the current certificate. These two operations can be -used to iterate over all certificates in an B<SSL_CTX> structure. - -SSL_set_current_cert() also supports the option B<SSL_CERT_SET_SERVER>. -If B<ssl> is a server and has sent a certificate to a connected client -this option sets that certificate to the current certificate and returns 1. -If the negotiated ciphersuite is anonymous (and thus no certificate will -be sent) 2 is returned and the current certificate is unchanged. If B<ssl> -is not a server or a certificate has not been sent 0 is returned and -the current certificate is unchanged. - -All these functions are implemented as macros. Those containing a B<1> -increment the reference count of the supplied certificate or chain so it must -be freed at some point after the operation. Those containing a B<0> do -not increment reference counts and the supplied certificate or chain -B<MUST NOT> be freed after the operation. - -=head1 NOTES - -The chains associate with an SSL_CTX structure are copied to any SSL -structures when SSL_new() is called. SSL structures will not be affected -by any chains subsequently changed in the parent SSL_CTX. - -One chain can be set for each key type supported by a server. So, for example, -an RSA and a DSA certificate can (and often will) have different chains. - -The functions SSL_CTX_build_cert_chain() and SSL_build_cert_chain() can -be used to check application configuration and to ensure any necessary -subordinate CAs are sent in the correct order. Misconfigured applications -sending incorrect certificate chains often cause problems with peers. - -For example an application can add any set of certificates using -SSL_CTX_use_certificate_chain_file() then call SSL_CTX_build_cert_chain() -with the option B<SSL_BUILD_CHAIN_FLAG_CHECK> to check and reorder them. - -Applications can issue non fatal warnings when checking chains by setting -the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS> and checking the return -value. - -Calling SSL_CTX_build_cert_chain() or SSL_build_cert_chain() is more -efficient than the automatic chain building as it is only performed once. -Automatic chain building is performed on each new session. - -If any certificates are added using these functions no certificates added -using SSL_CTX_add_extra_chain_cert() will be used. - -=head1 RETURN VALUES - -SSL_set_current_cert() with B<SSL_CERT_SET_SERVER> return 1 for success, 2 if -no server certificate is used because the ciphersuites is anonymous and 0 -for failure. - -SSL_CTX_build_cert_chain() and SSL_build_cert_chain() return 1 for success -and 0 for failure. If the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> and -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)> - -=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 diff --git a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod deleted file mode 100644 index e2783de9c7..0000000000 --- a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod +++ /dev/null @@ -1,80 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_add_extra_chain_cert, SSL_CTX_clear_extra_chain_certs - add or clear -extra chain certificates - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509); - long SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the extra chain -certificates associated with B<ctx>. Several certificates can be added one -after another. - -SSL_CTX_clear_extra_chain_certs() clears all extra chain certificates -associated with B<ctx>. - -These functions are implemented as macros. - -=head1 NOTES - -When sending a certificate chain, extra chain certificates are sent in order -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)>. - -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 -B<should not> free the B<x509> object. - -=head1 RESTRICTIONS - -Only one set of extra chain certificates can be specified per SSL_CTX -structure. Different chains for different certificates (for example if both -RSA and DSA certificates are specified by the same server) or different SSL -structures with the same parent SSL_CTX cannot be specified using this -function. For more flexibility functions such as SSL_add1_chain_cert() should -be used instead. - -=head1 RETURN VALUES - -SSL_CTX_add_extra_chain_cert() and SSL_CTX_clear_extra_chain_certs() return -1 on success and 0 for failure. Check out the error stack to find out the -reason for failure. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_add_session.pod b/doc/ssl/SSL_CTX_add_session.pod deleted file mode 100644 index dbdd9f0c54..0000000000 --- a/doc/ssl/SSL_CTX_add_session.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c); - int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c); - - int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c); - int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c); - -=head1 DESCRIPTION - -SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The -reference count for session B<c> is incremented by 1. If a session with -the same session id already exists, the old session is removed by calling -L<SSL_SESSION_free(3)>. - -SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>. -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. - -=head1 NOTES - -When adding a new session to the internal session cache, it is examined -whether a session with the same session id already exists. In this case -it is assumed that both sessions are identical. If the same session is -stored in a different SSL_SESSION object, The old session is -removed and replaced by the new session. If the session is actually -identical (the SSL_SESSION object is identical), SSL_CTX_add_session() -is a no-op, and the return value is 0. - -If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE -flag then the internal cache will not be populated automatically by new -sessions negotiated by the SSL/TLS implementation, even though the internal -cache will be searched automatically for session-resume requests (the -latter can be suppressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the -application can use SSL_CTX_add_session() directly to have full control -over the sessions that can be resumed if desired. - - -=head1 RETURN VALUES - -The following values are returned by all functions: - -=over 4 - -=item Z<>0 - - The operation failed. In case of the add operation, it was tried to add - the same (identical) session twice. In case of the remove operation, the - session was not found in the cache. - -=item Z<>1 - - The operation succeeded. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_config.pod b/doc/ssl/SSL_CTX_config.pod deleted file mode 100644 index 802c4c359e..0000000000 --- a/doc/ssl/SSL_CTX_config.pod +++ /dev/null @@ -1,93 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_config(SSL_CTX *ctx, const char *name); - int SSL_config(SSL *s, const char *name); - -=head1 DESCRIPTION - -The functions SSL_CTX_config() and SSL_config() configure an B<SSL_CTX> or -B<SSL> structure using the configuration B<name>. - -=head1 NOTES - -By calling SSL_CTX_config() or SSL_config() an application can perform many -complex tasks based on the contents of the configuration file: greatly -simplifying application configuration code. A degree of future proofing -can also be achieved: an application can support configuration features -in newer versions of OpenSSL automatically. - -A configuration file must have been previously loaded, for example using -CONF_modules_load_file(). See L<config(3)> for details of the configuration -file syntax. - -=head1 RETURN VALUES - -SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error -occurred. - -=head1 EXAMPLE - -If the file "config.cnf" contains the following: - - testapp = test_sect - - [test_sect] - # list of confuration modules - - ssl_conf = ssl_sect - - [ssl_sect] - - server = server_section - - [server_section] - - RSA.Certificate = server-rsa.pem - ECDSA.Certificate = server-ecdsa.pem - Ciphers = ALL:!RC4 - -An application could call: - - if (CONF_modules_load_file("config.cnf", "testapp", 0) <= 0) { - fprintf(stderr, "Error processing config file\n"); - goto err; - } - - ctx = SSL_CTX_new(TLS_server_method()); - - if (SSL_CTX_config(ctx, "server") == 0) { - fprintf(stderr, "Error configuring server.\n"); - goto err; - } - -In this example two certificates and the cipher list are configured without -the need for any additional application code. - -=head1 SEE ALSO - -L<config(3)>, -L<SSL_CONF_cmd(3)>, -L<CONF_modules_load_file(3)> - -=head1 HISTORY - -SSL_CTX_config() and SSL_config() were first added to OpenSSL 1.1.0 - -=head1 COPYRIGHT - -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_CTX_ctrl.pod b/doc/ssl/SSL_CTX_ctrl.pod deleted file mode 100644 index e8386a5930..0000000000 --- a/doc/ssl/SSL_CTX_ctrl.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl - internal handling functions for SSL_CTX and SSL objects - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, void *parg); - long SSL_CTX_callback_ctrl(SSL_CTX *, int cmd, void (*fp)()); - - long SSL_ctrl(SSL *ssl, int cmd, long larg, void *parg); - long SSL_callback_ctrl(SSL *, int cmd, void (*fp)()); - -=head1 DESCRIPTION - -The SSL_*_ctrl() family of functions is used to manipulate settings of -the SSL_CTX and SSL objects. Depending on the command B<cmd> the arguments -B<larg>, B<parg>, or B<fp> are evaluated. These functions should never -be called directly. All functionalities needed are made available via -other functions or macros. - -=head1 RETURN VALUES - -The return values of the SSL*_ctrl() functions depend on the command -supplied via the B<cmd> parameter. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_dane_enable.pod b/doc/ssl/SSL_CTX_dane_enable.pod deleted file mode 100644 index fb535ec527..0000000000 --- a/doc/ssl/SSL_CTX_dane_enable.pod +++ /dev/null @@ -1,382 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable, -SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa -SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags, -SSL_dane_set_flags, SSL_dane_clear_flags - -enable DANE TLS authentication of the remote TLS server in the local -TLS client - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_dane_enable(SSL_CTX *ctx); - int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md, - uint8_t mtype, uint8_t ord); - int SSL_dane_enable(SSL *s, const char *basedomain); - int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector, - uint8_t mtype, unsigned char *data, size_t dlen); - int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki); - int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector, - uint8_t *mtype, unsigned const char **data, - size_t *dlen); - unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags); - unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags); - unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags); - unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags); - -=head1 DESCRIPTION - -These functions implement support for DANE TLSA (RFC6698 and RFC7671) -peer authentication. - -SSL_CTX_dane_enable() must be called first to initialize the shared state -required for DANE support. -Individual connections associated with the context can then enable -per-connection DANE support as appropriate. -DANE authentication is implemented in the L<X509_verify_cert(3)> function, and -applications that override L<X509_verify_cert(3)> via -L<SSL_CTX_set_cert_verify_callback(3)> are responsible to authenticate the peer -chain in whatever manner they see fit. - -SSL_CTX_dane_mtype_set() may then be called zero or more times to adjust the -supported digest algorithms. -This must be done before any SSL handles are created for the context. - -The B<mtype> argument specifies a DANE TLSA matching type and the B<md> -argument specifies the associated digest algorithm handle. -The B<ord> argument specifies a strength ordinal. -Algorithms with a larger strength ordinal are considered more secure. -Strength ordinals are used to implement RFC7671 digest algorithm agility. -Specifying a B<NULL> digest algorithm for a matching type disables -support for that matching type. -Matching type Full(0) cannot be modified or disabled. - -By default, matching type C<SHA2-256(1)> (see RFC7218 for definitions -of the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()> -with a strength ordinal of C<1> and matching type C<SHA2-512(2)> -is mapped to C<EVP_sha512()> with a strength ordinal of C<2>. - -SSL_dane_enable() must be called before the SSL handshake is initiated with -L<SSL_connect(3)> if (and only if) you want to enable DANE for that connection. -(The connection must be associated with a DANE-enabled SSL context). -The B<basedomain> argument specifies the RFC7671 TLSA base domain, -which will be the primary peer reference identifier for certificate -name checks. -Additional server names can be specified via L<SSL_add1_host(3)>. -The B<basedomain> is used as the default SNI hint if none has yet been -specified via L<SSL_set_tlsext_host_name(3)>. - -SSL_dane_tlsa_add() may then be called one or more times, to load each of the -TLSA records that apply to the remote TLS peer. -(This too must be done prior to the beginning of the SSL handshake). -The arguments specify the fields of the TLSA record. -The B<data> field is provided in binary (wire RDATA) form, not the hexadecimal -ASCII presentation form, with an explicit length passed via B<dlen>. -A return value of 0 indicates that "unusable" TLSA records (with invalid or -unsupported parameters) were provided. -A negative return value indicates an internal error in processing the record. - -The caller is expected to check the return value of each SSL_dane_tlsa_add() -call and take appropriate action if none are usable or an internal error -is encountered in processing some records. - -If no TLSA records are added successfully, DANE authentication is not enabled, -and authentication will be based on any configured traditional trust-anchors; -authentication success in this case does not mean that the peer was -DANE-authenticated. - -SSL_get0_dane_authority() can be used to get more detailed information about -the matched DANE trust-anchor after successful connection completion. -The return value is negative if DANE verification failed (or was not enabled), -0 if an EE TLSA record directly matched the leaf certificate, or a positive -number indicating the depth at which a TA record matched an issuer certificate. -The complete verified chain can be retrieved via L<SSL_get0_verified_chain(3)>. -The return value is an index into this verified chain, rather than the list of -certificates sent by the peer as returned by L<SSL_get_peer_cert_chain(3)>. - -If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain -certificate, a pointer to the matching certificate is returned via B<mcert>. -The returned address is a short-term internal reference to the certificate and -must not be freed by the application. -Applications that want to retain access to the certificate can call -L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via -L<X509_free(3)> once no longer needed. - -If no TLSA records directly matched any elements of the certificate chain, but -a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an -element of the chain, then that key is returned via B<mspki> argument (if not -NULL). -In this case the return value is the depth of the top-most element of the -validated certificate chain. -As with B<mcert> this is a short-term internal reference, and -L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and -release long-term references respectively. - -SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that -matched the peer certificate chain. -The return value indicates the match depth or failure to match just as with -SSL_get0_dane_authority(). -When the return value is non-negative, the storage pointed to by the B<usage>, -B<selector>, B<mtype> and B<data> parameters is updated to the corresponding -TLSA record fields. -The B<data> field is in binary wire form, and is therefore not NUL-terminated, -its length is returned via the B<dlen> parameter. -If any of these parameters is NULL, the corresponding field is not returned. -The B<data> parameter is set to a short-term internal-copy of the associated -data field and must not be freed by the application. -Applications that need long-term access to this field need to copy the content. - -SSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable -optional DANE verification features. -SSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable -the same features. -The B<flags> argument is a bitmask of the features to enable or disable. -The B<flags> set for an B<SSL_CTX> context are copied to each B<SSL> handle -associated with that context at the time the handle is created. -Subsequent changes in the context's B<flags> have no effect on the B<flags> set -for the handle. - -At present, the only available option is B<DANE_FLAG_NO_DANE_EE_NAMECHECKS> -which can be used to disable server name checks when authenticating via -DANE-EE(3) TLSA records. -For some applications, primarily web browsers, it is not safe to disable name -checks due to "unknown key share" attacks, in which a malicious server can -convince a client that a connection to a victim server is instead a secure -connection to the malicious server. -The malicious server may then be able to violate cross-origin scripting -restrictions. -Thus, despite the text of RFC7671, name checks are by default enabled for -DANE-EE(3) TLSA records, and can be disabled in applications where it is safe -to do so. -In particular, SMTP and XMPP clients should set this option as SRV and MX -records already make it possible for a remote domain to redirect client -connections to any server of its choice, and in any case SMTP and XMPP clients -do not execute scripts downloaded from remote servers. - -=head1 RETURN VALUES - -The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(), -SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success. -Negative return values indicate resource problems (out of memory, etc.) in the -SSL library, while a return value of B<0> indicates incorrect usage or invalid -input, such as an unsupported TLSA record certificate usage, selector or -matching type. -Invalid input also includes malformed data, either a digest length that does -not match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form) -certificate or a public key that fails to parse. - -The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a -negative value when DANE authentication failed or was not enabled, a -non-negative value indicates the chain depth at which the TLSA record matched a -chain certificate, or the depth of the top-most certificate, when the TLSA -record is a full public key that is its signer. - -The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(), -SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect -before they were called. - -=head1 EXAMPLE - -Suppose "smtp.example.com" is the MX host of the domain "example.com", and has -DNSSEC-validated TLSA records. -The calls below will perform DANE authentication and arrange to match either -the MX hostname or the destination domain name in the SMTP server certificate. -Wildcards are supported, but must match the entire label. -The actual name matched in the certificate (which might be a wildcard) is -retrieved, and must be copied by the application if it is to be retained beyond -the lifetime of the SSL connection. - - SSL_CTX *ctx; - SSL *ssl; - int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL; - int num_usable = 0; - const char *nexthop_domain = "example.com"; - const char *dane_tlsa_domain = "smtp.example.com"; - uint8_t usage, selector, mtype; - - if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) - /* handle error */ - if (SSL_CTX_dane_enable(ctx) <= 0) - /* handle error */ - - if ((ssl = SSL_new(ctx)) == NULL) - /* handle error */ - - if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) - /* handle error */ - - /* - * For many applications it is safe to skip DANE-EE(3) namechecks. Do not - * disable the checks unless "unknown key share" attacks pose no risk for - * your application. - */ - SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS); - - if (!SSL_add1_host(ssl, nexthop_domain)) - /* handle error */ - SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); - - for (... each TLSA record ...) { - unsigned char *data; - size_t len; - int ret; - - /* set usage, selector, mtype, data, len */ - - /* - * Opportunistic DANE TLS clients support only DANE-TA(2) or DANE-EE(3). - * They treat all other certificate usages, and in particular PKIX-TA(0) - * and PKIX-EE(1), as unusable. - */ - switch (usage) { - default: - case 0: /* PKIX-TA(0) */ - case 1: /* PKIX-EE(1) */ - continue; - case 2: /* DANE-TA(2) */ - case 3: /* DANE-EE(3) */ - break; - } - - ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len); - /* free data as appropriate */ - - if (ret < 0) - /* handle SSL library internal error */ - else if (ret == 0) - /* handle unusable TLSA record */ - else - ++num_usable; - } - - /* - * At this point, the verification mode is still the default SSL_VERIFY_NONE. - * Opportunistic DANE clients use unauthenticated TLS when all TLSA records - * are unusable, so continue the handshake even if authentication fails. - */ - if (num_usable == 0) { - /* Log all records unusable? */ - - /* Optionally set verify_cb to a suitable non-NULL callback. */ - SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb); - } else { - /* At least one usable record. We expect to verify the peer */ - - /* Optionally set verify_cb to a suitable non-NULL callback. */ - - /* - * Below we elect to fail the handshake when peer verification fails. - * Alternatively, use the permissive SSL_VERIFY_NONE verification mode, - * complete the handshake, check the verification status, and if not - * verified disconnect gracefully at the application layer, especially if - * application protocol supports informing the server that authentication - * failed. - */ - SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb); - } - - /* - * Load any saved session for resumption, making sure that the previous - * session applied the same security and authentication requirements that - * would be expected of a fresh connection. - */ - - /* Perform SSL_connect() handshake and handle errors here */ - - if (SSL_session_reused(ssl)) { - if (SSL_get_verify_result(ssl) == X509_V_OK) { - /* - * Resumed session was originally verified, this connection is - * authenticated. - */ - } else { - /* - * Resumed session was not originally verified, this connection is not - * authenticated. - */ - } - } else if (SSL_get_verify_result(ssl) == X509_V_OK) { - const char *peername = SSL_get0_peername(ssl); - EVP_PKEY *mspki = NULL; - - int depth = SSL_get0_dane_authority(ssl, NULL, &mspki); - if (depth >= 0) { - (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL); - printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype, - (mspki != NULL) ? "TA public key verified certificate" : - depth ? "matched TA certificate" : "matched EE certificate", - depth); - } - if (peername != NULL) { - /* Name checks were in scope and matched the peername */ - printf("Verified peername: %s\n", peername); - } - } else { - /* - * Not authenticated, presumably all TLSA rrs unusable, but possibly a - * callback suppressed connection termination despite the presence of - * usable TLSA RRs none of which matched. Do whatever is appropriate for - * fresh unauthenticated connections. - */ - } - -=head1 NOTES - -It is expected that the majority of clients employing DANE TLS will be doing -"opportunistic DANE TLS" in the sense of RFC7672 and RFC7435. -That is, they will use DANE authentication when DNSSEC-validated TLSA records -are published for a given peer, and otherwise will use unauthenticated TLS or -even cleartext. - -Such applications should generally treat any TLSA records published by the peer -with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include -them among the TLSA records used to authenticate peer connections. -In addition, some TLSA records with supported usages may be "unusable" as a -result of invalid or unsupported parameters. - -When a peer has TLSA records, but none are "usable", an opportunistic -application must avoid cleartext, but cannot authenticate the peer, -and so should generally proceed with an unauthenticated connection. -Opportunistic applications need to note the return value of each -call to SSL_dane_tlsa_add(), and if all return 0 (due to invalid -or unsupported parameters) disable peer authentication by calling -L<SSL_set_verify(3)> with B<mode> equal to B<SSL_VERIFY_NONE>. - -=head1 SEE ALSO - -L<SSL_new(3)>, -L<SSL_add1_host(3)>, -L<SSL_set_hostflags(3)>, -L<SSL_set_tlsext_host_name(3)>, -L<SSL_set_verify(3)>, -L<SSL_CTX_set_cert_verify_callback(3)>, -L<SSL_get0_verified_chain(3)>, -L<SSL_get_peer_cert_chain(3)>, -L<SSL_get_verify_result(3)>, -L<SSL_connect(3)>, -L<SSL_get0_peername(3)>, -L<X509_verify_cert(3)>, -L<X509_up_ref(3)>, -L<X509_free(3)>, -L<EVP_get_digestbyname(3)>, -L<EVP_PKEY_up_ref(3)>, -L<EVP_PKEY_free(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.1.0. - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_CTX_flush_sessions.pod b/doc/ssl/SSL_CTX_flush_sessions.pod deleted file mode 100644 index 7639451c5d..0000000000 --- a/doc/ssl/SSL_CTX_flush_sessions.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm); - void SSL_flush_sessions(SSL_CTX *ctx, long tm); - -=head1 DESCRIPTION - -SSL_CTX_flush_sessions() causes a run through the session cache of -B<ctx> to remove sessions expired at time B<tm>. - -SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions(). - -=head1 NOTES - -If enabled, the internal session cache will collect all sessions established -up to the specified maximum number (see SSL_CTX_sess_set_cache_size()). -As sessions will not be reused ones they are expired, they should be -removed from the cache to save resources. This can either be done - automatically whenever 255 new sessions were established (see -L<SSL_CTX_set_session_cache_mode(3)>) -or manually by calling SSL_CTX_flush_sessions(). - -The parameter B<tm> specifies the time which should be used for the -expiration test, in most cases the actual time given by time(0) -will be used. - -SSL_CTX_flush_sessions() will only check sessions stored in the internal -cache. When a session is found and removed, the remove_session_cb is however -called to synchronize with the external cache (see -L<SSL_CTX_sess_set_get_cb(3)>). - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_free.pod b/doc/ssl/SSL_CTX_free.pod deleted file mode 100644 index e5cc1aab77..0000000000 --- a/doc/ssl/SSL_CTX_free.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_free - free an allocated SSL_CTX object - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_free(SSL_CTX *ctx); - -=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 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 -callback will be called for each session being freed from B<ctx>'s -session cache. This implies, that all corresponding sessions from an -external session cache are removed as well. If this is not desired, the user -should explicitly unset the callback by calling -SSL_CTX_sess_set_remove_cb(B<ctx>, NULL) prior to calling SSL_CTX_free(). - -=head1 RETURN VALUES - -SSL_CTX_free() does not provide diagnostic information. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_get0_param.pod b/doc/ssl/SSL_CTX_get0_param.pod deleted file mode 100644 index 6b93737458..0000000000 --- a/doc/ssl/SSL_CTX_get0_param.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param - -get and set verification parameters - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx) - X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl) - int SSL_CTX_set1_param(SSL_CTX *ctx, X509_VERIFY_PARAM *vpm) - int SSL_set1_param(SSL *ssl, X509_VERIFY_PARAM *vpm) - -=head1 DESCRIPTION - -SSL_CTX_get0_param() and SSL_get0_param() retrieve an internal pointer to -the verification parameters for B<ctx> or B<ssl> respectively. The returned -pointer must not be freed by the calling application. - -SSL_CTX_set1_param() and SSL_set1_param() set the verification parameters -to B<vpm> for B<ctx> or B<ssl>. - -=head1 NOTES - -Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure -using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies -them to suit its needs: for example to add a hostname check. - -=head1 EXAMPLE - -Check hostname matches "www.foo.com" in peer certificate: - - X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl); - X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0); - -=head1 RETURN VALUES - -SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an -B<X509_VERIFY_PARAM> structure. - -SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0 -for failure. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_get_verify_mode.pod b/doc/ssl/SSL_CTX_get_verify_mode.pod deleted file mode 100644 index bd100344d1..0000000000 --- a/doc/ssl/SSL_CTX_get_verify_mode.pod +++ /dev/null @@ -1,59 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_get_verify_mode(const SSL_CTX *ctx); - int SSL_get_verify_mode(const SSL *ssl); - int SSL_CTX_get_verify_depth(const SSL_CTX *ctx); - int SSL_get_verify_depth(const SSL *ssl); - int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int, X509_STORE_CTX *); - int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *); - -=head1 DESCRIPTION - -SSL_CTX_get_verify_mode() returns the verification mode currently set in -B<ctx>. - -SSL_get_verify_mode() returns the verification mode currently set in -B<ssl>. - -SSL_CTX_get_verify_depth() returns the verification depth limit currently set -in B<ctx>. If no limit has been explicitly set, -1 is returned and the -default value will be used. - -SSL_get_verify_depth() returns the verification depth limit currently set -in B<ssl>. If no limit has been explicitly set, -1 is returned and the -default value will be used. - -SSL_CTX_get_verify_callback() returns a function pointer to the verification -callback currently set in B<ctx>. If no callback was explicitly set, the -NULL pointer is returned and the default callback will be used. - -SSL_get_verify_callback() returns a function pointer to the verification -callback currently set in B<ssl>. If no callback was explicitly set, the -NULL pointer is returned and the default callback will be used. - -=head1 RETURN VALUES - -See DESCRIPTION - -=head1 SEE ALSO - -L<ssl(3)>, 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 diff --git a/doc/ssl/SSL_CTX_has_client_custom_ext.pod b/doc/ssl/SSL_CTX_has_client_custom_ext.pod deleted file mode 100644 index d9e9a066ea..0000000000 --- a/doc/ssl/SSL_CTX_has_client_custom_ext.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_has_client_custom_ext - check whether a handler exists for a particular -client extension type - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_has_client_custom_ext(const SSL_CTX *ctx, unsigned int ext_type); - -=head1 DESCRIPTION - -SSL_CTX_has_client_custom_ext() checks whether a handler has been set for a -client extension of type B<ext_type> using SSL_CTX_add_client_custom_ext(). - -=head1 RETURN VALUES - -Returns 1 if a handler has been set, 0 otherwise. - -=head1 SEE ALSO - -L<ssl(3)>, -L<SSL_CTX_add_client_custom_ext(3)> - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_CTX_load_verify_locations.pod b/doc/ssl/SSL_CTX_load_verify_locations.pod deleted file mode 100644 index 59d11e03ee..0000000000 --- a/doc/ssl/SSL_CTX_load_verify_locations.pod +++ /dev/null @@ -1,161 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/ssl.h> - - 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 -format. The file can contain several CA certificates identified by - - -----BEGIN CERTIFICATE----- - ... (CA certificate in base64 encoding) ... - -----END CERTIFICATE----- - -sequences. Before, between, and after the certificates text is allowed -which can be used e.g. for descriptions of the certificates. - -The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations() -function. - -If B<CApath> is not NULL, it points to a directory containing CA certificates -in PEM format. The files each contain one CA certificate. The files are -looked up by the CA subject name hash value, which must hence be available. -If more than one CA certificate with the same name hash value exist, the -extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search -is performed in the ordering of the extension number, regardless of other -properties of the certificates. -Use the B<c_rehash> utility to create the necessary links. - -The certificates in B<CApath> are only looked up when required, e.g. when -building the certificate chain or when actually performing the verification -of a peer certificate. - -When looking up CA certificates, the OpenSSL library will first search the -certificates in B<CAfile>, then those in B<CApath>. Certificate matching -is done based on the subject name, the key identifier (if present), and the -serial number as taken from the certificate to be verified. If these data -do not match, the next certificate will be tried. If a first certificate -matching the parameters is found, the verification process will be performed; -no other certificates for the same parameters will be searched in case of -failure. - -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)> -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)>, -L<SSL_CTX_use_certificate(3)>. - -=head1 WARNINGS - -If several CA certificates matching the name, key identifier, and serial -number condition are available, only the first one will be examined. This -may lead to unexpected results if the same CA certificate is available -with different expiration dates. If a "certificate expired" verification -error occurs, no other certificate will be searched. Make sure to not -have expired certificates mixed with valid ones. - -=head1 EXAMPLES - -Generate a CA certificate file with descriptive text from the CA certificates -ca1.pem ca2.pem ca3.pem: - - #!/bin/sh - rm CAfile.pem - for i in ca1.pem ca2.pem ca3.pem ; do - openssl x509 -in $i -text >> CAfile.pem - done - -Prepare the directory /some/where/certs containing several CA certificates -for use as B<CApath>: - - cd /some/where/certs - c_rehash . - -=head1 RETURN VALUES - -For SSL_CTX_load_verify_locations the following return values can occur: - -=over 4 - -=item Z<>0 - -The operation failed because B<CAfile> and B<CApath> are NULL or the -processing at one of the locations specified failed. Check the error -stack to find out the reason. - -=item Z<>1 - -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)>, -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 diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod deleted file mode 100644 index 29387d343f..0000000000 --- a/doc/ssl/SSL_CTX_new.pod +++ /dev/null @@ -1,218 +0,0 @@ -=pod - -=head1 NAME - -TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method, -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); - - #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_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); - - #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 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: - -=over 4 - -=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 SSLv3, TLSv1, TLSv1.1 and TLSv1.2. -Applications should use these methods, and avoid the version-specific -methods described below. - -=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() - -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. - -=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. - -=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() - -A TLS/SSL connection established with these methods will only understand the -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. -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() - -These are the version-specific methods for DTLSv1.2. - -=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() - -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 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 -LSSL_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 - -The following return values can occur: - -=over 4 - -=item NULL - -The creation of a new SSL_CTX object failed. Check the error stack to find out -the reason. - -=item Pointer to an SSL_CTX object - -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_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 diff --git a/doc/ssl/SSL_CTX_sess_number.pod b/doc/ssl/SSL_CTX_sess_number.pod deleted file mode 100644 index 049c04c449..0000000000 --- a/doc/ssl/SSL_CTX_sess_number.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full - obtain session cache statistics - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_sess_number(SSL_CTX *ctx); - long SSL_CTX_sess_connect(SSL_CTX *ctx); - long SSL_CTX_sess_connect_good(SSL_CTX *ctx); - long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx); - long SSL_CTX_sess_accept(SSL_CTX *ctx); - long SSL_CTX_sess_accept_good(SSL_CTX *ctx); - long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx); - long SSL_CTX_sess_hits(SSL_CTX *ctx); - long SSL_CTX_sess_cb_hits(SSL_CTX *ctx); - long SSL_CTX_sess_misses(SSL_CTX *ctx); - long SSL_CTX_sess_timeouts(SSL_CTX *ctx); - long SSL_CTX_sess_cache_full(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_sess_number() returns the current number of sessions in the internal -session cache. - -SSL_CTX_sess_connect() returns the number of started SSL/TLS handshakes in -client mode. - -SSL_CTX_sess_connect_good() returns the number of successfully established -SSL/TLS sessions in client mode. - -SSL_CTX_sess_connect_renegotiate() returns the number of start renegotiations -in client mode. - -SSL_CTX_sess_accept() returns the number of started SSL/TLS handshakes in -server mode. - -SSL_CTX_sess_accept_good() returns the number of successfully established -SSL/TLS sessions in server mode. - -SSL_CTX_sess_accept_renegotiate() returns the number of start renegotiations -in server mode. - -SSL_CTX_sess_hits() returns the number of successfully reused sessions. -In client mode a session set with L<SSL_set_session(3)> -successfully reused is counted as a hit. In server mode a session successfully -retrieved from internal or external cache is counted as a hit. - -SSL_CTX_sess_cb_hits() returns the number of successfully retrieved sessions -from the external session cache in server mode. - -SSL_CTX_sess_misses() returns the number of sessions proposed by clients -that were not found in the internal session cache in server mode. - -SSL_CTX_sess_timeouts() returns the number of sessions proposed by clients -and either found in the internal or external session cache in server mode, - but that were invalid due to timeout. These sessions are not included in -the SSL_CTX_sess_hits() count. - -SSL_CTX_sess_cache_full() returns the number of sessions that were removed -because the maximum session cache size was exceeded. - -=head1 RETURN VALUES - -The functions return the values indicated in the DESCRIPTION section. - -=head1 SEE ALSO - -L<ssl(3)>, 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 diff --git a/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/doc/ssl/SSL_CTX_sess_set_cache_size.pod deleted file mode 100644 index 5aef10bd8e..0000000000 --- a/doc/ssl/SSL_CTX_sess_set_cache_size.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t); - long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_sess_set_cache_size() sets the size of the internal session cache -of context B<ctx> to B<t>. -This value is a hint and not an absolute; see the notes below. - -SSL_CTX_sess_get_cache_size() returns the currently valid session cache size. - -=head1 NOTES - -The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT, -currently 1024*20, so that up to 20000 sessions can be held. This size -can be modified using the SSL_CTX_sess_set_cache_size() call. A special -case is the size 0, which is used for unlimited size. - -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)> to remove -expired sessions. - -If the size of the session cache is reduced and more sessions are already -in the session cache, old session will be removed at the next time a -session shall be added. This removal is not synchronized with the -expiration of sessions. - -=head1 RETURN VALUES - -SSL_CTX_sess_set_cache_size() returns the previously valid size. - -SSL_CTX_sess_get_cache_size() returns the currently valid size. - -=head1 SEE ALSO - -L<ssl(3)>, -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 diff --git a/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/doc/ssl/SSL_CTX_sess_set_get_cb.pod deleted file mode 100644 index d2b0e04737..0000000000 --- a/doc/ssl/SSL_CTX_sess_set_get_cb.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, - int (*new_session_cb)(SSL *, SSL_SESSION *)); - void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, - void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)); - void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, - SSL_SESSION (*get_session_cb)(SSL *, 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, 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); - -=head1 DESCRIPTION - -SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically -called whenever a new session was negotiated. - -SSL_CTX_sess_set_remove_cb() sets the callback function, which is -automatically called whenever a session is removed by the SSL engine, -because it is considered faulty or the session has become obsolete because -of exceeding the timeout value. - -SSL_CTX_sess_set_get_cb() sets the callback function which is called, -whenever a SSL/TLS client proposed to resume a session but the session -could not be found in the internal session cache (see -L<SSL_CTX_set_session_cache_mode(3)>). -(SSL/TLS server only.) - -SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and -SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the -provided callback functions. If a callback function has not been set, -the NULL pointer is returned. - -=head1 NOTES - -In order to allow external session caching, synchronization with the internal -session cache is realized via callback functions. Inside these callback -functions, session can be saved to disk or put into a database using the -L<d2i_SSL_SESSION(3)> 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)>). -The new_session_cb() is passed the B<ssl> connection and the ssl session -B<sess>. If the callback returns B<0>, the session will be immediately -removed again. - -The remove_session_cb() is called, whenever the SSL engine removes a session -from the internal cache. This happens 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)> 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 -proposed by the client. The get_session_cb() is always called, also when -session caching was disabled. The get_session_cb() is passed the -B<ssl> connection, the session id of length B<length> at the memory location -B<data>. With the parameter B<copy> the callback can require the -SSL engine to increment the reference count of the SSL_SESSION object, -Normally the reference count is not incremented and therefore the -session must not be explicitly freed with -L<SSL_SESSION_free(3)>. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_sessions.pod b/doc/ssl/SSL_CTX_sessions.pod deleted file mode 100644 index bc4a55e1a2..0000000000 --- a/doc/ssl/SSL_CTX_sessions.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_sessions - access internal session cache - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_sessions() returns a pointer to the lhash databases containing the -internal session cache for B<ctx>. - -=head1 NOTES - -The sessions in the internal session cache are kept in an -L<lhash(3)> 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)> operations, so that the database must not be -modified directly but by using the -L<SSL_CTX_add_session(3)> family of functions. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set1_curves.pod b/doc/ssl/SSL_CTX_set1_curves.pod deleted file mode 100644 index b0276c80f3..0000000000 --- a/doc/ssl/SSL_CTX_set1_curves.pod +++ /dev/null @@ -1,90 +0,0 @@ -=pod - -=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 - EC supported curve functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen); - int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list); - - int SSL_set1_curves(SSL *ssl, int *clist, int clistlen); - int SSL_set1_curves_list(SSL *ssl, char *list); - - int SSL_get1_curves(SSL *ssl, int *curves); - int SSL_get_shared_curve(SSL *s, int n); - -=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 -determine the set of shared curves. - -SSL_CTX_set1_curves_list() sets the supported curves for B<ctx> to -string B<list>. The string is a colon separated list of curve NIDs or -names, for example "P-521:P-384:P-256". - -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 -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 -order. It can return zero if the client did not send a supported curves -extension. - -SSL_get_shared_curve() returns shared curve B<n> for a server-side -SSL B<ssl>. If B<n> is -1 then the total number of shared curves is -returned, which may be zero. Other than for diagnostic purposes, -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. - -All these functions are implemented as macros. - -=head1 NOTES - -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. - -=head1 RETURN VALUES - -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. - -SSL_get_shared_curve() returns the NID of shared curve B<n> or NID_undef if there -is no shared curve B<n>; or the total number of shared curves if B<n> -is -1. - -When called on a client B<ssl>, SSL_get_shared_curve() has no meaning and -returns -1. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set1_sigalgs.pod b/doc/ssl/SSL_CTX_set1_sigalgs.pod deleted file mode 100644 index e9073b99e3..0000000000 --- a/doc/ssl/SSL_CTX_set1_sigalgs.pod +++ /dev/null @@ -1,113 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set1_sigalgs, SSL_set1_sigalgs, SSL_CTX_set1_sigalgs_list, -SSL_set1_sigalgs_list, SSL_CTX_set1_client_sigalgs, -SSL_set1_client_sigalgs, SSL_CTX_set1_client_sigalgs_list, -SSL_set1_client_sigalgs_list - set supported signature algorithms - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_set1_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); - long SSL_set1_sigalgs(SSL *ssl, const int *slist, long slistlen); - long SSL_CTX_set1_sigalgs_list(SSL_CTX *ctx, const char *str); - long SSL_set1_sigalgs_list(SSL *ssl, const char *str); - - long SSL_CTX_set1_client_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); - long SSL_set1_client_sigalgs(SSL *ssl, const int *slist, long slistlen); - long SSL_CTX_set1_client_sigalgs_list(SSL_CTX *ctx, const char *str); - long SSL_set1_client_sigalgs_list(SSL *ssl, const char *str); - -=head1 DESCRIPTION - -SSL_CTX_set1_sigalgs() and SSL_set1_sigalgs() set the supported signature -algorithms for B<ctx> or B<ssl>. The array B<slist> of length B<slistlen> -must consist of pairs of NIDs corresponding to digest and public key -algorithms. - -SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list() set the supported -signature algorithms for B<ctx> or B<ssl>. The B<str> parameter -must be a null terminated string consisting or a colon separated list of -public key algorithms and digests separated by B<+>. - -SSL_CTX_set1_client_sigalgs(), SSL_set1_client_sigalgs(), -SSL_CTX_set1_client_sigalgs_list() and SSL_set1_client_sigalgs_list() set -signature algorithms related to client authentication, otherwise they are -identical to SSL_CTX_set1_sigalgs(), SSL_set1_sigalgs(), -SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list(). - -All these functions are implemented as macros. The signature algorithm -parameter (integer array or string) is not freed: the application should -free it, if necessary. - -=head1 NOTES - -If an application wishes to allow the setting of signature algorithms -as one of many user configurable options it should consider using the more -flexible SSL_CONF API instead. - -The signature algorithms set by a client are used directly in the supported -signature algorithm in the client hello message. - -The supported signature algorithms set by a server are not sent to the -client but are used to determine the set of shared signature algorithms -and (if server preferences are set with SSL_OP_CIPHER_SERVER_PREFERENCE) -their order. - -The client authentication signature algorithms set by a server are sent -in a certificate request message if client authentication is enabled, -otherwise they are unused. - -Similarly client authentication signature algorithms set by a client are -used to determined the set of client authentication shared signature -algorithms. - -Signature algorithms will neither be advertised nor used if the security level -prohibits them (for example SHA1 if the security level is 4 or more). - -Currently the NID_md5, NID_sha1, NID_sha224, NID_sha256, NID_sha384 and -NID_sha512 digest NIDs are supported and the public key algorithm NIDs -EVP_PKEY_RSA, EVP_PKEY_DSA and EVP_PKEY_EC. - -The short or long name values for digests can be used in a string (for -example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and -the public key algorithm strings "RSA", "DSA" or "ECDSA". - -The use of MD5 as a digest is strongly discouraged due to security weaknesses. - -=head1 EXAMPLES - -Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA -using an array: - - const int slist[] = {NID_sha256, EVP_PKEY_EC, NID_sha256, EVP_PKEY_RSA}; - - SSL_CTX_set1_sigalgs(ctx, slist, 4); - -Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA -using a string: - - SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256"); - -=head1 RETURN VALUES - -All these functions return 1 for success and 0 for failure. - -=head1 SEE ALSO - -L<ssl(3)>, L<SSL_get_shared_sigalgs(3)>, -L<SSL_CONF_CTX_new(3)> - -=head1 COPYRIGHT - -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_CTX_set1_verify_cert_store.pod b/doc/ssl/SSL_CTX_set1_verify_cert_store.pod deleted file mode 100644 index bfe8b70af9..0000000000 --- a/doc/ssl/SSL_CTX_set1_verify_cert_store.pod +++ /dev/null @@ -1,100 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set0_verify_cert_store, SSL_CTX_set1_verify_cert_store, -SSL_CTX_set0_chain_cert_store, SSL_CTX_set1_chain_cert_store, -SSL_set0_verify_cert_store, SSL_set1_verify_cert_store, -SSL_set0_chain_cert_store, SSL_set1_chain_cert_store - set certificate -verification or chain store - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set0_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); - int SSL_CTX_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); - int SSL_CTX_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); - int SSL_CTX_set1_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); - - int SSL_set0_verify_cert_store(SSL *ctx, X509_STORE *st); - int SSL_set1_verify_cert_store(SSL *ctx, X509_STORE *st); - int SSL_set0_chain_cert_store(SSL *ctx, X509_STORE *st); - int SSL_set1_chain_cert_store(SSL *ctx, X509_STORE *st); - -=head1 DESCRIPTION - -SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store() -set the certificate store used for certificate verification to B<st>. - -SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store() -set the certificate store used for certificate chain building to B<st>. - -SSL_set0_verify_cert_store(), SSL_set1_verify_cert_store(), -SSL_set0_chain_cert_store() and SSL_set1_chain_cert_store() are similar -except they apply to SSL structure B<ssl>. - -All these functions are implemented as macros. Those containing a B<1> -increment the reference count of the supplied store so it must -be freed at some point after the operation. Those containing a B<0> do -not increment reference counts and the supplied store B<MUST NOT> be freed -after the operation. - -=head1 NOTES - -The stores pointers associated with an SSL_CTX structure are copied to any SSL -structures when SSL_new() is called. As a result SSL structures will not be -affected if the parent SSL_CTX store pointer is set to a new value. - -The verification store is used to verify the certificate chain sent by the -peer: that is an SSL/TLS client will use the verification store to verify -the server's certificate chain and a SSL/TLS server will use it to verify -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)> 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 -is disabled. - -If the chain or the verification store is not set then the store associated -with the parent SSL_CTX is used instead to retain compatibility with previous -versions of OpenSSL. - -=head1 RETURN VALUES - -All these functions return 1 for success and 0 for failure. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_alpn_select_cb.pod b/doc/ssl/SSL_CTX_set_alpn_select_cb.pod deleted file mode 100644 index 59acbad545..0000000000 --- a/doc/ssl/SSL_CTX_set_alpn_select_cb.pod +++ /dev/null @@ -1,136 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, -SSL_select_next_proto, SSL_get0_alpn_selected - handle application layer -protocol negotiation (ALPN) - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos, - unsigned int protos_len); - int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos, - unsigned int protos_len); - void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx, - int (*cb) (SSL *ssl, - const unsigned char **out, - unsigned char *outlen, - const unsigned char *in, - unsigned int inlen, - void *arg), void *arg); - int SSL_select_next_proto(unsigned char **out, unsigned char *outlen, - const unsigned char *server, - unsigned int server_len, - const unsigned char *client, - unsigned int client_len) - void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, - unsigned int *len); - -=head1 DESCRIPTION - -SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to -set the list of protocols available to be negotiated. The B<protos> must be in -protocol-list format, described below. The length of B<protos> is specified in -B<protos_len>. - -SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a -server to select which protocol to use for the incoming connection. When B<cb> -is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to -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<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 -implements the standard protocol selection. It is expected that this function -is called from the application callback B<cb>. The protocol data in B<server>, -B<server_len> and B<client>, B<client_len> must be in the protocol-list format -described below. The first item in the B<server>, B<server_len> list that -matches an item in the B<client>, B<client_len> list is selected, and returned -in B<out>, B<outlen>. The B<out> value will point into either B<server> or -B<client>, so it should be copied immediately. If no match is found, the first -item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This -function can also be used in the NPN callback. - -SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data> -with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len> -is set to 0 if no protocol has been selected. B<data> must not be freed. - -=head1 NOTES - -The protocol-lists must be in wire-format, which is defined as a vector of -non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not -included in the length. Each string is limited to 255 bytes. A byte-string -length of 0 is invalid. A truncated byte-string is invalid. The length of the -vector is not in the vector itself, but in a separate variable. - -Example: - - unsigned char vector[] = { - 6, 's', 'p', 'd', 'y', '/', '1', - 8, 'h', 't', 't', 'p', '/', '1', '.', '1' - }; - unsigned int length = sizeof(vector); - -The ALPN callback is executed after the servername callback; as that servername -callback may update the SSL_CTX, and subsequently, the ALPN callback. - -If there is no ALPN proposed in the ClientHello, the ALPN callback is not -invoked. - -=head1 RETURN VALUES - -SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and -non-0 on failure. WARNING: these functions reverse the return value convention. - -SSL_select_next_proto() returns one of the following: - -=over 4 - -=item OPENSSL_NPN_NEGOTIATED - -A match was found and is returned in B<out>, B<outlen>. - -=item OPENSSL_NPN_NO_OVERLAP - -No match was found. The first item in B<client>, B<client_len> is returned in -B<out>, B<outlen>. - -=back - -The ALPN select callback B<cb>, must return one of the following: - -=over 4 - -=item SSL_TLSEXT_ERR_OK - -ALPN protocol selected. - -=item SSL_TLSEXT_ERR_NOACK - -ALPN protocol not selected. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_cert_cb.pod b/doc/ssl/SSL_CTX_set_cert_cb.pod deleted file mode 100644 index eaa7a4e3cb..0000000000 --- a/doc/ssl/SSL_CTX_set_cert_cb.pod +++ /dev/null @@ -1,77 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg); - void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); - - int (*cert_cb)(SSL *ssl, void *arg); - -=head1 DESCRIPTION - -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 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 -the passed B<ssl> structure and set or clear any appropriate certificates. If -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)> 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, -if required to continue. - -=head1 NOTES - -An application will typically call SSL_use_certificate() and -SSL_use_PrivateKey() to set the end entity certificate and private key. -It can add intermediate and optionally the root CA certificates using -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 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. - -A more advanced callback might examine the handshake parameters and set -whatever chain is appropriate. For example a legacy client supporting only -TLS v1.0 might receive a certificate chain signed using SHA1 whereas a -TLS v1.2 client which advertises support for SHA256 could receive a chain -using SHA256. - -Normal server sanity checks are performed on any certificates set -by the callback. So if an EC chain is set for a curve the client does not -support it will B<not> be used. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_cert_store.pod b/doc/ssl/SSL_CTX_set_cert_store.pod deleted file mode 100644 index 7f7a794bdf..0000000000 --- a/doc/ssl/SSL_CTX_set_cert_store.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_cert_store, SSL_CTX_get_cert_store - manipulate X509 certificate verification storage - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *store); - X509_STORE *SSL_CTX_get_cert_store(const SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_set_cert_store() sets/replaces the certificate verification storage -of B<ctx> to/with B<store>. If another X509_STORE object is currently -set in B<ctx>, it will be X509_STORE_free()ed. - -SSL_CTX_get_cert_store() returns a pointer to the current certificate -verification storage. - -=head1 NOTES - -In order to verify the certificates presented by the peer, trusted CA -certificates must be accessed. These CA certificates are made available -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)>. -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)> -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)> family of functions. -This document must therefore be updated when documentation about the -X509_STORE object and its handling becomes available. - -=head1 RESTRICTIONS - -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 -functions such as SSL_CTX_set1_verify_cert_store() instead. - -=head1 RETURN VALUES - -SSL_CTX_set_cert_store() does not return diagnostic output. - -SSL_CTX_get_cert_store() returns the current setting. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/doc/ssl/SSL_CTX_set_cert_verify_callback.pod deleted file mode 100644 index af303f25fa..0000000000 --- a/doc/ssl/SSL_CTX_set_cert_verify_callback.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - 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)> is called. - -=head1 NOTES - -Whenever a certificate is verified during a SSL/TLS handshake, a verification -function is called. If the application does not explicitly specify a -verification callback function, the built-in verification function is used. -If a verification callback I<callback> is specified via -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 -argument I<arg> is specified by the application when setting I<callback>. - -I<callback> should return 1 to indicate verification success and 0 to -indicate verification failure. If SSL_VERIFY_PEER is set and I<callback> -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! - -Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback> -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)> -family of functions. - -Providing a complete verification procedure including certificate purpose -settings etc is a complex task. The built-in procedure is quite powerful -and in most cases it should be sufficient to modify its behaviour using -the B<verify_callback> function. - -=head1 BUGS - -SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. - -=head1 SEE ALSO - -L<ssl(3)>, L<SSL_CTX_set_verify(3)>, -L<SSL_get_verify_result(3)>, -L<SSL_CTX_load_verify_locations(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 diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod deleted file mode 100644 index 4e66917bab..0000000000 --- a/doc/ssl/SSL_CTX_set_cipher_list.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str); - int SSL_set_cipher_list(SSL *ssl, const char *str); - -=head1 DESCRIPTION - -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)>. 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>. - -=head1 NOTES - -The control string B<str> should be universally usable and not depend -on details of the library configuration (ciphers compiled in). Thus no -syntax checking takes place. Items that are not recognized, because the -corresponding ciphers are not compiled in or because they are mistyped, -are simply ignored. Failure is only flagged if no ciphers could be collected -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 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 ciphers using DHE need a certificate and key and additional DH-parameters -(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)>). - -When these conditions are not met for any cipher in the list (e.g. a -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. - -=head1 RETURN VALUES - -SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher -could be selected and 0 on complete failure. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_client_CA_list.pod b/doc/ssl/SSL_CTX_set_client_CA_list.pod deleted file mode 100644 index 0252e7b521..0000000000 --- a/doc/ssl/SSL_CTX_set_client_CA_list.pod +++ /dev/null @@ -1,103 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA, -SSL_add_client_CA - set list of CAs sent to the client when requesting a -client certificate - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); - void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); - int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); - int SSL_add_client_CA(SSL *ssl, X509 *cacert); - -=head1 DESCRIPTION - -SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when -requesting a client certificate for B<ctx>. - -SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when -requesting a client certificate for the chosen B<ssl>, overriding the -setting valid for B<ssl>'s SSL_CTX object. - -SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the -list of CAs sent to the client when requesting a client certificate for -B<ctx>. - -SSL_add_client_CA() adds the CA name extracted from B<cacert> to the -list of CAs sent to the client when requesting a client certificate for -the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object. - -=head1 NOTES - -When a TLS/SSL server requests a client certificate (see -B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which -it will accept certificates, to the client. - -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)> -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)> -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 -items the list of client CAs. If no list was specified before using -SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client -CA list for B<ctx> or B<ssl> (as appropriate) is opened. - -These functions are only useful for TLS/SSL servers. - -=head1 RETURN VALUES - -SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return -diagnostic information. - -SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return -values: - -=over 4 - -=item Z<>0 - -A failure while manipulating the STACK_OF(X509_NAME) object occurred or -the X509_NAME could not be extracted from B<cacert>. Check the error stack -to find out the reason. - -=item Z<>1 - -The operation succeeded. - -=back - -=head1 EXAMPLES - -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)); - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/doc/ssl/SSL_CTX_set_client_cert_cb.pod deleted file mode 100644 index aed7d4f0c1..0000000000 --- a/doc/ssl/SSL_CTX_set_client_cert_cb.pod +++ /dev/null @@ -1,103 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); - int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); - int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey); - -=head1 DESCRIPTION - -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 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. - -client_cert_cb() is the application defined callback. If it wants to -set a certificate, a certificate/private key combination must be set -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)> -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 -about the state of the last call, if required to continue. - -=head1 NOTES - -During a handshake (or renegotiation) a server may request a certificate -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)> 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 -library. Using the callback function it is possible to implement a proper -selection routine or to allow a user interaction to choose the certificate to -be sent. - -If a callback function is defined and no certificate was yet defined for the -SSL object, the callback function will be called. -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)>. -If the callback returns no certificate, the OpenSSL library will not send -a certificate. - -=head1 BUGS - -The client_cert_cb() cannot return a complete certificate chain, it can -only return one client certificate. If the chain only has a length of 2, -the root CA certificate may be omitted according to the TLS standard and -thus a standard conforming answer can be sent to the server. For a -longer chain, the client must send the complete chain (with the option -to leave out the root CA certificate). This can only be accomplished by -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)> -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 -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)> 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)>, 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 diff --git a/doc/ssl/SSL_CTX_set_ct_validation_callback.pod b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod deleted file mode 100644 index c481ecbc87..0000000000 --- a/doc/ssl/SSL_CTX_set_ct_validation_callback.pod +++ /dev/null @@ -1,138 +0,0 @@ -=pod - -=head1 NAME - -SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct, -SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, -SSL_ct_is_enabled, SSL_CTX_ct_is_enabled - -control Certificate Transparency policy - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_enable_ct(SSL *s, int validation_mode); - int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode); - int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback, - void *arg); - int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, - ssl_ct_validation_cb callback, - void *arg); - void SSL_disable_ct(SSL *s); - void SSL_CTX_disable_ct(SSL_CTX *ctx); - int SSL_ct_is_enabled(const SSL *s); - int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_enable_ct() and SSL_CTX_enable_ct() enable the processing of signed -certificate timestamps (SCTs) either for a given SSL connection or for all -connections that share the given SSL context, respectively. -This is accomplished by setting a built-in CT validation callback. -The behaviour of the callback is determined by the B<validation_mode> argument, -which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or -B<SSL_CT_VALIDATION_STRICT> as described below. - -If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full -TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer -presents no valid SCTs the handshake will be aborted. -If the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue -despite lack of valid SCTs. -However, in that case if the verification status before the built-in callback -was B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the -callback. -Applications can call L<SSL_get_verify_result(3)> to check the status at -handshake completion, even after session resumption since the verification -status is part of the saved session state. -See L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>. - -If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the -handshake continues, and the verification status is not modified, regardless of -the validation status of any SCTs. -The application can still inspect the validation status of the SCTs at -handshake completion. -Note that with session resumption there will not be any SCTs presented during -the handshake. -Therefore, in applications that delay SCT policy enforcement until after -handshake completion, such delayed SCT checks should only be performed when the -session is not resumed. - -SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() -register a custom callback that may implement a different policy than either of -the above. -This callback can examine the peer's SCTs and determine whether they are -sufficient to allow the connection to continue. -The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE> -and the callback returns a non-positive result. - -An arbitrary callback context argument, B<arg>, can be passed in when setting -the callback. -This will be passed to the callback whenever it is invoked. -Ownership of this context remains with the caller. - -If no callback is set, SCTs will not be requested and Certificate Transparency -validation will not occur. - -No callback will be invoked when the peer presents no certificate, e.g. by -employing an anonymous (aNULL) ciphersuite. -In that case the handshake continues as it would had no callback been -requested. -Callbacks are also not invoked when the peer certificate chain is invalid or -validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509 -PKI, or no X.509 PKI at all, respectively. -Clients that require SCTs are expected to not have enabled any aNULL ciphers -nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA -records. - -SSL_disable_ct() and SSL_CTX_disable_ct() turn off CT processing, whether -enabled via the built-in or the custom callbacks, by setting a NULL callback. -These may be implemented as macros. - -SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is -enabled via either SSL_enable_ct() or a non-null custom callback, and 0 -otherwise. - -=head1 NOTES - -When SCT processing is enabled, OCSP stapling will be enabled. This is because -one possible source of SCTs is the OCSP response from a server. - -=head1 RESTRICTIONS - -Certificate Transparency validation cannot be enabled and so a callback cannot -be set if a custom client extension handler has been registered to handle SCT -extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>). - -=head1 RETURN VALUES - -SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and -SSL_set_ct_validation_callback() return 1 if the B<callback> is successfully -set. -They return 0 if an error occurs, e.g. a custom client extension handler has -been setup to handle SCTs. - -SSL_disable_ct() and SSL_CTX_disable_ct() do not return a result. - -SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT -validation callback is set, or 0 if no callback (or equivalently a NULL -callback) is set. - -=head1 SEE ALSO - -L<ssl(3)>, -<SSL_get_verify_result(3)>, -L<SSL_session_reused(3)>, -L<SSL_set_verify(3)>, -L<SSL_CTX_set_verify(3)>, -L<ssl_ct_validation_cb(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 diff --git a/doc/ssl/SSL_CTX_set_ctlog_list_file.pod b/doc/ssl/SSL_CTX_set_ctlog_list_file.pod deleted file mode 100644 index 4a2fa946fe..0000000000 --- a/doc/ssl/SSL_CTX_set_ctlog_list_file.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_default_ctlog_list_file, SSL_CTX_set_ctlog_list_file - -load a Certificate Transparency log list from a file - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set_default_ctlog_list_file(SSL_CTX *ctx); - int SSL_CTX_set_ctlog_list_file(SSL_CTX *ctx, const char *path); - -=head1 DESCRIPTION - -SSL_CTX_set_default_ctlog_list_file() loads a list of Certificate Transparency -(CT) logs from the default file location, "ct_log_list.cnf", found in the -directory where OpenSSL is installed. - -SSL_CTX_set_ctlog_list_file() loads a list of CT logs from a specific path. -See L<CTLOG_STORE_new(3)> for the file format. - -=head1 NOTES - -These functions will not clear the existing CT log list - it will be appended -to. To replace the existing list, use L<SSL_CTX_set0_ctlog_store> first. - -If an error occurs whilst parsing a particular log entry in the file, that log -entry will be skipped. - -=head1 RETURN VALUES - -SSL_CTX_set_default_ctlog_list_file() and SSL_CTX_set_ctlog_list_file() -return 1 if the log list is successfully loaded, and 0 if an error occurs. In -the case of an error, the log list may have been partially loaded. - -=head1 SEE ALSO - -L<ssl(3)>, -L<SSL_CTX_set_ct_validation_callback(3)>, -L<CTLOG_STORE_new(3)> - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/doc/ssl/SSL_CTX_set_default_passwd_cb.pod deleted file mode 100644 index 2196906141..0000000000 --- a/doc/ssl/SSL_CTX_set_default_passwd_cb.pod +++ /dev/null @@ -1,113 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/ssl.h> - - void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb); - void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u); - pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx); - void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx); - - 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 userdata, B<u>, -which will be provided to the password callback on invocation. - -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 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 userdata storage and the -callback only returns the password already stored. - -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 -impossible. - -Other items in PEM formatting (certificates) can also be encrypted, it is -however not usual, as certificate information is considered public. - -=head1 RETURN VALUES - -These functions do not provide diagnostic information. - -=head1 EXAMPLES - -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 my_cb(char *buf, int size, int rwflag, void *u) - { - 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)>, -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 diff --git a/doc/ssl/SSL_CTX_set_generate_session_id.pod b/doc/ssl/SSL_CTX_set_generate_session_id.pod deleted file mode 100644 index 515fd251d2..0000000000 --- a/doc/ssl/SSL_CTX_set_generate_session_id.pod +++ /dev/null @@ -1,137 +0,0 @@ -=pod - -=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) - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id, - unsigned int *id_len); - - 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); - -=head1 DESCRIPTION - -SSL_CTX_set_generate_session_id() sets the callback function for generating -new session ids for SSL/TLS sessions for B<ctx> to be B<cb>. - -SSL_set_generate_session_id() sets the callback function for generating -new session ids for SSL/TLS sessions for B<ssl> to be B<cb>. - -SSL_has_matching_session_id() checks, whether a session with id B<id> -(of length B<id_len>) is already contained in the internal session cache -of the parent context of B<ssl>. - -=head1 NOTES - -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 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. - -Without a callback being set, an OpenSSL server will generate a unique -session id from pseudo random numbers of the maximum possible length. -Using the callback function, the session id can be changed to contain -additional information like e.g. a host id in order to improve load balancing -or external caching techniques. - -The callback function receives a pointer to the memory location to put -B<id> into and a pointer to the maximum allowed length B<id_len>. The -buffer at location B<id> is only guaranteed to have the size B<id_len>. -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. - -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^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 -a unique sequence number into the session id, uniqueness could easily be -achieved without randomness added (it should however be taken care that -no confidential information is leaked this way). If the application can not -guarantee uniqueness, it is recommended to use the maximum B<id_len> and -fill in the bytes not used to code special information with random data -to avoid collisions. - -SSL_has_matching_session_id() will only query the internal session cache, -not the external one. Since the session id is generated before the -handshake is completed, it is not immediately added to the cache. If -another thread is using the same internal session cache, a race condition -can occur in that another thread generates the same session id. -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. - -The callback must return 0 if it cannot generate a session id for whatever -reason and return 1 on success. - -=head1 EXAMPLES - -The callback function listed will generate a session id with the -server id given, and will fill the rest with pseudo random bytes: - - const char session_id_prefix = "www-18"; - - #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; - 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) - return 0; - return 1; - } - - -=head1 RETURN VALUES - -SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id() -always return 1. - -SSL_has_matching_session_id() returns 1 if another session with the -same id is already in the cache. - -=head1 SEE ALSO - -L<ssl(3)>, L<SSL_get_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 diff --git a/doc/ssl/SSL_CTX_set_info_callback.pod b/doc/ssl/SSL_CTX_set_info_callback.pod deleted file mode 100644 index f36f217e3b..0000000000 --- a/doc/ssl/SSL_CTX_set_info_callback.pod +++ /dev/null @@ -1,162 +0,0 @@ -=pod - -=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 - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)()); - void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))(); - - void SSL_set_info_callback(SSL *ssl, void (*callback)()); - void (*SSL_get_info_callback(const SSL *ssl))(); - -=head1 DESCRIPTION - -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, 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. -When B<callback> is NULL, the callback setting currently valid for -B<ctx> is used. - -SSL_CTX_get_info_callback() returns a pointer to the currently set information -callback function for B<ctx>. - -SSL_get_info_callback() returns a pointer to the currently set information -callback function for B<ssl>. - -=head1 NOTES - -When setting up a connection and during use, it is possible to obtain state -information from the SSL/TLS engine. When set, an information callback function -is called whenever the state changes, an alert appears, or an error occurs. - -The callback function is called as B<callback(SSL *ssl, int where, int ret)>. -The B<where> argument specifies information about where (in which context) -the callback function was called. If B<ret> is 0, an error condition occurred. -If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert -information. - -B<where> is a bitmask made up of the following bits: - -=over 4 - -=item SSL_CB_LOOP - -Callback has been called to indicate state change inside a loop. - -=item SSL_CB_EXIT - -Callback has been called to indicate error exit of a handshake function. -(May be soft error with retry option for non-blocking setups.) - -=item SSL_CB_READ - -Callback has been called during read operation. - -=item SSL_CB_WRITE - -Callback has been called during write operation. - -=item SSL_CB_ALERT - -Callback has been called due to an alert being sent or received. - -=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ) - -=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE) - -=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP) - -=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT) - -=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP) - -=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT) - -=item SSL_CB_HANDSHAKE_START - -Callback has been called because a new handshake is started. - -=item SSL_CB_HANDSHAKE_DONE 0x20 - -Callback has been called because a handshake is finished. - -=back - -The current state information can be obtained using the -L<SSL_state_string(3)> family of functions. - -The B<ret> information can be evaluated using the -L<SSL_alert_type_string(3)> family of functions. - -=head1 RETURN VALUES - -SSL_set_info_callback() does not provide diagnostic information. - -SSL_get_info_callback() returns the current setting. - -=head1 EXAMPLES - -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; - - 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 (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)>, 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 diff --git a/doc/ssl/SSL_CTX_set_max_cert_list.pod b/doc/ssl/SSL_CTX_set_max_cert_list.pod deleted file mode 100644 index 482751e73c..0000000000 --- a/doc/ssl/SSL_CTX_set_max_cert_list.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=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 size for the peer's certificate chain - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size); - long SSL_CTX_get_max_cert_list(SSL_CTX *ctx); - - long SSL_set_max_cert_list(SSL *ssl, long size); - long SSL_get_max_cert_list(SSL *ctx); - -=head1 DESCRIPTION - -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)> is being called. - -SSL_CTX_get_max_cert_list() returns the currently set maximum size for B<ctx>. - -SSL_set_max_cert_list() sets the maximum size allowed for the peer's -certificate chain for B<ssl> to be <size> bytes. This setting stays valid -until a new value is set. - -SSL_get_max_cert_list() returns the currently set maximum size for B<ssl>. - -=head1 NOTES - -During the handshake process, the peer may send a certificate chain. -The TLS/SSL standard does not give any maximum size of the certificate chain. -The OpenSSL library handles incoming data by a dynamically allocated buffer. -In order to prevent this buffer from growing without bounds due to data -received from a faulty or malicious peer, a maximum size for the certificate -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)>, and certificates -without special extensions have a typical size of 1-2kB). - -For special applications it can be necessary to extend the maximum certificate -chain size allowed to be sent by the peer, see e.g. the work on -"Internet X.509 Public Key Infrastructure Proxy Certificate Profile" -and "TLS Delegation Protocol" at http://www.ietf.org/ and -http://www.globus.org/ . - -Under normal conditions it should never be necessary to set a value smaller -than the default, as the buffer is handled dynamically and only uses the -memory actually required by the data sent by the peer. - -If the maximum certificate chain size allowed is exceeded, the handshake will -fail with a SSL_R_EXCESSIVE_MESSAGE_SIZE error. - -=head1 RETURN VALUES - -SSL_CTX_set_max_cert_list() and SSL_set_max_cert_list() return the previously -set value. - -SSL_CTX_get_max_cert_list() and SSL_get_max_cert_list() return the currently -set value. - -=head1 SEE ALSO - -L<ssl(3)>, L<SSL_new(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 diff --git a/doc/ssl/SSL_CTX_set_min_proto_version.pod b/doc/ssl/SSL_CTX_set_min_proto_version.pod deleted file mode 100644 index 3e9fe80b70..0000000000 --- a/doc/ssl/SSL_CTX_set_min_proto_version.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version, -SSL_set_min_proto_version, SSL_set_max_proto_version - Set minimum -and maximum supported protocol version - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version); - int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version); - int SSL_set_min_proto_version(SSL *ssl, int version); - int SSL_set_max_proto_version(SSL *ssl, int version); - -=head1 DESCRIPTION - -The functions set the minimum and maximum supported protocol versions -for the B<ctx> or B<ssl>. -This works in combination with the options set via -L<SSL_CTX_set_options(3)> that also make it possible to disable -specific protocol versions. -Use these functions instead of disabling specific protocol versions. - -Setting the minimum or maximum version to 0, will enable protocol -versions down to the lowest version, or up to the highest version -supported by the library, respectively. - -Currently supported versions are B<SSL3_VERSION>, B<TLS1_VERSION>, -B<TLS1_1_VERSION>, B<TLS1_2_VERSION> for TLS and B<DTLS1_VERSION>, -B<DTLS1_2_VERSION> for DTLS. - -=head1 RETURN VALUES - -These functions return 1 on success and 0 on failure. - -=head1 NOTES - -All these functions are implemented using macros. - -=head1 HISTORY - -The functions were added in OpenSSL 1.1.0 - -=head1 SEE ALSO - -L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)> - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_CTX_set_mode.pod b/doc/ssl/SSL_CTX_set_mode.pod deleted file mode 100644 index 1b3e783ad6..0000000000 --- a/doc/ssl/SSL_CTX_set_mode.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); - long SSL_set_mode(SSL *ssl, long mode); - - long SSL_CTX_get_mode(SSL_CTX *ctx); - long SSL_get_mode(SSL *ssl); - -=head1 DESCRIPTION - -SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>. -Options already set before are not cleared. - -SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>. -Options already set before are not cleared. - -SSL_CTX_get_mode() returns the mode set for B<ctx>. - -SSL_get_mode() returns the mode set for B<ssl>. - -=head1 NOTES - -The following mode changes are available: - -=over 4 - -=item SSL_MODE_ENABLE_PARTIAL_WRITE - -Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success -when just a single record has been written). When not set (the default), -SSL_write() will only report success once the complete chunk was written. -Once SSL_write() returns with r, r bytes have been successfully written -and the next call to SSL_write() must only send the n-r bytes left, -imitating the behaviour of write(). - -=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER - -Make it possible to retry SSL_write() with changed buffer location -(the buffer contents must stay the same). This is not the default to avoid -the misconception that non-blocking SSL_write() behaves like -non-blocking write(). - -=item SSL_MODE_AUTO_RETRY - -Never bother the application with retries if the transport is blocking. -If a renegotiation take place during normal operation, a -L<SSL_read(3)> 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. -In a blocking environment, applications are not always prepared to -deal with read/write operations returning without success report. The -flag SSL_MODE_AUTO_RETRY will cause read/write operations to only -return after the handshake and successful completion. - -=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. -Using this flag can -save around 34k per idle SSL connection. -This flag has no effect on SSL v2 connections, or on DTLS connections. - -=item SSL_MODE_SEND_FALLBACK_SCSV - -Send TLS_FALLBACK_SCSV in the ClientHello. -To be set only by applications that reconnect with a downgraded protocol -version; see draft-ietf-tls-downgrade-scsv-00 for details. - -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 - -SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask -after adding B<mode>. - -SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask. - -=head1 SEE ALSO - -L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)>, L<SSL_get_error(3)> - -=head1 HISTORY - -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 diff --git a/doc/ssl/SSL_CTX_set_msg_callback.pod b/doc/ssl/SSL_CTX_set_msg_callback.pod deleted file mode 100644 index 9546e75124..0000000000 --- a/doc/ssl/SSL_CTX_set_msg_callback.pod +++ /dev/null @@ -1,103 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/ssl.h> - - void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); - void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg); - - void SSL_set_msg_callback(SSL *ssl, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); - void SSL_set_msg_callback_arg(SSL *ssl, void *arg); - -=head1 DESCRIPTION - -SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to -define a message callback function I<cb> for observing all SSL/TLS -protocol messages (such as handshake messages) that are received or -sent. SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg() -can be used to set argument I<arg> to the callback function, which is -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_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. - -When I<cb> is called by the SSL/TLS library for a protocol message, -the function arguments have the following meaning: - -=over 4 - -=item I<write_p> - -This flag is B<0> when a protocol message has been received and B<1> -when a protocol message has been sent. - -=item I<version> - -The protocol version according to which the protocol message is -interpreted by the library. Currently, this is one of -B<SSL2_VERSION>, B<SSL3_VERSION> and B<TLS1_VERSION> (for SSL 2.0, SSL -3.0 and TLS 1.0, respectively). - -=item I<content_type> - -In the case of SSL 2.0, this is always B<0>. In the case of SSL 3.0 -or TLS 1.0, this is one of the B<ContentType> values defined in the -protocol specification (B<change_cipher_spec(20)>, B<alert(21)>, -B<handshake(22)>; but never B<application_data(23)> because the -callback will only be called for protocol messages). - -=item I<buf>, I<len> - -I<buf> points to a buffer containing the protocol message, which -consists of I<len> bytes. The buffer is no longer valid after the -callback function has returned. - -=item I<ssl> - -The B<SSL> object that received or sent the message. - -=item I<arg> - -The user-defined argument optionally defined by -SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg(). - -=back - -=head1 NOTES - -Protocol messages are passed to the callback function after decryption -and fragment collection where applicable. (Thus record boundaries are -not visible.) - -If processing a received protocol message results in an error, -the callback function may not be called. For example, the callback -function will never see messages that are considered too large to be -processed. - -Due to automatic protocol version negotiation, I<version> is not -necessarily the protocol version used by the sender of the message: If -a TLS 1.0 ClientHello message is received by an SSL 3.0-only server, -I<version> will be B<SSL3_VERSION>. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod deleted file mode 100644 index 63609f3a31..0000000000 --- a/doc/ssl/SSL_CTX_set_options.pod +++ /dev/null @@ -1,300 +0,0 @@ -=pod - -=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 - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_set_options(SSL_CTX *ctx, long options); - long SSL_set_options(SSL *ssl, long options); - - long SSL_CTX_clear_options(SSL_CTX *ctx, long options); - long SSL_clear_options(SSL *ssl, long options); - - long SSL_CTX_get_options(SSL_CTX *ctx); - long SSL_get_options(SSL *ssl); - - long SSL_get_secure_renegotiation_support(SSL *ssl); - -=head1 DESCRIPTION - -SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. -Options already set before are not cleared! - -SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. -Options already set before are not cleared! - -SSL_CTX_clear_options() clears the options set via bitmask in B<options> -to B<ctx>. - -SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>. - -SSL_CTX_get_options() returns the options set for B<ctx>. - -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 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)> 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 -option setting is copied. Changes to B<ctx> do not affect already created -SSL objects. SSL_clear() does not affect the settings. - -The following B<bug workaround> options are available: - -=over 4 - -=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG - -... - -=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER - -... - -=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG - -Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X. -OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers. - -=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG - -... - -=item SSL_OP_TLS_D5_BUG - -... - -=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS - -Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol -vulnerability affecting CBC ciphers, which cannot be handled by some -broken SSL implementations. This option has no effect for connections -using other ciphers. - -=item SSL_OP_TLSEXT_PADDING - -Adds a padding extension to ensure the ClientHello size is never between -256 and 511 bytes in length. This is needed as a workaround for some -implementations. - -=item SSL_OP_ALL - -All of the above bug workarounds. - -=back - -It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround -options if compatibility with somewhat broken implementations is -desired. - -The following B<modifying> options are available: - -=over 4 - -=item SSL_OP_TLS_ROLLBACK_BUG - -Disable version rollback attack detection. - -During the client key exchange, the client must send the same information -about acceptable SSL/TLS protocol levels as during the first hello. Some -clients violate this rule by adapting to the server's answer. (Example: -the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server -only understands up to SSLv3. In this case the client must still use the -same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect -to the server's answer and violate the version rollback protection.) - -=item SSL_OP_SINGLE_DH_USE - -Always create a new key when using temporary/ephemeral DH parameters -(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)>). -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 -temporary/ephemeral DH parameters are used. - -=item SSL_OP_EPHEMERAL_RSA - -This option is no longer implemented and is treated as no op. - -=item SSL_OP_CIPHER_SERVER_PREFERENCE - -When choosing a cipher, use the server's preferences instead of the client -preferences. When not set, the SSL server will always follow the clients -preferences. When set, the SSL/TLS server will choose following its -own preferences. - -=item SSL_OP_PKCS1_CHECK_1 - -... - -=item SSL_OP_PKCS1_CHECK_2 - -... - - -=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 - -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 - -When performing renegotiation as a server, always start a new session -(i.e., session resumption requests are only accepted in the initial -handshake). This option is not needed for clients. - -=item SSL_OP_NO_TICKET - -Normally clients and servers will, where possible, transparently make use -of RFC4507bis tickets for stateless session resumption. - -If this option is set this functionality is disabled and tickets will -not be used by clients or servers. - -=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION - -Allow legacy insecure renegotiation between OpenSSL and unpatched clients or -servers. See the B<SECURE RENEGOTIATION> section for more details. - -=item SSL_OP_LEGACY_SERVER_CONNECT - -Allow legacy insecure renegotiation between OpenSSL and unpatched servers -B<only>: this option is currently set by default. See the -B<SECURE RENEGOTIATION> section for more details. - -=item SSL_OP_NO_ENCRYPT_THEN_MAC - -Normally clients and servers will transparently attempt to negotiate the -RFC7366 Encrypt-then-MAC option on TLS and DTLS connection. - -If this option is set, Encrypt-then-MAC is disabled. Clients will not -propose, and servers will not accept the extension. - -=back - -=head1 SECURE RENEGOTIATION - -OpenSSL always attempts to use secure renegotiation as -described in RFC5746. This counters the prefix attack described in -CVE-2009-3555 and elsewhere. - -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 -renegotiation is referred to as I<unpatched>. - -The following sections describe the operations permitted by OpenSSL's secure -renegotiation implementation. - -=head2 Patched client and server - -Connections and renegotiation are always permitted by OpenSSL implementations. - -=head2 Unpatched client and patched OpenSSL server - -The initial connection succeeds but client renegotiation is denied by the -server with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal -B<handshake_failure> alert in SSL v3.0. - -If the patched OpenSSL server attempts to renegotiate a fatal -B<handshake_failure> alert is sent. This is because the server code may be -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. - -=head2 Patched OpenSSL client and unpatched server. - -If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or -B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections -and renegotiation between patched OpenSSL clients and unpatched servers -succeeds. If neither option is set then initial connections to unpatched -servers will fail. - -The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even -though it has security implications: otherwise it would be impossible to -connect to unpatched servers (i.e. all of them initially) and this is clearly -not acceptable. Renegotiation is permitted because this does not add any -additional security issues: during an attack clients do not see any -renegotiations anyway. - -As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will -B<not> be set by default in a future version of OpenSSL. - -OpenSSL client applications wishing to ensure they can connect to unpatched -servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT> - -OpenSSL client applications that want to ensure they can B<not> connect to -unpatched servers (and thus avoid any security issues) should always B<clear> -B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or -SSL_clear_options(). - -The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and -B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that -B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure -renegotiation between OpenSSL clients and unpatched servers B<only>, while -B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections -and renegotiation between OpenSSL and unpatched clients or servers. - -=head1 RETURN VALUES - -SSL_CTX_set_options() and SSL_set_options() return the new options bitmask -after adding B<options>. - -SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask -after clearing B<options>. - -SSL_CTX_get_options() and SSL_get_options() return the current bitmask. - -SSL_get_secure_renegotiation_support() returns 1 is the peer supports -secure renegotiation and 0 if it does not. - -=head1 SEE ALSO - -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 - -The attempt to always try to use secure renegotiation was added in -Openssl 0.9.8m. - -=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 diff --git a/doc/ssl/SSL_CTX_set_psk_client_callback.pod b/doc/ssl/SSL_CTX_set_psk_client_callback.pod deleted file mode 100644 index a4175081c5..0000000000 --- a/doc/ssl/SSL_CTX_set_psk_client_callback.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client callback - -=head1 SYNOPSIS - - #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)); - 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)); - - -=head1 DESCRIPTION - -A client application must provide a callback function which is called -when the client is sending the ClientKeyExchange message to the server. - -The purpose of the callback function is to select the PSK identity and -the pre-shared key to use during the connection setup phase. - -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 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. - -=head1 NOTES - -Note that parameter B<hint> given to the callback may be B<NULL>. - -=head1 RETURN VALUES - -Return values from the client callback are interpreted as follows: - -On success (callback found a PSK identity and a pre-shared key to use) -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 diff --git a/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/doc/ssl/SSL_CTX_set_quiet_shutdown.pod deleted file mode 100644 index d39d747ce7..0000000000 --- a/doc/ssl/SSL_CTX_set_quiet_shutdown.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown, SSL_get_quiet_shutdown - manipulate shutdown behaviour - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode); - int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx); - - void SSL_set_quiet_shutdown(SSL *ssl, int mode); - int SSL_get_quiet_shutdown(const SSL *ssl); - -=head1 DESCRIPTION - -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)> 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)> 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>. - -=head1 NOTES - -Normally when a SSL connection is finished, the parties must send out -"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)> -will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN. -(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. - -The default is normal shutdown behaviour as described by the TLS standard. - -=head1 RETURN VALUES - -SSL_CTX_set_quiet_shutdown() and SSL_set_quiet_shutdown() do not return -diagnostic information. - -SSL_CTX_get_quiet_shutdown() and SSL_get_quiet_shutdown return the current -setting. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_read_ahead.pod b/doc/ssl/SSL_CTX_set_read_ahead.pod deleted file mode 100644 index bea8390085..0000000000 --- a/doc/ssl/SSL_CTX_set_read_ahead.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -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> - - void SSL_set_read_ahead(SSL *s, int yes); - int SSL_get_read_ahead(const SSL *s); - - 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 - -SSL_CTX_set_read_ahead() and SSL_set_read_ahead() set whether we should read as -many input bytes as possible (for non-blocking reads) or not. For example if -B<x> bytes are currently required by OpenSSL, but B<y> bytes are available from -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 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. - -=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. 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, -and non zero otherwise. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_security_level.pod b/doc/ssl/SSL_CTX_set_security_level.pod deleted file mode 100644 index 577b393729..0000000000 --- a/doc/ssl/SSL_CTX_set_security_level.pod +++ /dev/null @@ -1,169 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_security_level, SSL_set_security_level, SSL_CTX_get_security_level, SSL_get_security_level, SSL_CTX_set_security_callback, SSL_set_security_callback, SSL_CTX_get_security_callback, SSL_get_security_callback, SSL_CTX_set0_security_ex_data, SSL_set0_security_ex_data, SSL_CTX_get0_security_ex_data, SSL_get0_security_ex_data - SSL/TLS security framework - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_security_level(SSL_CTX *ctx, int level); - void SSL_set_security_level(SSL *s, int level); - - int SSL_CTX_get_security_level(const SSL_CTX *ctx); - int SSL_get_security_level(const SSL *s); - - void SSL_CTX_set_security_callback(SSL_CTX *ctx, - int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, - void *other, void *ex)); - - void SSL_set_security_callback(SSL *s, - int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, - void *other, void *ex)); - - int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex); - int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex); - - void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex); - void SSL_set0_security_ex_data(SSL *s, void *ex); - - void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx); - void *SSL_get0_security_ex_data(const SSL *s); - -=head1 DESCRIPTION - -The functions SSL_CTX_set_security_level() and SSL_set_security_level() set -the security level to B<level>. If not set the library default security level -is used. - -The functions SSL_CTX_get_security_level() and SSL_get_security_level() -retrieve the current security level. - -SSL_CTX_set_security_callback(), SSL_set_security_callback(), -SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set -the security callback associated with B<ctx> or B<s>. If not set a default -security callback is used. The meaning of the parameters and the behaviour -of the default callbacks is described below. - -SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(), -SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the -extra data pointer passed to the B<ex> parameter of the callback. This -value is passed to the callback verbatim and can be set to any convenient -application specific value. - -=head1 DEFAULT CALLBACK BEHAVIOUR - -If an application doesn't set its own security callback the default -callback is used. It is intended to provide sane defaults. The meaning -of each level is described below. - -=over 4 - -=item B<Level 0> - -Everything is permitted. This retains compatibility with previous versions of -OpenSSL. - -=item B<Level 1> - -The security level corresponds to a minimum of 80 bits of security. Any -parameters offering below 80 bits of security are excluded. As a result RSA, -DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits -are prohibited. All export ciphersuites are prohibited since they all offer -less than 80 bits of security. SSL version 2 is prohibited. Any ciphersuite -using MD5 for the MAC is also prohibited. - -=item B<Level 2> - -Security level set to 112 bits of security. As a result RSA, DSA and DH keys -shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. -In addition to the level 1 exclusions any ciphersuite using RC4 is also -prohibited. SSL version 3 is also not allowed. Compression is disabled. - -=item B<Level 3> - -Security level set to 128 bits of security. As a result RSA, DSA and DH keys -shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. -In addition to the level 2 exclusions ciphersuites not offering forward -secrecy are prohibited. TLS versions below 1.1 are not permitted. Session -tickets are disabled. - -=item B<Level 4> - -Security level set to 192 bits of security. As a result RSA, DSA and DH keys -shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited. -Ciphersuites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are -not permitted. - -=item B<Level 5> - -Security level set to 256 bits of security. As a result RSA, DSA and DH keys -shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited. - -=back - -=head1 APPLICATION DEFINED SECURITY CALLBACKS - -I<Documentation to be provided.> - -=head1 NOTES - -B<WARNING> at this time setting the security level higher than 1 for -general internet use is likely to cause B<considerable> interoperability -issues and is not recommended. This is because the B<SHA1> algorithm -is very widely used in certificates and will be rejected at levels -higher than 1 because it only offers 80 bits of security. - -The default security level can be configured when OpenSSL is compiled by -setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 1 is used. - -The security framework disables or reject parameters inconsistent with the -set security level. In the past this was difficult as applications had to set -a number of distinct parameters (supported ciphers, supported curves supported -signature algorithms) to achieve this end and some cases (DH parameter size -for example) could not be checked at all. - -By setting an appropriate security level much of this complexity can be -avoided. - -The bits of security limits affect all relevant parameters including -ciphersuite encryption algorithms, supported ECC curves, supported -signature algorithms, DH parameter sizes, certificate key sizes and -signature algorithms. This limit applies no matter what other custom -settings an application has set: so if the ciphersuite is set to B<ALL> -then only ciphersuites consistent with the security level are permissible. - -See SP800-57 for how the security limits are related to individual -algorithms. - -Some security levels require large key sizes for non-ECC public key -algorithms which can severely degrade performance. For example 256 bits -of security requires the use of RSA keys of at least 15360 bits in size. - -Some restrictions can be gracefully handled: for example ciphersuites -offering insufficient security are not sent by the client and will not -be selected by the server. Other restrictions such as the peer certificate -key size or the DH parameter size will abort the handshake with a fatal -alert. - -Attempts to set certificates or parameters with insufficient security are -also blocked. For example trying to set a certificate using a 512 bit RSA -key using SSL_CTX_use_certificate() at level 1. Applications which do not -check the return values for errors will misbehave: for example it might -appear that a certificate is not set at all because it had been rejected. - -=head1 HISTORY - -These functions were first added to OpenSSL 1.1.0 - -=head1 COPYRIGHT - -Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/doc/ssl/SSL_CTX_set_session_cache_mode.pod deleted file mode 100644 index a2e82664d0..0000000000 --- a/doc/ssl/SSL_CTX_set_session_cache_mode.pod +++ /dev/null @@ -1,141 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); - long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); - -=head1 DESCRIPTION - -SSL_CTX_set_session_cache_mode() enables/disables session caching -by setting the operational mode for B<ctx> to <mode>. - -SSL_CTX_get_session_cache_mode() returns the currently used cache mode. - -=head1 NOTES - -The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. -The sessions can be held in memory for each B<ctx>, if more than one -SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX -object. - -In order to reuse a session, a client must send the session's id to the -server. It can only send exactly one id. The server then either -agrees to reuse the session or it starts a full handshake (to create a new -session). - -A server will lookup up the session in its internal session storage. If the -session is not found in internal storage or lookups for the internal storage -have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try -the external storage if available. - -Since a client may try to reuse a session intended for use in a different -context, the session id context must be set by the server (see -L<SSL_CTX_set_session_id_context(3)>). - -The following session cache modes and modifiers are available: - -=over 4 - -=item SSL_SESS_CACHE_OFF - -No session caching for client or server takes place. - -=item SSL_SESS_CACHE_CLIENT - -Client sessions are added to the session cache. As there is no reliable way -for the OpenSSL library to know whether a session should be reused or which -session to choose (due to the abstract BIO layer the SSL engine does not -have details about the connection), the application must select the session -to be reused by using the L<SSL_set_session(3)> -function. This option is not activated by default. - -=item SSL_SESS_CACHE_SERVER - -Server sessions are added to the session cache. When a client proposes a -session to be reused, the server looks for the corresponding session in (first) -the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set), -then (second) in the external cache if available. If the session is found, the -server will try to reuse the session. This is the default. - -=item SSL_SESS_CACHE_BOTH - -Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. - -=item SSL_SESS_CACHE_NO_AUTO_CLEAR - -Normally the session cache is checked for expired sessions every -255 connections using the -L<SSL_CTX_flush_sessions(3)> 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)> can be called -explicitly by the application. - -=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP - -By setting this flag, session-resume operations in an SSL/TLS server will not -automatically look up sessions in the internal cache, even if sessions are -automatically stored there. If external session caching callbacks are in use, -this flag guarantees that all lookups are directed to the external cache. -As automatic lookup only applies for SSL/TLS servers, the flag has no effect on -clients. - -=item SSL_SESS_CACHE_NO_INTERNAL_STORE - -Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER, -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)>). 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 -prevents these additions to the internal cache as well. - -=item SSL_SESS_CACHE_NO_INTERNAL - -Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and -SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time. - - -=back - -The default mode is SSL_SESS_CACHE_SERVER. - -=head1 RETURN VALUES - -SSL_CTX_set_session_cache_mode() returns the previously set cache mode. - -SSL_CTX_get_session_cache_mode() returns the currently set cache mode. - - -=head1 SEE ALSO - -L<ssl(3)>, 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 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 diff --git a/doc/ssl/SSL_CTX_set_session_id_context.pod b/doc/ssl/SSL_CTX_set_session_id_context.pod deleted file mode 100644 index a873b0389e..0000000000 --- a/doc/ssl/SSL_CTX_set_session_id_context.pod +++ /dev/null @@ -1,92 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only) - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx, - unsigned int sid_ctx_len); - int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx, - unsigned int sid_ctx_len); - -=head1 DESCRIPTION - -SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length -B<sid_ctx_len> within which a session can be reused for the B<ctx> object. - -SSL_set_session_id_context() sets the context B<sid_ctx> of length -B<sid_ctx_len> within which a session can be reused for the B<ssl> object. - -=head1 NOTES - -Sessions are generated within a certain context. When exporting/importing -sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible, -to re-import a session generated from another context (e.g. another -application), which might lead to malfunctions. Therefore each application -must set its own session id context B<sid_ctx> which is used to distinguish -the contexts and is stored in exported sessions. The B<sid_ctx> can be -any kind of binary data with a given length, it is therefore possible -to use e.g. the name of the application and/or the hostname and/or service -name ... - -The session id context becomes part of the session. The session id context -is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and -SSL_set_session_id_context() functions are therefore only useful on the -server side. - -OpenSSL clients will check the session id context returned by the server -when reusing a session. - -The maximum length of the B<sid_ctx> is limited to -B<SSL_MAX_SSL_SESSION_ID_LENGTH>. - -=head1 WARNINGS - -If the session id context is not set on an SSL/TLS server and client -certificates are used, stored sessions -will not be reused but a fatal error will be flagged and the handshake -will fail. - -If a server returns a different session id context to an OpenSSL client -when reusing a session, an error will be flagged and the handshake will -fail. OpenSSL servers will always return the correct session id context, -as an OpenSSL server checks the session id context itself before reusing -a session as described above. - -=head1 RETURN VALUES - -SSL_CTX_set_session_id_context() and SSL_set_session_id_context() -return the following values: - -=over 4 - -=item Z<>0 - -The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded -the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error -is logged to the error stack. - -=item Z<>1 - -The operation succeeded. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_split_send_fragment.pod b/doc/ssl/SSL_CTX_set_split_send_fragment.pod deleted file mode 100644 index accf5af247..0000000000 --- a/doc/ssl/SSL_CTX_set_split_send_fragment.pod +++ /dev/null @@ -1,132 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment, -SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment, -SSL_CTX_set_max_pipelines, SSL_set_max_pipelines, -SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len - Control -fragment sizes and pipelining operations - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long); - long SSL_set_max_send_fragment(SSL *ssl, long m); - - long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m); - long SSL_set_max_pipelines(SSL_CTX *ssl, long m); - - long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m); - long SSL_set_split_send_fragment(SSL *ssl, long m); - - void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len); - void SSL_set_default_read_buffer_len(SSL *s, size_t len); - -=head1 DESCRIPTION - -Some engines are able to process multiple simultaneous crypto operations. This -capability could be utilised to parallelise the processing of a single -connection. For example a single write can be split into multiple records and -each one encrypted independently and in parallel. Note: this will only work in -TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This -capability is known as "pipelining" within OpenSSL. - -In order to benefit from the pipelining capability. You need to have an engine -that provides ciphers that support this. The OpenSSL "dasync" engine provides -AES128-SHA based ciphers that have this capability. However these are for -development and test purposes only. - -SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the -B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This -value restricts the amount of plaintext bytes that will be sent in any one -SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These -functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH. - -SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number -of pipelines that will be used at any one time. This value applies to both -"read" pipelining and "write" pipelining. By default only one pipeline will be -used (i.e. normal non-parallel operation). The number of pipelines set must be -in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also -automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is -explained further below. OpenSSL will only every use more than one pipeline if -a ciphersuite is negotiated that uses a pipeline capable cipher provided by an -engine. - -Pipelining operates slightly differently for reading encrypted data compared to -writing encrypted data. SSL_CTX_set_split_send_fragment() and -SSL_set_split_send_fragment() define how data is split up into pipelines when -writing encrypted data. The number of pipelines used will be determined by the -amount of data provided to the SSL_write() call divided by -B<split_send_fragment>. - -For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4 -then: - -SSL_write called with 0-2000 bytes == 1 pipeline used - -SSL_write called with 2001-4000 bytes == 2 pipelines used - -SSL_write called with 4001-6000 bytes == 3 pipelines used - -SSL_write called with 6001+ bytes == 4 pipelines used - -B<split_send_fragment> must always be less than or equal to -B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>. -This will mean that the same number of records will always be created as would -have been created in the non-parallel case, although the data will be -apportioned differently. In the parallel case data will be spread equally -between the pipelines. - -Read pipelining is controlled in a slightly different way than with write -pipelining. While reading we are constrained by the number of records that the -peer (and the network) can provide to us in one go. The more records we can get -in one go the more opportunity we have to parallelise the processing. As noted -above when setting B<max_pipelines> to a value greater than one, B<read_ahead> -is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to -read as much data into the read buffer as the network can provide and will fit -into the buffer. Without this set data is read into the read buffer one record -at a time. The more data that can be read, the more opportunity there is for -parallelising the processing at the cost of increased memory overhead per -connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending() -function (see L<SSL_pending(3)>). - -The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() -functions control the size of the read buffer that will be used. The B<len> -parameter sets the size of the buffer. The value will only be used if it is -greater than the default that would have been used anyway. The normal default -value depends on a number of factors but it will be at least -SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes. - -=head1 RETURN VALUES - -All non-void functions return 1 on success and 0 on failure. - -=head1 NOTES - -With the exception of SSL_CTX_set_default_read_buffer_len() and -SSL_set_default_read_buffer_len() all these functions are implemented using -macros. - -=head1 HISTORY - -The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(), -SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(), -SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() -functions were added in OpenSSL 1.1.0. - -=head1 SEE ALSO - -L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)> - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_CTX_set_ssl_version.pod b/doc/ssl/SSL_CTX_set_ssl_version.pod deleted file mode 100644 index 22c0370b75..0000000000 --- a/doc/ssl/SSL_CTX_set_ssl_version.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method -- choose a new TLS/SSL method - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *method); - int SSL_set_ssl_method(SSL *s, const SSL_METHOD *method); - const SSL_METHOD *SSL_get_ssl_method(SSL *ssl); - -=head1 DESCRIPTION - -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)> 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. - -SSL_get_ssl_method() returns a function pointer to the TLS/SSL method -set in B<ssl>. - -=head1 NOTES - -The available B<method> choices are described in -L<SSL_CTX_new(3)>. - -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. - -=head1 RETURN VALUES - -The following return values can occur for SSL_CTX_set_ssl_version() -and SSL_set_ssl_method(): - -=over 4 - -=item Z<>0 - -The new choice failed, check the error stack to find out the reason. - -=item Z<>1 - -The operation succeeded. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_timeout.pod b/doc/ssl/SSL_CTX_set_timeout.pod deleted file mode 100644 index 470efdfc29..0000000000 --- a/doc/ssl/SSL_CTX_set_timeout.pod +++ /dev/null @@ -1,68 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_CTX_set_timeout(SSL_CTX *ctx, long t); - long SSL_CTX_get_timeout(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_set_timeout() sets the timeout for newly created sessions for -B<ctx> to B<t>. The timeout value B<t> must be given in seconds. - -SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>. - -=head1 NOTES - -Whenever a new session is created, it is assigned a maximum lifetime. This -lifetime is specified by storing the creation time of the session and the -timeout value valid at this time. If the actual time is later than creation -time plus timeout, the session is not reused. - -Due to this realization, all sessions behave according to the timeout value -valid at the time of the session negotiation. Changes of the timeout value -do not affect already established sessions. - -The expiration time of a single session can be modified using the -L<SSL_SESSION_get_time(3)> family of functions. - -Expired sessions are removed from the internal session cache, whenever -L<SSL_CTX_flush_sessions(3)> is called, either -directly by the application or automatically (see -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)>. -All currently supported protocols have the same default timeout value -of 300 seconds. - -=head1 RETURN VALUES - -SSL_CTX_set_timeout() returns the previously set timeout value. - -SSL_CTX_get_timeout() returns the currently set timeout value. - -=head1 SEE ALSO - -L<ssl(3)>, -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 diff --git a/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod b/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod deleted file mode 100644 index c12ff0e587..0000000000 --- a/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod +++ /dev/null @@ -1,125 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/tls1.h> - - 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); - -=head1 DESCRIPTION - -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_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. 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 -to the OCSP response data and the return value will be the length of that data. -Typically a callback would obtain an OCSP_RESPONSE object from this data via a -call to the d2i_OCSP_RESPONSE() function. If the server has not provided any -response data then B<*resp> will be NULL and the return value from -SSL_get_tlsext_status_ocsp_resp() will be -1. - -A server application must also call the SSL_CTX_set_tlsext_status_cb() function -if it wants to be able to provide clients with OCSP Certificate Status -responses. Typically the server callback would obtain the server certificate -that is being sent back to the client via a call to SSL_get_certificate(); -obtain the OCSP response to be sent back; and then set that response data by -calling SSL_set_tlsext_status_ocsp_resp(). A pointer to the response data should -be provided in the B<resp> argument, and the length of that data should be in -the B<len> argument. - -=head1 RETURN VALUES - -The callback when used on the client side should return a negative value on -error; 0 if the response is not acceptable (in which case the handshake will -fail) or a positive value if it is acceptable. - -The callback when used on the server side should return with either -SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be -returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be -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_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 diff --git a/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod b/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod deleted file mode 100644 index 34d8ce9ae0..0000000000 --- a/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod +++ /dev/null @@ -1,198 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing - -=head1 SYNOPSIS - - #include <openssl/tls1.h> - - 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)); - -=head1 DESCRIPTION - -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 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 -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 -maintained by the callback function implementation. - -In order to reuse a session, a TLS client must send the a session ticket -extension to the server. The client can only send exactly one session ticket. -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 -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 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 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 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(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 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 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 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: - -=over 4 - -=item Z<>2 - -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 -3.3 paragraph 2). - -=item Z<>1 - -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 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 -a new set of parameters. - -=item less than 0 - -This indicates an error. - -=back - -=head1 NOTES - -Session resumption shortcuts the TLS so that the 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 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 -using that session: even if the ciphersuite supports forward secrecy. As -a result applications may wish to use multiple keys and avoid using long term -keys stored in files. - -Applications can use longer keys to maintain a consistent level of security. -For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key -the overall security is only 128 bits because breaking the ticket key will -enable an attacker to obtain the session keys. - -=head1 EXAMPLES - -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) - { - if (enc) { /* create new session */ - 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 */ - key = createkey(); /* something that you need to implement. - * createkey needs to initialise, a name, - * an aes_key, a hmac_key and optionally - * an expire time. */ - if ( !key ) { /* key couldn't be created */ - return 0; - } - } - 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 ); - - if (key->expire < ( now() - RENEW_TIME ) ) { - /* return 2 - this session will get a new ticket even though the current is still valid */ - return 2; - } - return 1; - - } - } - - - -=head1 RETURN VALUES - -returns 0 to indicate the callback function was set. - -=head1 SEE ALSO - -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 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 diff --git a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod deleted file mode 100644 index fbfb8cbaa5..0000000000 --- a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod +++ /dev/null @@ -1,137 +0,0 @@ -=pod - -=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 - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, - DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); - long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh); - - void SSL_set_tmp_dh_callback(SSL *ctx, - DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); - long SSL_set_tmp_dh(SSL *ssl, DH *dh) - -=head1 DESCRIPTION - -SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be -used when a DH parameters are required to B<tmp_dh_callback>. -The callback is inherited by all B<ssl> objects created from B<ctx>. - -SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. -The key is inherited by all B<ssl> objects created from B<ctx>. - -SSL_set_tmp_dh_callback() sets the callback only for B<ssl>. - -SSL_set_tmp_dh() sets the parameters only for B<ssl>. - -These functions apply to SSL/TLS servers only. - -=head1 NOTES - -When using a cipher with RSA authentication, an ephemeral DH key exchange -can take place. Ciphers with DSA keys always use ephemeral DH keys as well. -In these cases, the session data are negotiated using the -ephemeral/temporary DH key and the key supplied and certified -by the certificate chain is only used for signing. -Anonymous ciphers (without a permanent server key) also use ephemeral DH keys. - -Using ephemeral DH key exchange yields forward secrecy, as the connection -can only be decrypted, when the DH key is known. By generating a temporary -DH 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) key, as this key was -only used for signing. - -In order to perform a DH key exchange the server must use a DH group -(DH parameters) and generate a DH key. The server will always generate -a new DH key during the negotiation. - -As generating DH parameters is extremely time consuming, an application -should not generate the parameters on the fly but supply the parameters. -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)> 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)> application. Generation of custom DH -parameters during installation should still be preferred to stop an -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. - -Previous versions of the callback used B<is_export> and B<keylength> -parameters to control parameter generation for export and non-export -cipher suites. Modern servers that do not support export ciphersuites -are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use -the callback but ignore B<keylength> and B<is_export> and simply -supply at least 2048-bit parameters in the callback. - -=head1 EXAMPLES - -Setup DH parameters with a key length of 2048 bits. (Error handling -partly left out.) - - Command-line parameter generation: - $ openssl dhparam -out dh_param_2048.pem 2048 - - Code for setting up parameters during server initialization: - - ... - SSL_CTX ctx = SSL_CTX_new(); - ... - - /* Set up ephemeral DH parameters. */ - DH *dh_2048 = NULL; - FILE *paramfile; - paramfile = fopen("dh_param_2048.pem", "r"); - if (paramfile) { - dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); - fclose(paramfile); - } else { - /* Error. */ - } - if (dh_2048 == NULL) { - /* Error. */ - } - if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { - /* Error. */ - } - ... - -=head1 RETURN VALUES - -SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return -diagnostic output. - -SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 -on failure. Check the error queue to find out the reason of failure. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_CTX_set_verify.pod b/doc/ssl/SSL_CTX_set_verify.pod deleted file mode 100644 index 96a98acaac..0000000000 --- a/doc/ssl/SSL_CTX_set_verify.pod +++ /dev/null @@ -1,290 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, - int (*verify_callback)(int, X509_STORE_CTX *)); - void SSL_set_verify(SSL *s, int mode, - int (*verify_callback)(int, X509_STORE_CTX *)); - void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth); - void SSL_set_verify_depth(SSL *s, int depth); - - int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx); - -=head1 DESCRIPTION - -SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and -specifies the B<verify_callback> function to be used. If no callback function -shall be specified, the NULL pointer can be used for B<verify_callback>. - -SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and -specifies the B<verify_callback> function to be used. If no callback function -shall be specified, the NULL pointer can be used for B<verify_callback>. In -this case last B<verify_callback> set specifically for this B<ssl> remains. If -no special B<callback> was set before, the default callback for the underlying -B<ctx> is used, that was valid at the time B<ssl> was created with -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.) - -SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain -verification that shall be allowed for B<ssl>. (See the BUGS section.) - -=head1 NOTES - -The verification of certificates can be controlled by a set of logically -or'ed B<mode> flags: - -=over 4 - -=item SSL_VERIFY_NONE - -B<Server mode:> the server will not send a client certificate request to the -client, so the client will not send a certificate. - -B<Client mode:> if not using an anonymous cipher (by default disabled), the -server will send a certificate which will be checked. The result of the -certificate verification process can be checked after the TLS/SSL handshake -using the L<SSL_get_verify_result(3)> function. -The handshake will be continued regardless of the verification result. - -=item SSL_VERIFY_PEER - -B<Server mode:> the server sends a client certificate request to the client. -The certificate returned (if any) is checked. If the verification process -fails, the TLS/SSL handshake is -immediately terminated with an alert message containing the reason for -the verification failure. -The behaviour can be controlled by the additional -SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags. - -B<Client mode:> the server certificate is verified. If the verification process -fails, the TLS/SSL handshake is -immediately terminated with an alert message containing the reason for -the verification failure. If no server certificate is sent, because an -anonymous cipher is used, SSL_VERIFY_PEER is ignored. - -=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT - -B<Server mode:> if the client did not return a certificate, the TLS/SSL -handshake is immediately terminated with a "handshake failure" alert. -This flag must be used together with SSL_VERIFY_PEER. - -B<Client mode:> ignored - -=item SSL_VERIFY_CLIENT_ONCE - -B<Server mode:> only request a client certificate on the initial TLS/SSL -handshake. Do not ask for a client certificate again in case of a -renegotiation. This flag must be used together with SSL_VERIFY_PEER. - -B<Client mode:> ignored - -=back - -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)>. -The following descriptions apply in the case of the built-in procedure. An -application provided procedure also has access to the verify depth information -and the verify_callback() function, but the way this information is used -may be different. - -SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up -to which depth certificates in a chain are used during the verification -procedure. If the certificate chain is longer than allowed, the certificates -above the limit are ignored. Error messages are generated as if these -certificates would not be present, most likely a -X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. -The depth count is "level 0:peer certificate", "level 1: CA certificate", -"level 2: higher level CA certificate", and so on. Setting the maximum -depth to 2 allows the levels 0, 1, and 2. The default depth limit is 100, -allowing for the peer certificate and additional 100 CA certificates. - -The B<verify_callback> function is used to control the behaviour when the -SSL_VERIFY_PEER flag is set. It must be supplied by the application and -receives two arguments: B<preverify_ok> indicates, whether the verification of -the certificate in question was passed (preverify_ok=1) or not -(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used -for the certificate chain verification. - -The certificate chain is checked starting with the deepest nesting level -(the root CA certificate) and worked upward to the peer's certificate. -At each level signatures and issuer attributes are checked. Whenever -a verification error is found, the error number is stored in B<x509_ctx> -and B<verify_callback> is called with B<preverify_ok>=0. By applying -X509_CTX_store_* functions B<verify_callback> can locate the certificate -in question and perform additional steps (see EXAMPLES). If no error is -found for a certificate, B<verify_callback> is called with B<preverify_ok>=1 -before advancing to the next level. - -The return value of B<verify_callback> controls the strategy of the further -verification process. If B<verify_callback> returns 0, the verification -process is immediately stopped with "verification failed" state. If -SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and -the TLS/SSL handshake is terminated. If B<verify_callback> returns 1, -the verification process is continued. If B<verify_callback> always returns -1, the TLS/SSL handshake will 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)> or by maintaining its -own error storage managed by B<verify_callback>. - -If no B<verify_callback> is specified, the default callback will be used. -Its return value is identical to B<preverify_ok>, so that any verification -failure will lead to a termination of the TLS/SSL handshake with an -alert message, if SSL_VERIFY_PEER is set. - -=head1 RETURN VALUES - -The SSL*_set_verify*() functions do not provide diagnostic information. - -=head1 EXAMPLES - -The following code sequence realizes an example B<verify_callback> function -that will always continue the TLS/SSL handshake regardless of verification -failure, if wished. The callback realizes a verification depth limit with -more informational output. - -All verification errors are printed; information about the certificate chain -is printed on request. -The example is realized for a server that does allow but not require client -certificates. - -The example makes use of the ex_data technique to store application data -into/retrieve application data from the SSL structure -(see L<SSL_get_ex_new_index(3)>, -L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>). - - ... - typedef struct { - int verbose_mode; - int verify_depth; - int always_continue; - } mydata_t; - int mydata_index; - ... - static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) - { - char buf[256]; - X509 *err_cert; - int err, depth; - SSL *ssl; - mydata_t *mydata; - - err_cert = X509_STORE_CTX_get_current_cert(ctx); - err = X509_STORE_CTX_get_error(ctx); - depth = X509_STORE_CTX_get_error_depth(ctx); - - /* - * Retrieve the pointer to the SSL of the connection currently treated - * and the application specific data stored into the SSL object. - */ - ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); - mydata = SSL_get_ex_data(ssl, mydata_index); - - X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); - - /* - * Catch a too long certificate chain. The depth limit set using - * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so - * that whenever the "depth>verify_depth" condition is met, we - * have violated the limit and want to log this error condition. - * We must do it here, because the CHAIN_TOO_LONG error would not - * be found explicitly; only errors introduced by cutting off the - * additional certificates would be logged. - */ - if (depth > mydata->verify_depth) { - preverify_ok = 0; - err = X509_V_ERR_CERT_CHAIN_TOO_LONG; - X509_STORE_CTX_set_error(ctx, err); - } - if (!preverify_ok) { - printf("verify error:num=%d:%s:depth=%d:%s\n", err, - X509_verify_cert_error_string(err), depth, buf); - } - else if (mydata->verbose_mode) - { - printf("depth=%d:%s\n", depth, buf); - } - - /* - * At this point, err contains the last verification error. We can use - * it for something special - */ - if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) - { - X509_NAME_oneline(X509_get_issuer_name(err_cert), buf, 256); - printf("issuer= %s\n", buf); - } - - if (mydata->always_continue) - return 1; - else - return preverify_ok; - } - ... - - mydata_t mydata; - - ... - mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); - - ... - SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, - verify_callback); - - /* - * Let the verify_callback catch the verify_depth error so that we get - * an appropriate error in the logfile. - */ - SSL_CTX_set_verify_depth(verify_depth + 1); - - /* - * Set up the SSL specific data into "mydata" and store it into th SSL - * structure. - */ - mydata.verify_depth = verify_depth; ... - SSL_set_ex_data(ssl, mydata_index, &mydata); - - ... - SSL_accept(ssl); /* check of success left out for clarity */ - if (peer = SSL_get_peer_certificate(ssl)) - { - if (SSL_get_verify_result(ssl) == X509_V_OK) - { - /* The client sent a certificate which verified OK */ - } - } - -=head1 SEE ALSO - -L<ssl(3)>, 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 diff --git a/doc/ssl/SSL_CTX_use_certificate.pod b/doc/ssl/SSL_CTX_use_certificate.pod deleted file mode 100644 index c645f58078..0000000000 --- a/doc/ssl/SSL_CTX_use_certificate.pod +++ /dev/null @@ -1,180 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, -SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, -SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, -SSL_use_certificate_chain_file, -SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, -SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, -SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, -SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, -SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, -SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key -- load certificate and key data - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x); - int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d); - int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type); - int SSL_use_certificate(SSL *ssl, X509 *x); - int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len); - int SSL_use_certificate_file(SSL *ssl, const char *file, int type); - - int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file); - int SSL_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); - int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type); - int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa); - int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len); - int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type); - int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey); - int SSL_use_PrivateKey_ASN1(int pk, SSL *ssl, unsigned char *d, long len); - int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type); - int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa); - int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len); - int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type); - - int SSL_CTX_check_private_key(const SSL_CTX *ctx); - int SSL_check_private_key(const SSL *ssl); - -=head1 DESCRIPTION - -These functions load the certificates and private keys into the SSL_CTX -or SSL object, respectively. - -The SSL_CTX_* class of functions loads the certificates and keys into the -SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl> -created from B<ctx> with L<SSL_new(3)> 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)> 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)> -function. - -SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from -the memory location B<d> (with length B<len>) into B<ctx>, -SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>. - -SSL_CTX_use_certificate_file() loads the first certificate stored in B<file> -into B<ctx>. The formatting B<type> of the certificate must be specified -from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. -SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>. -See the NOTES section on why SSL_CTX_use_certificate_chain_file() -should be preferred. - -SSL_CTX_use_certificate_chain_file() loads a certificate chain from -B<file> into B<ctx>. The certificates must be in PEM format and must -be sorted starting with the subject's certificate (actual client or server -certificate), followed by intermediate CA certificates if applicable, and -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 -to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>; -SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>. -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_ASN1() adds the private key of type B<pk> -stored at memory location B<d> (length B<len>) to B<ctx>. -SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA -stored at memory location B<d> (length B<len>) to B<ctx>. -SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private -key to B<ssl>. - -SSL_CTX_use_PrivateKey_file() adds the first private key found in -B<file> to B<ctx>. The formatting B<type> of the certificate must be specified -from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. -SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in -B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found -in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private -RSA key found to B<ssl>. - -SSL_CTX_check_private_key() checks the consistency of a private key with -the corresponding certificate loaded into B<ctx>. If more than one -key/certificate pair (RSA/DSA) is installed, the last item installed will -be checked. If e.g. the last item was a RSA certificate or key, the RSA -key/certificate pair will be checked. SSL_check_private_key() performs -the same check for B<ssl>. If no key/certificate was explicitly added for -this B<ssl>, the last item added into B<ctx> will be checked. - -=head1 NOTES - -The internal certificate store of OpenSSL can hold 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)>. - -When reading certificates and private keys from file, files of type -SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain -one certificate or private key, consequently -SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting. -Files of type SSL_FILETYPE_PEM can contain more than one item. - -SSL_CTX_use_certificate_chain_file() adds the first certificate found -in the file to the certificate store. The other certificates are added -to the store of chain certificates using L<SSL_CTX_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() -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 -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)>. - -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)>. -(Certificate files might be encrypted as well from the technical point -of view, it however does not make sense as the data in the certificate -is considered public anyway.) - -=head1 RETURN VALUES - -On success, the functions return 1. -Otherwise check out the error stack to find out the reason. - -=head1 SEE ALSO - -L<ssl(3)>, 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 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 diff --git a/doc/ssl/SSL_CTX_use_psk_identity_hint.pod b/doc/ssl/SSL_CTX_use_psk_identity_hint.pod deleted file mode 100644 index 753074a720..0000000000 --- a/doc/ssl/SSL_CTX_use_psk_identity_hint.pod +++ /dev/null @@ -1,87 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint, -SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK -identity hint to use - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); - 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)); - void SSL_set_psk_server_callback(SSL *ssl, - unsigned int (*callback)(SSL *ssl, const char *identity, - unsigned char *psk, int max_psk_len)); - - -=head1 DESCRIPTION - -SSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK -identity hint B<hint> to SSL context object -B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated -PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint> -is B<NULL> the current hint from B<ctx> or B<ssl> is deleted. - -In the case where PSK identity hint is B<NULL>, the server -does not send the ServerKeyExchange message to the client. - -A server application must provide a callback function which is called -when the server receives the ClientKeyExchange message from the -client. The purpose of the callback function is to validate the -received PSK identity and to fetch the pre-shared key used during the -connection setup phase. The callback is set using functions -SSL_CTX_set_psk_server_callback() or -SSL_set_psk_server_callback(). The callback function is given the -connection in parameter B<ssl>, B<NULL>-terminated PSK identity sent -by the client in parameter B<identity>, and a buffer B<psk> of length -B<max_psk_len> bytes where the pre-shared key is to be stored. - - -=head1 RETURN VALUES - -SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return -1 on success, 0 otherwise. - -Return values from the server callback are interpreted as follows: - -=over 4 - -=item Z<>0 - -PSK identity was not found. An "unknown_psk_identity" alert message -will be sent and the connection setup fails. - -=item E<gt>0 - -PSK identity was found and the server callback has provided the PSK -successfully in parameter B<psk>. Return value is the length of -B<psk> in bytes. It is an error to return a value greater than -B<max_psk_len>. - -If the PSK identity was not found but the callback instructs the -protocol to continue anyway, the callback must provide some random -data to B<psk> and return the length of the random data, so the -connection will fail with decryption_error before it will be finished -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 diff --git a/doc/ssl/SSL_CTX_use_serverinfo.pod b/doc/ssl/SSL_CTX_use_serverinfo.pod deleted file mode 100644 index bd496ff8c5..0000000000 --- a/doc/ssl/SSL_CTX_use_serverinfo.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_use_serverinfo, SSL_CTX_use_serverinfo_file - use serverinfo extension - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_use_serverinfo(SSL_CTX *ctx, const unsigned char *serverinfo, - size_t serverinfo_length); - - int SSL_CTX_use_serverinfo_file(SSL_CTX *ctx, const char *file); - -=head1 DESCRIPTION - -These functions load "serverinfo" TLS ServerHello Extensions into the SSL_CTX. -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 2-byte length, and then length bytes of extension_data. - -SSL_CTX_use_serverinfo_file() loads one or more serverinfo extensions from -B<file> into B<ctx>. The extensions must be in PEM format. Each extension -must consist of a 2-byte Extension Type, a 2-byte length, and then length -bytes of extension_data. Each PEM extension name must begin with the phrase -"BEGIN SERVERINFO FOR ". - -If more than one certificate (RSA/DSA) is installed using -SSL_CTX_use_certificate(), the serverinfo extension will be loaded into the -last certificate installed. If e.g. the last item was a RSA certificate, the -loaded serverinfo extension data will be loaded for that certificate. To -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 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 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 diff --git a/doc/ssl/SSL_SESSION_free.pod b/doc/ssl/SSL_SESSION_free.pod deleted file mode 100644 index 1906510e41..0000000000 --- a/doc/ssl/SSL_SESSION_free.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_free - free an allocated SSL_SESSION structure - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_SESSION_free(SSL_SESSION *session); - -=head1 DESCRIPTION - -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)>, -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 -object at the same time. It is therefore crucial to keep the reference -count (usage information) correct and not delete a SSL_SESSION object -that is still used, as this may lead to program failures due to -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)> 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)>) -or when the SSL_SESSION object was generated outside a TLS handshake -operation, e.g. by using L<d2i_SSL_SESSION(3)>. -It must not be called on other SSL_SESSION objects, as this would cause -incorrect reference counts and therefore program failures. - -=head1 RETURN VALUES - -SSL_SESSION_free() does not provide diagnostic information. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_SESSION_get0_cipher.pod b/doc/ssl/SSL_SESSION_get0_cipher.pod deleted file mode 100644 index fdd36edc0c..0000000000 --- a/doc/ssl/SSL_SESSION_get0_cipher.pod +++ /dev/null @@ -1,42 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get0_cipher - retrieve the SSL cipher associated with a session - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const SSL_CIPHER *SSL_SESSION_get0_cipher(const SSL_SESSSION *s); - -=head1 DESCRIPTION - -SSL_SESSION_get0_cipher() retrieves the cipher that was used by the -connection when the session was created, or NULL if it cannot be determined. - -The value returned is a pointer to an object maintained within B<s> and -should not be released. - -=head1 SEE ALSO - -L<ssl(3)>, -L<d2i_SSL_SESSION(3)>, -L<SSL_SESSION_get_time(3)>, -L<SSL_SESSION_get0_hostname(3)>, -L<SSL_SESSION_free(3)> - -=head1 HISTORY - -SSL_SESSION_get0_cipher() was first added to OpenSSL 1.1.0 - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_SESSION_get0_hostname.pod b/doc/ssl/SSL_SESSION_get0_hostname.pod deleted file mode 100644 index 6fb12bec37..0000000000 --- a/doc/ssl/SSL_SESSION_get0_hostname.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get0_hostname - retrieve the SNI hostname associated with a session - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const char *SSL_SESSION_get0_hostname(const SSL_SESSSION *s); - -=head1 DESCRIPTION - -SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the -client when the session was created, or NULL if no value was sent. - -The value returned is a pointer to memory maintained within B<s> and -should not be free'd. - -=head1 SEE ALSO - -L<ssl(3)>, -L<d2i_SSL_SESSION(3)>, -L<SSL_SESSION_get_time(3)>, -L<SSL_SESSION_free(3)> - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_SESSION_get0_id_context.pod b/doc/ssl/SSL_SESSION_get0_id_context.pod deleted file mode 100644 index 2ac3fc4dd0..0000000000 --- a/doc/ssl/SSL_SESSION_get0_id_context.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get0_id_context - get the SSL ID context associated with a session - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const unsigned char *SSL_SESSION_get0_id_context(const SSL_SESSION *s, - unsigned int *len) - -=head1 DESCRIPTION - -SSL_SESSION_get0_id_context() returns the ID context associated with -the SSL/TLS session B<s>. The length of the ID context is written to -B<*len> if B<len> is not NULL. - -The value returned is a pointer to an object maintained within B<s> and -should not be released. - -=head1 SEE ALSO - -L<ssl(3)>, -L<SSL_set_session_id_context(3)> - -=head1 HISTORY - -SSL_SESSION_get0_id_context() was first added to OpenSSL 1.1.0 - -=head1 COPYRIGHT - -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_SESSION_get_protocol_version.pod b/doc/ssl/SSL_SESSION_get_protocol_version.pod deleted file mode 100644 index a033fdd9bb..0000000000 --- a/doc/ssl/SSL_SESSION_get_protocol_version.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get_protocol_version - retrieve session protocol version - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_SESSION_get_protocol_version(const SSL_SESSION *s); - -=head1 DESCRIPTION - -SSL_SESSION_get_protocol_version() returns the protocol version number used -by session B<s>. - -=head1 RETURN VALUES - -SSL_SESSION_get_protocol_version() returns a number indicating the protocol -version used for the session; this number matches the constants I<e.g.> -B<TLS1_VERSION> or B<TLS1_2_VERSION>. - -Note that the SSL_SESSION_get_protocol_version() function -does B<not> perform a null check on the provided session B<s> pointer. - -=head1 SEE ALSO - -L<ssl(3)> - -=head1 HISTORY - -SSL_SESSION_get_protocol_version() was first added to OpenSSL 1.1.0 - -=head1 COPYRIGHT - -Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_SESSION_get_time.pod b/doc/ssl/SSL_SESSION_get_time.pod deleted file mode 100644 index d92a8efb10..0000000000 --- a/doc/ssl/SSL_SESSION_get_time.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/ssl.h> - - long SSL_SESSION_get_time(const SSL_SESSION *s); - long SSL_SESSION_set_time(SSL_SESSION *s, long tm); - long SSL_SESSION_get_timeout(const SSL_SESSION *s); - long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm); - - long SSL_get_time(const SSL_SESSION *s); - long SSL_set_time(SSL_SESSION *s, long tm); - long SSL_get_timeout(const SSL_SESSION *s); - long SSL_set_timeout(SSL_SESSION *s, long tm); - -=head1 DESCRIPTION - -SSL_SESSION_get_time() returns the time at which the session B<s> was -established. The time is given in seconds since the Epoch and therefore -compatible to the time delivered by the time() call. - -SSL_SESSION_set_time() replaces the creation time of the session B<s> with -the chosen value B<tm>. - -SSL_SESSION_get_timeout() returns the timeout value set for session B<s> -in seconds. - -SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds -to B<tm>. - -The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout() -functions are synonyms for the SSL_SESSION_*() counterparts. - -=head1 NOTES - -Sessions are expired by examining the creation time and the timeout value. -Both are set at creation time of the session to the actual time and the -default timeout value at creation, respectively, as set by -L<SSL_CTX_set_timeout(3)>. -Using these functions it is possible to extend or shorten the lifetime -of the session. - -=head1 RETURN VALUES - -SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently -valid values. - -SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success. - -If any of the function is passed the NULL pointer for the session B<s>, -0 is returned. - -=head1 SEE ALSO - -L<ssl(3)>, -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 diff --git a/doc/ssl/SSL_SESSION_has_ticket.pod b/doc/ssl/SSL_SESSION_has_ticket.pod deleted file mode 100644 index 9e37255299..0000000000 --- a/doc/ssl/SSL_SESSION_has_ticket.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get0_ticket, -SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint, -- get details about the ticket associated with a session - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_SESSION_has_ticket(const SSL_SESSION *s); - unsigned long SSL_SESSION_get_ticket_lifetime_hint(const SSL_SESSION *s); - void SSL_SESSION_get0_ticket(const SSL_SESSION *s, const unsigned char **tick, - size_t *len); - -=head1 DESCRIPTION - -SSL_SESSION_has_ticket() returns 1 if there is a Session Ticket associated with -this session, and 0 otherwise. - -SSL_SESSION_get_ticket_lifetime_hint returns the lifetime hint in seconds -associated with the session ticket. - -SSL_SESSION_get0_ticket obtains a pointer to the ticket associated with a -session. The length of the ticket is written to B<*len>. If B<tick> is non -NULL then a pointer to the ticket is written to B<*tick>. The pointer is only -valid while the connection is in use. The session (and hence the ticket pointer) -may also become invalid as a result of a call to SSL_CTX_flush_sessions(). - -=head1 SEE ALSO - -L<ssl(3)>, -L<d2i_SSL_SESSION(3)>, -L<SSL_SESSION_get_time(3)>, -L<SSL_SESSION_free(3)> - -=head1 HISTORY - -SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint and -SSL_SESSION_get0_ticket were added in OpenSSL 1.1.0. - -=head1 COPYRIGHT - -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_SESSION_set1_id.pod b/doc/ssl/SSL_SESSION_set1_id.pod deleted file mode 100644 index fe8a1c485a..0000000000 --- a/doc/ssl/SSL_SESSION_set1_id.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_set1_id - set the SSL session ID - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_SESSION_set1_id(SSL_SESSION *s, const unsigned char *sid, - unsigned int sid_len); - -=head1 DESCRIPTION - -SSL_SESSION_set1_id() sets the the session ID for the B<ssl> SSL/TLS session -to B<sid> of length B<sid_len>. - -=head1 RETURN VALUES - -SSL_SESSION_set1_id() returns 1 for success and 0 for failure, for example -if the supplied session ID length exceeds B<SSL_MAX_SSL_SESSION_ID_LENGTH>. - -=head1 SEE ALSO - -L<ssl(3)> - -=head1 HISTORY - -SSL_SESSION_set1_id() was first added to OpenSSL 1.1.0 - -=head1 COPYRIGHT - -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_accept.pod b/doc/ssl/SSL_accept.pod deleted file mode 100644 index 3248cacf1e..0000000000 --- a/doc/ssl/SSL_accept.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_accept(SSL *ssl); - -=head1 DESCRIPTION - -SSL_accept() waits for a TLS/SSL client to initiate the TLS/SSL handshake. -The communication channel must already have been set and assigned to the -B<ssl> by setting an underlying B<BIO>. - -=head1 NOTES - -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. - -If the underlying BIO is B<non-blocking>, SSL_accept() will also return -when the underlying BIO could not satisfy the needs of SSL_accept() -to continue the handshake, indicating the problem by the return value -1. -In this case a call to SSL_get_error() with the -return value of SSL_accept() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_accept(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check 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. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item Z<>0 - -The TLS/SSL handshake was not successful but was shut down controlled and -by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the -return value B<ret> to find out the reason. - -=item Z<>1 - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item E<lt>0 - -The TLS/SSL handshake was not successful because a fatal error occurred either -at the protocol level or a connection failure occurred. The shutdown was -not clean. It can also occur of action is need to continue the operation -for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> -to find out the reason. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_alert_type_string.pod b/doc/ssl/SSL_alert_type_string.pod deleted file mode 100644 index 6e2768e8ff..0000000000 --- a/doc/ssl/SSL_alert_type_string.pod +++ /dev/null @@ -1,242 +0,0 @@ -=pod - -=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 - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const char *SSL_alert_type_string(int value); - const char *SSL_alert_type_string_long(int value); - - const char *SSL_alert_desc_string(int value); - const char *SSL_alert_desc_string_long(int value); - -=head1 DESCRIPTION - -SSL_alert_type_string() returns a one letter string indicating the -type of the alert specified by B<value>. - -SSL_alert_type_string_long() returns a string indicating the type of the alert -specified by B<value>. - -SSL_alert_desc_string() returns a two letter string as a short form -describing the reason of the alert specified by B<value>. - -SSL_alert_desc_string_long() returns a string describing the reason -of the alert specified by B<value>. - -=head1 NOTES - -When one side of an SSL/TLS communication wants to inform the peer about -a special situation, it sends an alert. The alert is sent as a special message -and does not influence the normal data stream (unless its contents results -in the communication being canceled). - -A warning alert is sent, when a non-fatal error condition occurs. The -"close notify" alert is sent as a warning alert. Other examples for -non-fatal errors are certificate errors ("certificate expired", -"unsupported certificate"), for which a warning alert may be sent. -(The sending party may however decide to send a fatal error.) The -receiving side may cancel the connection on reception of a warning -alert on it discretion. - -Several alert messages must be sent as fatal alert messages as specified -by the TLS RFC. A fatal alert always leads to a connection abort. - -=head1 RETURN VALUES - -The following strings can occur for SSL_alert_type_string() or -SSL_alert_type_string_long(): - -=over 4 - -=item "W"/"warning" - -=item "F"/"fatal" - -=item "U"/"unknown" - -This indicates that no support is available for this alert type. -Probably B<value> does not contain a correct alert message. - -=back - -The following strings can occur for SSL_alert_desc_string() or -SSL_alert_desc_string_long(): - -=over 4 - -=item "CN"/"close notify" - -The connection shall be closed. This is a warning alert. - -=item "UM"/"unexpected message" - -An inappropriate message was received. This alert is always fatal -and should never be observed in communication between proper -implementations. - -=item "BM"/"bad record mac" - -This alert is returned if a record is received with an incorrect -MAC. This message is always fatal. - -=item "DF"/"decompression failure" - -The decompression function received improper input (e.g. data -that would expand to excessive length). This message is always -fatal. - -=item "HF"/"handshake failure" - -Reception of a handshake_failure alert message indicates that the -sender was unable to negotiate an acceptable set of security -parameters given the options available. This is a fatal error. - -=item "NC"/"no certificate" - -A client, that was asked to send a certificate, does not send a certificate -(SSLv3 only). - -=item "BC"/"bad certificate" - -A certificate was corrupt, contained signatures that did not -verify correctly, etc - -=item "UC"/"unsupported certificate" - -A certificate was of an unsupported type. - -=item "CR"/"certificate revoked" - -A certificate was revoked by its signer. - -=item "CE"/"certificate expired" - -A certificate has expired or is not currently valid. - -=item "CU"/"certificate unknown" - -Some other (unspecified) issue arose in processing the -certificate, rendering it unacceptable. - -=item "IP"/"illegal parameter" - -A field in the handshake was out of range or inconsistent with -other fields. This is always fatal. - -=item "DC"/"decryption failed" - -A TLSCiphertext decrypted in an invalid way: either it wasn't an -even multiple of the block length or its padding values, when -checked, weren't correct. This message is always fatal. - -=item "RO"/"record overflow" - -A TLSCiphertext record was received which had a length more than -2^14+2048 bytes, or a record decrypted to a TLSCompressed record -with more than 2^14+1024 bytes. This message is always fatal. - -=item "CA"/"unknown CA" - -A valid certificate chain or partial chain was received, but the -certificate was not accepted because the CA certificate could not -be located or couldn't be matched with a known, trusted CA. This -message is always fatal. - -=item "AD"/"access denied" - -A valid certificate was received, but when access control was -applied, the sender decided not to proceed with negotiation. -This message is always fatal. - -=item "DE"/"decode error" - -A message could not be decoded because some field was out of the -specified range or the length of the message was incorrect. This -message is always fatal. - -=item "CY"/"decrypt error" - -A handshake cryptographic operation failed, including being -unable to correctly verify a signature, decrypt a key exchange, -or validate a finished message. - -=item "ER"/"export restriction" - -A negotiation not in compliance with export restrictions was -detected; for example, attempting to transfer a 1024 bit -ephemeral RSA key for the RSA_EXPORT handshake method. This -message is always fatal. - -=item "PV"/"protocol version" - -The protocol version the client has attempted to negotiate is -recognized, but not supported. (For example, old protocol -versions might be avoided for security reasons). This message is -always fatal. - -=item "IS"/"insufficient security" - -Returned instead of handshake_failure when a negotiation has -failed specifically because the server requires ciphers more -secure than those supported by the client. This message is always -fatal. - -=item "IE"/"internal error" - -An internal error unrelated to the peer or the correctness of the -protocol makes it impossible to continue (such as a memory -allocation failure). This message is always fatal. - -=item "US"/"user canceled" - -This handshake is being canceled for some reason unrelated to a -protocol failure. If the user cancels an operation after the -handshake is complete, just closing the connection by sending a -close_notify is more appropriate. This alert should be followed -by a close_notify. This message is generally a warning. - -=item "NR"/"no renegotiation" - -Sent by the client in response to a hello request or by the -server in response to a client hello after initial handshaking. -Either of these would normally lead to renegotiation; when that -is not appropriate, the recipient should respond with this alert; -at that point, the original requester can decide whether to -proceed with the connection. One case where this would be -appropriate would be where a server has spawned a process to -satisfy a request; the process might receive security parameters -(key length, authentication, etc.) at startup and it might be -difficult to communicate changes to these parameters after that -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. - -=item "UK"/"unknown" - -This indicates that no description is available for this alert type. -Probably B<value> does not contain a correct alert message. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_check_chain.pod b/doc/ssl/SSL_check_chain.pod deleted file mode 100644 index 8691994229..0000000000 --- a/doc/ssl/SSL_check_chain.pod +++ /dev/null @@ -1,94 +0,0 @@ -=pod - -=head1 NAME - -SSL_check_chain - check certificate chain suitability - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain); - -=head1 DESCRIPTION - -SSL_check_chain() checks whether certificate B<x>, private key B<pk> and -certificate chain B<chain> is suitable for use with the current session -B<s>. - -=head1 RETURN VALUES - -SSL_check_chain() returns a bitmap of flags indicating the validity of the -chain. - -B<CERT_PKEY_VALID>: the chain can be used with the current session. -If this flag is B<not> set then the certificate will never be used even -if the application tries to set it because it is inconsistent with the -peer preferences. - -B<CERT_PKEY_SIGN>: the EE key can be used for signing. - -B<CERT_PKEY_EE_SIGNATURE>: the signature algorithm of the EE certificate is -acceptable. - -B<CERT_PKEY_CA_SIGNATURE>: the signature algorithms of all CA certificates -are acceptable. - -B<CERT_PKEY_EE_PARAM>: the parameters of the end entity certificate are -acceptable (e.g. it is a supported curve). - -B<CERT_PKEY_CA_PARAM>: the parameters of all CA certificates are acceptable. - -B<CERT_PKEY_EXPLICIT_SIGN>: the end entity certificate algorithm -can be used explicitly for signing (i.e. it is mentioned in the signature -algorithms extension). - -B<CERT_PKEY_ISSUER_NAME>: the issuer name is acceptable. This is only -meaningful for client authentication. - -B<CERT_PKEY_CERT_TYPE>: the certificate type is acceptable. Only meaningful -for client authentication. - -B<CERT_PKEY_SUITEB>: chain is suitable for Suite B use. - -=head1 NOTES - -SSL_check_chain() must be called in servers after a client hello message or in -clients after a certificate request message. It will typically be called -in the certificate callback. - -An application wishing to support multiple certificate chains may call this -function on each chain in turn: starting with the one it considers the -most secure. It could then use the chain of the first set which returns -suitable flags. - -As a minimum the flag B<CERT_PKEY_VALID> must be set for a chain to be -usable. An application supporting multiple chains with different CA signature -algorithms may also wish to check B<CERT_PKEY_CA_SIGNATURE> too. If no -chain is suitable a server should fall back to the most secure chain which -sets B<CERT_PKEY_VALID>. - -The validity of a chain is determined by checking if it matches a supported -signature algorithm, supported curves and in the case of client authentication -certificate types and issuer names. - -Since the supported signature algorithms extension is only used in TLS 1.2 -and DTLS 1.2 the results for earlier versions of TLS and DTLS may not be -very useful. Applications may wish to specify a different "legacy" chain -for earlier versions of TLS or DTLS. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_clear.pod b/doc/ssl/SSL_clear.pod deleted file mode 100644 index ed0ad60cbe..0000000000 --- a/doc/ssl/SSL_clear.pod +++ /dev/null @@ -1,84 +0,0 @@ -=pod - -=head1 NAME - -SSL_clear - reset SSL object to allow another connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_clear(SSL *ssl); - -=head1 DESCRIPTION - -Reset B<ssl> to allow another connection. All settings (method, ciphers, -BIOs) are kept. - -=head1 NOTES - -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)> 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 -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 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 - -SSL_clear() resets the SSL object to allow for another connection. The -reset operation however keeps several settings of the last sessions -(some of these settings were made automatically during the last -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)>; -L<SSL_new(3)>; -L<SSL_set_session(3)>; -L<SSL_free(3)> -instead to avoid such failures -(or simply L<SSL_free(3)>; L<SSL_new(3)> -if session reuse is not desired). - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item Z<>0 - -The SSL_clear() operation could not be performed. Check the error stack to -find out the reason. - -=item Z<>1 - -The SSL_clear() operation was successful. - -=back - -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 diff --git a/doc/ssl/SSL_connect.pod b/doc/ssl/SSL_connect.pod deleted file mode 100644 index df198f9b2e..0000000000 --- a/doc/ssl/SSL_connect.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_connect(SSL *ssl); - -=head1 DESCRIPTION - -SSL_connect() initiates the TLS/SSL handshake with a server. The communication -channel must already have been set and assigned to the B<ssl> by setting an -underlying B<BIO>. - -=head1 NOTES - -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. - -If the underlying BIO is B<non-blocking>, SSL_connect() will also return -when the underlying BIO could not satisfy the needs of SSL_connect() -to continue the handshake, indicating the problem by the return value -1. -In this case a call to SSL_get_error() with the -return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_connect(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check 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. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item Z<>0 - -The TLS/SSL handshake was not successful but was shut down controlled and -by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the -return value B<ret> to find out the reason. - -=item Z<>1 - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item E<lt>0 - -The TLS/SSL handshake was not successful, because a fatal error occurred either -at the protocol level or a connection failure occurred. The shutdown was -not clean. It can also occur of action is need to continue the operation -for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> -to find out the reason. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_do_handshake.pod b/doc/ssl/SSL_do_handshake.pod deleted file mode 100644 index ffb71cc0b8..0000000000 --- a/doc/ssl/SSL_do_handshake.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -SSL_do_handshake - perform a TLS/SSL handshake - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_do_handshake(SSL *ssl); - -=head1 DESCRIPTION - -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)> or -L<SSL_set_accept_state(3)>. - -=head1 NOTES - -The behaviour of SSL_do_handshake() depends on the underlying BIO. - -If the underlying BIO is B<blocking>, SSL_do_handshake() will only return -once the handshake has been finished or an error occurred. - -If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return -when the underlying BIO could not satisfy the needs of SSL_do_handshake() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_do_handshake(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check 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. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item Z<>0 - -The TLS/SSL handshake was not successful but was shut down controlled and -by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the -return value B<ret> to find out the reason. - -=item Z<>1 - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item E<lt>0 - -The TLS/SSL handshake was not successful because a fatal error occurred either -at the protocol level or a connection failure occurred. The shutdown was -not clean. It can also occur of action is need to continue the operation -for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> -to find out the reason. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_extension_supported.pod b/doc/ssl/SSL_extension_supported.pod deleted file mode 100644 index a56087e130..0000000000 --- a/doc/ssl/SSL_extension_supported.pod +++ /dev/null @@ -1,144 +0,0 @@ -=pod - -=head1 NAME - -SSL_extension_supported, -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. - -=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 diff --git a/doc/ssl/SSL_free.pod b/doc/ssl/SSL_free.pod deleted file mode 100644 index eb69a162bc..0000000000 --- a/doc/ssl/SSL_free.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -SSL_free - free an allocated SSL structure - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_free(SSL *ssl); - -=head1 DESCRIPTION - -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 - -SSL_free() also calls the free()ing procedures for indirectly affected items, if -applicable: the buffering BIO, the read and write BIOs, -cipher lists specially created for this B<ssl>, the B<SSL_SESSION>. -Do not explicitly free these indirectly freed up items before or after -calling SSL_free(), as trying to free things twice may lead to program -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)> 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. - -=head1 RETURN VALUES - -SSL_free() does not provide diagnostic information. - -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 diff --git a/doc/ssl/SSL_get0_peer_scts.pod b/doc/ssl/SSL_get0_peer_scts.pod deleted file mode 100644 index 05d39fee8c..0000000000 --- a/doc/ssl/SSL_get0_peer_scts.pod +++ /dev/null @@ -1,45 +0,0 @@ -=pod - -=head1 NAME - -SSL_get0_peer_scts - get SCTs received - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s); - -=head1 DESCRIPTION - -SSL_get0_peer_scts() returns the signed certificate timestamps (SCTs) that have -been received. If this is the first time that this function has been called for -a given B<SSL> instance, it will examine the TLS extensions, OCSP response and -the peer's certificate for SCTs. Future calls will return the same SCTs. - -=head1 RESTRICTIONS - -If no Certificate Transparency validation callback has been set (using -B<SSL_CTX_set_ct_validation_callback> or B<SSL_set_ct_validation_callback>), -this function is not guaranteed to return all of the SCTs that the peer is -capable of sending. - -=head1 RETURN VALUES - -SSL_get0_peer_scts() returns a list of SCTs found, or NULL if an error occurs. - -=head1 SEE ALSO - -L<ssl(3)>, -L<SSL_CTX_set_ct_validation_callback(3)> - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_get_SSL_CTX.pod b/doc/ssl/SSL_get_SSL_CTX.pod deleted file mode 100644 index 98b9bc67eb..0000000000 --- a/doc/ssl/SSL_get_SSL_CTX.pod +++ /dev/null @@ -1,35 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_SSL_CTX - get the SSL_CTX from which an SSL is created - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl); - -=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)>. - -=head1 RETURN VALUES - -The pointer to the SSL_CTX object is returned. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_get_all_async_fds.pod b/doc/ssl/SSL_get_all_async_fds.pod deleted file mode 100644 index b4fa4ee0d1..0000000000 --- a/doc/ssl/SSL_get_all_async_fds.pod +++ /dev/null @@ -1,88 +0,0 @@ -=pod - -=head1 NAME - -SSL_waiting_for_async, -SSL_get_all_async_fds, -SSL_get_changed_async_fds -- manage asynchronous operations - -=for comment multiple includes - -=head1 SYNOPSIS - - #include <openssl/async.h> - #include <openssl/ssl.h> - - int SSL_waiting_for_async(SSL *s); - int SSL_get_all_async_fds(SSL *s, OSSL_ASYNC_FD *fd, size_t *numfds); - int SSL_get_changed_async_fds(SSL *s, OSSL_ASYNC_FD *addfd, size_t *numaddfds, - OSSL_ASYNC_FD *delfd, size_t *numdelfds); - -=head1 DESCRIPTION - -SSL_waiting_for_async() determines whether an SSL connection is currently -waiting for asynchronous operations to complete (see the SSL_MODE_ASYNC mode in -L<SSL_CTX_set_mode(3)>). - -SSL_get_all_async_fds() returns a list of file descriptor which can be used in a -call to select() or poll() to determine whether the current asynchronous -operation has completed or not. A completed operation will result in data -appearing as "read ready" on the file descriptor (no actual data should be read -from the file descriptor). This function should only be called if the SSL object -is currently waiting for asynchronous work to complete (i.e. -SSL_ERROR_WANT_ASYNC has been received - see L<SSL_get_error(3)>). Typically the -list will only contain one file descriptor. However if multiple asynchronous -capable engines are in use then more than one is possible. The number of file -descriptors returned is stored in B<*numfds> and the file descriptors themselves -are in B<*fds>. The B<fds> parameter may be NULL in which case no file -descriptors are returned but B<*numfds> is still populated. It is the callers -responsibility to ensure sufficient memory is allocated at B<*fds> so typically -this function is called twice (once with a NULL B<fds> parameter and once -without). - -SSL_get_changed_async_fds() returns a list of the asynchronous file descriptors -that have been added and a list that have been deleted since the last -SSL_ERROR_WANT_ASYNC was received (or since the SSL object was created if no -SSL_ERROR_WANT_ASYNC has been received). Similar to SSL_get_all_async_fds() it -is the callers responsibility to ensure that B<*addfd> and B<*delfd> have -sufficient memory allocated, although they may be NULL. The number of added fds -and the number of deleted fds are stored in B<*numaddfds> and B<*numdelfds> -respectively. - -=head1 RETURN VALUES - -SSL_waiting_for_async() will return 1 if the current SSL operation is waiting -for an async operation to complete and 0 otherwise. - -SSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or -0 on error. - -=head1 NOTES - -On Windows platforms the openssl/async.h header is dependent on some -of the types customarily made available by including windows.h. The -application developer is likely to require control over when the latter -is included, commonly as one of the first included headers. Therefore -it is defined as an application developer's responsibility to include -windows.h prior to async.h. - -=head1 SEE ALSO - -L<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)> - -=head1 HISTORY - -SSL_waiting_for_async(), SSL_get_all_async_fds() and SSL_get_changed_async_fds() -were first added to OpenSSL 1.1.0. - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_get_ciphers.pod b/doc/ssl/SSL_get_ciphers.pod deleted file mode 100644 index cc55095d47..0000000000 --- a/doc/ssl/SSL_get_ciphers.pod +++ /dev/null @@ -1,84 +0,0 @@ -=pod - -=head1 NAME - -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 - -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 -is returned. - -=head1 NOTES - -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)>, 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 diff --git a/doc/ssl/SSL_get_client_CA_list.pod b/doc/ssl/SSL_get_client_CA_list.pod deleted file mode 100644 index b6092fe32d..0000000000 --- a/doc/ssl/SSL_get_client_CA_list.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s); - 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_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)>, when in -server mode. In client mode, SSL_get_client_CA_list returns the list of -client CAs sent from the server, if any. - -=head1 RETURN VALUES - -SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return -diagnostic information. - -SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return -values: - -=over 4 - -=item STACK_OF(X509_NAMES) - -List of CA names explicitly set (for B<ctx> or in server mode) or send -by the server (client mode). - -=item NULL - -No client CA list was explicitly set (for B<ctx> or in server mode) or -the server did not send a list of CAs (client mode). - -=back - -=head1 SEE ALSO - -L<ssl(3)>, -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 diff --git a/doc/ssl/SSL_get_client_random.pod b/doc/ssl/SSL_get_client_random.pod deleted file mode 100644 index 46a2aa35ea..0000000000 --- a/doc/ssl/SSL_get_client_random.pod +++ /dev/null @@ -1,88 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key - retrieve internal TLS/SSL random values and master key - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen); - size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen); - size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, unsigned char *out, size_t outlen); - -=head1 DESCRIPTION - -SSL_get_client_random() extracts the random value sent from the client -to the server during the initial SSL/TLS handshake. It copies as many -bytes as it can of this value into the buffer provided in B<out>, -which must have at least B<outlen> bytes available. It returns the -total number of bytes that were actually copied. If B<outlen> is -zero, SSL_get_client_random() copies nothing, and returns the -total size of the client_random value. - -SSL_get_server_random() behaves the same, but extracts the random value -sent from the server to the client during the initial SSL/TLS handshake. - -SSL_SESSION_get_master_key() behaves the same, but extracts the master -secret used to guarantee the security of the SSL/TLS session. This one -can be dangerous if misused; see NOTES below. - - -=head1 NOTES - -You probably shouldn't use these functions. - -These functions expose internal values from the TLS handshake, for -use in low-level protocols. You probably should not use them, unless -you are implementing something that needs access to the internal protocol -details. - -Despite the names of SSL_get_client_random() and SSL_get_server_random(), they -ARE NOT random number generators. Instead, they return the mostly-random values that -were already generated and used in the TLS protocol. Using them -in place of RAND_bytes() would be grossly foolish. - -The security of your TLS session depends on keeping the master key secret: -do not expose it, or any information about it, to anybody. -If you need to calculate another secret value that depends on the master -secret, you should probably use SSL_export_keying_material() instead, and -forget that you ever saw these functions. - -In current versions of the TLS protocols, the length of client_random -(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for -other outlen arguments to the SSL_get_*_random() functions is provided -in case of the unlikely event that a future version or variant of TLS -uses some other length there. - -Finally, though the "client_random" and "server_random" values are called -"random", many TLS implementations will generate four bytes of those -values based on their view of the current time. - - -=head1 RETURN VALUES - -If B<outlen> is greater than 0, these functions return the number of bytes -actually copied, which will be less than or equal to B<outlen>. - -If B<outlen> is 0, these functions return the maximum number -of bytes they would copy--that is, the length of the underlying field. - -=head1 SEE ALSO - -L<ssl(3)>, -L<RAND_bytes(3)>, -L<SSL_export_keying_material(3)> - - -=head1 COPYRIGHT - -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_get_current_cipher.pod b/doc/ssl/SSL_get_current_cipher.pod deleted file mode 100644 index 87cecb0ce2..0000000000 --- a/doc/ssl/SSL_get_current_cipher.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 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 - - #include <openssl/ssl.h> - - SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl); - - 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_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. - -=head1 RETURN VALUES - -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)>, 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 diff --git a/doc/ssl/SSL_get_default_timeout.pod b/doc/ssl/SSL_get_default_timeout.pod deleted file mode 100644 index 875d38a9e6..0000000000 --- a/doc/ssl/SSL_get_default_timeout.pod +++ /dev/null @@ -1,50 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_default_timeout - get default session timeout value - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_get_default_timeout(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_default_timeout() returns the default timeout value assigned to -SSL_SESSION objects negotiated for the protocol valid for B<ssl>. - -=head1 NOTES - -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)>, 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. - -=head1 RETURN VALUES - -See description. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_get_error.pod b/doc/ssl/SSL_get_error.pod deleted file mode 100644 index ddd72f7065..0000000000 --- a/doc/ssl/SSL_get_error.pod +++ /dev/null @@ -1,145 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_error - obtain result code for TLS/SSL I/O operation - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_error(const SSL *ssl, int ret); - -=head1 DESCRIPTION - -SSL_get_error() returns a result code (suitable for the C "switch" -statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(), -SSL_read(), SSL_peek(), or SSL_write() on B<ssl>. The value returned by -that TLS/SSL I/O function must be passed to SSL_get_error() in parameter -B<ret>. - -In addition to B<ssl> and B<ret>, SSL_get_error() inspects the -current thread's OpenSSL error queue. Thus, SSL_get_error() must be -used in the same thread that performed the TLS/SSL I/O operation, and no -other OpenSSL function calls should appear in between. The current -thread's error queue must be empty before the TLS/SSL I/O operation is -attempted, or SSL_get_error() will not work reliably. - -=head1 RETURN VALUES - -The following return values can currently occur: - -=over 4 - -=item SSL_ERROR_NONE - -The TLS/SSL I/O operation completed. This result code is returned -if and only if B<ret E<gt> 0>. - -=item SSL_ERROR_ZERO_RETURN - -The TLS/SSL connection has been closed. If the protocol version is SSL 3.0 -or TLS 1.0, this result code is returned only if a closure -alert has occurred in the protocol, i.e. if the connection has been -closed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN> -does not necessarily indicate that the underlying transport -has been closed. - -=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE - -The operation did not complete; the same TLS/SSL I/O function should be -called again later. If, by then, the underlying B<BIO> has data -available for reading (if the result code is B<SSL_ERROR_WANT_READ>) -or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL -protocol progress will take place, i.e. at least part of an TLS/SSL -record will be read or written. Note that the retry may again lead to -a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition. -There is no fixed upper limit for the number of iterations that -may be necessary until progress becomes visible at application -protocol level. - -For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or -poll() on the underlying socket can be used to find out when the -TLS/SSL I/O function should be retried. - -Caveat: Any TLS/SSL I/O function can lead to either of -B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. In particular, -SSL_read() or SSL_peek() may want to write data and SSL_write() may want -to read data. This is mainly because TLS/SSL handshakes may occur at any -time during the protocol (initiated by either the client or the server); -SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes. - -=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT - -The operation did not complete; the same TLS/SSL I/O function should be -called again later. The underlying BIO was not connected yet to the peer -and the call would block in connect()/accept(). The SSL function should be -called again when the connection is established. These messages can only -appear with a BIO_s_connect() or BIO_s_accept() BIO, respectively. -In order to find out, when the connection has been successfully established, -on many platforms select() or poll() for writing on the socket file descriptor -can be used. - -=item SSL_ERROR_WANT_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. -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 I/O error occurred. The OpenSSL error queue may contain more -information on the error. If the error queue is empty -(i.e. ERR_get_error() returns 0), B<ret> can be used to find out more -about the error: If B<ret == 0>, an EOF was observed that violates -the protocol. If B<ret == -1>, the underlying B<BIO> reported an -I/O error (for socket I/O on Unix systems, consult B<errno> for details). - -=item SSL_ERROR_SSL - -A failure in the SSL library occurred, usually a protocol error. The -OpenSSL error queue contains more information on the error. - -=back - -=head1 SEE ALSO - -L<ssl(3)>, L<err(3)> - -=head1 HISTORY - -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 diff --git a/doc/ssl/SSL_get_extms_support.pod b/doc/ssl/SSL_get_extms_support.pod deleted file mode 100644 index ba4de3a560..0000000000 --- a/doc/ssl/SSL_get_extms_support.pod +++ /dev/null @@ -1,40 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_extms_support - extended master secret support - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_extms_support(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_extms_support() indicates whether the current session used extended -master secret. - -This function is implemented as a macro. - -=head1 RETURN VALUES - -SSL_get_extms_support() returns 1 if the current session used extended -master secret, 0 if it did not and -1 if a handshake is currently in -progress i.e. it is not possible to determine if extended master secret -was used. - -=head1 SEE ALSO - -L<ssl(3)> - -=head1 COPYRIGHT - -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_get_fd.pod b/doc/ssl/SSL_get_fd.pod deleted file mode 100644 index cd5b6ecf4f..0000000000 --- a/doc/ssl/SSL_get_fd.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_fd, SSL_get_rfd, SSL_get_wfd - get file descriptor linked to an SSL object - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_fd(const SSL *ssl); - int SSL_get_rfd(const SSL *ssl); - int SSL_get_wfd(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_fd() returns the file descriptor which is linked to B<ssl>. -SSL_get_rfd() and SSL_get_wfd() return the file descriptors for the -read or the write channel, which can be different. If the read and the -write channel are different, SSL_get_fd() will return the file descriptor -of the read channel. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item -1 - -The operation failed, because the underlying BIO is not of the correct type -(suitable for file descriptors). - -=item E<gt>=0 - -The file descriptor linked to B<ssl>. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_get_peer_cert_chain.pod b/doc/ssl/SSL_get_peer_cert_chain.pod deleted file mode 100644 index 2e4f1e4185..0000000000 --- a/doc/ssl/SSL_get_peer_cert_chain.pod +++ /dev/null @@ -1,77 +0,0 @@ -=pod - -=head1 NAME - -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 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)>. -If the peer did not present a certificate, NULL is returned. - -NB: SSL_get_peer_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 - -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 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 - -The following return values can occur: - -=over 4 - -=item NULL - -No certificate was presented by the peer or no connection was established -or the certificate chain is no longer available when a session is reused. - -=item Pointer to a STACK_OF(X509) - -The return value points to the certificate chain presented by the peer. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_get_peer_certificate.pod b/doc/ssl/SSL_get_peer_certificate.pod deleted file mode 100644 index 57ed2723eb..0000000000 --- a/doc/ssl/SSL_get_peer_certificate.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_peer_certificate - get the X509 certificate of the peer - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - X509 *SSL_get_peer_certificate(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_peer_certificate() returns a pointer to the X509 certificate the -peer presented. If the peer did not present a certificate, NULL is returned. - -=head1 NOTES - -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)>). 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)> -to check the verification state. - -The reference count of the X509 object is incremented by one, so that it -will not be destroyed when the session containing the peer certificate is -freed. The X509 object must be explicitly freed using X509_free(). - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -No certificate was presented by the peer or no connection was established. - -=item Pointer to an X509 certificate - -The return value points to the certificate presented by the peer. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_get_psk_identity.pod b/doc/ssl/SSL_get_psk_identity.pod deleted file mode 100644 index d330eee52d..0000000000 --- a/doc/ssl/SSL_get_psk_identity.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_psk_identity, SSL_get_psk_identity_hint - get PSK client identity and hint - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const char *SSL_get_psk_identity_hint(const SSL *ssl); - const char *SSL_get_psk_identity(const SSL *ssl); - - -=head1 DESCRIPTION - -SSL_get_psk_identity_hint() is used to retrieve the PSK identity hint -used during the connection setup related to SSL object -B<ssl>. Similarly, SSL_get_psk_identity() is used to retrieve the PSK -identity used during the connection setup. - - -=head1 RETURN VALUES - -If non-B<NULL>, SSL_get_psk_identity_hint() returns the PSK identity -hint and SSL_get_psk_identity() returns the PSK identity. Both are -B<NULL>-terminated. SSL_get_psk_identity_hint() may return B<NULL> if -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 diff --git a/doc/ssl/SSL_get_rbio.pod b/doc/ssl/SSL_get_rbio.pod deleted file mode 100644 index 5ac4ca2740..0000000000 --- a/doc/ssl/SSL_get_rbio.pod +++ /dev/null @@ -1,49 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_rbio, SSL_get_wbio - get BIO linked to an SSL object - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - BIO *SSL_get_rbio(SSL *ssl); - BIO *SSL_get_wbio(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the -read or the write channel, which can be different. The reference count -of the BIO is not incremented. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -No BIO was connected to the SSL object - -=item Any other pointer - -The BIO linked to B<ssl>. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_get_session.pod b/doc/ssl/SSL_get_session.pod deleted file mode 100644 index 99936ad765..0000000000 --- a/doc/ssl/SSL_get_session.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_session, SSL_get0_session, SSL_get1_session - retrieve TLS/SSL session data - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL_SESSION *SSL_get_session(const SSL *ssl); - SSL_SESSION *SSL_get0_session(const SSL *ssl); - SSL_SESSION *SSL_get1_session(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in -B<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so -that the pointer can become invalid by other operations. - -SSL_get0_session() is the same as SSL_get_session(). - -SSL_get1_session() is the same as SSL_get_session(), but the reference -count of the B<SSL_SESSION> is incremented by one. - -=head1 NOTES - -The ssl session contains all information required to re-establish the -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)> 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)>. - -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)> must be explicitly called once -to decrement the reference count again. - -SSL_SESSION objects keep internal link information about the session cache -list, when being inserted into one SSL_CTX object's session cache. -One SSL_SESSION object, regardless of its reference count, must therefore -only be used with one SSL_CTX object (and the SSL objects created -from this SSL_CTX object). - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -There is no session available in B<ssl>. - -=item Pointer to an SSL_SESSION - -The return value points to the data of an SSL session. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_get_shared_sigalgs.pod b/doc/ssl/SSL_get_shared_sigalgs.pod deleted file mode 100644 index 6a70e9023b..0000000000 --- a/doc/ssl/SSL_get_shared_sigalgs.pod +++ /dev/null @@ -1,86 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_shared_sigalgs, SSL_get_sigalgs - get supported signature algorithms - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_shared_sigalgs(SSL *s, int idx, - int *psign, int *phash, int *psignhash, - unsigned char *rsig, unsigned char *rhash); - - int SSL_get_sigalgs(SSL *s, int idx, - int *psign, int *phash, int *psignhash, - unsigned char *rsig, unsigned char *rhash); - -=head1 DESCRIPTION - -SSL_get_shared_sigalgs() returns information about the shared signature -algorithms supported by peer B<s>. The parameter B<idx> indicates the index -of the shared signature algorithm to return starting from zero. The signature -algorithm NID is written to B<*psign>, the hash NID to B<*phash> and the -sign and hash NID to B<*psignhash>. The raw signature and hash values -are written to B<*rsig> and B<*rhash>. - -SSL_get_sigalgs() is similar to SSL_get_shared_sigalgs() except it returns -information about all signature algorithms supported by B<s> in the order -they were sent by the peer. - -=head1 RETURN VALUES - -SSL_get_shared_sigalgs() and SSL_get_sigalgs() return the number of -signature algorithms or B<0> if the B<idx> parameter is out of range. - -=head1 NOTES - -These functions are typically called for debugging purposes (to report -the peer's preferences) or where an application wants finer control over -certificate selection. Most applications will rely on internal handling -and will not need to call them. - -If an application is only interested in the highest preference shared -signature algorithm it can just set B<idx> to zero. - -Any or all of the parameters B<psign>, B<phash>, B<psignhash>, B<rsig> or -B<rhash> can be set to B<NULL> if the value is not required. By setting -them all to B<NULL> and setting B<idx> to zero the total number of -signature algorithms can be determined: which can be zero. - -These functions must be called after the peer has sent a list of supported -signature algorithms: after a client hello (for servers) or a certificate -request (for clients). They can (for example) be called in the certificate -callback. - -Only TLS 1.2 and DTLS 1.2 currently support signature algorithms. If these -functions are called on an earlier version of TLS or DTLS zero is returned. - -The shared signature algorithms returned by SSL_get_shared_sigalgs() are -ordered according to configuration and peer preferences. - -The raw values correspond to the on the wire form as defined by RFC5246 et al. -The NIDs are OpenSSL equivalents. For example if the peer sent sha256(4) and -rsa(1) then B<*rhash> would be 4, B<*rsign> 1, B<*phash> NID_sha256, B<*psig> -NID_rsaEncryption and B<*psighash> NID_sha256WithRSAEncryption. - -If a signature algorithm is not recognised the corresponding NIDs -will be set to B<NID_undef>. This may be because the value is not supported -or is not an appropriate combination (for example MD5 and DSA). - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_get_verify_result.pod b/doc/ssl/SSL_get_verify_result.pod deleted file mode 100644 index 3b8b657846..0000000000 --- a/doc/ssl/SSL_get_verify_result.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_verify_result - get result of peer certificate verification - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - long SSL_get_verify_result(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_verify_result() returns the result of the verification of the -X509 certificate presented by the peer, if any. - -=head1 NOTES - -SSL_get_verify_result() can only return one error code while the verification -of a certificate can fail because of many reasons at the same time. Only -the last verification error that occurred during the processing is available -from SSL_get_verify_result(). - -The verification result is part of the established session and is restored -when a session is reused. - -=head1 BUGS - -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)>. - -=head1 RETURN VALUES - -The following return values can currently occur: - -=over 4 - -=item X509_V_OK - -The verification succeeded or no peer certificate was presented. - -=item Any other value - -Documented in L<verify(1)>. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_get_version.pod b/doc/ssl/SSL_get_version.pod deleted file mode 100644 index 23b6497d4f..0000000000 --- a/doc/ssl/SSL_get_version.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_version, SSL_is_dtls - get the protocol information of a connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - 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 - -SSL_get_version() returns one of the following strings: - -=over 4 - -=item SSLv3 - -The connection uses the SSLv3 protocol. - -=item TLSv1 - -The connection uses the TLSv1.0 protocol. - -=item TLSv1.1 - -The connection uses the TLSv1.1 protocol. - -=item TLSv1.2 - -The connection uses the TLSv1.2 protocol. - -=item unknown - -This indicates that no version has been set (no connection established). - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_library_init.pod b/doc/ssl/SSL_library_init.pod deleted file mode 100644 index 6b921f66e7..0000000000 --- a/doc/ssl/SSL_library_init.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -SSL_library_init, OpenSSL_add_ssl_algorithms, -- initialize SSL library by registering algorithms - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_library_init(void); - - int OpenSSL_add_ssl_algorithms(void); - -=head1 DESCRIPTION - -SSL_library_init() registers the available SSL/TLS ciphers and digests. - -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. - -=head1 WARNING - -SSL_library_init() adds ciphers and digests used directly and indirectly by -SSL/TLS. - -=head1 RETURN VALUES - -SSL_library_init() always returns "1", so it is safe to discard the return -value. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_load_client_CA_file.pod b/doc/ssl/SSL_load_client_CA_file.pod deleted file mode 100644 index cc6a19cdea..0000000000 --- a/doc/ssl/SSL_load_client_CA_file.pod +++ /dev/null @@ -1,71 +0,0 @@ -=pod - -=head1 NAME - -SSL_load_client_CA_file - load certificate names from file - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file); - -=head1 DESCRIPTION - -SSL_load_client_CA_file() reads certificates from B<file> and returns -a STACK_OF(X509_NAME) with the subject names found. - -=head1 NOTES - -SSL_load_client_CA_file() reads a file of PEM formatted certificates and -extracts the X509_NAMES of the certificates found. While the name suggests -the specific usage as support function for -L<SSL_CTX_set_client_CA_list(3)>, -it is not limited to CA certificates. - -=head1 EXAMPLES - -Load names of CAs from file and use it as a client CA list: - - SSL_CTX *ctx; - STACK_OF(X509_NAME) *cert_names; - - ... - cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem"); - if (cert_names != NULL) - SSL_CTX_set_client_CA_list(ctx, cert_names); - else - error_handling(); - ... - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -The operation failed, check out the error stack for the reason. - -=item Pointer to STACK_OF(X509_NAME) - -Pointer to the subject names of the successfully read certificates. - -=back - -=head1 SEE ALSO - -L<ssl(3)>, -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 diff --git a/doc/ssl/SSL_new.pod b/doc/ssl/SSL_new.pod deleted file mode 100644 index a5a3ff98f7..0000000000 --- a/doc/ssl/SSL_new.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -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, -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 - -The following return values can occur: - -=over 4 - -=item NULL - -The creation of a new SSL structure failed. Check the error stack to -find out the reason. - -=item Pointer to an SSL structure - -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)>, 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 diff --git a/doc/ssl/SSL_pending.pod b/doc/ssl/SSL_pending.pod deleted file mode 100644 index f6ed5652a1..0000000000 --- a/doc/ssl/SSL_pending.pod +++ /dev/null @@ -1,68 +0,0 @@ -=pod - -=head1 NAME - -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 - -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)>. - -SSL_pending() returns the number of bytes which have been processed, buffered -and are available inside B<ssl> for immediate read. - -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 - -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)>, 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 diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod deleted file mode 100644 index 8dff2448d0..0000000000 --- a/doc/ssl/SSL_read.pod +++ /dev/null @@ -1,128 +0,0 @@ -=pod - -=head1 NAME - -SSL_read - read bytes from a TLS/SSL connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_read(SSL *ssl, void *buf, int num); - -=head1 DESCRIPTION - -SSL_read() tries to read B<num> bytes from the specified B<ssl> into the -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)> 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. - -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)> 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 -records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a -record has been completely received, it can be processed (decryption and -check of integrity). Therefore data that was not retrieved at the last -call of SSL_read() can still be buffered inside the SSL layer and will be -retrieved on the next call to SSL_read(). If B<num> is higher than the -number of bytes buffered, SSL_read() will return with the bytes buffered. -If no more bytes are in the buffer, SSL_read() will trigger the processing -of the next record. Only when the record has been received and processed -completely, SSL_read() will return reporting success. At most the contents -of the record will be returned. As the size of an SSL/TLS record may exceed -the maximum packet size of the underlying transport (e.g. TCP), it may -be necessary to read several packets from the transport layer before the -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. -This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the -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)> 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 -then must repeat the call after taking appropriate action to satisfy the -needs of SSL_read(). The action depends on the underlying BIO. When using a -non-blocking socket, nothing is to be done, but select() can be used to check -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)> 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. - -=head1 WARNING - -When an SSL_read() operation has to be repeated because of -B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated -with the same arguments. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item E<gt>0 - -The read operation was successful; the return value is the number of -bytes actually read from the TLS/SSL connection. - -=item Z<>0 - -The read operation was not successful. The reason may either be a clean -shutdown due to a "close notify" alert sent by the peer (in which case -the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set -(see L<SSL_shutdown(3)>, -L<SSL_set_shutdown(3)>). It is also possible, that -the peer simply shut down the underlying transport and the shutdown is -incomplete. Call SSL_get_error() with the return value B<ret> to find out, -whether an error occurred or the connection was shut down cleanly -(SSL_ERROR_ZERO_RETURN). - -=item E<lt>0 - -The read operation was not successful, because either an error occurred -or action must be taken by the calling process. Call SSL_get_error() with the -return value B<ret> to find out the reason. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_rstate_string.pod b/doc/ssl/SSL_rstate_string.pod deleted file mode 100644 index 7775913beb..0000000000 --- a/doc/ssl/SSL_rstate_string.pod +++ /dev/null @@ -1,68 +0,0 @@ -=pod - -=head1 NAME - -SSL_rstate_string, SSL_rstate_string_long - get textual description of state of an SSL object during read operation - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const char *SSL_rstate_string(SSL *ssl); - const char *SSL_rstate_string_long(SSL *ssl); - -=head1 DESCRIPTION - -SSL_rstate_string() returns a 2 letter string indicating the current read state -of the SSL object B<ssl>. - -SSL_rstate_string_long() returns a string indicating the current read state of -the SSL object B<ssl>. - -=head1 NOTES - -When performing a read operation, the SSL/TLS engine must parse the record, -consisting of header and body. When working in a blocking environment, -SSL_rstate_string[_long]() should always return "RD"/"read done". - -This function should only seldom be needed in applications. - -=head1 RETURN VALUES - -SSL_rstate_string() and SSL_rstate_string_long() can return the following -values: - -=over 4 - -=item "RH"/"read header" - -The header of the record is being evaluated. - -=item "RB"/"read body" - -The body of the record is being evaluated. - -=item "RD"/"read done" - -The record has been completely processed. - -=item "unknown"/"unknown" - -The read state is unknown. This should never happen. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_session_reused.pod b/doc/ssl/SSL_session_reused.pod deleted file mode 100644 index eda66b2bc8..0000000000 --- a/doc/ssl/SSL_session_reused.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -SSL_session_reused - query whether a reused session was negotiated during handshake - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_session_reused(SSL *ssl); - -=head1 DESCRIPTION - -Query, whether a reused session was negotiated during the handshake. - -=head1 NOTES - -During the negotiation, a client can propose to reuse a session. The server -then looks up the session in its cache. If both client and server agree -on the session, it will be reused and a flag is being set that can be -queried by the application. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item Z<>0 - -A new session was negotiated. - -=item Z<>1 - -A session was reused. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_set1_host.pod b/doc/ssl/SSL_set1_host.pod deleted file mode 100644 index 3339a0e803..0000000000 --- a/doc/ssl/SSL_set1_host.pod +++ /dev/null @@ -1,121 +0,0 @@ -=pod - -=head1 NAME - -SSL_set1_host, SSL_add1_host, SSL_set_hostflags, SSL_get0_peername - -SSL server verification parameters - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_set1_host(SSL *s, const char *hostname); - int SSL_add1_host(SSL *s, const char *hostname); - void SSL_set_hostflags(SSL *s, unsigned int flags); - const char *SSL_get0_peername(SSL *s); - -=head1 DESCRIPTION - -These functions configure server hostname checks in the SSL client. - -SSL_set1_host() sets the expected DNS hostname to B<name> clearing -any previously specified host name or names. If B<name> is NULL, -or the empty string the list of hostnames is cleared, and name -checks are not performed on the peer certificate. When a non-empty -B<name> is specified, certificate verification automatically checks -the peer hostname via L<X509_check_host(3)> with B<flags> as specified -via SSL_set_hostflags(). Clients that enable DANE TLSA authentication -via L<SSL_dane_enable(3)> should leave it to that function to set -the primary reference identifier of the peer, and should not call -SSL_set1_host(). - -SSL_add1_host() adds B<name> as an additional reference identifier -that can match the peer's certificate. Any previous names set via -SSL_set1_host() or SSL_add1_host() are retained, no change is made -if B<name> is NULL or empty. When multiple names are configured, -the peer is considered verified when any name matches. This function -is required for DANE TLSA in the presence of service name indirection -via CNAME, MX or SRV records as specified in RFC7671, RFC7672 or -RFC7673. - -SSL_set_hostflags() sets the B<flags> that will be passed to -L<X509_check_host(3)> when name checks are applicable, by default -the B<flags> value is 0. See L<X509_check_host(3)> for the list -of available flags and their meaning. - -SSL_get0_peername() returns the DNS hostname or subject CommonName -from the peer certificate that matched one of the reference -identifiers. When wildcard matching is not disabled, the name -matched in the peer certificate may be a wildcard name. When one -of the reference identifiers configured via SSL_set1_host() or -SSL_add1_host() starts with ".", which indicates a parent domain prefix -rather than a fixed name, the matched peer name may be a sub-domain -of the reference identifier. The returned string is allocated by -the library and is no longer valid once the associated B<ssl> handle -is cleared or freed, or a renegotiation takes place. Applications -must not free the return value. - -SSL clients are advised to use these functions in preference to -explicitly calling L<X509_check_host(3)>. Hostname checks are out -of scope with the RFC7671 DANE-EE(3) certificate usage, and the -internal check will be suppressed as appropriate when DANE is -enabled. - -=head1 RETURN VALUES - -SSL_set1_host() and SSL_add1_host() return 1 for success and 0 for -failure. - -SSL_get0_peername() returns NULL if peername verification is not -applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was -matched. Otherwise, it returns the matched peername. To determine -whether verification succeeded call L<SSL_get_verify_result(3)>. - -=head1 EXAMPLE - -Suppose "smtp.example.com" is the MX host of the domain "example.com". -The calls below will arrange to match either the MX hostname or the -destination domain name in the SMTP server certificate. Wildcards -are supported, but must match the entire label. The actual name -matched in the certificate (which might be a wildcard) is retrieved, -and must be copied by the application if it is to be retained beyond -the lifetime of the SSL connection. - - SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); - if (!SSL_set1_host(ssl, "smtp.example.com")) { - /* handle error */ - } - if (!SSL_add1_host(ssl, "example.com")) { - /* handle error */ - } - - /* XXX: Perform SSL_connect() handshake and handle errors here */ - - if (SSL_get_verify_result(ssl) == X509_V_OK) { - const char *peername = SSL_get0_peername(ssl); - - if (peername != NULL) { - /* Name checks were in scope and matched the peername */ - } - } - -=head1 SEE ALSO - -L<X509_check_host(3)>, -L<SSL_get_verify_result(3)>. -L<SSL_dane_enable(3)>. - -=head1 HISTORY - -These functions were first added to OpenSSL 1.1.0. - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut diff --git a/doc/ssl/SSL_set_bio.pod b/doc/ssl/SSL_set_bio.pod deleted file mode 100644 index e8e55f4648..0000000000 --- a/doc/ssl/SSL_set_bio.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=head1 NAME - -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_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). - -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. - -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(), SSL_set_rbio() and SSL_set_wbio() cannot fail. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_set_connect_state.pod b/doc/ssl/SSL_set_connect_state.pod deleted file mode 100644 index 60c18a4510..0000000000 --- a/doc/ssl/SSL_set_connect_state.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_connect_state, SSL_set_accept_state - prepare SSL object to work in client or server mode - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_set_connect_state(SSL *ssl); - - void SSL_set_accept_state(SSL *ssl); - -=head1 DESCRIPTION - -SSL_set_connect_state() sets B<ssl> to work in client mode. - -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)>, -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)> 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)> or -L<SSL_accept(3)> routines, the correct handshake -routines are automatically set. When performing a transparent negotiation -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(). - -=head1 RETURN VALUES - -SSL_set_connect_state() and SSL_set_accept_state() do not return diagnostic -information. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_set_fd.pod b/doc/ssl/SSL_set_fd.pod deleted file mode 100644 index e1f9988db5..0000000000 --- a/doc/ssl/SSL_set_fd.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_fd, SSL_set_rfd, SSL_set_wfd - connect the SSL object with a file descriptor - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_set_fd(SSL *ssl, int fd); - int SSL_set_rfd(SSL *ssl, int fd); - int SSL_set_wfd(SSL *ssl, int fd); - -=head1 DESCRIPTION - -SSL_set_fd() sets the file descriptor B<fd> as the input/output facility -for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the -socket file descriptor of a network connection. - -When performing the operation, a B<socket BIO> is automatically created to -interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine -inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will -also have non-blocking behaviour. - -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_rfd() and SSL_set_wfd() perform the respective action, but only -for the read channel or the write channel, which can be set independently. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item Z<>0 - -The operation failed. Check the error stack to find out why. - -=item Z<>1 - -The operation succeeded. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_set_session.pod b/doc/ssl/SSL_set_session.pod deleted file mode 100644 index 1de533f4c5..0000000000 --- a/doc/ssl/SSL_set_session.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_set_session(SSL *ssl, SSL_SESSION *session); - -=head1 DESCRIPTION - -SSL_set_session() sets B<session> to be used when the TLS/SSL connection -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)> 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. 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 - -SSL_SESSION objects keep internal link information about the session cache -list, when being inserted into one SSL_CTX object's session cache. -One SSL_SESSION object, regardless of its reference count, must therefore -only be used with one SSL_CTX object (and the SSL objects created -from this SSL_CTX object). - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item Z<>0 - -The operation failed; check the error stack to find out the reason. - -=item Z<>1 - -The operation succeeded. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_set_shutdown.pod b/doc/ssl/SSL_set_shutdown.pod deleted file mode 100644 index ecdf60cff3..0000000000 --- a/doc/ssl/SSL_set_shutdown.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_set_shutdown(SSL *ssl, int mode); - - int SSL_get_shutdown(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_set_shutdown() sets the shutdown state of B<ssl> to B<mode>. - -SSL_get_shutdown() returns the shutdown mode of B<ssl>. - -=head1 NOTES - -The shutdown state of an ssl connection is a bitmask of: - -=over 4 - -=item Z<>0 - -No shutdown setting, yet. - -=item SSL_SENT_SHUTDOWN - -A "close notify" shutdown alert was sent to the peer, the connection is being -considered closed and the session is closed and correct. - -=item SSL_RECEIVED_SHUTDOWN - -A shutdown alert was received form the peer, either a normal "close notify" -or a fatal error. - -=back - -SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time. - -The shutdown state of the connection is used to determine the state of -the ssl session. If the session is still open, when -L<SSL_clear(3)> 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)>). - -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)> or SSL_set_shutdown() itself. - -=head1 RETURN VALUES - -SSL_set_shutdown() does not return diagnostic information. - -SSL_get_shutdown() returns the current setting. - -=head1 SEE ALSO - -L<ssl(3)>, 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 diff --git a/doc/ssl/SSL_set_verify_result.pod b/doc/ssl/SSL_set_verify_result.pod deleted file mode 100644 index 8738d7828c..0000000000 --- a/doc/ssl/SSL_set_verify_result.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_verify_result - override result of peer certificate verification - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_set_verify_result(SSL *ssl, long verify_result); - -=head1 DESCRIPTION - -SSL_set_verify_result() sets B<verify_result> of the object B<ssl> to be the -result of the verification of the X509 certificate presented by the peer, -if any. - -=head1 NOTES - -SSL_set_verify_result() overrides the verification result. It only changes -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)>. - -=head1 RETURN VALUES - -SSL_set_verify_result() does not provide a return value. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_shutdown.pod b/doc/ssl/SSL_shutdown.pod deleted file mode 100644 index e8ec4546a3..0000000000 --- a/doc/ssl/SSL_shutdown.pod +++ /dev/null @@ -1,132 +0,0 @@ -=pod - -=head1 NAME - -SSL_shutdown - shut down a TLS/SSL connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_shutdown(SSL *ssl); - -=head1 DESCRIPTION - -SSL_shutdown() shuts down an active TLS/SSL connection. It sends the -"close notify" shutdown alert to the peer. - -=head1 NOTES - -SSL_shutdown() tries to send the "close notify" shutdown alert to the peer. -Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and -a currently open session is considered closed and good and will be kept in the -session cache for further reuse. - -The shutdown procedure consists of 2 steps: the sending of the "close notify" -shutdown alert and the reception of the peer's "close notify" shutdown -alert. According to the TLS standard, it is acceptable for an application -to only send its shutdown alert and then close the underlying connection -without waiting for the peer's response (this way resources can be saved, -as the process can already terminate or serve another connection). -When the underlying connection shall be used for more communications, the -complete shutdown procedure (bidirectional "close notify" alerts) must be -performed, so that the peers stay synchronized. - -SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step -behaviour. - -=over 4 - -=item When the application is the first party to send the "close notify" -alert, SSL_shutdown() will only send the alert and then set the -SSL_SENT_SHUTDOWN flag (so that the session is considered good and will -be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional -shutdown is enough (the underlying connection shall be closed anyway), this -first call to SSL_shutdown() is sufficient. In order to complete the -bidirectional shutdown handshake, SSL_shutdown() must be called again. -The second call will make SSL_shutdown() wait for the peer's "close notify" -shutdown alert. On success, the second call to SSL_shutdown() will return -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)>), 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)> 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). - -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. - -If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return -when the underlying BIO could not satisfy the needs of SSL_shutdown() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or -B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_shutdown(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check 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. - -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)>. -When "quiet shutdown" is enabled, SSL_shutdown() will always succeed -and return 1. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item Z<>0 - -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)> may be misleading, as an -erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. - -=item Z<>1 - -The shutdown was successfully completed. The "close notify" alert was sent -and the peer's "close notify" alert was received. - -=item E<lt>0 - -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)> with the return value B<ret> -to find out the reason. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_state_string.pod b/doc/ssl/SSL_state_string.pod deleted file mode 100644 index a2f59e84e8..0000000000 --- a/doc/ssl/SSL_state_string.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -SSL_state_string, SSL_state_string_long - get textual description of state of an SSL object - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const char *SSL_state_string(const SSL *ssl); - const char *SSL_state_string_long(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_state_string() returns a 6 letter string indicating the current state -of the SSL object B<ssl>. - -SSL_state_string_long() returns a string indicating the current state of -the SSL object B<ssl>. - -=head1 NOTES - -During its use, an SSL objects passes several states. The state is internally -maintained. Querying the state information is not very informative before -or when a connection has been established. It however can be of significant -interest during the handshake. - -When using non-blocking sockets, the function call performing the handshake -may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition, -so that SSL_state_string[_long]() may be called. - -For both blocking or non-blocking sockets, the details state information -can be used within the info_callback function set with the -SSL_set_info_callback() call. - -=head1 RETURN VALUES - -Detailed description of possible states to be included later. - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/SSL_want.pod b/doc/ssl/SSL_want.pod deleted file mode 100644 index e179d6befa..0000000000 --- a/doc/ssl/SSL_want.pod +++ /dev/null @@ -1,103 +0,0 @@ -=pod - -=head1 NAME - -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 - - #include <openssl/ssl.h> - - int SSL_want(const SSL *ssl); - int SSL_want_nothing(const SSL *ssl); - 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 - -SSL_want() returns state information for the SSL object B<ssl>. - -The other SSL_want_*() calls are shortcuts for the possible states returned -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)>. -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)>. - -The result returned by SSL_want() should always be consistent with -the result of L<SSL_get_error(3)>. - -=head1 RETURN VALUES - -The following return values can currently occur for SSL_want(): - -=over 4 - -=item SSL_NOTHING - -There is no data to be written or to be read. - -=item SSL_WRITING - -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)> 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)> 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)> 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(), -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)>, 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 diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod deleted file mode 100644 index 5ab079042e..0000000000 --- a/doc/ssl/SSL_write.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -SSL_write - write bytes to a TLS/SSL connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_write(SSL *ssl, const void *buf, int num); - -=head1 DESCRIPTION - -SSL_write() writes B<num> bytes from the buffer B<buf> into the specified -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)> 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. - -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)> 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. -This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the -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)> 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 -then must repeat the call after taking appropriate action to satisfy the -needs of SSL_write(). The action depends on the underlying BIO. When using a -non-blocking socket, nothing is to be done, but select() can be used to check -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. - -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)>. 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 -buffer (with the already sent bytes removed) must be started. -A partial write is performed with the size of a message block, which is -16kB for SSLv3/TLSv1. - -=head1 WARNING - -When an SSL_write() operation has to be repeated because of -B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated -with the same arguments. - -When calling SSL_write() with num=0 bytes to be sent the behaviour is -undefined. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item E<gt>0 - -The write operation was successful, the return value is the number of -bytes actually written to the TLS/SSL connection. - -=item Z<>0 - -The write operation was not successful. Probably the underlying connection -was closed. Call SSL_get_error() with the return value B<ret> to find out, -whether an error occurred or the connection was shut down cleanly -(SSL_ERROR_ZERO_RETURN). - -=item E<lt>0 - -The write operation was not successful, because either an error occurred -or action must be taken by the calling process. Call SSL_get_error() with the -return value B<ret> to find out the reason. - -=back - -=head1 SEE ALSO - -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 diff --git a/doc/ssl/d2i_SSL_SESSION.pod b/doc/ssl/d2i_SSL_SESSION.pod deleted file mode 100644 index d6b17071f6..0000000000 --- a/doc/ssl/d2i_SSL_SESSION.pod +++ /dev/null @@ -1,49 +0,0 @@ -=pod - -=head1 NAME - -d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length); - int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an SSL_SESSION object. -For encoding details see L<d2i_X509(3)>. - -SSL_SESSION objects keep internal link information about the session cache -list, when being inserted into one SSL_CTX object's session cache. -One SSL_SESSION object, regardless of its reference count, must therefore -only be used with one SSL_CTX object (and the SSL objects created -from this SSL_CTX object). - -=head1 RETURN VALUES - -d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION -object. In case of failure the NULL-pointer is returned and the error message -can be retrieved from the error stack. - -i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes. -When the session is not valid, B<0> is returned and no operation is performed. - -=head1 SEE ALSO - -L<ssl(3)>, L<SSL_SESSION_free(3)>, -L<SSL_CTX_sess_set_get_cb(3)>, -L<d2i_X509(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 diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod deleted file mode 100644 index 582a276a8f..0000000000 --- a/doc/ssl/ssl.pod +++ /dev/null @@ -1,832 +0,0 @@ -=pod - -=for comment openssl_manual_section:7 - -=head1 NAME - -SSL - OpenSSL SSL/TLS library - -=head1 SYNOPSIS - -See the individual manual pages for details. - -=head1 DESCRIPTION - -The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and -Transport Layer Security (TLS v1) protocols. It provides a rich API which is -documented here. - -Then an B<SSL_CTX> object is created as a framework to establish -TLS/SSL enabled connections (see L<SSL_CTX_new(3)>). -Various options regarding certificates, algorithms etc. can be set -in this object. - -When a network connection has been created, it can be assigned to an -B<SSL> object. After the B<SSL> object has been created using -L<SSL_new(3)>, L<SSL_set_fd(3)> or -L<SSL_set_bio(3)> can be used to associate the network -connection with the object. - -Then the TLS/SSL handshake is performed using -L<SSL_accept(3)> or L<SSL_connect(3)> -respectively. -L<SSL_read(3)> and L<SSL_write(3)> are used -to read and write data on the TLS/SSL connection. -L<SSL_shutdown(3)> can be used to shut down the -TLS/SSL connection. - -=head1 DATA STRUCTURES - -Currently the OpenSSL B<ssl> library functions deals with the following data -structures: - -=over 4 - -=item B<SSL_METHOD> (SSL Method) - -That's a dispatch structure describing the internal B<ssl> library -methods/functions which implement the various protocol versions (SSLv3 -TLSv1, ...). It's needed to create an B<SSL_CTX>. - -=item B<SSL_CIPHER> (SSL Cipher) - -This structure holds the algorithm information for a particular cipher which -are a core part of the SSL/TLS protocol. The available ciphers are configured -on a B<SSL_CTX> basis and the actually used ones are then part of the -B<SSL_SESSION>. - -=item B<SSL_CTX> (SSL Context) - -That's the global context structure which is created by a server or client -once per program life-time and which holds mainly default values for the -B<SSL> structures which are later created for the connections. - -=item B<SSL_SESSION> (SSL Session) - -This is a structure containing the current TLS/SSL session details for a -connection: B<SSL_CIPHER>s, client and server certificates, keys, etc. - -=item B<SSL> (SSL Connection) - -That's the main SSL/TLS structure which is created by a server or client per -established connection. This actually is the core structure in the SSL API. -Under run-time the application usually deals with this structure which has -links to mostly all other structures. - -=back - - -=head1 HEADER FILES - -Currently the OpenSSL B<ssl> library provides the following C header files -containing the prototypes for the data structures and functions: - -=over 4 - -=item B<ssl.h> - -That's the common header file for the SSL/TLS API. Include it into your -program to make the API of the B<ssl> library available. It internally -includes both more private SSL headers and headers from the B<crypto> library. -Whenever you need hard-core details on the internals of the SSL API, look -inside this header file. - -=item B<ssl2.h> - -Unused. Present for backwards compatibility only. - -=item B<ssl3.h> - -That's the sub header file dealing with the SSLv3 protocol only. -I<Usually you don't have to include it explicitly because -it's already included by ssl.h>. - -=item B<tls1.h> - -That's the sub header file dealing with the TLSv1 protocol only. -I<Usually you don't have to include it explicitly because -it's already included by ssl.h>. - -=back - -=head1 API FUNCTIONS - -Currently the OpenSSL B<ssl> library exports 214 API functions. -They are documented in the following: - -=head2 Dealing with Protocol Methods - -Here we document the various API functions which deal with the SSL/TLS -protocol methods defined in B<SSL_METHOD> structures. - -=over 4 - -=item const SSL_METHOD *B<TLS_method>(void); - -Constructor for the I<version-flexible> SSL_METHOD structure for clients, -servers or both. -See L<SSL_CTX_new(3)> for details. - -=item const SSL_METHOD *B<TLS_client_method>(void); - -Constructor for the I<version-flexible> SSL_METHOD structure for clients. - -=item const SSL_METHOD *B<TLS_server_method>(void); - -Constructor for the I<version-flexible> SSL_METHOD structure for servers. - -=item const SSL_METHOD *B<TLSv1_2_method>(void); - -Constructor for the TLSv1.2 SSL_METHOD structure for clients, servers or both. - -=item const SSL_METHOD *B<TLSv1_2_client_method>(void); - -Constructor for the TLSv1.2 SSL_METHOD structure for clients. - -=item const SSL_METHOD *B<TLSv1_2_server_method>(void); - -Constructor for the TLSv1.2 SSL_METHOD structure for servers. - -=item const SSL_METHOD *B<TLSv1_1_method>(void); - -Constructor for the TLSv1.1 SSL_METHOD structure for clients, servers or both. - -=item const SSL_METHOD *B<TLSv1_1_client_method>(void); - -Constructor for the TLSv1.1 SSL_METHOD structure for clients. - -=item const SSL_METHOD *B<TLSv1_1_server_method>(void); - -Constructor for the TLSv1.1 SSL_METHOD structure for servers. - -=item const SSL_METHOD *B<TLSv1_method>(void); - -Constructor for the TLSv1 SSL_METHOD structure for clients, servers or both. - -=item const SSL_METHOD *B<TLSv1_client_method>(void); - -Constructor for the TLSv1 SSL_METHOD structure for clients. - -=item const SSL_METHOD *B<TLSv1_server_method>(void); - -Constructor for the TLSv1 SSL_METHOD structure for servers. - -=item const SSL_METHOD *B<SSLv3_method>(void); - -Constructor for the SSLv3 SSL_METHOD structure for clients, servers or both. - -=item const SSL_METHOD *B<SSLv3_client_method>(void); - -Constructor for the SSLv3 SSL_METHOD structure for clients. - -=item const SSL_METHOD *B<SSLv3_server_method>(void); - -Constructor for the SSLv3 SSL_METHOD structure for servers. - -=back - -=head2 Dealing with Ciphers - -Here we document the various API functions which deal with the SSL/TLS -ciphers defined in B<SSL_CIPHER> structures. - -=over 4 - -=item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len); - -Write a string to I<buf> (with a maximum size of I<len>) containing a human -readable description of I<cipher>. Returns I<buf>. - -=item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits); - -Determine the number of bits in I<cipher>. Because of export crippled ciphers -there are two bits: The bits the algorithm supports in general (stored to -I<alg_bits>) and the bits which are actually used (the return value). - -=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher); - -Return the internal name of I<cipher> as a string. These are the various -strings defined by the I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx> -definitions in the header files. - -=item const char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher); - -Returns a string like "C<SSLv3>" or "C<TLSv1.2>" which indicates the -SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined -in the specification the first time). - -=back - -=head2 Dealing with Protocol Contexts - -Here we document the various API functions which deal with the SSL/TLS -protocol context defined in the B<SSL_CTX> structure. - -=over 4 - -=item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x); - -=item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509); - -=item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c); - -=item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx); - -=item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg); - -=item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t); - -=item void B<SSL_CTX_free>(SSL_CTX *a); - -=item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx); - -=item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx); - -=item STACK *B<SSL_CTX_get_ciphers>(const SSL_CTX *ctx); - -=item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx); - -=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); - -=item void B<SSL_CTX_get_default_read_ahead>(SSL_CTX *ctx); - -=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx); - -=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) - -=item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret); - -=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx); - -=item void B<SSL_CTX_get_read_ahead>(SSL_CTX *ctx); - -=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx); - -=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx); - -=item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx); - -=item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx); - -=item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, const char *CAfile, const char *CApath); - -=item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth); - -=item int SSL_CTX_up_ref(SSL_CTX *ctx); - -=item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c); - -=item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx); - -=item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy); - -=item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess); - -=item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess); - -=item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx); - -=item int B<SSL_CTX_sess_number>(SSL_CTX *ctx); - -=item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx, t); - -=item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)); - -=item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess)); - -=item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)); - -=item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx); - -=item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx); - -=item int B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg); - -=item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs); - -=item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg) - -=item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str); - -=item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list); - -=item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); - -=item int B<SSL_CTX_set_ct_validation_callback>(SSL_CTX *ctx, ssl_ct_validation_cb callback, void *arg); - -=item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void)) - -=item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m); - -=item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx); - -Use the default paths to locate trusted CA certificates. There is one default -directory path and one default file path. Both are set via this call. - -=item int B<SSL_CTX_set_default_verify_dir>(SSL_CTX *ctx) - -Use the default directory path to locate trusted CA certificates. - -=item int B<SSL_CTX_set_default_verify_file>(SSL_CTX *ctx) - -Use the file path to locate trusted CA certificates. - -=item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg); - -=item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret)); - -=item void B<SSL_CTX_set_msg_callback>(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); - -=item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg); - -=item unsigned long B<SSL_CTX_clear_options>(SSL_CTX *ctx, unsigned long op); - -=item unsigned long B<SSL_CTX_get_options>(SSL_CTX *ctx); - -=item unsigned long B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op); - -=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode); - -=item void B<SSL_CTX_set_read_ahead>(SSL_CTX *ctx, int m); - -=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode); - -=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth); - -=item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t); - -=item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh); - -=item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void)); - -=item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void)) - -=item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey); - -=item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len); - -=item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, const char *file, int type); - -=item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa); - -=item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len); - -=item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, const char *file, int type); - -=item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x); - -=item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d); - -=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, const char *file, int type); - -=item X509 *B<SSL_CTX_get0_certificate>(const SSL_CTX *ctx); - -=item EVP_PKEY *B<SSL_CTX_get0_privatekey>(const SSL_CTX *ctx); - -=item void B<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)); - -=item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint); - -=item void B<SSL_CTX_set_psk_server_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); - - -=back - -=head2 Dealing with Sessions - -Here we document the various API functions which deal with the SSL/TLS -sessions defined in the B<SSL_SESSION> structures. - -=over 4 - -=item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b); - -=item void B<SSL_SESSION_free>(SSL_SESSION *ss); - -=item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s); - -=item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx); - -=item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) - -=item long B<SSL_SESSION_get_time>(const SSL_SESSION *s); - -=item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s); - -=item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a); - -=item SSL_SESSION *B<SSL_SESSION_new>(void); - -=item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x); - -=item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x); - -=item int B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a); - -=item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg); - -=item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t); - -=item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t); - -=back - -=head2 Dealing with Connections - -Here we document the various API functions which deal with the SSL/TLS -connection defined in the B<SSL> structure. - -=over 4 - -=item int B<SSL_accept>(SSL *ssl); - -=item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir); - -=item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file); - -=item int B<SSL_add_client_CA>(SSL *ssl, X509 *x); - -=item char *B<SSL_alert_desc_string>(int value); - -=item char *B<SSL_alert_desc_string_long>(int value); - -=item char *B<SSL_alert_type_string>(int value); - -=item char *B<SSL_alert_type_string_long>(int value); - -=item int B<SSL_check_private_key>(const SSL *ssl); - -=item void B<SSL_clear>(SSL *ssl); - -=item long B<SSL_clear_num_renegotiations>(SSL *ssl); - -=item int B<SSL_connect>(SSL *ssl); - -=item int B<SSL_copy_session_id>(SSL *t, const SSL *f); - -Sets the session details for B<t> to be the same as in B<f>. Returns 1 on -success or 0 on failure. - -=item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg); - -=item int B<SSL_do_handshake>(SSL *ssl); - -=item SSL *B<SSL_dup>(SSL *ssl); - -SSL_dup() allows applications to configure an SSL handle for use -in multiple SSL connections, and then duplicate it prior to initiating -each connection with the duplicated handle. -Use of SSL_dup() avoids the need to repeat the configuration of the -handles for each connection. -This is used internally by L<BIO_s_accept(3)> to construct -per-connection SSL handles after L<accept(2)>. - -For SSL_dup() to work, the connection MUST be in its initial state -and MUST NOT have not yet have started the SSL handshake. -For connections that are not in their initial state SSL_dup() just -increments an internal reference count and returns the I<same> -handle. -It may be possible to use L<SSL_clear(3)> to recycle an SSL handle -that is not in its initial state for re-use, but this is best -avoided. -Instead, save and restore the session, if desired, and construct a -fresh handle for each connection. - -=item STACK *B<SSL_dup_CA_list>(STACK *sk); - -=item void B<SSL_free>(SSL *ssl); - -=item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl); - -=item char *B<SSL_get_app_data>(SSL *ssl); - -=item X509 *B<SSL_get_certificate>(const SSL *ssl); - -=item const char *B<SSL_get_cipher>(const SSL *ssl); - -=item int B<SSL_is_dtls>(const SSL *ssl); - -=item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits); - -=item char *B<SSL_get_cipher_list>(const SSL *ssl, int n); - -=item char *B<SSL_get_cipher_name>(const SSL *ssl); - -=item char *B<SSL_get_cipher_version>(const SSL *ssl); - -=item STACK *B<SSL_get_ciphers>(const SSL *ssl); - -=item STACK *B<SSL_get_client_CA_list>(const SSL *ssl); - -=item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl); - -=item long B<SSL_get_default_timeout>(const SSL *ssl); - -=item int B<SSL_get_error>(const SSL *ssl, int i); - -=item char *B<SSL_get_ex_data>(const SSL *ssl, int idx); - -=item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void); - -=item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) - -=item int B<SSL_get_fd>(const SSL *ssl); - -=item void (*B<SSL_get_info_callback>(const SSL *ssl);)() - -=item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl); - -=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl); - -=item const STACK_OF(SCT) *B<SSL_get0_peer_scts>(SSL *s); - -=item EVP_PKEY *B<SSL_get_privatekey>(const SSL *ssl); - -=item int B<SSL_get_quiet_shutdown>(const SSL *ssl); - -=item BIO *B<SSL_get_rbio>(const SSL *ssl); - -=item int B<SSL_get_read_ahead>(const SSL *ssl); - -=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl); - -=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len); - -=item int B<SSL_get_shutdown>(const SSL *ssl); - -=item const SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl); - -=item int B<SSL_get_state>(const SSL *ssl); - -=item long B<SSL_get_time>(const SSL *ssl); - -=item long B<SSL_get_timeout>(const SSL *ssl); - -=item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int, X509_STORE_CTX *) - -=item int B<SSL_get_verify_mode>(const SSL *ssl); - -=item long B<SSL_get_verify_result>(const SSL *ssl); - -=item char *B<SSL_get_version>(const SSL *ssl); - -=item BIO *B<SSL_get_wbio>(const SSL *ssl); - -=item int B<SSL_in_accept_init>(SSL *ssl); - -=item int B<SSL_in_before>(SSL *ssl); - -=item int B<SSL_in_connect_init>(SSL *ssl); - -=item int B<SSL_in_init>(SSL *ssl); - -=item int B<SSL_is_init_finished>(SSL *ssl); - -=item STACK *B<SSL_load_client_CA_file>(const char *file); - -=item SSL *B<SSL_new>(SSL_CTX *ctx); - -=item int SSL_up_ref(SSL *s); - -=item long B<SSL_num_renegotiations>(SSL *ssl); - -=item int B<SSL_peek>(SSL *ssl, void *buf, int num); - -=item int B<SSL_pending>(const SSL *ssl); - -=item int B<SSL_read>(SSL *ssl, void *buf, int num); - -=item int B<SSL_renegotiate>(SSL *ssl); - -=item char *B<SSL_rstate_string>(SSL *ssl); - -=item char *B<SSL_rstate_string_long>(SSL *ssl); - -=item long B<SSL_session_reused>(SSL *ssl); - -=item void B<SSL_set_accept_state>(SSL *ssl); - -=item void B<SSL_set_app_data>(SSL *ssl, char *arg); - -=item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio); - -=item int B<SSL_set_cipher_list>(SSL *ssl, char *str); - -=item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list); - -=item void B<SSL_set_connect_state>(SSL *ssl); - -=item int B<SSL_set_ct_validation_callback>(SSL *ssl, ssl_ct_validation_cb callback, void *arg); - -=item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg); - -=item int B<SSL_set_fd>(SSL *ssl, int fd); - -=item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void)) - -=item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); - -=item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg); - -=item unsigned long B<SSL_clear_options>(SSL *ssl, unsigned long op); - -=item unsigned long B<SSL_get_options>(SSL *ssl); - -=item unsigned long B<SSL_set_options>(SSL *ssl, unsigned long op); - -=item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode); - -=item void B<SSL_set_read_ahead>(SSL *ssl, int yes); - -=item int B<SSL_set_rfd>(SSL *ssl, int fd); - -=item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session); - -=item void B<SSL_set_shutdown>(SSL *ssl, int mode); - -=item int B<SSL_set_ssl_method>(SSL *ssl, const SSL_METHOD *meth); - -=item void B<SSL_set_time>(SSL *ssl, long t); - -=item void B<SSL_set_timeout>(SSL *ssl, long t); - -=item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void)) - -=item void B<SSL_set_verify_result>(SSL *ssl, long arg); - -=item int B<SSL_set_wfd>(SSL *ssl, int fd); - -=item int B<SSL_shutdown>(SSL *ssl); - -=item OSSL_HANDSHAKE_STATE B<SSL_get_state>(const SSL *ssl); - -Returns the current handshake state. - -=item char *B<SSL_state_string>(const SSL *ssl); - -=item char *B<SSL_state_string_long>(const SSL *ssl); - -=item long B<SSL_total_renegotiations>(SSL *ssl); - -=item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey); - -=item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len); - -=item int B<SSL_use_PrivateKey_file>(SSL *ssl, const char *file, int type); - -=item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa); - -=item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len); - -=item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, const char *file, int type); - -=item int B<SSL_use_certificate>(SSL *ssl, X509 *x); - -=item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d); - -=item int B<SSL_use_certificate_file>(SSL *ssl, const char *file, int type); - -=item int B<SSL_version>(const SSL *ssl); - -=item int B<SSL_want>(const SSL *ssl); - -=item int B<SSL_want_nothing>(const SSL *ssl); - -=item int B<SSL_want_read>(const SSL *ssl); - -=item int B<SSL_want_write>(const SSL *ssl); - -=item int B<SSL_want_x509_lookup>(const SSL *ssl); - -=item int B<SSL_write>(SSL *ssl, const void *buf, int num); - -=item void B<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)); - -=item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint); - -=item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); - -=item const char *B<SSL_get_psk_identity_hint>(SSL *ssl); - -=item const char *B<SSL_get_psk_identity>(SSL *ssl); - -=back - -=head1 RETURN VALUES - -See the individual manual pages for details. - -=head1 SEE ALSO - -L<openssl(1)>, L<crypto(3)>, -L<CRYPTO_get_ex_new_index(3)>, -L<SSL_accept(3)>, L<SSL_clear(3)>, -L<SSL_connect(3)>, -L<SSL_CIPHER_get_name(3)>, -L<SSL_COMP_add_compression_method(3)>, -L<SSL_CTX_add_extra_chain_cert(3)>, -L<SSL_CTX_add_session(3)>, -L<SSL_CTX_ctrl(3)>, -L<SSL_CTX_flush_sessions(3)>, -L<SSL_CTX_get_verify_mode(3)>, -L<SSL_CTX_load_verify_locations(3)> -L<SSL_CTX_new(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_sessions(3)>, -L<SSL_CTX_set_cert_store(3)>, -L<SSL_CTX_set_cert_verify_callback(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_set_default_passwd_cb(3)>, -L<SSL_CTX_set_generate_session_id(3)>, -L<SSL_CTX_set_info_callback(3)>, -L<SSL_CTX_set_max_cert_list(3)>, -L<SSL_CTX_set_mode(3)>, -L<SSL_CTX_set_msg_callback(3)>, -L<SSL_CTX_set_options(3)>, -L<SSL_CTX_set_quiet_shutdown(3)>, -L<SSL_CTX_set_read_ahead(3)>, -L<SSL_CTX_set_session_cache_mode(3)>, -L<SSL_CTX_set_session_id_context(3)>, -L<SSL_CTX_set_ssl_version(3)>, -L<SSL_CTX_set_timeout(3)>, -L<SSL_CTX_set_tmp_dh_callback(3)>, -L<SSL_CTX_set_verify(3)>, -L<SSL_CTX_use_certificate(3)>, -L<SSL_alert_type_string(3)>, -L<SSL_do_handshake(3)>, -L<SSL_enable_ct(3)>, -L<SSL_get_SSL_CTX(3)>, -L<SSL_get_ciphers(3)>, -L<SSL_get_client_CA_list(3)>, -L<SSL_get_default_timeout(3)>, -L<SSL_get_error(3)>, -L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>, -L<SSL_get_fd(3)>, -L<SSL_get_peer_cert_chain(3)>, -L<SSL_get_rbio(3)>, -L<SSL_get_session(3)>, -L<SSL_get_verify_result(3)>, -L<SSL_get_version(3)>, -L<SSL_load_client_CA_file(3)>, -L<SSL_new(3)>, -L<SSL_pending(3)>, -L<SSL_read(3)>, -L<SSL_rstate_string(3)>, -L<SSL_session_reused(3)>, -L<SSL_set_bio(3)>, -L<SSL_set_connect_state(3)>, -L<SSL_set_fd(3)>, -L<SSL_set_session(3)>, -L<SSL_set_shutdown(3)>, -L<SSL_shutdown(3)>, -L<SSL_state_string(3)>, -L<SSL_want(3)>, -L<SSL_write(3)>, -L<SSL_SESSION_free(3)>, -L<SSL_SESSION_get_time(3)>, -L<d2i_SSL_SESSION(3)>, -L<SSL_CTX_set_psk_client_callback(3)>, -L<SSL_CTX_use_psk_identity_hint(3)>, -L<SSL_get_psk_identity(3)>, -L<DTLSv1_listen(3)> - -=head1 HISTORY - -B<SSLv2_client_method>, B<SSLv2_server_method> and B<SSLv2_method> where removed -in OpenSSL 1.1.0. - -The return type of B<SSL_copy_session_id> was changed from void to int 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 |