| Index: openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod | 
| =================================================================== | 
| --- openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod	(revision 0) | 
| +++ openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod	(revision 0) | 
| @@ -0,0 +1,102 @@ | 
| +=pod | 
| + | 
| +=begin comment | 
| + | 
| +Copyright 2005 Nokia. All rights reserved. | 
| + | 
| +The portions of the attached software ("Contribution") is developed by | 
| +Nokia Corporation and is licensed pursuant to the OpenSSL open source | 
| +license. | 
| + | 
| +The Contribution, originally written by Mika Kousa and Pasi Eronen of | 
| +Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites | 
| +support (see RFC 4279) to OpenSSL. | 
| + | 
| +No patent licenses or other rights except those expressly stated in | 
| +the OpenSSL open source license shall be deemed granted or received | 
| +expressly, by implication, estoppel, or otherwise. | 
| + | 
| +No assurances are provided by Nokia that the Contribution does not | 
| +infringe the patent or other intellectual property rights of any third | 
| +party or that the license provides you with all the necessary rights | 
| +to make use of the Contribution. | 
| + | 
| +THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN | 
| +ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA | 
| +SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY | 
| +OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR | 
| +OTHERWISE. | 
| + | 
| +=end comment | 
| + | 
| +=head1 NAME | 
| + | 
| +SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint, | 
| +SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK | 
| +identity hint to use | 
| + | 
| + | 
| +=head1 SYNOPSIS | 
| + | 
| + #include <openssl/ssl.h> | 
| + | 
| + int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); | 
| + int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); | 
| + | 
| + void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, | 
| +	unsigned int (*callback)(SSL *ssl, const char *identity, | 
| +	unsigned char *psk, int max_psk_len)); | 
| + void SSL_set_psk_server_callback(SSL *ssl, | 
| +	unsigned int (*callback)(SSL *ssl, const char *identity, | 
| +	unsigned char *psk, int max_psk_len)); | 
| + | 
| + | 
| +=head1 DESCRIPTION | 
| + | 
| +SSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK | 
| +identity hint B<hint> to SSL context object | 
| +B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated | 
| +PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint> | 
| +is B<NULL> the current hint from B<ctx> or B<ssl> is deleted. | 
| + | 
| +In the case where PSK identity hint is B<NULL>, the server | 
| +does not send the ServerKeyExchange message to the client. | 
| + | 
| +A server application must provide a callback function which is called | 
| +when the server receives the ClientKeyExchange message from the | 
| +client. The purpose of the callback function is to validate the | 
| +received PSK identity and to fetch the pre-shared key used during the | 
| +connection setup phase. The callback is set using functions | 
| +SSL_CTX_set_psk_server_callback() or | 
| +SSL_set_psk_server_callback(). The callback function is given the | 
| +connection in parameter B<ssl>, B<NULL>-terminated PSK identity sent | 
| +by the client in parameter B<identity>, and a buffer B<psk> of length | 
| +B<max_psk_len> bytes where the pre-shared key is to be stored. | 
| + | 
| + | 
| +=head1 RETURN VALUES | 
| + | 
| +SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return | 
| +1 on success, 0 otherwise. | 
| + | 
| +Return values from the server callback are interpreted as follows: | 
| + | 
| +=item > 0 | 
| + | 
| +PSK identity was found and the server callback has provided the PSK | 
| +successfully in parameter B<psk>. Return value is the length of | 
| +B<psk> in bytes. It is an error to return a value greater than | 
| +B<max_psk_len>. | 
| + | 
| +If the PSK identity was not found but the callback instructs the | 
| +protocol to continue anyway, the callback must provide some random | 
| +data to B<psk> and return the length of the random data, so the | 
| +connection will fail with decryption_error before it will be finished | 
| +completely. | 
| + | 
| +=item 0 | 
| + | 
| +PSK identity was not found. An "unknown_psk_identity" alert message | 
| +will be sent and the connection setup fails. | 
| + | 
| +=cut | 
|  |