SSL extra chain certificates doc
[openssl.git] / doc / man7 / ssl.pod
index 7b5b39e..6cc1c4b 100644 (file)
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-SSL - OpenSSL SSL/TLS library
+ssl - OpenSSL SSL/TLS library
 
 =head1 SYNOPSIS
 
@@ -14,7 +14,7 @@ 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
+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.
@@ -25,7 +25,7 @@ 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
+When the TLS/SSL handshake is performed using
 L<SSL_accept(3)> or L<SSL_connect(3)>
 respectively.
 L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> and L<SSL_write(3)> are
@@ -42,7 +42,7 @@ structures:
 
 =item B<SSL_METHOD> (SSL Method)
 
-That's a dispatch structure describing the internal B<ssl> library
+This is 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>.
 
@@ -50,12 +50,12 @@ TLSv1, ...). It's needed to create an B<SSL_CTX>.
 
 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
+on a B<SSL_CTX> basis and the actual ones used 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
+This is 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.
 
@@ -66,9 +66,9 @@ 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
+This is 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
+At run-time the application usually deals with this structure which has
 links to mostly all other structures.
 
 =back
@@ -83,7 +83,7 @@ containing the prototypes for the data structures and functions:
 
 =item B<ssl.h>
 
-That's the common header file for the SSL/TLS API.  Include it into your
+This is 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
@@ -95,13 +95,13 @@ Unused. Present for backwards compatibility only.
 
 =item B<ssl3.h>
 
-That's the sub header file dealing with the SSLv3 protocol only.
+This is 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.
+This is 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>.
 
@@ -128,10 +128,12 @@ 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.
+Must be used to support the TLSv1.3 protocol.
 
 =item const SSL_METHOD *B<TLS_server_method>(void);
 
 Constructor for the I<version-flexible> SSL_METHOD structure for servers.
+Must be used to support the TLSv1.3 protocol.
 
 =item const SSL_METHOD *B<TLSv1_2_method>(void);
 
@@ -252,6 +254,10 @@ protocol context defined in the B<SSL_CTX> structure.
 
 =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 long B<SSL_CTX_get_extra_chain_certs>(SSL_CTX *ctx, STACK_OF(X509) **sk);
+
+=item long B<SSL_CTX_get_extra_chain_certs_only>(SSL_CTX *ctx, STACK_OF(X509) **sk);
+
 =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);
@@ -397,6 +403,8 @@ Use the file path to locate trusted CA certificates.
 
 =item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, const char *file, int type);
 
+=item int B<SSL_CTX_use_cert_and_key>(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);
+
 =item X509 *B<SSL_CTX_get0_certificate>(const SSL_CTX *ctx);
 
 =item EVP_PKEY *B<SSL_CTX_get0_privatekey>(const SSL_CTX *ctx);
@@ -496,8 +504,6 @@ in multiple SSL connections, and then duplicate it prior to initiating
 each connection with the duplicated handle.
 Use of SSL_dup() avoids the need to repeat the configuration of the
 handles for each connection.
-This is used internally by L<BIO_s_accept(3)> to construct
-per-connection SSL handles after L<accept(2)>.
 
 For SSL_dup() to work, the connection MUST be in its initial state
 and MUST NOT have not yet have started the SSL handshake.
@@ -552,6 +558,8 @@ fresh handle for each connection.
 
 =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);
@@ -568,7 +576,7 @@ fresh handle for each connection.
 
 =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 char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int size);
 
 =item int B<SSL_get_shutdown>(const SSL *ssl);
 
@@ -600,6 +608,8 @@ fresh handle for each connection.
 
 =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);
@@ -704,6 +714,8 @@ Returns the current handshake state.
 
 =item int B<SSL_use_certificate_file>(SSL *ssl, const char *file, int type);
 
+=item int B<SSL_use_cert_and_key>(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);
+
 =item int B<SSL_version>(const SSL *ssl);
 
 =item int B<SSL_want>(const SSL *ssl);
@@ -736,7 +748,7 @@ See the individual manual pages for details.
 
 =head1 SEE ALSO
 
-L<openssl(1)>, L<crypto(3)>,
+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)>,
@@ -767,6 +779,7 @@ 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)>,
@@ -816,7 +829,7 @@ L<DTLSv1_listen(3)>
 
 =head1 HISTORY
 
-B<SSLv2_client_method>, B<SSLv2_server_method> and B<SSLv2_method> where removed
+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
@@ -824,7 +837,7 @@ OpenSSL 1.1.0.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+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