]>
Commit | Line | Data |
---|---|---|
ddac1974 NL |
1 | =pod |
2 | ||
ddac1974 NL |
3 | =head1 NAME |
4 | ||
93a048a1 MC |
5 | SSL_psk_server_cb_func, |
6 | SSL_psk_find_session_cb_func, | |
7 | SSL_CTX_use_psk_identity_hint, | |
8 | SSL_use_psk_identity_hint, | |
9 | SSL_CTX_set_psk_server_callback, | |
10 | SSL_set_psk_server_callback, | |
11 | SSL_CTX_set_psk_find_session_callback, | |
12 | SSL_set_psk_find_session_callback | |
13 | - set PSK identity hint to use | |
ddac1974 | 14 | |
ddac1974 NL |
15 | =head1 SYNOPSIS |
16 | ||
17 | #include <openssl/ssl.h> | |
18 | ||
93a048a1 MC |
19 | typedef int (*SSL_psk_find_session_cb_func)(SSL *ssl, |
20 | const unsigned char *identity, | |
21 | size_t identity_len, | |
22 | SSL_SESSION **sess); | |
23 | ||
4a192c77 MC |
24 | |
25 | void SSL_CTX_set_psk_find_session_callback(SSL_CTX *ctx, | |
26 | SSL_psk_find_session_cb_func cb); | |
27 | void SSL_set_psk_find_session_callback(SSL *s, SSL_psk_find_session_cb_func cb); | |
28 | ||
29 | typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl, | |
30 | const char *identity, | |
31 | unsigned char *psk, | |
32 | unsigned int max_psk_len); | |
33 | ||
ddac1974 NL |
34 | int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); |
35 | int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); | |
36 | ||
93a048a1 MC |
37 | void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, SSL_psk_server_cb_func cb); |
38 | void SSL_set_psk_server_callback(SSL *ssl, SSL_psk_server_cb_func cb); | |
ddac1974 | 39 | |
ddac1974 NL |
40 | =head1 DESCRIPTION |
41 | ||
3a9080d6 MC |
42 | A server application wishing to use TLSv1.3 PSKs should set a callback |
43 | using either SSL_CTX_set_psk_find_session_callback() or | |
44 | SSL_set_psk_find_session_callback() as appropriate. | |
4a192c77 MC |
45 | |
46 | The callback function is given a pointer to the SSL connection in B<ssl> and | |
47 | an identity in B<identity> of length B<identity_len>. The callback function | |
48 | should identify an SSL_SESSION object that provides the PSK details and store it | |
49 | in B<*sess>. The SSL_SESSION object should, as a minimum, set the master key, | |
50 | the ciphersuite and the protocol version. See | |
51 | L<SSL_CTX_set_psk_use_session_callback(3)> for details. | |
52 | ||
53 | It is also possible for the callback to succeed but not supply a PSK. In this | |
54 | case no PSK will be used but the handshake will continue. To do this the | |
55 | callback should return successfully and ensure that B<*sess> is | |
56 | NULL. | |
93a048a1 MC |
57 | |
58 | Identity hints are not relevant for TLSv1.3. A server application wishing to use | |
59 | PSK ciphersuites for TLSv1.2 and below may call SSL_CTX_use_psk_identity_hint() | |
72257204 MC |
60 | to set the given B<NUL>-terminated PSK identity hint B<hint> for SSL context |
61 | object B<ctx>. SSL_use_psk_identity_hint() sets the given B<NUL>-terminated PSK | |
93a048a1 MC |
62 | identity hint B<hint> for the SSL connection object B<ssl>. If B<hint> is |
63 | B<NULL> the current hint from B<ctx> or B<ssl> is deleted. | |
ddac1974 | 64 | |
93a048a1 MC |
65 | In the case where PSK identity hint is B<NULL>, the server does not send the |
66 | ServerKeyExchange message to the client. | |
ddac1974 | 67 | |
4a192c77 MC |
68 | A server application wishing to use PSKs for TLSv1.2 and below must provide a |
69 | callback function which is called when the server receives the | |
70 | ClientKeyExchange message from the client. The purpose of the callback function | |
71 | is to validate the received PSK identity and to fetch the pre-shared key used | |
72 | during the connection setup phase. The callback is set using the functions | |
93a048a1 | 73 | SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback(). The callback |
72257204 | 74 | function is given the connection in parameter B<ssl>, B<NUL>-terminated PSK |
93a048a1 MC |
75 | identity sent by the client in parameter B<identity>, and a buffer B<psk> of |
76 | length B<max_psk_len> bytes where the pre-shared key is to be stored. | |
77 | ||
4a192c77 MC |
78 | The callback for use in TLSv1.2 will also work in TLSv1.3 although it is |
79 | recommended to use SSL_CTX_set_psk_find_session_callback() | |
80 | or SSL_set_psk_find_session_callback() for this purpose instead. If TLSv1.3 has | |
81 | been negotiated then OpenSSL will first check to see if a callback has been set | |
82 | via SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback() | |
83 | and it will use that in preference. If no such callback is present then it will | |
84 | check to see if a callback has been set via SSL_CTX_set_psk_server_callback() or | |
85 | SSL_set_psk_server_callback() and use that. In this case the handshake digest | |
86 | will default to SHA-256 for any returned PSK. | |
ddac1974 | 87 | |
8ead6158 MC |
88 | =head1 NOTES |
89 | ||
90 | A connection established via a TLSv1.3 PSK will appear as if session resumption | |
91 | has occurred so that L<SSL_session_reused(3)> will return true. | |
92 | ||
ddac1974 NL |
93 | =head1 RETURN VALUES |
94 | ||
72257204 | 95 | B<SSL_CTX_use_psk_identity_hint()> and B<SSL_use_psk_identity_hint()> return |
ddac1974 NL |
96 | 1 on success, 0 otherwise. |
97 | ||
93a048a1 MC |
98 | Return values from the TLSv1.2 and below server callback are interpreted as |
99 | follows: | |
ddac1974 | 100 | |
5cc27077 NA |
101 | =over 4 |
102 | ||
fe757304 SS |
103 | =item Z<>0 |
104 | ||
105 | PSK identity was not found. An "unknown_psk_identity" alert message | |
106 | will be sent and the connection setup fails. | |
107 | ||
108 | =item E<gt>0 | |
ddac1974 NL |
109 | |
110 | PSK identity was found and the server callback has provided the PSK | |
111 | successfully in parameter B<psk>. Return value is the length of | |
112 | B<psk> in bytes. It is an error to return a value greater than | |
113 | B<max_psk_len>. | |
114 | ||
115 | If the PSK identity was not found but the callback instructs the | |
116 | protocol to continue anyway, the callback must provide some random | |
117 | data to B<psk> and return the length of the random data, so the | |
118 | connection will fail with decryption_error before it will be finished | |
119 | completely. | |
120 | ||
5cc27077 NA |
121 | =back |
122 | ||
72257204 | 123 | The B<SSL_psk_find_session_cb_func> callback should return 1 on success or 0 on |
93a048a1 MC |
124 | failure. In the event of failure the connection setup fails. |
125 | ||
354e0107 MC |
126 | =head1 NOTES |
127 | ||
128 | There are no known security issues with sharing the same PSK between TLSv1.2 (or | |
129 | below) and TLSv1.3. However the RFC has this note of caution: | |
130 | ||
131 | "While there is no known way in which the same PSK might produce related output | |
132 | in both versions, only limited analysis has been done. Implementations can | |
133 | ensure safety from cross-protocol related output by not reusing PSKs between | |
134 | TLS 1.3 and TLS 1.2." | |
135 | ||
e105ae84 MC |
136 | =head1 SEE ALSO |
137 | ||
138 | L<SSL_CTX_set_psk_use_session_callback(3)>, | |
139 | L<SSL_set_psk_use_session_callback(3)> | |
140 | ||
141 | =head1 HISTORY | |
142 | ||
143 | SSL_CTX_set_psk_find_session_callback() and SSL_set_psk_find_session_callback() | |
144 | were added in OpenSSL 1.1.1. | |
145 | ||
e2f92610 RS |
146 | =head1 COPYRIGHT |
147 | ||
b0edda11 | 148 | Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
149 | |
150 | Licensed under the OpenSSL license (the "License"). You may not use | |
151 | this file except in compliance with the License. You can obtain a copy | |
152 | in the file LICENSE in the source distribution or at | |
153 | L<https://www.openssl.org/source/license.html>. | |
154 | ||
e2f92610 | 155 | =cut |