doc/ssl/SSL_CTX_set_psk_client_callback.pod

   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_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client callback
  35
  36 =head1 SYNOPSIS
  37
  38  #include <openssl/ssl.h>
  39
  40  void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx,
  41         unsigned int (*callback)(SSL *ssl, const char *hint,
  42         char *identity, unsigned int max_identity_len,
  43         unsigned char *psk, unsigned int max_psk_len));
  44  void SSL_set_psk_client_callback(SSL *ssl,
  45         unsigned int (*callback)(SSL *ssl, const char *hint,
  46         char *identity, unsigned int max_identity_len,
  47         unsigned char *psk, unsigned int max_psk_len));
  48
  49
  50 =head1 DESCRIPTION
  51
  52 A client application must provide a callback function which is called
  53 when the client is sending the ClientKeyExchange message to the server.
  54
  55 The purpose of the callback function is to select the PSK identity and
  56 the pre-shared key to use during the connection setup phase.
  57
  58 The callback is set using functions SSL_CTX_set_psk_client_callback()
  59 or SSL_set_psk_client_callback(). The callback function is given the
  60 connection in parameter B<ssl>, a B<NULL>-terminated PSK identity hint
  61 sent by the server in parameter B<hint>, a buffer B<identity> of
  62 length B<max_identity_len> bytes where the the resulting
  63 B<NULL>-terminated identity is to be stored, and a buffer B<psk> of
  64 length B<max_psk_len> bytes where the resulting pre-shared key is to
  65 be stored.
  66
  67 =head1 NOTES
  68
  69 Note that parameter B<hint> given to the callback may be B<NULL>.
  70
  71 =head1 RETURN VALUES
  72
  73 Return values from the client callback are interpreted as follows:
  74
  75 On success (callback found a PSK identity and a pre-shared key to use)
  76 the length (> 0) of B<psk> in bytes is returned.
  77
  78 Otherwise or on errors callback should return 0. In this case
  79 the connection setup fails.
  80
  81 =cut