#include <openssl/tls1.h>
long 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));
+ 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
ticket.
Before the callback function is started I<ctx> and I<hctx> have been
-initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively.
+initialised with L<EVP_CIPHER_CTX_reset(3)> and L<HMAC_CTX_reset(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,
If an attacker can obtain the key used to encrypt a session ticket, they can
obtain the master secret for any ticket using that key and decrypt any traffic
-using that session: even if the ciphersuite supports forward secrecy. As
+using that session: even if the cipher suite supports forward secrecy. As
a result applications may wish to use multiple keys and avoid using long term
keys stored in files.
Applications can use longer keys to maintain a consistent level of security.
-For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key
+For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key
the overall security is only 128 bits because breaking the ticket key will
enable an attacker to obtain the session keys.
-=head1 EXAMPLES
-
-Reference Implementation:
- SSL_CTX_set_tlsext_ticket_key_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)
- {
- if (enc) { /* create new session */
- if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) {
- return -1; /* insufficient random */
- }
-
- key = currentkey(); /* something that you need to implement */
- if ( !key ) {
- /* current key doesn't exist or isn't valid */
- key = createkey(); /* something that you need to implement.
- * createkey needs to initialise, a name,
- * an aes_key, a hmac_key and optionally
- * an expire time. */
- if ( !key ) { /* key couldn't be created */
- return 0;
- }
- }
- 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);
-
- return 1;
-
- } else { /* retrieve session */
- key = findkey(name);
-
- if (!key || key->expire < now() ) {
- return 0;
- }
-
- HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
- EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv );
-
- if (key->expire < ( now() - RENEW_TIME ) )
- /* return 2 - this session will get a new ticket even though the current is still valid */
- return 2;
-
- return 1;
-
- }
- }
+=head1 RETURN VALUES
+returns 0 to indicate the callback function was set.
+=head1 EXAMPLES
-=head1 RETURN VALUES
+Reference Implementation:
-returns 0 to indicate the callback function was set.
+ SSL_CTX_set_tlsext_ticket_key_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)
+ {
+ if (enc) { /* create new session */
+ if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0)
+ return -1; /* insufficient random */
+
+ key = currentkey(); /* something that you need to implement */
+ if (key == NULL) {
+ /* current key doesn't exist or isn't valid */
+ key = createkey(); /*
+ * Something that you need to implement.
+ * createkey needs to initialise a name,
+ * an aes_key, a hmac_key and optionally
+ * an expire time.
+ */
+ if (key == NULL) /* key couldn't be created */
+ return 0;
+ }
+ 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);
+
+ return 1;
+
+ } else { /* retrieve session */
+ key = findkey(name);
+
+ if (key == NULL || key->expire < now())
+ return 0;
+
+ HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
+ EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
+
+ if (key->expire < now() - RENEW_TIME) {
+ /*
+ * return 2 - This session will get a new ticket even though the
+ * current one is still valid.
+ */
+ return 2;
+ }
+ return 1;
+ }
+ }
=head1 SEE ALSO
=head1 COPYRIGHT
-Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2014-2018 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+Licensed under the Apache License 2.0 (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>.