Hakase/openssl-custom
1
0 Fork 0
Code Issues Pull Requests Releases Wiki Activity

Latest update.

Browse Source
This commit is contained in:
Hakase
2020-02-11 23:20:44 +09:00
parent 047a30700b
commit 9dfeec3942
639 changed files with 14024 additions and 31198 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
+55 -12
View File
@@ -2,20 +2,31 @@
=head1 NAME
SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing
SSL_CTX_set_tlsext_ticket_key_evp_cb,
SSL_CTX_set_tlsext_ticket_key_cb
- set a callback for session ticket processing
=head1 SYNOPSIS
#include <openssl/tls1.h>
long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
int SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL_CTX sslctx,
int (*cb)(SSL *s, unsigned char key_name[16],
unsigned char iv[EVP_MAX_IV_LENGTH],
EVP_CIPHER_CTX *ctx, EVP_MAC_CTX *hctx, int enc));
Deprecated since OpenSSL 3.0, can be hidden entirely by defining
B<OPENSSL_API_COMPAT> with a suitable version value, see
L<openssl_user_macros(7)>:
int SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
int (*cb)(SSL *s, unsigned char key_name[16],
unsigned char iv[EVP_MAX_IV_LENGTH],
EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
=head1 DESCRIPTION
SSL_CTX_set_tlsext_ticket_key_cb() sets a callback function I<cb> for handling
SSL_CTX_set_tlsext_ticket_key_evp_cb() sets a callback function I<cb> for handling
session tickets for the ssl context I<sslctx>. Session tickets, defined in
RFC5077 provide an enhanced session resumption capability where the server
implementation is not required to maintain per session state. It only applies
@@ -38,7 +49,8 @@ ticket information or it starts a full TLS handshake to create a new session
ticket.
Before the callback function is started I<ctx> and I<hctx> have been
initialised with L<EVP_CIPHER_CTX_reset(3)> and L<HMAC_CTX_reset(3)> respectively.
initialised with L<EVP_CIPHER_CTX_reset(3)> and L<EVP_MAC_CTX_new(3)>
respectively.
For new sessions tickets, when the client doesn't present a session ticket, or
an attempted retrieval of the ticket failed, or a renew option was indicated,
@@ -53,8 +65,9 @@ maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>.
The initialization vector I<iv> should be a random value. The cipher context
I<ctx> should use the initialisation vector I<iv>. The cipher context can be
set using L<EVP_EncryptInit_ex(3)>. The hmac context can be set using
L<HMAC_Init_ex(3)>.
set using L<EVP_EncryptInit_ex(3)>. The hmac context and digest can be set using
L<EVP_MAC_CTX_set_params(3)> with the B<OSSL_MAC_PARAM_KEY> and
B<OSSL_MAC_PARAM_DIGEST> parameters respectively.
When the client presents a session ticket, the callback function with be called
with I<enc> set to 0 indicating that the I<cb> function should retrieve a set
@@ -62,8 +75,9 @@ of parameters. In this case I<name> and I<iv> have already been parsed out of
the session ticket. The OpenSSL library expects that the I<name> will be used
to retrieve a cryptographic parameters and that the cryptographic context
I<ctx> will be set with the retrieved parameters and the initialization vector
I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The I<hctx> needs to be
set using L<HMAC_Init_ex(3)>.
I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The key material and
digest for I<hctx> need to be set using L<EVP_MAC_CTX_set_params(3)> with the
B<OSSL_MAC_PARAM_KEY> and B<OSSL_MAC_PARAM_DIGEST> parameters respectively.
If the I<name> is still valid but a renewal of the ticket is required the
callback function should return 2. The library will call the callback again
@@ -102,6 +116,14 @@ This indicates an error.
=back
The SSL_CTX_set_tlsext_ticket_key_cb() function is identical to
SSL_CTX_set_tlsext_ticket_key_evp_cb() except that it takes a deprecated
HMAC_CTX pointer instead of an EVP_MAC_CTX one.
Before this callback function is started I<hctx> will have been
initialised with L<EVP_MAC_CTX_new(3)> and the digest set with
L<EVP_MAC_CTX_set_params(3)>.
The I<hctx> key material can be set using L<HMAC_Init_ex(3)>.
=head1 NOTES
Session resumption shortcuts the TLS so that the client certificate
@@ -129,13 +151,15 @@ returns 0 to indicate the callback function was set.
Reference Implementation:
SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb);
SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL, ssl_tlsext_ticket_key_cb);
...
static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16],
unsigned char *iv, EVP_CIPHER_CTX *ctx,
HMAC_CTX *hctx, int enc)
EVP_MAC_CTX *hctx, int enc)
{
OSSL_PARAM params[3];
if (enc) { /* create new session */
if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0)
return -1; /* insufficient random */
@@ -155,7 +179,13 @@ Reference Implementation:
memcpy(key_name, key->name, 16);
EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
params[0] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY,
key->hmac_key, 16);
params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
"sha256", 0);
params[2] = OSSL_PARAM_construct_end();
EVP_MAC_CTX_set_params(hctx, params);
return 1;
@@ -165,7 +195,13 @@ Reference Implementation:
if (key == NULL || key->expire < now())
return 0;
HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
params[0] = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
key->hmac_key, 16);
params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
"sha256", 0);
params[2] = OSSL_PARAM_construct_end();
EVP_MAC_CTX_set_params(hctx, params);
EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
if (key->expire < now() - RENEW_TIME) {
@@ -188,6 +224,13 @@ L<SSL_CTX_sess_number(3)>,
L<SSL_CTX_sess_set_get_cb(3)>,
L<SSL_CTX_set_session_id_context(3)>,
=head1 HISTORY
The SSL_CTX_set_tlsext_ticket_key_cb() function was deprecated in OpenSSL 3.0.
The SSL_CTX_set_tlsext_ticket_key_evp_cb() function was introduced in
OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2014-2018 The OpenSSL Project Authors. All Rights Reserved.