improve SSL_CTX_set_tlsext_ticket_key_cb ref impl

improve reference implementation code in
  SSL_CTX_set_tlsext_ticket_key_cb man page

change EVP_aes_128_cbc() to EVP_aes_256_cbc(), with the implication
of requiring longer keys.  Updating this code brings the reference
implementation in line with implementation in openssl committed in 2016:
commit 05df5c20
Use AES256 for the default encryption algorithm for TLS session tickets

add comments where user-implementation is needed to complete code

(backport from https://github.com/openssl/openssl/pull/12063)

Reviewed-by: Ben Kaduk <kaduk@mit.edu>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12391)

diff --git a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
index 43bddc51e8cf16a23d6e4cdfeabced6dee712722..d56c0c540b22c62651908382e6516496598d003a 100644 (file)
--- a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
+++ b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
@@ -136,6 +136,8 @@ Reference Implementation:
                                      unsigned char *iv, EVP_CIPHER_CTX *ctx,
                                      HMAC_CTX *hctx, int enc)
  {
+     your_type_t *key; /* something that you need to implement */
+
      if (enc) { /* create new session */
          if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0)
              return -1; /* insufficient random */
@@ -154,21 +156,22 @@ 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);
+         EVP_EncryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key, iv);
+         HMAC_Init_ex(&hctx, key->hmac_key, 32, EVP_sha256(), NULL);
 
          return 1;
 
      } else { /* retrieve session */
-         key = findkey(name);
+         time_t t = time(NULL);
+         key = findkey(key_name); /* something that you need to implement */
 
-         if (key == NULL || key->expire < now())
+         if (key == NULL || key->expire < t)
              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);
+         HMAC_Init_ex(&hctx, key->hmac_key, 32, EVP_sha256(), NULL);
+         EVP_DecryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key, iv);
 
-         if (key->expire < now() - RENEW_TIME) {
+         if (key->expire < t - RENEW_TIME) { /* RENEW_TIME: implement */
              /*
               * return 2 - This session will get a new ticket even though the
               * current one is still valid.