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