]>
Commit | Line | Data |
---|---|---|
ddac1974 NL |
1 | =pod |
2 | ||
ddac1974 NL |
3 | =head1 NAME |
4 | ||
93a048a1 MC |
5 | SSL_psk_client_cb_func, |
6 | SSL_psk_use_session_cb_func, | |
7 | SSL_CTX_set_psk_client_callback, | |
8 | SSL_set_psk_client_callback, | |
9 | SSL_CTX_set_psk_use_session_callback, | |
10 | SSL_set_psk_use_session_callback | |
11 | - set PSK client callback | |
ddac1974 NL |
12 | |
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/ssl.h> | |
16 | ||
801d9fbd MC |
17 | typedef int (*SSL_psk_use_session_cb_func)(SSL *ssl, const EVP_MD *md, |
18 | const unsigned char **id, | |
19 | size_t *idlen, | |
20 | SSL_SESSION **sess); | |
21 | ||
ddac1974 | 22 | |
801d9fbd MC |
23 | void SSL_CTX_set_psk_use_session_callback(SSL_CTX *ctx, |
24 | SSL_psk_use_session_cb_func cb); | |
93a048a1 | 25 | void SSL_set_psk_use_session_callback(SSL *s, SSL_psk_use_session_cb_func cb); |
ddac1974 | 26 | |
ddac1974 | 27 | |
4a192c77 MC |
28 | typedef unsigned int (*SSL_psk_client_cb_func)(SSL *ssl, |
29 | const char *hint, | |
30 | char *identity, | |
31 | unsigned int max_identity_len, | |
32 | unsigned char *psk, | |
33 | unsigned int max_psk_len); | |
93a048a1 | 34 | |
4a192c77 MC |
35 | void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, SSL_psk_client_cb_func cb); |
36 | void SSL_set_psk_client_callback(SSL *ssl, SSL_psk_client_cb_func cb); | |
ddac1974 | 37 | |
ddac1974 | 38 | |
4a192c77 | 39 | =head1 DESCRIPTION |
ddac1974 | 40 | |
4a192c77 MC |
41 | A client application wishing to use TLSv1.3 PSKs should use either |
42 | SSL_CTX_set_psk_use_session_callback() or SSL_set_psk_use_session_callback() as | |
43 | appropriate. These functions cannot be used for TLSv1.2 and below PSKs. | |
93a048a1 | 44 | |
72257204 | 45 | The callback function is given a pointer to the SSL connection in B<ssl>. |
93a048a1 MC |
46 | |
47 | The first time the callback is called for a connection the B<md> parameter is | |
48 | NULL. In some circumstances the callback will be called a second time. In that | |
49 | case the server will have specified a ciphersuite to use already and the PSK | |
50 | must be compatible with the digest for that ciphersuite. The digest will be | |
51 | given in B<md>. The PSK returned by the callback is allowed to be different | |
52 | between the first and second time it is called. | |
53 | ||
54 | On successful completion the callback must store a pointer to an identifier for | |
55 | the PSK in B<*id>. The identifier length in bytes should be stored in B<*idlen>. | |
56 | The memory pointed to by B<*id> remains owned by the application and should | |
57 | be freed by it as required at any point after the handshake is complete. | |
58 | ||
72257204 | 59 | Additionally the callback should store a pointer to an SSL_SESSION object in |
93a048a1 MC |
60 | B<*sess>. This is used as the basis for the PSK, and should, at a minimum, have |
61 | the following fields set: | |
62 | ||
63 | =over 4 | |
64 | ||
65 | =item The master key | |
66 | ||
67 | This can be set via a call to L<SSL_SESSION_set1_master_key(3)>. | |
68 | ||
69 | =item A ciphersuite | |
70 | ||
71 | Only the handshake digest associated with the ciphersuite is relevant for the | |
72 | PSK (the server may go on to negotiate any ciphersuite which is compatible with | |
72257204 MC |
73 | the digest). The application can use any TLSv1.3 ciphersuite. If B<md> is |
74 | not NULL the handshake digest for the ciphersuite should be the same. | |
93a048a1 MC |
75 | The ciphersuite can be set via a call to <SSL_SESSION_set_cipher(3)>. The |
76 | handshake digest of an SSL_CIPHER object can be checked using | |
77 | <SSL_CIPHER_get_handshake_digest(3)>. | |
78 | ||
79 | =item The protocol version | |
80 | ||
72257204 MC |
81 | This can be set via a call to L<SSL_SESSION_set_protocol_version(3)> and should |
82 | be TLS1_3_VERSION. | |
93a048a1 MC |
83 | |
84 | =back | |
85 | ||
e17e1df7 MC |
86 | Additionally the maximum early data value should be set via a call to |
87 | L<SSL_SESSION_set_max_early_data(3)> if the PSK will be used for sending early | |
88 | data. | |
89 | ||
93a048a1 MC |
90 | Alternatively an SSL_SESSION created from a previous non-PSK handshake may also |
91 | be used as the basis for a PSK. | |
92 | ||
93 | Ownership of the SSL_SESSION object is passed to the OpenSSL library and so it | |
94 | should not be freed by the application. | |
95 | ||
96 | It is also possible for the callback to succeed but not supply a PSK. In this | |
97 | case no PSK will be sent to the server but the handshake will continue. To do | |
8ead6158 | 98 | this the callback should return successfully and ensure that B<*sess> is |
93a048a1 MC |
99 | NULL. The contents of B<*id> and B<*idlen> will be ignored. |
100 | ||
4a192c77 MC |
101 | A client application wishing to use PSK ciphersuites for TLSv1.2 and below must |
102 | provide a different callback function. This function will be called when the | |
103 | client is sending the ClientKeyExchange message to the server. | |
104 | ||
105 | The purpose of the callback function is to select the PSK identity and | |
106 | the pre-shared key to use during the connection setup phase. | |
107 | ||
108 | The callback is set using functions SSL_CTX_set_psk_client_callback() | |
109 | or SSL_set_psk_client_callback(). The callback function is given the | |
110 | connection in parameter B<ssl>, a B<NULL>-terminated PSK identity hint | |
111 | sent by the server in parameter B<hint>, a buffer B<identity> of | |
112 | length B<max_identity_len> bytes where the resulting | |
113 | B<NUL>-terminated identity is to be stored, and a buffer B<psk> of | |
114 | length B<max_psk_len> bytes where the resulting pre-shared key is to | |
115 | be stored. | |
116 | ||
117 | The callback for use in TLSv1.2 will also work in TLSv1.3 although it is | |
118 | recommended to use SSL_CTX_set_psk_use_session_callback() | |
119 | or SSL_set_psk_use_session_callback() for this purpose instead. If TLSv1.3 has | |
120 | been negotiated then OpenSSL will first check to see if a callback has been set | |
121 | via SSL_CTX_set_psk_use_session_callback() or SSL_set_psk_use_session_callback() | |
122 | and it will use that in preference. If no such callback is present then it will | |
123 | check to see if a callback has been set via SSL_CTX_set_psk_client_callback() or | |
124 | SSL_set_psk_client_callback() and use that. In this case the B<hint> value will | |
125 | always be NULL and the handshake digest will default to SHA-256 for any returned | |
e0bcb4f9 | 126 | PSK. TLSv1.3 early data exchanges are possible in PSK connections only with the |
127 | B<SSL_psk_use_session_cb_func> callback, and are not possible with the | |
128 | B<SSL_psk_client_cb_func> callback. | |
4a192c77 | 129 | |
ddac1974 NL |
130 | =head1 NOTES |
131 | ||
132 | Note that parameter B<hint> given to the callback may be B<NULL>. | |
133 | ||
93a048a1 MC |
134 | A connection established via a TLSv1.3 PSK will appear as if session resumption |
135 | has occurred so that L<SSL_session_reused(3)> will return true. | |
136 | ||
354e0107 | 137 | There are no known security issues with sharing the same PSK between TLSv1.2 (or |
8c1cbc72 | 138 | below) and TLSv1.3. However, the RFC has this note of caution: |
354e0107 MC |
139 | |
140 | "While there is no known way in which the same PSK might produce related output | |
141 | in both versions, only limited analysis has been done. Implementations can | |
142 | ensure safety from cross-protocol related output by not reusing PSKs between | |
143 | TLS 1.3 and TLS 1.2." | |
144 | ||
ddac1974 NL |
145 | =head1 RETURN VALUES |
146 | ||
72257204 | 147 | Return values from the B<SSL_psk_client_cb_func> callback are interpreted as |
93a048a1 | 148 | follows: |
ddac1974 NL |
149 | |
150 | On success (callback found a PSK identity and a pre-shared key to use) | |
151 | the length (> 0) of B<psk> in bytes is returned. | |
152 | ||
93a048a1 | 153 | Otherwise or on errors the callback should return 0. In this case |
ddac1974 NL |
154 | the connection setup fails. |
155 | ||
93a048a1 MC |
156 | The SSL_psk_use_session_cb_func callback should return 1 on success or 0 on |
157 | failure. In the event of failure the connection setup fails. | |
158 | ||
e105ae84 MC |
159 | =head1 SEE ALSO |
160 | ||
98ca37e4 | 161 | L<ssl(7)>, |
e105ae84 MC |
162 | L<SSL_CTX_set_psk_find_session_callback(3)>, |
163 | L<SSL_set_psk_find_session_callback(3)> | |
164 | ||
165 | =head1 HISTORY | |
166 | ||
167 | SSL_CTX_set_psk_use_session_callback() and SSL_set_psk_use_session_callback() | |
168 | were added in OpenSSL 1.1.1. | |
169 | ||
e2f92610 RS |
170 | =head1 COPYRIGHT |
171 | ||
00c405b3 | 172 | Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 173 | |
4746f25a | 174 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
175 | this file except in compliance with the License. You can obtain a copy |
176 | in the file LICENSE in the source distribution or at | |
177 | L<https://www.openssl.org/source/license.html>. | |
178 | ||
e2f92610 | 179 | =cut |