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