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 Z<>0 87 88PSK identity was not found. An "unknown_psk_identity" alert message 89will be sent and the connection setup fails. 90 91=item E<gt>0 92 93PSK identity was found and the server callback has provided the PSK 94successfully in parameter B<psk>. Return value is the length of 95B<psk> in bytes. It is an error to return a value greater than 96B<max_psk_len>. 97 98If the PSK identity was not found but the callback instructs the 99protocol to continue anyway, the callback must provide some random 100data to B<psk> and return the length of the random data, so the 101connection will fail with decryption_error before it will be finished 102completely. 103 104=back 105 106=cut 107