Add a note about aborts encountered while sending early_data

[openssl.git] / doc / man3 / SSL_CTX_set_verify.pod

diff --git a/doc/man3/SSL_CTX_set_verify.pod b/doc/man3/SSL_CTX_set_verify.pod
index 53615b528144a0ada49b1896cc843020068037eb..716554793311efb9fd92b0be8ca5bcb0614d82a3 100644 (file)
--- a/doc/man3/SSL_CTX_set_verify.pod
+++ b/doc/man3/SSL_CTX_set_verify.pod
@@ -5,22 +5,26 @@
 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_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
+SSL_verify_cb,
+SSL_verify_client_post_handshake,
+SSL_force_post_handshake_auth

 - set peer certificate verification parameters
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
 - set peer certificate verification parameters
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 

+ typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx);
+

  void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback);
  void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback);

- void SSL_set_verify(SSL *s, int mode, SSL_verify_cb verify_callback);
+ void SSL_set_verify(SSL *ssl, 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);
  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);
+ void SSL_set_verify_depth(SSL *ssl, int depth);

 
 

-
- typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx);
+ int SSL_verify_client_post_handshake(SSL *ssl);
+ void SSL_force_post_handshake_auth(SSL *ssl);

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -44,6 +48,16 @@ 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>.
 
 SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
 verification that shall be allowed for B<ssl>.
 

+SSL_force_post_handshake_auth() forces the Post-Handshake Authentication
+extension to be added to the ClientHello regardless of certificate configuration
+at the time of the initial handshake, such that post-handshake authentication
+can be requested by the server. A certificate callback will need to be set via
+SSL_CTX_set_client_cert_cb() if no certificate is provided at initialization.
+
+SSL_verify_client_post_handshake() causes a CertificateRequest message to be
+sent by a server on the given B<ssl> connection. The SSL_VERIFY_PEER flag must
+be set; the SSL_VERIFY_POST_HANDSHAKE flag is optional.
+

 =head1 NOTES
 
 The verification of certificates can be controlled by a set of logically
 =head1 NOTES
 
 The verification of certificates can be controlled by a set of logically


@@ -70,7 +84,8 @@ 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
 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.
+SSL_VERIFY_FAIL_IF_NO_PEER_CERT, SSL_VERIFY_CLIENT_ONCE and
+SSL_VERIFY_POST_HANDSHAKE flags.

 
 B<Client mode:> the server certificate is verified. If the verification process
 fails, the TLS/SSL handshake is
 
 B<Client mode:> the server certificate is verified. If the verification process
 fails, the TLS/SSL handshake is


@@ -88,9 +103,22 @@ B<Client mode:> ignored
 
 =item SSL_VERIFY_CLIENT_ONCE
 
 
 =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<Server mode:> only request a client certificate once during the
+connection. Do not ask for a client certificate again during
+renegotiation or post-authentication if a certificate was requested
+during the initial handshake. This flag must be used together with
+SSL_VERIFY_PEER.
+
+B<Client mode:> ignored
+
+=item SSL_VERIFY_POST_HANDSHAKE
+
+B<Server mode:> the server will not send a client certificate request
+during the initial handshake, but will send the request via
+SSL_verify_client_post_handshake(). This allows the SSL_CTX or SSL
+to be configured for post-handshake peer verification before the
+handshake occurs. This flag must be used together with
+SSL_VERIFY_PEER. TLSv1.3 only; no effect on pre-TLSv1.3 connections.

 
 B<Client mode:> ignored
 
 
 B<Client mode:> ignored
 


@@ -155,6 +183,20 @@ 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.
 
 failure will lead to a termination of the TLS/SSL handshake with an
 alert message, if SSL_VERIFY_PEER is set.
 

+After calling SSL_force_post_handshake_auth(), the client will need to add a
+certificate or certificate callback to its configuration before it can
+successfully authenticate. This must be called before SSL_connect().
+
+SSL_verify_client_post_handshake() requires that verify flags have been
+previously set, and that a client sent the post-handshake authentication
+extension. When the client returns a certificate the verify callback will be
+invoked. A write operation must take place for the Certificate Request to be
+sent to the client, this can be done with SSL_do_handshake() or SSL_write_ex().
+Only one certificate request may be outstanding at any time.
+
+When post-handshake authentication occurs, a refreshed NewSessionTicket
+message is sent to the client.
+

 =head1 BUGS
 
 In client mode, it is not checked whether the SSL_VERIFY_PEER flag
 =head1 BUGS
 
 In client mode, it is not checked whether the SSL_VERIFY_PEER flag


@@ -166,6 +208,10 @@ required.
 
 The SSL*_set_verify*() functions do not provide diagnostic information.
 
 
 The SSL*_set_verify*() functions do not provide diagnostic information.
 

+The SSL_verify_client_post_handshake() function returns 1 if the request
+succeeded, and 0 if the request failed. The error stack can be examined
+to determine the failure reason.
+

 =head1 EXAMPLES
 
 The following code sequence realizes an example B<verify_callback> function
 =head1 EXAMPLES
 
 The following code sequence realizes an example B<verify_callback> function


@@ -289,11 +335,17 @@ L<SSL_CTX_load_verify_locations(3)>,
 L<SSL_get_peer_certificate(3)>,
 L<SSL_CTX_set_cert_verify_callback(3)>,
 L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
 L<SSL_get_peer_certificate(3)>,
 L<SSL_CTX_set_cert_verify_callback(3)>,
 L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,

+L<SSL_CTX_set_client_cert_cb(3)>,

 L<CRYPTO_get_ex_new_index(3)>
 
 L<CRYPTO_get_ex_new_index(3)>
 

+=head1 HISTORY
+
+The SSL_VERIFY_POST_HANDSHAKE option, and the SSL_verify_client_post_handshake()
+and SSL_force_post_handshake_auth() functions were added in OpenSSL 1.1.1.
+

 =head1 COPYRIGHT
 
 =head1 COPYRIGHT
 

-Copyright 2000-2017 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
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy