Rename the master_key field in SSL_SESSION to secret.

It's not even accurate. The term "master key" dates to SSL 2, which we
do not implement. (Starting SSL 3, "key" was replaced with "secret".)
The field stores, at various points, the TLS 1.2 master secret, the TLS
1.3 resumption master secret, and the TLS 1.3 resumption PSK. Simply
rename the field to 'secret', which is as descriptive of a name as we
can get at this point.

I've left SSL_SESSION_get_master_key alone for now, as it's there for
OpenSSL compatibility, as well as references to the various TLS secrets
since those refer to concepts in the spec. (When the dust settles a bit
on rfc8446bis, we can fix those.)

Change-Id: I3c1007eb7982788789cc5db851de8724c7f35baf
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/44144
Reviewed-by: Adam Langley <agl@google.com>

include/openssl/ssl.h

@@ -1738,9 +1738,9 @@ OPENSSL_EXPORT void SSL_SESSION_get0_ocsp_response(const SSL_SESSION *session,
 // SSL_MAX_MASTER_KEY_LENGTH is the maximum length of a master secret.
 #define SSL_MAX_MASTER_KEY_LENGTH 48
 
-// SSL_SESSION_get_master_key writes up to |max_out| bytes of |session|'s master
-// secret to |out| and returns the number of bytes written. If |max_out| is
-// zero, it returns the size of the master secret.
+// SSL_SESSION_get_master_key writes up to |max_out| bytes of |session|'s secret
+// to |out| and returns the number of bytes written. If |max_out| is zero, it
+// returns the size of the secret.
 OPENSSL_EXPORT size_t SSL_SESSION_get_master_key(const SSL_SESSION *session,
                                                  uint8_t *out, size_t max_out);
 

ssl/handshake.cc

@@ -494,9 +494,8 @@ bool ssl_send_finished(SSL_HANDSHAKE *hs) {
   }
 
   // Log the master secret, if logging is enabled.
-  if (!ssl_log_secret(
-          ssl, "CLIENT_RANDOM",
-          MakeConstSpan(session->master_key, session->master_key_length))) {
+  if (!ssl_log_secret(ssl, "CLIENT_RANDOM",
+                      MakeConstSpan(session->secret, session->secret_length))) {
     return 0;
   }
 

ssl/handshake_client.cc

@@ -459,8 +459,8 @@ static enum ssl_hs_wait_t do_enter_early_data(SSL_HANDSHAKE *hs) {
   }
 
   if (!tls13_init_early_key_schedule(
-          hs, MakeConstSpan(ssl->session->master_key,
-                            ssl->session->master_key_length)) ||
+          hs,
+          MakeConstSpan(ssl->session->secret, ssl->session->secret_length)) ||
       !tls13_derive_early_secret(hs)) {
     return ssl_hs_error;
   }
@@ -1407,9 +1407,9 @@ static enum ssl_hs_wait_t do_send_client_key_exchange(SSL_HANDSHAKE *hs) {
     return ssl_hs_error;
   }
 
-  hs->new_session->master_key_length =
-      tls1_generate_master_secret(hs, hs->new_session->master_key, pms);
-  if (hs->new_session->master_key_length == 0) {
+  hs->new_session->secret_length =
+      tls1_generate_master_secret(hs, hs->new_session->secret, pms);
+  if (hs->new_session->secret_length == 0) {
     return ssl_hs_error;
   }
   hs->new_session->extended_master_secret = hs->extended_master_secret;

ssl/handshake_server.cc

@@ -1402,14 +1402,13 @@ static enum ssl_hs_wait_t do_read_client_key_exchange(SSL_HANDSHAKE *hs) {
   }
 
   // Compute the master secret.
-  hs->new_session->master_key_length = tls1_generate_master_secret(
-      hs, hs->new_session->master_key, premaster_secret);
-  if (hs->new_session->master_key_length == 0) {
+  hs->new_session->secret_length = tls1_generate_master_secret(
+      hs, hs->new_session->secret, premaster_secret);
+  if (hs->new_session->secret_length == 0) {
     return ssl_hs_error;
   }
   hs->new_session->extended_master_secret = hs->extended_master_secret;
-  CONSTTIME_DECLASSIFY(hs->new_session->master_key,
-                       hs->new_session->master_key_length);
+  CONSTTIME_DECLASSIFY(hs->new_session->secret, hs->new_session->secret_length);
 
   ssl->method->next_message(ssl);
   hs->state = state12_read_client_certificate_verify;

ssl/internal.h

@@ -3466,10 +3466,12 @@ struct ssl_session_st {
   // the peer, or zero if not applicable or unknown.
   uint16_t peer_signature_algorithm = 0;
 
-  // master_key, in TLS 1.2 and below, is the master secret associated with the
-  // session. In TLS 1.3 and up, it is the resumption secret.
-  int master_key_length = 0;
-  uint8_t master_key[SSL_MAX_MASTER_KEY_LENGTH] = {0};
+  // secret, in TLS 1.2 and below, is the master secret associated with the
+  // session. In TLS 1.3 and up, it is the resumption PSK for sessions handed to
+  // the caller, but it stores the resumption secret when stored on |SSL|
+  // objects.
+  int secret_length = 0;
+  uint8_t secret[SSL_MAX_MASTER_KEY_LENGTH] = {0};
 
   // session_id - valid?
   unsigned session_id_length = 0;

ssl/ssl_asn1.cc

@@ -105,7 +105,7 @@ BSSL_NAMESPACE_BEGIN
 //     sslVersion                  INTEGER,      -- protocol version number
 //     cipher                      OCTET STRING, -- two bytes long
 //     sessionID                   OCTET STRING,
-//     masterKey                   OCTET STRING,
+//     secret                      OCTET STRING,
 //     time                    [1] INTEGER, -- seconds since UNIX epoch
 //     timeout                 [2] INTEGER, -- in seconds
 //     peer                    [3] Certificate OPTIONAL,
@@ -218,8 +218,7 @@ static int SSL_SESSION_to_bytes_full(const SSL_SESSION *in, CBB *cbb,
       // The session ID is irrelevant for a session ticket.
       !CBB_add_asn1_octet_string(&session, in->session_id,
                                  for_ticket ? 0 : in->session_id_length) ||
-      !CBB_add_asn1_octet_string(&session, in->master_key,
-                                 in->master_key_length) ||
+      !CBB_add_asn1_octet_string(&session, in->secret, in->secret_length) ||
       !CBB_add_asn1(&session, &child, kTimeTag) ||
       !CBB_add_asn1_uint64(&child, in->time) ||
       !CBB_add_asn1(&session, &child, kTimeoutTag) ||
@@ -593,18 +592,18 @@ UniquePtr<SSL_SESSION> SSL_SESSION_parse(CBS *cbs,
     return nullptr;
   }
 
-  CBS session_id, master_key;
+  CBS session_id, secret;
   if (!CBS_get_asn1(&session, &session_id, CBS_ASN1_OCTETSTRING) ||
       CBS_len(&session_id) > SSL3_MAX_SSL_SESSION_ID_LENGTH ||
-      !CBS_get_asn1(&session, &master_key, CBS_ASN1_OCTETSTRING) ||
-      CBS_len(&master_key) > SSL_MAX_MASTER_KEY_LENGTH) {
+      !CBS_get_asn1(&session, &secret, CBS_ASN1_OCTETSTRING) ||
+      CBS_len(&secret) > SSL_MAX_MASTER_KEY_LENGTH) {
     OPENSSL_PUT_ERROR(SSL, SSL_R_INVALID_SSL_SESSION);
     return nullptr;
   }
   OPENSSL_memcpy(ret->session_id, CBS_data(&session_id), CBS_len(&session_id));
   ret->session_id_length = CBS_len(&session_id);
-  OPENSSL_memcpy(ret->master_key, CBS_data(&master_key), CBS_len(&master_key));
-  ret->master_key_length = CBS_len(&master_key);
+  OPENSSL_memcpy(ret->secret, CBS_data(&secret), CBS_len(&secret));
+  ret->secret_length = CBS_len(&secret);
 
   CBS child;
   uint64_t timeout;

ssl/ssl_session.cc

@@ -202,9 +202,8 @@ UniquePtr<SSL_SESSION> SSL_SESSION_dup(SSL_SESSION *session, int dup_flags) {
   OPENSSL_memcpy(new_session->sid_ctx, session->sid_ctx, session->sid_ctx_length);
 
   // Copy the key material.
-  new_session->master_key_length = session->master_key_length;
-  OPENSSL_memcpy(new_session->master_key, session->master_key,
-         session->master_key_length);
+  new_session->secret_length = session->secret_length;
+  OPENSSL_memcpy(new_session->secret, session->secret, session->secret_length);
   new_session->cipher = session->cipher;
 
   // Copy authentication state.
@@ -963,14 +962,14 @@ void SSL_SESSION_get0_ocsp_response(const SSL_SESSION *session,
 
 size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, uint8_t *out,
                                   size_t max_out) {
-  // TODO(davidben): Fix master_key_length's type and remove these casts.
+  // TODO(davidben): Fix secret_length's type and remove these casts.
   if (max_out == 0) {
-    return (size_t)session->master_key_length;
+    return (size_t)session->secret_length;
   }
-  if (max_out > (size_t)session->master_key_length) {
-    max_out = (size_t)session->master_key_length;
+  if (max_out > (size_t)session->secret_length) {
+    max_out = (size_t)session->secret_length;
   }
-  OPENSSL_memcpy(out, session->master_key, max_out);
+  OPENSSL_memcpy(out, session->secret, max_out);
   return max_out;
 }
 

ssl/ssl_transcript.cc

@@ -265,8 +265,8 @@ bool SSLTranscript::GetFinishedMAC(uint8_t *out, size_t *out_len,
 
   static const size_t kFinishedLen = 12;
   if (!tls1_prf(Digest(), MakeSpan(out, kFinishedLen),
-                MakeConstSpan(session->master_key, session->master_key_length),
-                label, MakeConstSpan(digest, digest_len), {})) {
+                MakeConstSpan(session->secret, session->secret_length), label,
+                MakeConstSpan(digest, digest_len), {})) {
     return false;
   }
 

ssl/t1_enc.cc

@@ -191,15 +191,14 @@ static bool get_key_block_lengths(const SSL *ssl, size_t *out_mac_secret_len,
 
 static bool generate_key_block(const SSL *ssl, Span<uint8_t> out,
                                const SSL_SESSION *session) {
-  auto master_key =
-      MakeConstSpan(session->master_key, session->master_key_length);
+  auto secret = MakeConstSpan(session->secret, session->secret_length);
   static const char kLabel[] = "key expansion";
   auto label = MakeConstSpan(kLabel, sizeof(kLabel) - 1);
 
   const EVP_MD *digest = ssl_session_get_digest(session);
   // Note this function assumes that |session|'s key material corresponds to
   // |ssl->s3->client_random| and |ssl->s3->server_random|.
-  return tls1_prf(digest, out, master_key, label, ssl->s3->server_random,
+  return tls1_prf(digest, out, secret, label, ssl->s3->server_random,
                   ssl->s3->client_random);
 }
 
@@ -379,8 +378,7 @@ int SSL_export_keying_material(SSL *ssl, uint8_t *out, size_t out_len,
 
   const SSL_SESSION *session = SSL_get_session(ssl);
   const EVP_MD *digest = ssl_session_get_digest(session);
-  return tls1_prf(
-      digest, MakeSpan(out, out_len),
-      MakeConstSpan(session->master_key, session->master_key_length),
-      MakeConstSpan(label, label_len), seed, {});
+  return tls1_prf(digest, MakeSpan(out, out_len),
+                  MakeConstSpan(session->secret, session->secret_length),
+                  MakeConstSpan(label, label_len), seed, {});
 }

ssl/tls13_client.cc

@@ -414,8 +414,8 @@ static enum ssl_hs_wait_t do_read_server_hello(SSL_HANDSHAKE *hs) {
   // Set up the key schedule and incorporate the PSK into the running secret.
   if (ssl->s3->session_reused) {
     if (!tls13_init_key_schedule(
-            hs, MakeConstSpan(hs->new_session->master_key,
-                              hs->new_session->master_key_length))) {
+            hs, MakeConstSpan(hs->new_session->secret,
+                              hs->new_session->secret_length))) {
       return ssl_hs_error;
     }
   } else if (!tls13_init_key_schedule(hs, MakeConstSpan(kZeroes, hash_len))) {

ssl/tls13_enc.cc

@@ -303,10 +303,9 @@ bool tls13_derive_resumption_secret(SSL_HANDSHAKE *hs) {
     OPENSSL_PUT_ERROR(SSL, ERR_R_INTERNAL_ERROR);
     return false;
   }
-  hs->new_session->master_key_length = hs->transcript.DigestLen();
+  hs->new_session->secret_length = hs->transcript.DigestLen();
   return derive_secret(
-      hs,
-      MakeSpan(hs->new_session->master_key, hs->new_session->master_key_length),
+      hs, MakeSpan(hs->new_session->secret, hs->new_session->secret_length),
       label_to_span(kTLS13LabelResumption));
 }
 
@@ -354,8 +353,8 @@ bool tls13_derive_session_psk(SSL_SESSION *session, Span<const uint8_t> nonce) {
   const EVP_MD *digest = ssl_session_get_digest(session);
   // The session initially stores the resumption_master_secret, which we
   // override with the PSK.
-  auto session_key = MakeSpan(session->master_key, session->master_key_length);
-  return hkdf_expand_label(session_key, digest, session_key,
+  auto session_secret = MakeSpan(session->secret, session->secret_length);
+  return hkdf_expand_label(session_secret, digest, session_secret,
                            label_to_span(kTLS13LabelResumptionPSK), nonce);
 }
 
@@ -460,11 +459,10 @@ bool tls13_write_psk_binder(SSL_HANDSHAKE *hs, Span<uint8_t> msg) {
   if (!hash_transcript_and_truncated_client_hello(
           hs, context, &context_len, digest, msg,
           1 /* length prefix */ + hash_len) ||
-      !tls13_psk_binder(verify_data, &verify_data_len,
-                        ssl->session->ssl_version, digest,
-                        MakeConstSpan(ssl->session->master_key,
-                                      ssl->session->master_key_length),
-                        MakeConstSpan(context, context_len)) ||
+      !tls13_psk_binder(
+          verify_data, &verify_data_len, ssl->session->ssl_version, digest,
+          MakeConstSpan(ssl->session->secret, ssl->session->secret_length),
+          MakeConstSpan(context, context_len)) ||
       verify_data_len != hash_len) {
     OPENSSL_PUT_ERROR(SSL, ERR_R_INTERNAL_ERROR);
     return false;
@@ -485,11 +483,10 @@ bool tls13_verify_psk_binder(SSL_HANDSHAKE *hs, SSL_SESSION *session,
   if (!hash_transcript_and_truncated_client_hello(hs, context, &context_len,
                                                   hs->transcript.Digest(),
                                                   msg.raw, CBS_len(binders)) ||
-      !tls13_psk_binder(
-          verify_data, &verify_data_len, hs->ssl->version,
-          hs->transcript.Digest(),
-          MakeConstSpan(session->master_key, session->master_key_length),
-          MakeConstSpan(context, context_len)) ||
+      !tls13_psk_binder(verify_data, &verify_data_len, hs->ssl->version,
+                        hs->transcript.Digest(),
+                        MakeConstSpan(session->secret, session->secret_length),
+                        MakeConstSpan(context, context_len)) ||
       // We only consider the first PSK, so compare against the first binder.
       !CBS_get_u8_length_prefixed(binders, &binder)) {
     OPENSSL_PUT_ERROR(SSL, ERR_R_INTERNAL_ERROR);

ssl/tls13_server.cc

@@ -477,8 +477,8 @@ static enum ssl_hs_wait_t do_select_session(SSL_HANDSHAKE *hs) {
   // Set up the key schedule and incorporate the PSK into the running secret.
   if (ssl->s3->session_reused) {
     if (!tls13_init_key_schedule(
-            hs, MakeConstSpan(hs->new_session->master_key,
-                              hs->new_session->master_key_length))) {
+            hs, MakeConstSpan(hs->new_session->secret,
+                              hs->new_session->secret_length))) {
       return ssl_hs_error;
     }
   } else if (!tls13_init_key_schedule(hs, MakeConstSpan(kZeroes, hash_len))) {