]>
Commit | Line | Data |
---|---|---|
39820637 MC |
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 | ||
4fbfe86a | 16 | int SSL_key_update(SSL *s, int updatetype); |
3499327b | 17 | int SSL_get_key_update_type(const SSL *s); |
39820637 MC |
18 | |
19 | int SSL_renegotiate(SSL *s); | |
20 | int SSL_renegotiate_abbreviated(SSL *s); | |
3499327b | 21 | int SSL_renegotiate_pending(const SSL *s); |
39820637 MC |
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 | |
27b138e9 | 77 | renegotiation request has been scheduled but not yet acted on, or 0 otherwise. |
39820637 MC |
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 | ||
27b138e9 | 87 | SSL_renegotiate_pending() returns 1 if a renegotiation or renegotiation request |
39820637 MC |
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 The OpenSSL Project Authors. All Rights Reserved. | |
104 | ||
4746f25a | 105 | Licensed under the Apache License 2.0 (the "License"). You may not use |
39820637 MC |
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 |