add initial support for RFC 4279 PSK SSL ciphersuites
PR: 1191 Submitted by: Mika Kousa and Pasi Eronen of Nokia Corporation Reviewed by: Nils Larsch
This commit is contained in:
Nils Larsch
81
doc/ssl/SSL_CTX_set_psk_client_callback.pod
Normal file
81
doc/ssl/SSL_CTX_set_psk_client_callback.pod
Normal file
@@ -0,0 +1,81 @@
|
||||
=pod
|
||||
|
||||
=begin comment
|
||||
|
||||
Copyright 2005 Nokia. All rights reserved.
|
||||
|
||||
The portions of the attached software ("Contribution") is developed by
|
||||
Nokia Corporation and is licensed pursuant to the OpenSSL open source
|
||||
license.
|
||||
|
||||
The Contribution, originally written by Mika Kousa and Pasi Eronen of
|
||||
Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites
|
||||
support (see RFC 4279) to OpenSSL.
|
||||
|
||||
No patent licenses or other rights except those expressly stated in
|
||||
the OpenSSL open source license shall be deemed granted or received
|
||||
expressly, by implication, estoppel, or otherwise.
|
||||
|
||||
No assurances are provided by Nokia that the Contribution does not
|
||||
infringe the patent or other intellectual property rights of any third
|
||||
party or that the license provides you with all the necessary rights
|
||||
to make use of the Contribution.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN
|
||||
ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA
|
||||
SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY
|
||||
OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR
|
||||
OTHERWISE.
|
||||
|
||||
=end comment
|
||||
|
||||
=head1 NAME
|
||||
|
||||
SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client callback
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/ssl.h>
|
||||
|
||||
void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx,
|
||||
unsigned int (*callback)(SSL *ssl, const char *hint,
|
||||
char *identity, unsigned int max_identity_len,
|
||||
unsigned char *psk, unsigned int max_psk_len));
|
||||
void SSL_set_psk_client_callback(SSL *ssl,
|
||||
unsigned int (*callback)(SSL *ssl, const char *hint,
|
||||
char *identity, unsigned int max_identity_len,
|
||||
unsigned char *psk, unsigned int max_psk_len));
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
A client application must provide a callback function which is called
|
||||
when the client is sending the ClientKeyExchange message to the server.
|
||||
|
||||
The purpose of the callback function is to select the PSK identity and
|
||||
the pre-shared key to use during the connection setup phase.
|
||||
|
||||
The callback is set using functions SSL_CTX_set_psk_client_callback()
|
||||
or SSL_set_psk_client_callback(). The callback function is given the
|
||||
connection in parameter B<ssl>, a B<NULL>-terminated PSK identity hint
|
||||
sent by the server in parameter B<hint>, a buffer B<identity> of
|
||||
length B<max_identity_len> bytes where the the resulting
|
||||
B<NULL>-terminated identity is to be stored, and a buffer B<psk> of
|
||||
length B<max_psk_len> bytes where the resulting pre-shared key is to
|
||||
be stored.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Note that parameter B<hint> given to the callback may be B<NULL>.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
Return values from the client callback are interpreted as follows:
|
||||
|
||||
On success (callback found a PSK identity and a pre-shared key to use)
|
||||
the length (> 0) of B<psk> in bytes is returned.
|
||||
|
||||
Otherwise or on errors callback should return 0. In this case
|
||||
the connection setup fails.
|
||||
|
||||
=cut
|
||||
102
doc/ssl/SSL_CTX_use_psk_identity_hint.pod
Normal file
102
doc/ssl/SSL_CTX_use_psk_identity_hint.pod
Normal file
@@ -0,0 +1,102 @@
|
||||
=pod
|
||||
|
||||
=begin comment
|
||||
|
||||
Copyright 2005 Nokia. All rights reserved.
|
||||
|
||||
The portions of the attached software ("Contribution") is developed by
|
||||
Nokia Corporation and is licensed pursuant to the OpenSSL open source
|
||||
license.
|
||||
|
||||
The Contribution, originally written by Mika Kousa and Pasi Eronen of
|
||||
Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites
|
||||
support (see RFC 4279) to OpenSSL.
|
||||
|
||||
No patent licenses or other rights except those expressly stated in
|
||||
the OpenSSL open source license shall be deemed granted or received
|
||||
expressly, by implication, estoppel, or otherwise.
|
||||
|
||||
No assurances are provided by Nokia that the Contribution does not
|
||||
infringe the patent or other intellectual property rights of any third
|
||||
party or that the license provides you with all the necessary rights
|
||||
to make use of the Contribution.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN
|
||||
ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA
|
||||
SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY
|
||||
OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR
|
||||
OTHERWISE.
|
||||
|
||||
=end comment
|
||||
|
||||
=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:
|
||||
|
||||
=item > 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.
|
||||
|
||||
=item 0
|
||||
|
||||
PSK identity was not found. An "unknown_psk_identity" alert message
|
||||
will be sent and the connection setup fails.
|
||||
|
||||
=cut
|
||||
63
doc/ssl/SSL_get_psk_identity.pod
Normal file
63
doc/ssl/SSL_get_psk_identity.pod
Normal file
@@ -0,0 +1,63 @@
|
||||
=pod
|
||||
|
||||
=begin comment
|
||||
|
||||
Copyright 2005 Nokia. All rights reserved.
|
||||
|
||||
The portions of the attached software ("Contribution") is developed by
|
||||
Nokia Corporation and is licensed pursuant to the OpenSSL open source
|
||||
license.
|
||||
|
||||
The Contribution, originally written by Mika Kousa and Pasi Eronen of
|
||||
Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites
|
||||
support (see RFC 4279) to OpenSSL.
|
||||
|
||||
No patent licenses or other rights except those expressly stated in
|
||||
the OpenSSL open source license shall be deemed granted or received
|
||||
expressly, by implication, estoppel, or otherwise.
|
||||
|
||||
No assurances are provided by Nokia that the Contribution does not
|
||||
infringe the patent or other intellectual property rights of any third
|
||||
party or that the license provides you with all the necessary rights
|
||||
to make use of the Contribution.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN
|
||||
ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA
|
||||
SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY
|
||||
OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR
|
||||
OTHERWISE.
|
||||
|
||||
=end comment
|
||||
|
||||
=head1 NAME
|
||||
|
||||
SSL_get_psk_identity, SSL_get_psk_identity_hint - get PSK client identity and hint
|
||||
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/ssl.h>
|
||||
|
||||
const char *SSL_get_psk_identity_hint(const SSL *ssl);
|
||||
const char *SSL_get_psk_identity(const SSL *ssl);
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
SSL_get_psk_identity_hint() is used to retrieve the PSK identity hint
|
||||
used during the connection setup related to SSL object
|
||||
B<ssl>. Similarly, SSL_get_psk_identity() is used to retrieve the PSK
|
||||
identity used during the connection setup.
|
||||
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
If non-B<NULL>, SSL_get_psk_identity_hint() returns the PSK identity
|
||||
hint and SSL_get_psk_identity() returns the PSK identity. Both are
|
||||
B<NULL>-terminated. SSL_get_psk_identity_hint() may return B<NULL> if
|
||||
no PSK identity hint was used during the connection setup.
|
||||
|
||||
Note that the return value is valid only during the lifetime of the
|
||||
SSL object B<ssl>.
|
||||
|
||||
=cut
|
||||
@@ -374,6 +374,15 @@ session instead of a context.
|
||||
|
||||
=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, char *file, int type);
|
||||
|
||||
=item void B<SSL_CTX_set_psk_client_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
|
||||
|
||||
=item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint);
|
||||
|
||||
=item void B<SSL_CTX_set_psk_server_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
|
||||
|
||||
|
||||
|
||||
|
||||
=back
|
||||
|
||||
=head2 DEALING WITH SESSIONS
|
||||
@@ -650,6 +659,16 @@ connection defined in the B<SSL> structure.
|
||||
|
||||
=item int B<SSL_write>(SSL *ssl, const void *buf, int num);
|
||||
|
||||
=item void B<SSL_set_psk_client_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
|
||||
|
||||
=item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint);
|
||||
|
||||
=item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
|
||||
|
||||
=item const char *B<SSL_get_psk_identity_hint>(SSL *ssl);
|
||||
|
||||
=item const char *B<SSL_get_psk_identity>(SSL *ssl);
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
@@ -726,7 +745,10 @@ L<SSL_write(3)|SSL_write(3)>,
|
||||
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
|
||||
L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>,
|
||||
L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>,
|
||||
L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>
|
||||
L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>,
|
||||
L<SSL_CTX_set_psk_client_callback(3)|SSL_CTX_set_psk_client_callback(3)>,
|
||||
L<SSL_CTX_use_psk_identity_hint(3)|SSL_CTX_use_psk_identity_hint(3)>,
|
||||
L<SSL_get_psk_identity(3)|SSL_get_psk_identity(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
||||
Reference in New Issue
Block a user