| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | SSL_key_update,
|
|---|
| 6 | SSL_get_key_update_type,
|
|---|
| 7 | SSL_renegotiate,
|
|---|
| 8 | SSL_renegotiate_abbreviated,
|
|---|
| 9 | SSL_renegotiate_pending
|
|---|
| 10 | - initiate and obtain information about updating connection keys
|
|---|
| 11 |
|
|---|
| 12 | =head1 SYNOPSIS
|
|---|
| 13 |
|
|---|
| 14 | #include <openssl/ssl.h>
|
|---|
| 15 |
|
|---|
| 16 | int SSL_key_update(SSL *s, int updatetype);
|
|---|
| 17 | int SSL_get_key_update_type(const SSL *s);
|
|---|
| 18 |
|
|---|
| 19 | int SSL_renegotiate(SSL *s);
|
|---|
| 20 | int SSL_renegotiate_abbreviated(SSL *s);
|
|---|
| 21 | int SSL_renegotiate_pending(const SSL *s);
|
|---|
| 22 |
|
|---|
| 23 | =head1 DESCRIPTION
|
|---|
| 24 |
|
|---|
| 25 | SSL_key_update() schedules an update of the keys for the current TLS connection.
|
|---|
| 26 | If the B<updatetype> parameter is set to B<SSL_KEY_UPDATE_NOT_REQUESTED> then
|
|---|
| 27 | the sending keys for this connection will be updated and the peer will be
|
|---|
| 28 | informed of the change. If the B<updatetype> parameter is set to
|
|---|
| 29 | B<SSL_KEY_UPDATE_REQUESTED> then the sending keys for this connection will be
|
|---|
| 30 | updated and the peer will be informed of the change along with a request for the
|
|---|
| 31 | peer to additionally update its sending keys. It is an error if B<updatetype> is
|
|---|
| 32 | set to B<SSL_KEY_UPDATE_NONE>.
|
|---|
| 33 |
|
|---|
| 34 | SSL_key_update() must only be called after the initial handshake has been
|
|---|
| 35 | completed and TLSv1.3 has been negotiated. The key update will not take place
|
|---|
| 36 | until the next time an IO operation such as SSL_read_ex() or SSL_write_ex()
|
|---|
| 37 | takes place on the connection. Alternatively SSL_do_handshake() can be called to
|
|---|
| 38 | force the update to take place immediately.
|
|---|
| 39 |
|
|---|
| 40 | SSL_get_key_update_type() can be used to determine whether a key update
|
|---|
| 41 | operation has been scheduled but not yet performed. The type of the pending key
|
|---|
| 42 | update operation will be returned if there is one, or SSL_KEY_UPDATE_NONE
|
|---|
| 43 | otherwise.
|
|---|
| 44 |
|
|---|
| 45 | SSL_renegotiate() and SSL_renegotiate_abbreviated() should only be called for
|
|---|
| 46 | connections that have negotiated TLSv1.2 or less. Calling them on any other
|
|---|
| 47 | connection will result in an error.
|
|---|
| 48 |
|
|---|
| 49 | When called from the client side, SSL_renegotiate() schedules a completely new
|
|---|
| 50 | handshake over an existing SSL/TLS connection. The next time an IO operation
|
|---|
| 51 | such as SSL_read_ex() or SSL_write_ex() takes place on the connection a check
|
|---|
| 52 | will be performed to confirm that it is a suitable time to start a
|
|---|
| 53 | renegotiation. If so, then it will be initiated immediately. OpenSSL will not
|
|---|
| 54 | attempt to resume any session associated with the connection in the new
|
|---|
| 55 | handshake.
|
|---|
| 56 |
|
|---|
| 57 | When called from the client side, SSL_renegotiate_abbreviated() works in the
|
|---|
| 58 | same was as SSL_renegotiate() except that OpenSSL will attempt to resume the
|
|---|
| 59 | session associated with the current connection in the new handshake.
|
|---|
| 60 |
|
|---|
| 61 | When called from the server side, SSL_renegotiate() and
|
|---|
| 62 | SSL_renegotiate_abbreviated() behave identically. They both schedule a request
|
|---|
| 63 | for a new handshake to be sent to the client. The next time an IO operation is
|
|---|
| 64 | performed then the same checks as on the client side are performed and then, if
|
|---|
| 65 | appropriate, the request is sent. The client may or may not respond with a new
|
|---|
| 66 | handshake and it may or may not attempt to resume an existing session. If
|
|---|
| 67 | a new handshake is started then this will be handled transparently by calling
|
|---|
| 68 | any OpenSSL IO function.
|
|---|
| 69 |
|
|---|
| 70 | If an OpenSSL client receives a renegotiation request from a server then again
|
|---|
| 71 | this will be handled transparently through calling any OpenSSL IO function. For
|
|---|
| 72 | a TLS connection the client will attempt to resume the current session in the
|
|---|
| 73 | new handshake. For historical reasons, DTLS clients will not attempt to resume
|
|---|
| 74 | the session in the new handshake.
|
|---|
| 75 |
|
|---|
| 76 | The SSL_renegotiate_pending() function returns 1 if a renegotiation or
|
|---|
| 77 | renegotiation request has been scheduled but not yet acted on, or 0 otherwise.
|
|---|
| 78 |
|
|---|
| 79 | =head1 RETURN VALUES
|
|---|
| 80 |
|
|---|
| 81 | SSL_key_update(), SSL_renegotiate() and SSL_renegotiate_abbreviated() return 1
|
|---|
| 82 | on success or 0 on error.
|
|---|
| 83 |
|
|---|
| 84 | SSL_get_key_update_type() returns the update type of the pending key update
|
|---|
| 85 | operation or SSL_KEY_UPDATE_NONE if there is none.
|
|---|
| 86 |
|
|---|
| 87 | SSL_renegotiate_pending() returns 1 if a renegotiation or renegotiation request
|
|---|
| 88 | has been scheduled but not yet acted on, or 0 otherwise.
|
|---|
| 89 |
|
|---|
| 90 | =head1 SEE ALSO
|
|---|
| 91 |
|
|---|
| 92 | L<ssl(7)>, L<SSL_read_ex(3)>,
|
|---|
| 93 | L<SSL_write_ex(3)>,
|
|---|
| 94 | L<SSL_do_handshake(3)>
|
|---|
| 95 |
|
|---|
| 96 | =head1 HISTORY
|
|---|
| 97 |
|
|---|
| 98 | The SSL_key_update() and SSL_get_key_update_type() functions were added in
|
|---|
| 99 | OpenSSL 1.1.1.
|
|---|
| 100 |
|
|---|
| 101 | =head1 COPYRIGHT
|
|---|
| 102 |
|
|---|
| 103 | Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 104 |
|
|---|
| 105 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 106 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 107 | in the file LICENSE in the source distribution or at
|
|---|
| 108 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 109 |
|
|---|
| 110 | =cut
|
|---|
