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 algoritm for TLS session tickets

add comments where user-implementation is needed to complete code

CLA: trivial

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

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 ae2ee2b4e275df4b93ec323557103dac8c89d651..ee726b3b649ef09d78d92dfceddd45069ff4f95a 100644 (file)
--- a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
+++ b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
@@ -159,6 +159,7 @@ Reference Implementation:
                                      EVP_MAC_CTX *hctx, int enc)
  {
      OSSL_PARAM params[3];
+     your_type_t *key; /* something that you need to implement */
 
      if (enc) { /* create new session */
          if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0)
@@ -178,10 +179,10 @@ Reference Implementation:
          }
          memcpy(key_name, key->name, 16);
 
-         EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
+         EVP_EncryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key, iv);
 
          params[0] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY,
-                                                       key->hmac_key, 16);
+                                                       key->hmac_key, 32);
          params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
                                                       "sha256", 0);
          params[2] = OSSL_PARAM_construct_end();
@@ -190,21 +191,22 @@ Reference Implementation:
          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;
 
          params[0] = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
-                                                       key->hmac_key, 16);
+                                                       key->hmac_key, 32);
          params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
                                                       "sha256", 0);
          params[2] = OSSL_PARAM_construct_end();
          EVP_MAC_set_ctx_params(hctx, params);
 
-         EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
+         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.