SSL_CTX_use_psk_identity_hint.pod 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102
  1. =pod
  2. =begin comment
  3. Copyright 2005 Nokia. All rights reserved.
  4. The portions of the attached software ("Contribution") is developed by
  5. Nokia Corporation and is licensed pursuant to the OpenSSL open source
  6. license.
  7. The Contribution, originally written by Mika Kousa and Pasi Eronen of
  8. Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites
  9. support (see RFC 4279) to OpenSSL.
  10. No patent licenses or other rights except those expressly stated in
  11. the OpenSSL open source license shall be deemed granted or received
  12. expressly, by implication, estoppel, or otherwise.
  13. No assurances are provided by Nokia that the Contribution does not
  14. infringe the patent or other intellectual property rights of any third
  15. party or that the license provides you with all the necessary rights
  16. to make use of the Contribution.
  17. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN
  18. ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA
  19. SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY
  20. OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR
  21. OTHERWISE.
  22. =end comment
  23. =head1 NAME
  24. SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint,
  25. SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK
  26. identity hint to use
  27. =head1 SYNOPSIS
  28. #include <openssl/ssl.h>
  29. int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
  30. int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
  31. void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx,
  32. unsigned int (*callback)(SSL *ssl, const char *identity,
  33. unsigned char *psk, int max_psk_len));
  34. void SSL_set_psk_server_callback(SSL *ssl,
  35. unsigned int (*callback)(SSL *ssl, const char *identity,
  36. unsigned char *psk, int max_psk_len));
  37. =head1 DESCRIPTION
  38. SSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK
  39. identity hint B<hint> to SSL context object
  40. B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated
  41. PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint>
  42. is B<NULL> the current hint from B<ctx> or B<ssl> is deleted.
  43. In the case where PSK identity hint is B<NULL>, the server
  44. does not send the ServerKeyExchange message to the client.
  45. A server application must provide a callback function which is called
  46. when the server receives the ClientKeyExchange message from the
  47. client. The purpose of the callback function is to validate the
  48. received PSK identity and to fetch the pre-shared key used during the
  49. connection setup phase. The callback is set using functions
  50. SSL_CTX_set_psk_server_callback() or
  51. SSL_set_psk_server_callback(). The callback function is given the
  52. connection in parameter B<ssl>, B<NULL>-terminated PSK identity sent
  53. by the client in parameter B<identity>, and a buffer B<psk> of length
  54. B<max_psk_len> bytes where the pre-shared key is to be stored.
  55. =head1 RETURN VALUES
  56. SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return
  57. 1 on success, 0 otherwise.
  58. Return values from the server callback are interpreted as follows:
  59. =item > 0
  60. PSK identity was found and the server callback has provided the PSK
  61. successfully in parameter B<psk>. Return value is the length of
  62. B<psk> in bytes. It is an error to return a value greater than
  63. B<max_psk_len>.
  64. If the PSK identity was not found but the callback instructs the
  65. protocol to continue anyway, the callback must provide some random
  66. data to B<psk> and return the length of the random data, so the
  67. connection will fail with decryption_error before it will be finished
  68. completely.
  69. =item 0
  70. PSK identity was not found. An "unknown_psk_identity" alert message
  71. will be sent and the connection setup fails.
  72. =cut