]>
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 unsigned int (*SSL_psk_server_cb_func)(SSL *ssl, |
20 | const char *identity, | |
21 | unsigned char *psk, | |
22 | unsigned int max_psk_len); | |
23 | ||
24 | typedef int (*SSL_psk_find_session_cb_func)(SSL *ssl, | |
25 | const unsigned char *identity, | |
26 | size_t identity_len, | |
27 | SSL_SESSION **sess); | |
28 | ||
ddac1974 NL |
29 | int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); |
30 | int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); | |
31 | ||
93a048a1 MC |
32 | void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, SSL_psk_server_cb_func cb); |
33 | void SSL_set_psk_server_callback(SSL *ssl, SSL_psk_server_cb_func cb); | |
ddac1974 | 34 | |
93a048a1 MC |
35 | void SSL_CTX_set_psk_find_session_callback(SSL_CTX *ctx, |
36 | SSL_psk_find_session_cb_func cb); | |
37 | void SSL_set_psk_find_session_callback(SSL *s, SSL_psk_find_session_cb_func cb); | |
ddac1974 NL |
38 | |
39 | =head1 DESCRIPTION | |
40 | ||
93a048a1 MC |
41 | TLSv1.3 Pre-Shared Keys (PSKs) and PSKs for TLSv1.2 and below are not |
42 | compatible. | |
43 | ||
44 | Identity hints are not relevant for TLSv1.3. A server application wishing to use | |
45 | PSK ciphersuites for TLSv1.2 and below may call SSL_CTX_use_psk_identity_hint() | |
72257204 MC |
46 | to set the given B<NUL>-terminated PSK identity hint B<hint> for SSL context |
47 | object B<ctx>. SSL_use_psk_identity_hint() sets the given B<NUL>-terminated PSK | |
93a048a1 MC |
48 | identity hint B<hint> for the SSL connection object B<ssl>. If B<hint> is |
49 | B<NULL> the current hint from B<ctx> or B<ssl> is deleted. | |
ddac1974 | 50 | |
93a048a1 MC |
51 | In the case where PSK identity hint is B<NULL>, the server does not send the |
52 | ServerKeyExchange message to the client. | |
ddac1974 | 53 | |
93a048a1 MC |
54 | A server application for TLSv1.2 and below must provide a callback function |
55 | which is called when the server receives the ClientKeyExchange message from the | |
ddac1974 NL |
56 | client. The purpose of the callback function is to validate the |
57 | received PSK identity and to fetch the pre-shared key used during the | |
93a048a1 MC |
58 | connection setup phase. The callback is set using the functions |
59 | SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback(). The callback | |
72257204 | 60 | function is given the connection in parameter B<ssl>, B<NUL>-terminated PSK |
93a048a1 MC |
61 | identity sent by the client in parameter B<identity>, and a buffer B<psk> of |
62 | length B<max_psk_len> bytes where the pre-shared key is to be stored. | |
63 | ||
64 | A client application wishing to use TLSv1.3 PSKs must set a different callback | |
65 | using either SSL_CTX_set_psk_use_session_callback() or | |
66 | SSL_set_psk_use_session_callback() as appropriate. | |
67 | ||
72257204 | 68 | The callback function is given a pointer to the SSL connection in B<ssl> and |
93a048a1 MC |
69 | an identity in B<identity> of length B<identity_len>. The callback function |
70 | should identify an SSL_SESSION object that provides the PSK details and store it | |
71 | in B<*sess>. The SSL_SESSION object should, as a minimum, set the master key, | |
72 | the ciphersuite and the protocol version. See | |
73 | L<SSL_CTX_set_psk_use_session_callback(3)> for details. | |
74 | ||
75 | It is also possible for the callback to succeed but not supply a PSK. In this | |
76 | case no PSK will be used but the handshake will continue. To do this the | |
77 | callback should return successfully and ensure that B<*sess> is | |
78 | NULL. | |
ddac1974 | 79 | |
8ead6158 MC |
80 | =head1 NOTES |
81 | ||
82 | A connection established via a TLSv1.3 PSK will appear as if session resumption | |
83 | has occurred so that L<SSL_session_reused(3)> will return true. | |
84 | ||
ddac1974 NL |
85 | =head1 RETURN VALUES |
86 | ||
72257204 | 87 | B<SSL_CTX_use_psk_identity_hint()> and B<SSL_use_psk_identity_hint()> return |
ddac1974 NL |
88 | 1 on success, 0 otherwise. |
89 | ||
93a048a1 MC |
90 | Return values from the TLSv1.2 and below server callback are interpreted as |
91 | follows: | |
ddac1974 | 92 | |
5cc27077 NA |
93 | =over 4 |
94 | ||
fe757304 SS |
95 | =item Z<>0 |
96 | ||
97 | PSK identity was not found. An "unknown_psk_identity" alert message | |
98 | will be sent and the connection setup fails. | |
99 | ||
100 | =item E<gt>0 | |
ddac1974 NL |
101 | |
102 | PSK identity was found and the server callback has provided the PSK | |
103 | successfully in parameter B<psk>. Return value is the length of | |
104 | B<psk> in bytes. It is an error to return a value greater than | |
105 | B<max_psk_len>. | |
106 | ||
107 | If the PSK identity was not found but the callback instructs the | |
108 | protocol to continue anyway, the callback must provide some random | |
109 | data to B<psk> and return the length of the random data, so the | |
110 | connection will fail with decryption_error before it will be finished | |
111 | completely. | |
112 | ||
5cc27077 NA |
113 | =back |
114 | ||
72257204 | 115 | The B<SSL_psk_find_session_cb_func> callback should return 1 on success or 0 on |
93a048a1 MC |
116 | failure. In the event of failure the connection setup fails. |
117 | ||
e105ae84 MC |
118 | =head1 SEE ALSO |
119 | ||
120 | L<SSL_CTX_set_psk_use_session_callback(3)>, | |
121 | L<SSL_set_psk_use_session_callback(3)> | |
122 | ||
123 | =head1 HISTORY | |
124 | ||
125 | SSL_CTX_set_psk_find_session_callback() and SSL_set_psk_find_session_callback() | |
126 | were added in OpenSSL 1.1.1. | |
127 | ||
e2f92610 RS |
128 | =head1 COPYRIGHT |
129 | ||
93a048a1 | 130 | Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
131 | |
132 | Licensed under the OpenSSL license (the "License"). You may not use | |
133 | this file except in compliance with the License. You can obtain a copy | |
134 | in the file LICENSE in the source distribution or at | |
135 | L<https://www.openssl.org/source/license.html>. | |
136 | ||
e2f92610 | 137 | =cut |