]>
Commit | Line | Data |
---|---|---|
ddac1974 NL |
1 | =pod |
2 | ||
ddac1974 NL |
3 | =head1 NAME |
4 | ||
5 | SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint, | |
6 | SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK | |
7 | identity hint to use | |
8 | ||
ddac1974 NL |
9 | =head1 SYNOPSIS |
10 | ||
11 | #include <openssl/ssl.h> | |
12 | ||
13 | int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); | |
14 | int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); | |
15 | ||
16 | void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, | |
e9b77246 BB |
17 | unsigned int (*callback)(SSL *ssl, |
18 | const char *identity, | |
19 | unsigned char *psk, | |
20 | int max_psk_len)); | |
ddac1974 | 21 | void SSL_set_psk_server_callback(SSL *ssl, |
e9b77246 BB |
22 | unsigned int (*callback)(SSL *ssl, |
23 | const char *identity, | |
24 | unsigned char *psk, | |
25 | int max_psk_len)); | |
ddac1974 NL |
26 | |
27 | ||
28 | =head1 DESCRIPTION | |
29 | ||
30 | SSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK | |
31 | identity hint B<hint> to SSL context object | |
32 | B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated | |
33 | PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint> | |
34 | is B<NULL> the current hint from B<ctx> or B<ssl> is deleted. | |
35 | ||
36 | In the case where PSK identity hint is B<NULL>, the server | |
37 | does not send the ServerKeyExchange message to the client. | |
38 | ||
39 | A server application must provide a callback function which is called | |
40 | when the server receives the ClientKeyExchange message from the | |
41 | client. The purpose of the callback function is to validate the | |
42 | received PSK identity and to fetch the pre-shared key used during the | |
43 | connection setup phase. The callback is set using functions | |
44 | SSL_CTX_set_psk_server_callback() or | |
45 | SSL_set_psk_server_callback(). The callback function is given the | |
46 | connection in parameter B<ssl>, B<NULL>-terminated PSK identity sent | |
47 | by the client in parameter B<identity>, and a buffer B<psk> of length | |
48 | B<max_psk_len> bytes where the pre-shared key is to be stored. | |
49 | ||
50 | ||
51 | =head1 RETURN VALUES | |
52 | ||
53 | SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return | |
54 | 1 on success, 0 otherwise. | |
55 | ||
56 | Return values from the server callback are interpreted as follows: | |
57 | ||
5cc27077 NA |
58 | =over 4 |
59 | ||
fe757304 SS |
60 | =item Z<>0 |
61 | ||
62 | PSK identity was not found. An "unknown_psk_identity" alert message | |
63 | will be sent and the connection setup fails. | |
64 | ||
65 | =item E<gt>0 | |
ddac1974 NL |
66 | |
67 | PSK identity was found and the server callback has provided the PSK | |
68 | successfully in parameter B<psk>. Return value is the length of | |
69 | B<psk> in bytes. It is an error to return a value greater than | |
70 | B<max_psk_len>. | |
71 | ||
72 | If the PSK identity was not found but the callback instructs the | |
73 | protocol to continue anyway, the callback must provide some random | |
74 | data to B<psk> and return the length of the random data, so the | |
75 | connection will fail with decryption_error before it will be finished | |
76 | completely. | |
77 | ||
5cc27077 NA |
78 | =back |
79 | ||
e2f92610 RS |
80 | =head1 COPYRIGHT |
81 | ||
82 | Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. | |
83 | ||
84 | Licensed under the OpenSSL license (the "License"). You may not use | |
85 | this file except in compliance with the License. You can obtain a copy | |
86 | in the file LICENSE in the source distribution or at | |
87 | L<https://www.openssl.org/source/license.html>. | |
88 | ||
e2f92610 | 89 | =cut |