diff options
Diffstat (limited to 'openssl-1.1.0h/doc/ssl')
124 files changed, 12524 insertions, 0 deletions
diff --git a/openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod b/openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod new file mode 100644 index 0000000..a839d9f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +DTLSv1_listen - listen for incoming DTLS connections + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer); + +=head1 DESCRIPTION + +DTLSv1_listen() listens for new incoming DTLS connections. If a ClientHello is +received that does not contain a cookie, then DTLSv1_listen() responds with a +HelloVerifyRequest. If a ClientHello is received with a cookie that is verified +then control is returned to user code to enable the handshake to be completed +(for example by using SSL_accept()). + +=head1 NOTES + +Datagram based protocols can be susceptible to Denial of Service attacks. A +DTLS attacker could, for example, submit a series of handshake initiation +requests that cause the server to allocate state (and possibly perform +cryptographic operations) thus consuming server resources. The attacker could +also (with UDP) quite simply forge the source IP address in such an attack. + +As a counter measure to that DTLS includes a stateless cookie mechanism. The +idea is that when a client attempts to connect to a server it sends a +ClientHello message. The server responds with a HelloVerifyRequest which +contains a unique cookie. The client then resends the ClientHello, but this time +includes the cookie in the message thus proving that the client is capable of +receiving messages sent to that address. All of this can be done by the server +without allocating any state, and thus without consuming expensive resources. + +OpenSSL implements this capability via the DTLSv1_listen() function. The B<ssl> +parameter should be a newly allocated SSL object with its read and write BIOs +set, in the same way as might be done for a call to SSL_accept(). Typically the +read BIO will be in an "unconnected" state and thus capable of receiving +messages from any peer. + +When a ClientHello is received that contains a cookie that has been verified, +then DTLSv1_listen() will return with the B<ssl> parameter updated into a state +where the handshake can be continued by a call to (for example) SSL_accept(). +Additionally the B<BIO_ADDR> pointed to by B<peer> will be filled in with +details of the peer that sent the ClientHello. If the underlying BIO is unable +to obtain the B<BIO_ADDR> of the peer (for example because the BIO does not +support this), then B<*peer> will be cleared and the family set to AF_UNSPEC. +Typically user code is expected to "connect" the underlying socket to the peer +and continue the handshake in a connected state. + +Prior to calling DTLSv1_listen() user code must ensure that cookie generation +and verification callbacks have been set up using +SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb() +respectively. + +Since DTLSv1_listen() operates entirely statelessly whilst processing incoming +ClientHellos it is unable to process fragmented messages (since this would +require the allocation of state). An implication of this is that DTLSv1_listen() +B<only> supports ClientHellos that fit inside a single datagram. + +=head1 RETURN VALUES + +From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance +the B<peer> value will be filled in and the B<ssl> object set up ready to +continue the handshake. + +A return value of 0 indicates a non-fatal error. This could (for +example) be because of non-blocking IO, or some invalid message having been +received from a peer. Errors may be placed on the OpenSSL error queue with +further information if appropriate. Typically user code is expected to retry the +call to DTLSv1_listen() in the event of a non-fatal error. Any old errors on the +error queue will be cleared in the subsequent call. + +A return value of <0 indicates a fatal error. This could (for example) be +because of a failure to allocate sufficient memory for the operation. + +Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return codes +<= 0 (in typical implementations user code treats all errors as non-fatal), +whilst return codes >0 indicate success. + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_accept(3)>, +L<ssl(3)>, L<bio(3)> + +=head1 HISTORY + +DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of "peer" +also changed in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod b/openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod new file mode 100644 index 0000000..b963e5e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +OPENSSL_init_ssl - OpenSSL (libssl and libcrypto) initialisation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); + +=head1 DESCRIPTION + +During normal operation OpenSSL (libssl and libcrypto) will allocate various +resources at start up that must, subsequently, be freed on close down of the +library. Additionally some resources are allocated on a per thread basis (if the +application is multi-threaded), and these resources must be freed prior to the +thread closing. + +As of version 1.1.0 OpenSSL will automatically allocate all resources that it +needs so no explicit initialisation is required. Similarly it will also +automatically deinitialise as required. + +However, there may be situations when explicit initialisation is desirable or +needed, for example when some non-default initialisation is required. The +function OPENSSL_init_ssl() can be used for this purpose. Calling +this function will explicitly initialise BOTH libcrypto and libssl. To +explicitly initialise ONLY libcrypto see the +L<OPENSSL_init_crypto(3)> function. + +Numerous internal OpenSSL functions call OPENSSL_init_ssl(). +Therefore, in order to perform non-default initialisation, +OPENSSL_init_ssl() MUST be called by application code prior to +any other OpenSSL function calls. + +The B<opts> parameter specifies which aspects of libssl and libcrypto should be +initialised. Valid options for libcrypto are described on the +L<OPENSSL_init_crypto(3)> page. In addition to any libcrypto +specific option the following libssl options can also be used: + +=over 4 + +=item OPENSSL_INIT_NO_LOAD_SSL_STRINGS + +Suppress automatic loading of the libssl error strings. This option is +not a default option. Once selected subsequent calls to +OPENSSL_init_ssl() with the option +B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored. + +=item OPENSSL_INIT_LOAD_SSL_STRINGS + +Automatic loading of the libssl error strings. This option is a +default option. Once selected subsequent calls to +OPENSSL_init_ssl() with the option +B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored. + +=back + +OPENSSL_init_ssl() takes a B<settings> parameter which can be used to +set parameter values. See L<OPENSSL_init_crypto(3)> for details. + +=head1 RETURN VALUES + +The function OPENSSL_init_ssl() returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L<OPENSSL_init_crypto(3)> + +=head1 HISTORY + +The OPENSSL_init_ssl() function was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod b/openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod new file mode 100644 index 0000000..b7ee3c8 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod @@ -0,0 +1,128 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod b/openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod new file mode 100644 index 0000000..15929df --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod @@ -0,0 +1,116 @@ +=pod + +=head1 NAME + +SSL_COMP_add_compression_method, SSL_COMP_get_compression_methods, +SSL_COMP_get0_name, SSL_COMP_get_id, SSL_COMP_free_compression_methods +- handle SSL/TLS integrated compression methods + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm); + STACK_OF(SSL_COMP) *SSL_COMP_get_compression_methods(void); + const char *SSL_COMP_get0_name(const SSL_COMP *comp); + int SSL_COMP_get_id(const SSL_COMP *comp); + +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. + +SSL_COMP_get_compression_methods() returns a stack of all of the available +compression methods or NULL on error. + +SSL_COMP_get0_name() returns the name of the compression method B<comp>. + +SSL_COMP_get_id() returns the id of the compression method B<comp>. + +In versions of OpenSSL prior to 1.1.0 SSL_COMP_free_compression_methods() freed +the internal table of compression methods that were built internally, and +possibly augmented by adding SSL_COMP_add_compression_method(). However this is +now unnecessary from version 1.1.0. No explicit initialisation or +de-initialisation is necessary. See L<OPENSSL_init_crypto(3)> and +L<OPENSSL_init_ssl(3)>. From OpenSSL 1.1.0 calling this function does nothing. + +=head1 NOTES + +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 + +SSL_COMP_get_compression_methods() returns the stack of compressions methods or +NULL on error. + +SSL_COMP_get0_name() returns the name of the compression method or NULL on error. + +SSL_COMP_get_id() returns the name of the compression method or -1 on error. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 HISTORY + +SSL_COMP_free_compression_methods() was deprecated in OpenSSL 1.1.0. +SSL_COMP_get0_name() and SSL_comp_get_id() were added in OpenSSL 1.1.0d. + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod new file mode 100644 index 0000000..79f0bbc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod @@ -0,0 +1,50 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod new file mode 100644 index 0000000..da9e580 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod @@ -0,0 +1,58 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod new file mode 100644 index 0000000..efd8da3 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod @@ -0,0 +1,84 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod new file mode 100644 index 0000000..7e4120f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod @@ -0,0 +1,56 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod new file mode 100644 index 0000000..a28e218 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod @@ -0,0 +1,563 @@ +=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<-no_renegotiation> + +Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting +B<SSL_OP_NO_RENEGOTIATION>. + +=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<NoRenegotiation> + +Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting +B<SSL_OP_NO_RENEGOTIATION>. + +=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 if 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-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. 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/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod new file mode 100644 index 0000000..15529a5 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod @@ -0,0 +1,51 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod new file mode 100644 index 0000000..1f0418b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod @@ -0,0 +1,158 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod new file mode 100644 index 0000000..e2783de --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod @@ -0,0 +1,80 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod new file mode 100644 index 0000000..dbdd9f0 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod @@ -0,0 +1,82 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod new file mode 100644 index 0000000..ec744ad --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_config(SSL_CTX *ctx, const char *name); + int SSL_config(SSL *s, const char *name); + +=head1 DESCRIPTION + +The functions SSL_CTX_config() and SSL_config() configure an B<SSL_CTX> or +B<SSL> structure using the configuration B<name>. + +=head1 NOTES + +By calling SSL_CTX_config() or SSL_config() an application can perform many +complex tasks based on the contents of the configuration file: greatly +simplifying application configuration code. A degree of future proofing +can also be achieved: an application can support configuration features +in newer versions of OpenSSL automatically. + +A configuration file must have been previously loaded, for example using +CONF_modules_load_file(). See L<config(3)> for details of the configuration +file syntax. + +=head1 RETURN VALUES + +SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error +occurred. + +=head1 EXAMPLE + +If the file "config.cnf" contains the following: + + testapp = test_sect + + [test_sect] + # list of configuration 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/openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod new file mode 100644 index 0000000..e8386a5 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod @@ -0,0 +1,43 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod new file mode 100644 index 0000000..cdb6d1b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod @@ -0,0 +1,384 @@ +=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>. +The library takes a copy of the B<data> buffer contents and the caller may +free the original B<data> buffer when convenient. +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-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. 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/openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod new file mode 100644 index 0000000..7639451 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod @@ -0,0 +1,56 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod new file mode 100644 index 0000000..e5cc1aa --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod @@ -0,0 +1,51 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod new file mode 100644 index 0000000..6b93737 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod @@ -0,0 +1,64 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod new file mode 100644 index 0000000..bd10034 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod @@ -0,0 +1,59 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod new file mode 100644 index 0000000..d9e9a06 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +SSL_CTX_has_client_custom_ext - check whether a handler exists for a particular +client extension type + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_has_client_custom_ext(const SSL_CTX *ctx, unsigned int ext_type); + +=head1 DESCRIPTION + +SSL_CTX_has_client_custom_ext() checks whether a handler has been set for a +client extension of type B<ext_type> using SSL_CTX_add_client_custom_ext(). + +=head1 RETURN VALUES + +Returns 1 if a handler has been set, 0 otherwise. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_add_client_custom_ext(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod new file mode 100644 index 0000000..59d11e0 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -0,0 +1,161 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod new file mode 100644 index 0000000..7b35bdd --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod @@ -0,0 +1,218 @@ +=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 +L<SSL_set_max_proto_version(3)> functions. +Using these functions it is possible to choose e.g. TLS_server_method() +and be able to negotiate with all possible clients, but to only +allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2. + +The list of protocols available can also be limited using the +B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> and +B<SSL_OP_NO_TLSv1_2> options of the L<SSL_CTX_set_options(3)> or +L<SSL_set_options(3)> functions, but this approach is not recommended. +Clients should avoid creating "holes" in the set of protocols they support. +When disabling a protocol, make sure that you also disable either all previous +or all subsequent protocol versions. +In clients, when a protocol version is disabled without disabling I<all> +previous protocol versions, the effect is to also disable all subsequent +protocol versions. + +The SSLv3 protocol is deprecated and should generally not be used. +Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set +the minimum protocol to at least B<TLS1_VERSION>. + +=head1 RETURN VALUES + +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/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod new file mode 100644 index 0000000..049c04c --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod @@ -0,0 +1,85 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod new file mode 100644 index 0000000..5aef10b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod @@ -0,0 +1,62 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod new file mode 100644 index 0000000..d2b0e04 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -0,0 +1,96 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod new file mode 100644 index 0000000..bc4a55e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod @@ -0,0 +1,43 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod new file mode 100644 index 0000000..b0276c8 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod @@ -0,0 +1,90 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod new file mode 100644 index 0000000..e9073b9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod @@ -0,0 +1,113 @@ +=pod + +=head1 NAME + +SSL_CTX_set1_sigalgs, SSL_set1_sigalgs, SSL_CTX_set1_sigalgs_list, +SSL_set1_sigalgs_list, SSL_CTX_set1_client_sigalgs, +SSL_set1_client_sigalgs, SSL_CTX_set1_client_sigalgs_list, +SSL_set1_client_sigalgs_list - set supported signature algorithms + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set1_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); + long SSL_set1_sigalgs(SSL *ssl, const int *slist, long slistlen); + long SSL_CTX_set1_sigalgs_list(SSL_CTX *ctx, const char *str); + long SSL_set1_sigalgs_list(SSL *ssl, const char *str); + + long SSL_CTX_set1_client_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); + long SSL_set1_client_sigalgs(SSL *ssl, const int *slist, long slistlen); + long SSL_CTX_set1_client_sigalgs_list(SSL_CTX *ctx, const char *str); + long SSL_set1_client_sigalgs_list(SSL *ssl, const char *str); + +=head1 DESCRIPTION + +SSL_CTX_set1_sigalgs() and SSL_set1_sigalgs() set the supported signature +algorithms for B<ctx> or B<ssl>. The array B<slist> of length B<slistlen> +must consist of pairs of NIDs corresponding to digest and public key +algorithms. + +SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list() set the supported +signature algorithms for B<ctx> or B<ssl>. The B<str> parameter +must be a null terminated string consisting or a colon separated list of +public key algorithms and digests separated by B<+>. + +SSL_CTX_set1_client_sigalgs(), SSL_set1_client_sigalgs(), +SSL_CTX_set1_client_sigalgs_list() and SSL_set1_client_sigalgs_list() set +signature algorithms related to client authentication, otherwise they are +identical to SSL_CTX_set1_sigalgs(), SSL_set1_sigalgs(), +SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list(). + +All these functions are implemented as macros. The signature algorithm +parameter (integer array or string) is not freed: the application should +free it, if necessary. + +=head1 NOTES + +If an application wishes to allow the setting of signature algorithms +as one of many user configurable options it should consider using the more +flexible SSL_CONF API instead. + +The signature algorithms set by a client are used directly in the supported +signature algorithm in the client hello message. + +The supported signature algorithms set by a server are not sent to the +client but are used to determine the set of shared signature algorithms +and (if server preferences are set with SSL_OP_CIPHER_SERVER_PREFERENCE) +their order. + +The client authentication signature algorithms set by a server are sent +in a certificate request message if client authentication is enabled, +otherwise they are unused. + +Similarly client authentication signature algorithms set by a client are +used to determined the set of client authentication shared signature +algorithms. + +Signature algorithms will neither be advertised nor used if the security level +prohibits them (for example SHA1 if the security level is 4 or more). + +Currently the NID_md5, NID_sha1, NID_sha224, NID_sha256, NID_sha384 and +NID_sha512 digest NIDs are supported and the public key algorithm NIDs +EVP_PKEY_RSA, EVP_PKEY_DSA and EVP_PKEY_EC. + +The short or long name values for digests can be used in a string (for +example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and +the public key algorithm strings "RSA", "DSA" or "ECDSA". + +The use of MD5 as a digest is strongly discouraged due to security weaknesses. + +=head1 EXAMPLES + +Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA +using an array: + + const int slist[] = {NID_sha256, EVP_PKEY_EC, NID_sha256, EVP_PKEY_RSA}; + + SSL_CTX_set1_sigalgs(ctx, slist, 4); + +Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA +using a string: + + SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256"); + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_get_shared_sigalgs(3)>, +L<SSL_CONF_CTX_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod new file mode 100644 index 0000000..bfe8b70 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod @@ -0,0 +1,100 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod new file mode 100644 index 0000000..56c8609 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod @@ -0,0 +1,197 @@ +=pod + +=head1 NAME + +SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, +SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb, +SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated +- handle application layer protocol negotiation (ALPN) + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos, + unsigned 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); + void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, + unsigned int *len); + + void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx, + int (*cb)(SSL *ssl, + const unsigned char **out, + unsigned int *outlen, + void *arg), + void *arg); + void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx, + int (*cb)(SSL *s, + unsigned char **out, + unsigned char *outlen, + const unsigned char *in, + unsigned int inlen, + void *arg), + void *arg); + int SSL_select_next_proto(unsigned char **out, unsigned char *outlen, + const unsigned char *server, + unsigned int server_len, + const unsigned char *client, + unsigned int client_len) + void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data, + unsigned *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_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a +client needs to select a protocol from the server's provided list, and a +user-defined pointer argument B<arg> which will be passed to this callback. +For the callback itself, B<out> +must be set to point to the selected protocol (which may be within B<in>). +The length of the protocol name must be written into B<outlen>. The +server's advertised protocols are provided in B<in> and B<inlen>. The +callback can assume that B<in> is syntactically valid. The client must +select a protocol. It is fatal to the connection if this callback returns +a value other than B<SSL_TLSEXT_ERR_OK>. The B<arg> parameter is the pointer +set via SSL_CTX_set_next_proto_select_cb(). + +SSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called +when a TLS server needs a list of supported protocols for Next Protocol +Negotiation. The returned list must be in protocol-list format, described +below. The list is +returned by setting B<out> to point to it and B<outlen> to its length. This +memory will not be modified, but the B<SSL> does keep a +reference to it. The callback should return B<SSL_TLSEXT_ERR_OK> if it +wishes to advertise. Otherwise, no such extension will be included in the +ServerHello. + +SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data> +with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len> +is set to 0 if no protocol has been selected. B<data> must not be freed. + +SSL_get0_next_proto_negotiated() sets B<data> and B<len> to point to the +client's requested protocol for this connection. If the client did not +request any protocol or NPN is not enabled, then B<data> is set to NULL and +B<len> to 0. Note that +the client can request any protocol it chooses. The value returned from +this function need not be a member of the list of supported protocols +provided by the callback. + +=head1 NOTES + +The protocol-lists must be in wire-format, which is defined as a vector of +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_ALERT_FATAL + +There was no overlap between the client's supplied list and the server +configuration. + +=item SSL_TLSEXT_ERR_NOACK + +ALPN protocol not selected, e.g., because no ALPN protocols are configured for +this connection. + +=back + +The callback set using SSL_CTX_set_next_proto_select_cb() should return +B<SSL_TLSEXT_ERR_OK> if successful. Any other value is fatal to the connection. + +The callback set using SSL_CTX_set_next_protos_advertised_cb() should return +B<SSL_TLSEXT_ERR_OK> if it wishes to advertise. Otherwise, no such extension +will be included in the ServerHello. + +=head1 SEE ALSO + +L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, +L<SSL_CTX_set_tlsext_servername_arg(3)> + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod new file mode 100644 index 0000000..eaa7a4e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod @@ -0,0 +1,77 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod new file mode 100644 index 0000000..7f7a794 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod @@ -0,0 +1,73 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod new file mode 100644 index 0000000..af303f2 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod @@ -0,0 +1,74 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod new file mode 100644 index 0000000..4e66917 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -0,0 +1,74 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod new file mode 100644 index 0000000..0252e7b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod @@ -0,0 +1,103 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod new file mode 100644 index 0000000..aed7d4f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod @@ -0,0 +1,103 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod new file mode 100644 index 0000000..afa45dc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod @@ -0,0 +1,145 @@ +=pod + +=head1 NAME + +ssl_ct_validation_cb, +SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct, +SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, +SSL_ct_is_enabled, SSL_CTX_ct_is_enabled - +control Certificate Transparency policy + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + typedef int (*ssl_ct_validation_cb)(const CT_POLICY_EVAL_CTX *ctx, + const STACK_OF(SCT) *scts, void *arg); + + int SSL_enable_ct(SSL *s, int validation_mode); + int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode); + int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback, + void *arg); + int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, + ssl_ct_validation_cb callback, + void *arg); + void SSL_disable_ct(SSL *s); + void SSL_CTX_disable_ct(SSL_CTX *ctx); + int SSL_ct_is_enabled(const SSL *s); + int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_enable_ct() and SSL_CTX_enable_ct() enable the processing of signed +certificate timestamps (SCTs) either for a given SSL connection or for all +connections that share the given SSL context, respectively. +This is accomplished by setting a built-in CT validation callback. +The behaviour of the callback is determined by the B<validation_mode> argument, +which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or +B<SSL_CT_VALIDATION_STRICT> as described below. + +If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full +TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer +presents no valid SCTs the handshake will be aborted. +If the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue +despite lack of valid SCTs. +However, in that case if the verification status before the built-in callback +was B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the +callback. +Applications can call L<SSL_get_verify_result(3)> to check the status at +handshake completion, even after session resumption since the verification +status is part of the saved session state. +See L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>. + +If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the +handshake continues, and the verification status is not modified, regardless of +the validation status of any SCTs. +The application can still inspect the validation status of the SCTs at +handshake completion. +Note that with session resumption there will not be any SCTs presented during +the handshake. +Therefore, in applications that delay SCT policy enforcement until after +handshake completion, such delayed SCT checks should only be performed when the +session is not resumed. + +SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() +register a custom callback that may implement a different policy than either of +the above. +This callback can examine the peer's SCTs and determine whether they are +sufficient to allow the connection to continue. +The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE> +and the callback returns a non-positive result. + +An arbitrary callback context argument, B<arg>, can be passed in when setting +the callback. +This will be passed to the callback whenever it is invoked. +Ownership of this context remains with the caller. + +If no callback is set, SCTs will not be requested and Certificate Transparency +validation will not occur. + +No callback will be invoked when the peer presents no certificate, e.g. by +employing an anonymous (aNULL) ciphersuite. +In that case the handshake continues as it would had no callback been +requested. +Callbacks are also not invoked when the peer certificate chain is invalid or +validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509 +PKI, or no X.509 PKI at all, respectively. +Clients that require SCTs are expected to not have enabled any aNULL ciphers +nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA +records. + +SSL_disable_ct() and SSL_CTX_disable_ct() turn off CT processing, whether +enabled via the built-in or the custom callbacks, by setting a NULL callback. +These may be implemented as macros. + +SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is +enabled via either SSL_enable_ct() or a non-null custom callback, and 0 +otherwise. + +=head1 NOTES + +When SCT processing is enabled, OCSP stapling will be enabled. This is because +one possible source of SCTs is the OCSP response from a server. + +The time returned by SSL_SESSION_get_time() will be used to evaluate whether any +presented SCTs have timestamps that are in the future (and therefore invalid). + +=head1 RESTRICTIONS + +Certificate Transparency validation cannot be enabled and so a callback cannot +be set if a custom client extension handler has been registered to handle SCT +extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>). + +=head1 RETURN VALUES + +SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and +SSL_set_ct_validation_callback() return 1 if the B<callback> is successfully +set. +They return 0 if an error occurs, e.g. a custom client extension handler has +been setup to handle SCTs. + +SSL_disable_ct() and SSL_CTX_disable_ct() do not return a result. + +SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT +validation callback is set, or 0 if no callback (or equivalently a NULL +callback) is set. + +=head1 SEE ALSO + +L<ssl(7)>, +<SSL_get_verify_result(3)>, +L<SSL_session_reused(3)>, +L<SSL_set_verify(3)>, +L<SSL_CTX_set_verify(3)>, +L<SSL_SESSION_get_time(3)> + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod new file mode 100644 index 0000000..4a2fa94 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_CTX_set_default_ctlog_list_file, SSL_CTX_set_ctlog_list_file - +load a Certificate Transparency log list from a file + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_default_ctlog_list_file(SSL_CTX *ctx); + int SSL_CTX_set_ctlog_list_file(SSL_CTX *ctx, const char *path); + +=head1 DESCRIPTION + +SSL_CTX_set_default_ctlog_list_file() loads a list of Certificate Transparency +(CT) logs from the default file location, "ct_log_list.cnf", found in the +directory where OpenSSL is installed. + +SSL_CTX_set_ctlog_list_file() loads a list of CT logs from a specific path. +See L<CTLOG_STORE_new(3)> for the file format. + +=head1 NOTES + +These functions will not clear the existing CT log list - it will be appended +to. To replace the existing list, use L<SSL_CTX_set0_ctlog_store> first. + +If an error occurs whilst parsing a particular log entry in the file, that log +entry will be skipped. + +=head1 RETURN VALUES + +SSL_CTX_set_default_ctlog_list_file() and SSL_CTX_set_ctlog_list_file() +return 1 if the log list is successfully loaded, and 0 if an error occurs. In +the case of an error, the log list may have been partially loaded. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_ct_validation_callback(3)>, +L<CTLOG_STORE_new(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod new file mode 100644 index 0000000..2196906 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod @@ -0,0 +1,113 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod new file mode 100644 index 0000000..fd0364b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +SSL_CTX_get_ex_data, SSL_CTX_set_ex_data, +SSL_get_ex_data, SSL_set_ex_data +- Store and retrieve extra data from the SSL_CTX, SSL or SSL_SESSION + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx); + + int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, void *arg); + + void *SSL_get_ex_data(const SSL *s, int idx); + + int SSL_set_ex_data(SSL *s, int idx, void *arg); + +=head1 DESCRIPTION + +SSL*_set_ex_data() functions can be used to store arbitrary user data into the +B<SSL_CTX>, or B<SSL> object. The user must supply a unique index +which they can subsequently use to retrieve the data using SSL*_get_ex_data(). + +For more detailed information see L<CRYPTO_get_ex_data(3)> and +L<CRYPTO_set_ex_data(3)> which implement these functions and +L<CRYPTO_get_ex_new_index(3)> for generating a unique index. + +=head1 RETURN VALUES + +The SSL*_set_ex_data() functions return 1 if the item is successfully stored +and 0 if it is not. +The SSL*_get_ex_data() functions return the ex_data pointer if successful, +otherwise NULL. + +=head1 SEE ALSO + +L<CRYPTO_get_ex_data(3)>, L<CRYPTO_set_ex_data(3)>, +L<CRYPTO_get_ex_new_index(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod new file mode 100644 index 0000000..1b1171f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod @@ -0,0 +1,139 @@ +=pod + +=head1 NAME + +SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, +SSL_has_matching_session_id, GEN_SESSION_CB +- manipulate generation of SSL session IDs (server only) + +=head1 SYNOPSIS + + #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(7)>, 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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod new file mode 100644 index 0000000..f36f217 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod @@ -0,0 +1,162 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod new file mode 100644 index 0000000..482751e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod @@ -0,0 +1,82 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod new file mode 100644 index 0000000..ff080e4 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version, +SSL_CTX_get_min_proto_version, SSL_CTX_get_max_proto_version, +SSL_set_min_proto_version, SSL_set_max_proto_version, +SSL_get_min_proto_version, SSL_get_max_proto_version - Get and 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_CTX_get_min_proto_version(SSL_CTX *ctx); + int SSL_CTX_get_max_proto_version(SSL_CTX *ctx); + + int SSL_set_min_proto_version(SSL *ssl, int version); + int SSL_set_max_proto_version(SSL *ssl, int version); + int SSL_get_min_proto_version(SSL *ssl); + int SSL_get_max_proto_version(SSL *ssl); + +=head1 DESCRIPTION + +The functions get or 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. + +Getters return 0 in case B<ctx> or B<ssl> have been configured to +automatically use the lowest or highest version supported by the library. + +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 setter functions return 1 on success and 0 on failure. The getter +functions return the configured version or 0 for auto-configuration of +lowest or highest protocol, respectively. + +=head1 NOTES + +All these functions are implemented using macros. + +=head1 HISTORY + +The setter functions were added in OpenSSL 1.1.0. The getter functions +were added in OpenSSL 1.1.1. + +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod new file mode 100644 index 0000000..1b3e783 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod @@ -0,0 +1,114 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod new file mode 100644 index 0000000..9546e75 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod @@ -0,0 +1,103 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod new file mode 100644 index 0000000..241aeb3 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod @@ -0,0 +1,307 @@ +=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. + +=item SSL_OP_NO_RENEGOTIATION + +Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest +messages, and ignore renegotiation requests via ClientHello. + +=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. + +B<SSL_OP_NO_RENEGOTIATION> was added in OpenSSL 1.1.0h. + +=head1 COPYRIGHT + +Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. 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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod new file mode 100644 index 0000000..a417508 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod @@ -0,0 +1,63 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod new file mode 100644 index 0000000..d39d747 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod @@ -0,0 +1,72 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod new file mode 100644 index 0000000..bea8390 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod @@ -0,0 +1,60 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod new file mode 100644 index 0000000..577b393 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod @@ -0,0 +1,169 @@ +=pod + +=head1 NAME + +SSL_CTX_set_security_level, SSL_set_security_level, SSL_CTX_get_security_level, SSL_get_security_level, SSL_CTX_set_security_callback, SSL_set_security_callback, SSL_CTX_get_security_callback, SSL_get_security_callback, SSL_CTX_set0_security_ex_data, SSL_set0_security_ex_data, SSL_CTX_get0_security_ex_data, SSL_get0_security_ex_data - SSL/TLS security framework + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_security_level(SSL_CTX *ctx, int level); + void SSL_set_security_level(SSL *s, int level); + + int SSL_CTX_get_security_level(const SSL_CTX *ctx); + int SSL_get_security_level(const SSL *s); + + void SSL_CTX_set_security_callback(SSL_CTX *ctx, + int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, + void *other, void *ex)); + + void SSL_set_security_callback(SSL *s, + int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, + void *other, void *ex)); + + int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex); + int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex); + + void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex); + void SSL_set0_security_ex_data(SSL *s, void *ex); + + void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx); + void *SSL_get0_security_ex_data(const SSL *s); + +=head1 DESCRIPTION + +The functions SSL_CTX_set_security_level() and SSL_set_security_level() set +the security level to B<level>. If not set the library default security level +is used. + +The functions SSL_CTX_get_security_level() and SSL_get_security_level() +retrieve the current security level. + +SSL_CTX_set_security_callback(), SSL_set_security_callback(), +SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set +the security callback associated with B<ctx> or B<s>. If not set a default +security callback is used. The meaning of the parameters and the behaviour +of the default callbacks is described below. + +SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(), +SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the +extra data pointer passed to the B<ex> parameter of the callback. This +value is passed to the callback verbatim and can be set to any convenient +application specific value. + +=head1 DEFAULT CALLBACK BEHAVIOUR + +If an application doesn't set its own security callback the default +callback is used. It is intended to provide sane defaults. The meaning +of each level is described below. + +=over 4 + +=item B<Level 0> + +Everything is permitted. This retains compatibility with previous versions of +OpenSSL. + +=item B<Level 1> + +The security level corresponds to a minimum of 80 bits of security. Any +parameters offering below 80 bits of security are excluded. As a result RSA, +DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits +are prohibited. All export ciphersuites are prohibited since they all offer +less than 80 bits of security. SSL version 2 is prohibited. Any ciphersuite +using MD5 for the MAC is also prohibited. + +=item B<Level 2> + +Security level set to 112 bits of security. As a result RSA, DSA and DH keys +shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. +In addition to the level 1 exclusions any ciphersuite using RC4 is also +prohibited. SSL version 3 is also not allowed. Compression is disabled. + +=item B<Level 3> + +Security level set to 128 bits of security. As a result RSA, DSA and DH keys +shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. +In addition to the level 2 exclusions ciphersuites not offering forward +secrecy are prohibited. TLS versions below 1.1 are not permitted. Session +tickets are disabled. + +=item B<Level 4> + +Security level set to 192 bits of security. As a result RSA, DSA and DH keys +shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited. +Ciphersuites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are +not permitted. + +=item B<Level 5> + +Security level set to 256 bits of security. As a result RSA, DSA and DH keys +shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited. + +=back + +=head1 APPLICATION DEFINED SECURITY CALLBACKS + +I<Documentation to be provided.> + +=head1 NOTES + +B<WARNING> at this time setting the security level higher than 1 for +general internet use is likely to cause B<considerable> interoperability +issues and is not recommended. This is because the B<SHA1> algorithm +is very widely used in certificates and will be rejected at levels +higher than 1 because it only offers 80 bits of security. + +The default security level can be configured when OpenSSL is compiled by +setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 1 is used. + +The security framework disables or reject parameters inconsistent with the +set security level. In the past this was difficult as applications had to set +a number of distinct parameters (supported ciphers, supported curves supported +signature algorithms) to achieve this end and some cases (DH parameter size +for example) could not be checked at all. + +By setting an appropriate security level much of this complexity can be +avoided. + +The bits of security limits affect all relevant parameters including +ciphersuite encryption algorithms, supported ECC curves, supported +signature algorithms, DH parameter sizes, certificate key sizes and +signature algorithms. This limit applies no matter what other custom +settings an application has set: so if the ciphersuite is set to B<ALL> +then only ciphersuites consistent with the security level are permissible. + +See SP800-57 for how the security limits are related to individual +algorithms. + +Some security levels require large key sizes for non-ECC public key +algorithms which can severely degrade performance. For example 256 bits +of security requires the use of RSA keys of at least 15360 bits in size. + +Some restrictions can be gracefully handled: for example ciphersuites +offering insufficient security are not sent by the client and will not +be selected by the server. Other restrictions such as the peer certificate +key size or the DH parameter size will abort the handshake with a fatal +alert. + +Attempts to set certificates or parameters with insufficient security are +also blocked. For example trying to set a certificate using a 512 bit RSA +key using SSL_CTX_use_certificate() at level 1. Applications which do not +check the return values for errors will misbehave: for example it might +appear that a certificate is not set at all because it had been rejected. + +=head1 HISTORY + +These functions were first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod new file mode 100644 index 0000000..b237076 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod @@ -0,0 +1,141 @@ +=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 look 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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod new file mode 100644 index 0000000..a873b03 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod @@ -0,0 +1,92 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod new file mode 100644 index 0000000..accf5af --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod @@ -0,0 +1,132 @@ +=pod + +=head1 NAME + +SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment, +SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment, +SSL_CTX_set_max_pipelines, SSL_set_max_pipelines, +SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len - Control +fragment sizes and pipelining operations + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long); + long SSL_set_max_send_fragment(SSL *ssl, long m); + + long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m); + long SSL_set_max_pipelines(SSL_CTX *ssl, long m); + + long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m); + long SSL_set_split_send_fragment(SSL *ssl, long m); + + void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len); + void SSL_set_default_read_buffer_len(SSL *s, size_t len); + +=head1 DESCRIPTION + +Some engines are able to process multiple simultaneous crypto operations. This +capability could be utilised to parallelise the processing of a single +connection. For example a single write can be split into multiple records and +each one encrypted independently and in parallel. Note: this will only work in +TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This +capability is known as "pipelining" within OpenSSL. + +In order to benefit from the pipelining capability. You need to have an engine +that provides ciphers that support this. The OpenSSL "dasync" engine provides +AES128-SHA based ciphers that have this capability. However these are for +development and test purposes only. + +SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the +B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This +value restricts the amount of plaintext bytes that will be sent in any one +SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These +functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH. + +SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number +of pipelines that will be used at any one time. This value applies to both +"read" pipelining and "write" pipelining. By default only one pipeline will be +used (i.e. normal non-parallel operation). The number of pipelines set must be +in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also +automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is +explained further below. OpenSSL will only every use more than one pipeline if +a ciphersuite is negotiated that uses a pipeline capable cipher provided by an +engine. + +Pipelining operates slightly differently for reading encrypted data compared to +writing encrypted data. SSL_CTX_set_split_send_fragment() and +SSL_set_split_send_fragment() define how data is split up into pipelines when +writing encrypted data. The number of pipelines used will be determined by the +amount of data provided to the SSL_write() call divided by +B<split_send_fragment>. + +For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4 +then: + +SSL_write called with 0-2000 bytes == 1 pipeline used + +SSL_write called with 2001-4000 bytes == 2 pipelines used + +SSL_write called with 4001-6000 bytes == 3 pipelines used + +SSL_write called with 6001+ bytes == 4 pipelines used + +B<split_send_fragment> must always be less than or equal to +B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>. +This will mean that the same number of records will always be created as would +have been created in the non-parallel case, although the data will be +apportioned differently. In the parallel case data will be spread equally +between the pipelines. + +Read pipelining is controlled in a slightly different way than with write +pipelining. While reading we are constrained by the number of records that the +peer (and the network) can provide to us in one go. The more records we can get +in one go the more opportunity we have to parallelise the processing. As noted +above when setting B<max_pipelines> to a value greater than one, B<read_ahead> +is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to +read as much data into the read buffer as the network can provide and will fit +into the buffer. Without this set data is read into the read buffer one record +at a time. The more data that can be read, the more opportunity there is for +parallelising the processing at the cost of increased memory overhead per +connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending() +function (see L<SSL_pending(3)>). + +The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() +functions control the size of the read buffer that will be used. The B<len> +parameter sets the size of the buffer. The value will only be used if it is +greater than the default that would have been used anyway. The normal default +value depends on a number of factors but it will be at least +SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes. + +=head1 RETURN VALUES + +All non-void functions return 1 on success and 0 on failure. + +=head1 NOTES + +With the exception of SSL_CTX_set_default_read_buffer_len() and +SSL_set_default_read_buffer_len() all these functions are implemented using +macros. + +=head1 HISTORY + +The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(), +SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(), +SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() +functions were added in OpenSSL 1.1.0. + +=head1 SEE ALSO + +L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod new file mode 100644 index 0000000..22c0370 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod @@ -0,0 +1,70 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod new file mode 100644 index 0000000..470efdf --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod @@ -0,0 +1,68 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod new file mode 100644 index 0000000..c12ff0e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod @@ -0,0 +1,125 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod new file mode 100644 index 0000000..34d8ce9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod @@ -0,0 +1,198 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod new file mode 100644 index 0000000..fbfb8cb --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod @@ -0,0 +1,137 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod new file mode 100644 index 0000000..7993498 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod @@ -0,0 +1,307 @@ +=pod + +=head1 NAME + +SSL_get_ex_data_X509_STORE_CTX_idx, +SSL_CTX_set_verify, SSL_set_verify, +SSL_CTX_set_verify_depth, SSL_set_verify_depth, +SSL_verify_cb +- set peer certificate verification parameters + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback); + void SSL_set_verify(SSL *s, int mode, SSL_verify_cb verify_callback); + SSL_get_ex_data_X509_STORE_CTX_idx(void); + + void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth); + void SSL_set_verify_depth(SSL *s, int depth); + + + typedef int (*SSL_verify_cb)(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)>. Within the callback function, +B<SSL_get_ex_data_X509_STORE_CTX_idx> can be called to get the data index +of the current SSL object that is doing the verification. + +SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain +verification that shall be allowed for B<ctx>. + +SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain +verification that shall be allowed for B<ssl>. + +=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 a limit on the +number of certificates between the end-entity and trust-anchor certificates. +Neither the +end-entity nor the trust-anchor certificates count against B<depth>. If the +certificate chain needed to reach a trusted issuer is longer than B<depth+2>, +X509_V_ERR_CERT_CHAIN_TOO_LONG will be issued. +The depth count is "level 0:peer certificate", "level 1: CA certificate", +"level 2: higher level CA certificate", and so on. Setting the maximum +depth to 2 allows the levels 0, 1, 2 and 3 (0 being the end-entity and 3 the +trust-anchor). +The default depth limit is 100, +allowing for the peer certificate, at most 100 intermediate CA certificates and +a final trust anchor certificate. + +The B<verify_callback> function is used to control the behaviour when the +SSL_VERIFY_PEER flag is set. It must be supplied by the application and +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 BUGS + +In client mode, it is not checked whether the SSL_VERIFY_PEER flag +is set, but whether any flags are set. This can lead to +unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as +required. + +=head1 RETURN VALUES + +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<CRYPTO_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(7)>, L<SSL_new(3)>, +L<SSL_CTX_get_verify_mode(3)>, +L<SSL_get_verify_result(3)>, +L<SSL_CTX_load_verify_locations(3)>, +L<SSL_get_peer_certificate(3)>, +L<SSL_CTX_set_cert_verify_callback(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>, +L<CRYPTO_get_ex_new_index(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod new file mode 100644 index 0000000..c645f58 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod @@ -0,0 +1,180 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod new file mode 100644 index 0000000..753074a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod @@ -0,0 +1,87 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod new file mode 100644 index 0000000..bd496ff --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod @@ -0,0 +1,56 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod new file mode 100644 index 0000000..5bea785 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod @@ -0,0 +1,78 @@ +=pod + +=head1 NAME + +SSL_SESSION_new, +SSL_SESSION_up_ref, +SSL_SESSION_free - create, free and manage SSL_SESSION structures + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_SESSION *SSL_SESSION_new(void); + int SSL_SESSION_up_ref(SSL_SESSION *ses); + void SSL_SESSION_free(SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_SESSION_new() creates a new SSL_SESSION structure and returns a pointer to +it. + +SSL_SESSION_up_ref() increments the reference count on the given SSL_SESSION +structure. + +SSL_SESSION_free() decrements the reference count of B<session> and removes +the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated +memory, if the reference count has reached 0. +If B<session> is NULL nothing is done. + +=head1 NOTES + +SSL_SESSION objects are allocated, when a TLS/SSL handshake operation +is successfully completed. Depending on the settings, see +L<SSL_CTX_set_session_cache_mode(3)>, +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_new returns a pointer to the newly allocated SSL_SESSION structure +or NULL on error. + +SSL_SESSION_up_ref returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L<ssl(3)>, 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/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod new file mode 100644 index 0000000..fdd36ed --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_cipher - retrieve the SSL cipher associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const SSL_CIPHER *SSL_SESSION_get0_cipher(const SSL_SESSSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_cipher() retrieves the cipher that was used by the +connection when the session was created, or NULL if it cannot be determined. + +The value returned is a pointer to an object maintained within B<s> and +should not be released. + +=head1 SEE ALSO + +L<ssl(3)>, +L<d2i_SSL_SESSION(3)>, +L<SSL_SESSION_get_time(3)>, +L<SSL_SESSION_get0_hostname(3)>, +L<SSL_SESSION_free(3)> + +=head1 HISTORY + +SSL_SESSION_get0_cipher() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod new file mode 100644 index 0000000..6fb12be --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_hostname - retrieve the SNI hostname associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_SESSION_get0_hostname(const SSL_SESSSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the +client when the session was created, or NULL if no value was sent. + +The value returned is a pointer to memory maintained within B<s> and +should not be free'd. + +=head1 SEE ALSO + +L<ssl(3)>, +L<d2i_SSL_SESSION(3)>, +L<SSL_SESSION_get_time(3)>, +L<SSL_SESSION_free(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod new file mode 100644 index 0000000..ee4a256 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_id_context, +SSL_SESSION_set1_id_context +- get and set the SSL ID context associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const unsigned char *SSL_SESSION_get0_id_context(const SSL_SESSION *s, + unsigned int *len) + int SSL_SESSION_set1_id_context(SSL_SESSION *s, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); + +=head1 DESCRIPTION + +See L<SSL_CTX_set_session_id_context(3)> for further details on session ID +contexts. + +SSL_SESSION_get0_id_context() returns the ID context associated with +the SSL/TLS session B<s>. The length of the ID context is written to +B<*len> if B<len> is not NULL. + +The value returned is a pointer to an object maintained within B<s> and +should not be released. + +SSL_SESSION_set1_id_context() takes a copy of the provided ID context given in +B<sid_ctx> and associates it with the session B<s>. The length of the ID context +is given by B<sid_ctx_len> which must not exceed SSL_MAX_SID_CTX_LENGTH bytes. + +=head1 RETURN VALUES + +SSL_SESSION_set1_id_context() returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_set_session_id_context(3)> + +=head1 HISTORY + +SSL_SESSION_get0_id_context() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod new file mode 100644 index 0000000..a95f8a5 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_peer +- get details about peer's certificate for a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + X509 *SSL_SESSION_get0_peer(SSL_SESSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_peer() returns the peer certificate associated with the session +B<s> or NULL if no peer certificate is available. The caller should not free the +returned value (unless L<X509_up_ref(3)> has also been called). + +=head1 RETURN VALUES + +SSL_SESSION_get0_peer() returns a pointer to the peer certificate or NULL if +no peer certificate is available. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod new file mode 100644 index 0000000..5045c53 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_compress_id +- get details about the compression associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + unsigned int SSL_SESSION_get_compress_id(const SSL_SESSION *s); + +=head1 DESCRIPTION + +If compression has been negotiated for an ssl session then +SSL_SESSION_get_compress_id() will return the id for the compression method or +0 otherwise. The only built-in supported compression method is zlib which has an +id of 1. + +=head1 RETURN VALUES + +SSL_SESSION_get_compress_id() returns the id of the compression method or 0 if +none. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod new file mode 100644 index 0000000..e922abc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +SSL_SESSION_set_ex_data, +SSL_SESSION_get_ex_data +- get and set application specific data on a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_set_ex_data(SSL_SESSION *ss, int idx, void *data); + void *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx); + +=head1 DESCRIPTION + +SSL_SESSION_set_ex_data() enables an application to store arbitrary application +specific data B<data> in an SSL_SESSION structure B<ss>. The index B<idx> should +be a value previously returned from a call to L<CRYPTO_get_ex_new_index(3)>. + +SSL_SESSION_get_ex_data() retrieves application specific data previously stored +in an SSL_SESSION structure B<s>. The B<idx> value should be the same as that +used when originally storing the data. + +=head1 RETURN VALUES + +SSL_SESSION_set_ex_data() returns 1 for success or 0 for failure. + +SSL_SESSION_get_ex_data() returns the previously stored value or NULL on +failure. NULL may also be a valid value. + +=head1 SEE ALSO + +L<ssl(3)>, +L<CRYPTO_get_ex_new_index(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod new file mode 100644 index 0000000..a033fdd --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_protocol_version - retrieve session protocol version + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_get_protocol_version(const SSL_SESSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get_protocol_version() returns the protocol version number used +by session B<s>. + +=head1 RETURN VALUES + +SSL_SESSION_get_protocol_version() returns a number indicating the protocol +version used for the session; this number matches the constants I<e.g.> +B<TLS1_VERSION> or B<TLS1_2_VERSION>. + +Note that the SSL_SESSION_get_protocol_version() function +does B<not> perform a null check on the provided session B<s> pointer. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 HISTORY + +SSL_SESSION_get_protocol_version() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod new file mode 100644 index 0000000..e98d128 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod @@ -0,0 +1,76 @@ +=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(7)>, +L<SSL_CTX_set_timeout(3)>, +L<SSL_get_default_timeout(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod new file mode 100644 index 0000000..a84440b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_ticket, +SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint +- get details about the ticket associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_has_ticket(const SSL_SESSION *s); + unsigned long SSL_SESSION_get_ticket_lifetime_hint(const SSL_SESSION *s); + void SSL_SESSION_get0_ticket(const SSL_SESSION *s, const unsigned char **tick, + size_t *len); + +=head1 DESCRIPTION + +SSL_SESSION_has_ticket() returns 1 if there is a Session Ticket associated with +this session, and 0 otherwise. + +SSL_SESSION_get_ticket_lifetime_hint returns the lifetime hint in seconds +associated with the session ticket. + +SSL_SESSION_get0_ticket obtains a pointer to the ticket associated with a +session. The length of the ticket is written to B<*len>. If B<tick> is non +NULL then a pointer to the ticket is written to B<*tick>. The pointer is only +valid while the connection is in use. The session (and hence the ticket pointer) +may also become invalid as a result of a call to SSL_CTX_flush_sessions(). + +=head1 SEE ALSO + +L<ssl(7)>, +L<d2i_SSL_SESSION(3)>, +L<SSL_SESSION_get_time(3)>, +L<SSL_SESSION_free(3)> + +=head1 HISTORY + +SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint and +SSL_SESSION_get0_ticket were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod new file mode 100644 index 0000000..9a44c11 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +SSL_SESSION_print, +SSL_SESSION_print_fp, +SSL_SESSION_print_keylog +- printf information about a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_print(BIO *fp, const SSL_SESSION *ses); + int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *ses); + int SSL_SESSION_print_keylog(BIO *bp, const SSL_SESSION *x); + +=head1 DESCRIPTION + +SSL_SESSION_print() prints summary information about the session provided in +B<ses> to the BIO B<fp>. + +SSL_SESSION_print_fp() does the same as SSL_SESSION_print() except it prints it +to the FILE B<fp>. + +SSL_SESSION_print_keylog() prints session information to the provided BIO <bp> +in NSS keylog format. + +=head1 RETURN VALUES + +SSL_SESSION_print(), SSL_SESSION_print_fp() and SSL_SESSION_print_keylog return +1 on success or 0 on error. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod new file mode 100644 index 0000000..0bd9b83 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_id, +SSL_SESSION_set1_id +- get and set the SSL session ID + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const unsigned char *SSL_SESSION_get_id(const SSL_SESSION *s, + unsigned int *len) + int SSL_SESSION_set1_id(SSL_SESSION *s, const unsigned char *sid, + unsigned int sid_len); + +=head1 DESCRIPTION + +SSL_SESSION_get_id() returns a pointer to the internal session id value for the +session B<s>. The length of the id in bytes is stored in B<*len>. The length may +be 0. The caller should not free the returned pointer directly. + +SSL_SESSION_set1_id() sets the the session ID for the B<ssl> SSL/TLS session +to B<sid> of length B<sid_len>. + +=head1 RETURN VALUES + +SSL_SESSION_get_id() returns a pointer to the session id value. +SSL_SESSION_set1_id() returns 1 for success and 0 for failure, for example +if the supplied session ID length exceeds B<SSL_MAX_SSL_SESSION_ID_LENGTH>. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 HISTORY + +SSL_SESSION_set1_id() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_accept.pod b/openssl-1.1.0h/doc/ssl/SSL_accept.pod new file mode 100644 index 0000000..3248cac --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_accept.pod @@ -0,0 +1,82 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod b/openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod new file mode 100644 index 0000000..6e2768e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod @@ -0,0 +1,242 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_check_chain.pod b/openssl-1.1.0h/doc/ssl/SSL_check_chain.pod new file mode 100644 index 0000000..8691994 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_check_chain.pod @@ -0,0 +1,94 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_clear.pod b/openssl-1.1.0h/doc/ssl/SSL_clear.pod new file mode 100644 index 0000000..ed0ad60 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_clear.pod @@ -0,0 +1,84 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_connect.pod b/openssl-1.1.0h/doc/ssl/SSL_connect.pod new file mode 100644 index 0000000..df198f9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_connect.pod @@ -0,0 +1,82 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod b/openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod new file mode 100644 index 0000000..ffb71cc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod @@ -0,0 +1,81 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod b/openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod new file mode 100644 index 0000000..ccb99ec --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_export_keying_material - obtain keying material for application use + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen, + const char *label, size_t llen, + const unsigned char *context, + size_t contextlen, int use_context); + +=head1 DESCRIPTION + +During the creation of a TLS or DTLS connection shared keying material is +established between the two endpoints. The function SSL_export_keying_material() +enables an application to use some of this keying material for its own purposes +in accordance with RFC5705. + +An application may need to securely establish the context within which this +keying material will be used. For example this may include identifiers for the +application session, application algorithms or parameters, or the lifetime of +the context. The context value is left to the application but must be the same +on both sides of the communication. + +For a given SSL connection B<s>, B<olen> bytes of data will be written to +B<out>. The application specific context should be supplied in the location +pointed to by B<context> and should be B<contextlen> bytes long. Provision of +a context is optional. If the context should be omitted entirely then +B<use_context> should be set to 0. Otherwise it should be any other value. If +B<use_context> is 0 then the values of B<context> and B<contextlen> are ignored. +Note that a zero length context is treated differently to no context at all, and +will result in different keying material being returned. + +An application specific label should be provided in the location pointed to by +B<label> and should be B<llen> bytes long. Typically this will be a value from +the IANA Exporter Label Registry +(L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels>). +Alternatively labels beginning with "EXPERIMENTAL" are permitted by the standard +to be used without registration. + +Note that this function is only defined for TLSv1.0 and above, and DTLSv1.0 and +above. Attempting to use it in SSLv3 will result in an error. + +=head1 RETURN VALUES + +SSL_export_keying_material() returns 0 or -1 on failure or 1 on success. + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_extension_supported.pod b/openssl-1.1.0h/doc/ssl/SSL_extension_supported.pod new file mode 100644 index 0000000..166c35a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_extension_supported.pod @@ -0,0 +1,145 @@ +=pod + +=head1 NAME + +SSL_extension_supported, +SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext, +custom_ext_add_cb, custom_ext_free_cb, custom_ext_parse_cb +- custom TLS extension handling + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type, + custom_ext_add_cb add_cb, + custom_ext_free_cb free_cb, void *add_arg, + custom_ext_parse_cb parse_cb, + void *parse_arg); + + 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/openssl-1.1.0h/doc/ssl/SSL_free.pod b/openssl-1.1.0h/doc/ssl/SSL_free.pod new file mode 100644 index 0000000..eb69a16 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_free.pod @@ -0,0 +1,54 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get0_peer_scts.pod b/openssl-1.1.0h/doc/ssl/SSL_get0_peer_scts.pod new file mode 100644 index 0000000..05d39fe --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get0_peer_scts.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +SSL_get0_peer_scts - get SCTs received + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s); + +=head1 DESCRIPTION + +SSL_get0_peer_scts() returns the signed certificate timestamps (SCTs) that have +been received. If this is the first time that this function has been called for +a given B<SSL> instance, it will examine the TLS extensions, OCSP response and +the peer's certificate for SCTs. Future calls will return the same SCTs. + +=head1 RESTRICTIONS + +If no Certificate Transparency validation callback has been set (using +B<SSL_CTX_set_ct_validation_callback> or B<SSL_set_ct_validation_callback>), +this function is not guaranteed to return all of the SCTs that the peer is +capable of sending. + +=head1 RETURN VALUES + +SSL_get0_peer_scts() returns a list of SCTs found, or NULL if an error occurs. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_ct_validation_callback(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_SSL_CTX.pod b/openssl-1.1.0h/doc/ssl/SSL_get_SSL_CTX.pod new file mode 100644 index 0000000..98b9bc6 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_SSL_CTX.pod @@ -0,0 +1,35 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_all_async_fds.pod b/openssl-1.1.0h/doc/ssl/SSL_get_all_async_fds.pod new file mode 100644 index 0000000..b4fa4ee --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_all_async_fds.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +SSL_waiting_for_async, +SSL_get_all_async_fds, +SSL_get_changed_async_fds +- manage asynchronous operations + +=for comment multiple includes + +=head1 SYNOPSIS + + #include <openssl/async.h> + #include <openssl/ssl.h> + + int SSL_waiting_for_async(SSL *s); + int SSL_get_all_async_fds(SSL *s, OSSL_ASYNC_FD *fd, size_t *numfds); + int SSL_get_changed_async_fds(SSL *s, OSSL_ASYNC_FD *addfd, size_t *numaddfds, + OSSL_ASYNC_FD *delfd, size_t *numdelfds); + +=head1 DESCRIPTION + +SSL_waiting_for_async() determines whether an SSL connection is currently +waiting for asynchronous operations to complete (see the SSL_MODE_ASYNC mode in +L<SSL_CTX_set_mode(3)>). + +SSL_get_all_async_fds() returns a list of file descriptor which can be used in a +call to select() or poll() to determine whether the current asynchronous +operation has completed or not. A completed operation will result in data +appearing as "read ready" on the file descriptor (no actual data should be read +from the file descriptor). This function should only be called if the SSL object +is currently waiting for asynchronous work to complete (i.e. +SSL_ERROR_WANT_ASYNC has been received - see L<SSL_get_error(3)>). Typically the +list will only contain one file descriptor. However if multiple asynchronous +capable engines are in use then more than one is possible. The number of file +descriptors returned is stored in B<*numfds> and the file descriptors themselves +are in B<*fds>. The B<fds> parameter may be NULL in which case no file +descriptors are returned but B<*numfds> is still populated. It is the callers +responsibility to ensure sufficient memory is allocated at B<*fds> so typically +this function is called twice (once with a NULL B<fds> parameter and once +without). + +SSL_get_changed_async_fds() returns a list of the asynchronous file descriptors +that have been added and a list that have been deleted since the last +SSL_ERROR_WANT_ASYNC was received (or since the SSL object was created if no +SSL_ERROR_WANT_ASYNC has been received). Similar to SSL_get_all_async_fds() it +is the callers responsibility to ensure that B<*addfd> and B<*delfd> have +sufficient memory allocated, although they may be NULL. The number of added fds +and the number of deleted fds are stored in B<*numaddfds> and B<*numdelfds> +respectively. + +=head1 RETURN VALUES + +SSL_waiting_for_async() will return 1 if the current SSL operation is waiting +for an async operation to complete and 0 otherwise. + +SSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or +0 on error. + +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)> + +=head1 HISTORY + +SSL_waiting_for_async(), SSL_get_all_async_fds() and SSL_get_changed_async_fds() +were first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_ciphers.pod b/openssl-1.1.0h/doc/ssl/SSL_get_ciphers.pod new file mode 100644 index 0000000..cc55095 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_ciphers.pod @@ -0,0 +1,84 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_client_CA_list.pod b/openssl-1.1.0h/doc/ssl/SSL_get_client_CA_list.pod new file mode 100644 index 0000000..b6092fe --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_client_CA_list.pod @@ -0,0 +1,62 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_client_random.pod b/openssl-1.1.0h/doc/ssl/SSL_get_client_random.pod new file mode 100644 index 0000000..46a2aa3 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_client_random.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key - retrieve internal TLS/SSL random values and master key + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen); + size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen); + size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, unsigned char *out, size_t outlen); + +=head1 DESCRIPTION + +SSL_get_client_random() extracts the random value sent from the client +to the server during the initial SSL/TLS handshake. It copies as many +bytes as it can of this value into the buffer provided in B<out>, +which must have at least B<outlen> bytes available. It returns the +total number of bytes that were actually copied. If B<outlen> is +zero, SSL_get_client_random() copies nothing, and returns the +total size of the client_random value. + +SSL_get_server_random() behaves the same, but extracts the random value +sent from the server to the client during the initial SSL/TLS handshake. + +SSL_SESSION_get_master_key() behaves the same, but extracts the master +secret used to guarantee the security of the SSL/TLS session. This one +can be dangerous if misused; see NOTES below. + + +=head1 NOTES + +You probably shouldn't use these functions. + +These functions expose internal values from the TLS handshake, for +use in low-level protocols. You probably should not use them, unless +you are implementing something that needs access to the internal protocol +details. + +Despite the names of SSL_get_client_random() and SSL_get_server_random(), they +ARE NOT random number generators. Instead, they return the mostly-random values that +were already generated and used in the TLS protocol. Using them +in place of RAND_bytes() would be grossly foolish. + +The security of your TLS session depends on keeping the master key secret: +do not expose it, or any information about it, to anybody. +If you need to calculate another secret value that depends on the master +secret, you should probably use SSL_export_keying_material() instead, and +forget that you ever saw these functions. + +In current versions of the TLS protocols, the length of client_random +(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for +other outlen arguments to the SSL_get_*_random() functions is provided +in case of the unlikely event that a future version or variant of TLS +uses some other length there. + +Finally, though the "client_random" and "server_random" values are called +"random", many TLS implementations will generate four bytes of those +values based on their view of the current time. + + +=head1 RETURN VALUES + +If B<outlen> is greater than 0, these functions return the number of bytes +actually copied, which will be less than or equal to B<outlen>. + +If B<outlen> is 0, these functions return the maximum number +of bytes they would copy--that is, the length of the underlying field. + +=head1 SEE ALSO + +L<ssl(3)>, +L<RAND_bytes(3)>, +L<SSL_export_keying_material(3)> + + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_current_cipher.pod b/openssl-1.1.0h/doc/ssl/SSL_get_current_cipher.pod new file mode 100644 index 0000000..87cecb0 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_current_cipher.pod @@ -0,0 +1,55 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_default_timeout.pod b/openssl-1.1.0h/doc/ssl/SSL_get_default_timeout.pod new file mode 100644 index 0000000..875d38a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_default_timeout.pod @@ -0,0 +1,50 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_error.pod b/openssl-1.1.0h/doc/ssl/SSL_get_error.pod new file mode 100644 index 0000000..47d2358 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_error.pod @@ -0,0 +1,143 @@ +=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 higher, 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 non-recoverable I/O error occurred. +The OpenSSL error queue may contain more information on the 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/openssl-1.1.0h/doc/ssl/SSL_get_extms_support.pod b/openssl-1.1.0h/doc/ssl/SSL_get_extms_support.pod new file mode 100644 index 0000000..ba4de3a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_extms_support.pod @@ -0,0 +1,40 @@ +=pod + +=head1 NAME + +SSL_get_extms_support - extended master secret support + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_extms_support(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_extms_support() indicates whether the current session used extended +master secret. + +This function is implemented as a macro. + +=head1 RETURN VALUES + +SSL_get_extms_support() returns 1 if the current session used extended +master secret, 0 if it did not and -1 if a handshake is currently in +progress i.e. it is not possible to determine if extended master secret +was used. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_fd.pod b/openssl-1.1.0h/doc/ssl/SSL_get_fd.pod new file mode 100644 index 0000000..cd5b6ec --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_fd.pod @@ -0,0 +1,53 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_peer_cert_chain.pod b/openssl-1.1.0h/doc/ssl/SSL_get_peer_cert_chain.pod new file mode 100644 index 0000000..f122124 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_peer_cert_chain.pod @@ -0,0 +1,77 @@ +=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_cert_chain() returns the peer chain as sent by the peer: it +only consists of certificates the peer has sent (in the order the peer +has sent them) it is B<not> a verified chain. + +SSL_get0_verified_chain() returns the B<verified> certificate chain +of the peer including the peer's end entity certificate. It must be called +after a session has been successfully established. If peer verification was +not successful (as indicated by SSL_get_verify_result() not returning +X509_V_OK) the chain may be incomplete or invalid. + +=head1 NOTES + +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/openssl-1.1.0h/doc/ssl/SSL_get_peer_certificate.pod b/openssl-1.1.0h/doc/ssl/SSL_get_peer_certificate.pod new file mode 100644 index 0000000..57ed272 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_peer_certificate.pod @@ -0,0 +1,64 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_psk_identity.pod b/openssl-1.1.0h/doc/ssl/SSL_get_psk_identity.pod new file mode 100644 index 0000000..d330eee --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_psk_identity.pod @@ -0,0 +1,44 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_rbio.pod b/openssl-1.1.0h/doc/ssl/SSL_get_rbio.pod new file mode 100644 index 0000000..5ac4ca2 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_rbio.pod @@ -0,0 +1,49 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_session.pod b/openssl-1.1.0h/doc/ssl/SSL_get_session.pod new file mode 100644 index 0000000..99936ad --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_session.pod @@ -0,0 +1,82 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_shared_sigalgs.pod b/openssl-1.1.0h/doc/ssl/SSL_get_shared_sigalgs.pod new file mode 100644 index 0000000..6a70e90 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_shared_sigalgs.pod @@ -0,0 +1,86 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_verify_result.pod b/openssl-1.1.0h/doc/ssl/SSL_get_verify_result.pod new file mode 100644 index 0000000..3b8b657 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_verify_result.pod @@ -0,0 +1,66 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_get_version.pod b/openssl-1.1.0h/doc/ssl/SSL_get_version.pod new file mode 100644 index 0000000..23b6497 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_version.pod @@ -0,0 +1,67 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_library_init.pod b/openssl-1.1.0h/doc/ssl/SSL_library_init.pod new file mode 100644 index 0000000..85768a1 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_library_init.pod @@ -0,0 +1,57 @@ +=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(7)>, +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/openssl-1.1.0h/doc/ssl/SSL_load_client_CA_file.pod b/openssl-1.1.0h/doc/ssl/SSL_load_client_CA_file.pod new file mode 100644 index 0000000..cc6a19c --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_load_client_CA_file.pod @@ -0,0 +1,71 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_new.pod b/openssl-1.1.0h/doc/ssl/SSL_new.pod new file mode 100644 index 0000000..a5a3ff9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_new.pod @@ -0,0 +1,61 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_pending.pod b/openssl-1.1.0h/doc/ssl/SSL_pending.pod new file mode 100644 index 0000000..f6ed565 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_pending.pod @@ -0,0 +1,68 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_read.pod b/openssl-1.1.0h/doc/ssl/SSL_read.pod new file mode 100644 index 0000000..20ccf40 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_read.pod @@ -0,0 +1,121 @@ +=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, because either the connection was closed, +an error occurred or action must be taken by the calling process. +Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason. + +Old documentation indicated a difference between 0 and -1, and that -1 was +retryable. +You should instead call SSL_get_error() to find out if it's retryable. + +=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/openssl-1.1.0h/doc/ssl/SSL_rstate_string.pod b/openssl-1.1.0h/doc/ssl/SSL_rstate_string.pod new file mode 100644 index 0000000..7775913 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_rstate_string.pod @@ -0,0 +1,68 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_session_reused.pod b/openssl-1.1.0h/doc/ssl/SSL_session_reused.pod new file mode 100644 index 0000000..eda66b2 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_session_reused.pod @@ -0,0 +1,54 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_set1_host.pod b/openssl-1.1.0h/doc/ssl/SSL_set1_host.pod new file mode 100644 index 0000000..3339a0e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set1_host.pod @@ -0,0 +1,121 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_set_bio.pod b/openssl-1.1.0h/doc/ssl/SSL_set_bio.pod new file mode 100644 index 0000000..4230940 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_bio.pod @@ -0,0 +1,108 @@ +=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 2 + +=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 consumed 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(7)>, L<bio(7)> + +=head1 HISTORY + +SSL_set0_rbio() and SSL_set0_wbio() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_set_connect_state.pod b/openssl-1.1.0h/doc/ssl/SSL_set_connect_state.pod new file mode 100644 index 0000000..9031aa7 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_connect_state.pod @@ -0,0 +1,64 @@ +=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(3).) + +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/openssl-1.1.0h/doc/ssl/SSL_set_fd.pod b/openssl-1.1.0h/doc/ssl/SSL_set_fd.pod new file mode 100644 index 0000000..e1f9988 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_fd.pod @@ -0,0 +1,63 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_set_session.pod b/openssl-1.1.0h/doc/ssl/SSL_set_session.pod new file mode 100644 index 0000000..1de533f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_session.pod @@ -0,0 +1,70 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_set_shutdown.pod b/openssl-1.1.0h/doc/ssl/SSL_set_shutdown.pod new file mode 100644 index 0000000..ecdf60c --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_shutdown.pod @@ -0,0 +1,81 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_set_verify_result.pod b/openssl-1.1.0h/doc/ssl/SSL_set_verify_result.pod new file mode 100644 index 0000000..8738d78 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_verify_result.pod @@ -0,0 +1,47 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_shutdown.pod b/openssl-1.1.0h/doc/ssl/SSL_shutdown.pod new file mode 100644 index 0000000..e8ec454 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_shutdown.pod @@ -0,0 +1,132 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_state_string.pod b/openssl-1.1.0h/doc/ssl/SSL_state_string.pod new file mode 100644 index 0000000..a2f59e8 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_state_string.pod @@ -0,0 +1,54 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_want.pod b/openssl-1.1.0h/doc/ssl/SSL_want.pod new file mode 100644 index 0000000..e179d6b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_want.pod @@ -0,0 +1,103 @@ +=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/openssl-1.1.0h/doc/ssl/SSL_write.pod b/openssl-1.1.0h/doc/ssl/SSL_write.pod new file mode 100644 index 0000000..ef3b92a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_write.pod @@ -0,0 +1,111 @@ +=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, because either the connection was +closed, an error occurred or action must be taken by the calling process. +Call SSL_get_error() with the return value B<ret> to find out the reason. + +Old documentation indicated a difference between 0 and -1, and that -1 was +retryable. +You should instead call SSL_get_error() to find out if it's retryable. + +=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/openssl-1.1.0h/doc/ssl/d2i_SSL_SESSION.pod b/openssl-1.1.0h/doc/ssl/d2i_SSL_SESSION.pod new file mode 100644 index 0000000..d6b1707 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/d2i_SSL_SESSION.pod @@ -0,0 +1,49 @@ +=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/openssl-1.1.0h/doc/ssl/ssl.pod b/openssl-1.1.0h/doc/ssl/ssl.pod new file mode 100644 index 0000000..4d91907 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/ssl.pod @@ -0,0 +1,843 @@ +=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. + +OPENSSL_VERSION_AT_LEAST(major,minor) can be +used in C<#if> statements in order to determine which version of the library is +being used. This can be used to either enable optional features at compile +time, or work around issues with a previous version. +See L<OPENSSL_VERSION_NUMBER(3)>. + +=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. + +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 int B<SSL_get_key_update_type>(SSL *s); + +=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 int B<SSL_key_update>(SSL *s, int updatetype); + +=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(7)>, +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_security_level(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_ex(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_ex(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> were 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-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |