SSL_CTX_use_psk_identity_hint.pod revision 290207
1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=begin comment 4238384Sjkim 5238384SjkimCopyright 2005 Nokia. All rights reserved. 6238384Sjkim 7238384SjkimThe portions of the attached software ("Contribution") is developed by 8238384SjkimNokia Corporation and is licensed pursuant to the OpenSSL open source 9238384Sjkimlicense. 10238384Sjkim 11238384SjkimThe Contribution, originally written by Mika Kousa and Pasi Eronen of 12238384SjkimNokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites 13238384Sjkimsupport (see RFC 4279) to OpenSSL. 14238384Sjkim 15238384SjkimNo patent licenses or other rights except those expressly stated in 16238384Sjkimthe OpenSSL open source license shall be deemed granted or received 17238384Sjkimexpressly, by implication, estoppel, or otherwise. 18238384Sjkim 19238384SjkimNo assurances are provided by Nokia that the Contribution does not 20238384Sjkiminfringe the patent or other intellectual property rights of any third 21238384Sjkimparty or that the license provides you with all the necessary rights 22238384Sjkimto make use of the Contribution. 23238384Sjkim 24238384SjkimTHE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN 25238384SjkimADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA 26238384SjkimSPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY 27238384SjkimOTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR 28238384SjkimOTHERWISE. 29238384Sjkim 30238384Sjkim=end comment 31238384Sjkim 32238384Sjkim=head1 NAME 33238384Sjkim 34238384SjkimSSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint, 35238384SjkimSSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK 36238384Sjkimidentity hint to use 37238384Sjkim 38238384Sjkim 39238384Sjkim=head1 SYNOPSIS 40238384Sjkim 41238384Sjkim #include <openssl/ssl.h> 42238384Sjkim 43238384Sjkim int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); 44238384Sjkim int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); 45238384Sjkim 46238384Sjkim void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, 47238384Sjkim unsigned int (*callback)(SSL *ssl, const char *identity, 48238384Sjkim unsigned char *psk, int max_psk_len)); 49238384Sjkim void SSL_set_psk_server_callback(SSL *ssl, 50238384Sjkim unsigned int (*callback)(SSL *ssl, const char *identity, 51238384Sjkim unsigned char *psk, int max_psk_len)); 52238384Sjkim 53238384Sjkim 54238384Sjkim=head1 DESCRIPTION 55238384Sjkim 56238384SjkimSSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK 57238384Sjkimidentity hint B<hint> to SSL context object 58238384SjkimB<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated 59238384SjkimPSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint> 60238384Sjkimis B<NULL> the current hint from B<ctx> or B<ssl> is deleted. 61238384Sjkim 62238384SjkimIn the case where PSK identity hint is B<NULL>, the server 63238384Sjkimdoes not send the ServerKeyExchange message to the client. 64238384Sjkim 65238384SjkimA server application must provide a callback function which is called 66238384Sjkimwhen the server receives the ClientKeyExchange message from the 67238384Sjkimclient. The purpose of the callback function is to validate the 68238384Sjkimreceived PSK identity and to fetch the pre-shared key used during the 69238384Sjkimconnection setup phase. The callback is set using functions 70238384SjkimSSL_CTX_set_psk_server_callback() or 71238384SjkimSSL_set_psk_server_callback(). The callback function is given the 72238384Sjkimconnection in parameter B<ssl>, B<NULL>-terminated PSK identity sent 73238384Sjkimby the client in parameter B<identity>, and a buffer B<psk> of length 74238384SjkimB<max_psk_len> bytes where the pre-shared key is to be stored. 75238384Sjkim 76238384Sjkim 77238384Sjkim=head1 RETURN VALUES 78238384Sjkim 79238384SjkimSSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return 80238384Sjkim1 on success, 0 otherwise. 81238384Sjkim 82238384SjkimReturn values from the server callback are interpreted as follows: 83238384Sjkim 84261037Sjkim=over 4 85261037Sjkim 86290207Sjkim=item Z<>0 87238384Sjkim 88290207SjkimPSK identity was not found. An "unknown_psk_identity" alert message 89290207Sjkimwill be sent and the connection setup fails. 90290207Sjkim 91290207Sjkim=item E<gt>0 92290207Sjkim 93238384SjkimPSK identity was found and the server callback has provided the PSK 94238384Sjkimsuccessfully in parameter B<psk>. Return value is the length of 95238384SjkimB<psk> in bytes. It is an error to return a value greater than 96238384SjkimB<max_psk_len>. 97238384Sjkim 98238384SjkimIf the PSK identity was not found but the callback instructs the 99238384Sjkimprotocol to continue anyway, the callback must provide some random 100238384Sjkimdata to B<psk> and return the length of the random data, so the 101238384Sjkimconnection will fail with decryption_error before it will be finished 102238384Sjkimcompletely. 103238384Sjkim 104261037Sjkim=back 105261037Sjkim 106238384Sjkim=cut 107