mirror of
https://github.com/openssl/openssl.git
synced 2024-11-27 05:21:51 +08:00
c80149d9f0
This is done with the kind permission of Nokia. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3722)
90 lines
3.3 KiB
Plaintext
90 lines
3.3 KiB
Plaintext
=pod
|
|
|
|
=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:
|
|
|
|
=over 4
|
|
|
|
=item Z<>0
|
|
|
|
PSK identity was not found. An "unknown_psk_identity" alert message
|
|
will be sent and the connection setup fails.
|
|
|
|
=item E<gt>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.
|
|
|
|
=back
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the OpenSSL license (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|