SSL_CTX_use_psk_identity_hint.pod revision 279264 
1=pod
2
3=begin comment
4
5Copyright 2005 Nokia. All rights reserved.
6
7The portions of the attached software ("Contribution") is developed by
8Nokia Corporation and is licensed pursuant to the OpenSSL open source
9license.
10
11The Contribution, originally written by Mika Kousa and Pasi Eronen of
12Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites
13support (see RFC 4279) to OpenSSL.
14
15No patent licenses or other rights except those expressly stated in
16the OpenSSL open source license shall be deemed granted or received
17expressly, by implication, estoppel, or otherwise.
18
19No assurances are provided by Nokia that the Contribution does not
20infringe the patent or other intellectual property rights of any third
21party or that the license provides you with all the necessary rights
22to make use of the Contribution.
23
24THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN
25ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA
26SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY
27OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR
28OTHERWISE.
29
30=end comment
31
32=head1 NAME
33
34SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint,
35SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK
36identity hint to use
37
38
39=head1 SYNOPSIS
40
41 #include <openssl/ssl.h>
42
43 int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
44 int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
45
46 void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx,
47	unsigned int (*callback)(SSL *ssl, const char *identity,
48	unsigned char *psk, int max_psk_len));
49 void SSL_set_psk_server_callback(SSL *ssl,
50	unsigned int (*callback)(SSL *ssl, const char *identity,
51	unsigned char *psk, int max_psk_len));
52
53
54=head1 DESCRIPTION
55
56SSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK
57identity hint B<hint> to SSL context object
58B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated
59PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint>
60is B<NULL> the current hint from B<ctx> or B<ssl> is deleted.
61
62In the case where PSK identity hint is B<NULL>, the server
63does not send the ServerKeyExchange message to the client.
64
65A server application must provide a callback function which is called
66when the server receives the ClientKeyExchange message from the
67client. The purpose of the callback function is to validate the
68received PSK identity and to fetch the pre-shared key used during the
69connection setup phase. The callback is set using functions
70SSL_CTX_set_psk_server_callback() or
71SSL_set_psk_server_callback(). The callback function is given the
72connection in parameter B<ssl>, B<NULL>-terminated PSK identity sent
73by the client in parameter B<identity>, and a buffer B<psk> of length
74B<max_psk_len> bytes where the pre-shared key is to be stored.
75
76
77=head1 RETURN VALUES
78
79SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return
801 on success, 0 otherwise.
81
82Return values from the server callback are interpreted as follows:
83
84=over 4
85
86=item > 0
87
88PSK identity was found and the server callback has provided the PSK
89successfully in parameter B<psk>. Return value is the length of
90B<psk> in bytes. It is an error to return a value greater than
91B<max_psk_len>.
92
93If the PSK identity was not found but the callback instructs the
94protocol to continue anyway, the callback must provide some random
95data to B<psk> and return the length of the random data, so the
96connection will fail with decryption_error before it will be finished
97completely.
98
99=item Z<>0
100
101PSK identity was not found. An "unknown_psk_identity" alert message
102will be sent and the connection setup fails.
103
104=back
105
106=cut
107