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 |