From 398206375688f053774ab0622a59db69fb2e2b99 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 14 Feb 2017 15:25:22 +0000 Subject: [PATCH] Add documentation for SSL_key_update() and SSL_get_key_update_type() This also adds documentation for the pre-existing and related SSL_renegotiate*() functions. Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/2609) --- doc/man3/SSL_key_update.pod | 119 ++++++++++++++++++++++++++++++++++++ doc/man7/ssl.pod | 4 ++ 2 files changed, 123 insertions(+) create mode 100644 doc/man3/SSL_key_update.pod diff --git a/doc/man3/SSL_key_update.pod b/doc/man3/SSL_key_update.pod new file mode 100644 index 0000000000..3aab0d6dc0 --- /dev/null +++ b/doc/man3/SSL_key_update.pod @@ -0,0 +1,119 @@ +=pod + +=head1 NAME + +SSL_key_update, +SSL_get_key_update_type, +SSL_renegotiate, +SSL_renegotiate_abbreviated, +SSL_renegotiate_pending +- initiate and obtain information about updating connection keys + +=head1 SYNOPSIS + + #include + + /* TLSv1.3 KeyUpdate message types */ + typedef enum { + /* -1 used so that this is an invalid value for the on-the-wire protocol */ + SSL_KEY_UPDATE_NONE = -1, + /* Values as defined for the on-the-wire protocol */ + SSL_KEY_UPDATE_NOT_REQUESTED = 0, + SSL_KEY_UPDATE_REQUESTED = 1 + } SSL_KEY_UPDATE; + + int SSL_key_update(SSL *s, SSL_KEY_UPDATE updatetype); + SSL_KEY_UPDATE SSL_get_key_update_type(SSL *s); + + int SSL_renegotiate(SSL *s); + int SSL_renegotiate_abbreviated(SSL *s); + int SSL_renegotiate_pending(SSL *s); + +=head1 DESCRIPTION + +SSL_key_update() schedules an update of the keys for the current TLS connection. +If the B parameter is set to B then +the sending keys for this connection will be updated and the peer will be +informed of the change. If the B parameter is set to +B then the sending keys for this connection will be +updated and the peer will be informed of the change along with a request for the +peer to additionally update its sending keys. It is an error if B is +set to B. + +SSL_key_update() must only be called after the initial handshake has been +completed and TLSv1.3 has been negotiated. The key update will not take place +until the next time an IO operation such as SSL_read_ex() or SSL_write_ex() +takes place on the connection. Alternatively SSL_do_handshake() can be called to +force the update to take place immediately. + +SSL_get_key_update_type() can be used to determine whether a key update +operation has been scheduled but not yet performed. The type of the pending key +update operation will be returned if there is one, or SSL_KEY_UPDATE_NONE +otherwise. + +SSL_renegotiate() and SSL_renegotiate_abbreviated() should only be called for +connections that have negotiated TLSv1.2 or less. Calling them on any other +connection will result in an error. + +When called from the client side, SSL_renegotiate() schedules a completely new +handshake over an existing SSL/TLS connection. The next time an IO operation +such as SSL_read_ex() or SSL_write_ex() takes place on the connection a check +will be performed to confirm that it is a suitable time to start a +renegotiation. If so, then it will be initiated immediately. OpenSSL will not +attempt to resume any session associated with the connection in the new +handshake. + +When called from the client side, SSL_renegotiate_abbreviated() works in the +same was as SSL_renegotiate() except that OpenSSL will attempt to resume the +session associated with the current connection in the new handshake. + +When called from the server side, SSL_renegotiate() and +SSL_renegotiate_abbreviated() behave identically. They both schedule a request +for a new handshake to be sent to the client. The next time an IO operation is +performed then the same checks as on the client side are performed and then, if +appropriate, the request is sent. The client may or may not respond with a new +handshake and it may or may not attempt to resume an existing session. If +a new handshake is started then this will be handled transparently by calling +any OpenSSL IO function. + +If an OpenSSL client receives a renegotiation request from a server then again +this will be handled transparently through calling any OpenSSL IO function. For +a TLS connection the client will attempt to resume the current session in the +new handshake. For historical reasons, DTLS clients will not attempt to resume +the session in the new handshake. + +The SSL_renegotiate_pending() function returns 1 if a renegotiation or +rengotiation request has been scheduled but not yet acted on, or 0 otherwise. + +=head1 RETURN VALUES + +SSL_key_update(), SSL_renegotiate() and SSL_renegotiate_abbreviated() return 1 +on success or 0 on error. + +SSL_get_key_update_type() returns the update type of the pending key update +operation or SSL_KEY_UPDATE_NONE if there is none. + +SSL_renegotiate_pending() returns 1 if a renegotiation or rengotiation request +has been scheduled but not yet acted on, or 0 otherwise. + +=head1 SEE ALSO + +L, L, +L, +L + +=head1 HISTORY + +The SSL_key_update() and SSL_get_key_update_type() functions were added in +OpenSSL 1.1.1. + +=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. + +=cut diff --git a/doc/man7/ssl.pod b/doc/man7/ssl.pod index 3b1b5810c6..b15ae7c3b6 100644 --- a/doc/man7/ssl.pod +++ b/doc/man7/ssl.pod @@ -552,6 +552,8 @@ fresh handle for each connection. =item void (*B(const SSL *ssl);)() +=item SSL_KEY_UPDATE B(SSL *s); + =item STACK *B(const SSL *ssl); =item X509 *B(const SSL *ssl); @@ -600,6 +602,8 @@ fresh handle for each connection. =item int B(SSL *ssl); +=item int B(SSL *s, SSL_KEY_UPDATE updatetype); + =item STACK *B(const char *file); =item SSL *B(SSL_CTX *ctx);