diff options
author | Nils Larsch <nils@openssl.org> | 2006-03-10 23:06:27 +0000 |
---|---|---|
committer | Nils Larsch <nils@openssl.org> | 2006-03-10 23:06:27 +0000 |
commit | ddac197404f585b8da58df794fc3beb9d08e8cd2 (patch) | |
tree | be75e03f93b8ad8c2cf5e76f58d3b11bb73854ed /doc/ssl | |
parent | 0e8e6f19b2919e14c5bb7b645a359b96ad9fc13d (diff) |
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
Diffstat (limited to 'doc/ssl')
-rw-r--r-- | doc/ssl/SSL_CTX_set_psk_client_callback.pod | 81 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_use_psk_identity_hint.pod | 102 | ||||
-rw-r--r-- | doc/ssl/SSL_get_psk_identity.pod | 63 | ||||
-rw-r--r-- | doc/ssl/ssl.pod | 24 |
4 files changed, 269 insertions, 1 deletions
diff --git a/doc/ssl/SSL_CTX_set_psk_client_callback.pod b/doc/ssl/SSL_CTX_set_psk_client_callback.pod new file mode 100644 index 0000000000..573f89a922 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_psk_client_callback.pod @@ -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 diff --git a/doc/ssl/SSL_CTX_use_psk_identity_hint.pod b/doc/ssl/SSL_CTX_use_psk_identity_hint.pod new file mode 100644 index 0000000000..b80e25be7e --- /dev/null +++ b/doc/ssl/SSL_CTX_use_psk_identity_hint.pod @@ -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 diff --git a/doc/ssl/SSL_get_psk_identity.pod b/doc/ssl/SSL_get_psk_identity.pod new file mode 100644 index 0000000000..fe6291649c --- /dev/null +++ b/doc/ssl/SSL_get_psk_identity.pod @@ -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 diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index 8391c66650..2b6004ee32 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -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 |