Use KEM terminology in TLS ECDHE and key_share abstractions TLS 1.2 ECDHE and TLS 1.3 key shares were originally designed around Diffie-Hellman-like primitives and use language based on that. Post-quantum replacements do not look like Diffie-Hellman, where each part exchanges a public key, but schemes that work differently can still slot in without protocol changes. We previously came up with our own Offer/Accept/Finish abstraction for early post-quantum experiments, but the NIST constructions are all expressed as KEMs: First, the recipient generates a keypair and sends the public key. Then the sender encapsulates a symmetric secret and sends the ciphertext. Finally, the recipient decapsulates the ciphertext to get the secret. Align our C++ and Go abstractions to this terminology. The functions are now called Generate/Encap/Decap, and the output of Encap is called "ciphertext", which seems to align with what most folks use. (RFC 9180 uses "enc" for "encapsulated key", but they staple a KEM to an AEAD, so "ciphertext" would be ambiguous.) Where variable names refer to parts of the protocol, rather than the the underlying KEM-like construction, I've kept variable names matching the protocol mechanism, so we still talk about "curves" and "key shares", but, when using the post-quantum replacements, the terminology is no longer quite accurate. I've also not yet renamed SSLKeyShare yet, though the name is now inaccurate. Also ideally we'd touch that up so the stateful object is just a KEM private key, for SSLKEMKey. Though at that point, we maybe should just add EVP_KEM and EVP_KEM_KEY APIs to libcrypto. Change-Id: Icbcc1840c5d2dfad210ef4caad2a7c4bf8146553 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/57726 Reviewed-by: Adam Langley <agl@google.com> Commit-Queue: David Benjamin <davidben@google.com>
diff --git a/ssl/ssl_key_share.cc b/ssl/ssl_key_share.cc index c604c87..a81b917 100644 --- a/ssl/ssl_key_share.cc +++ b/ssl/ssl_key_share.cc
@@ -43,7 +43,7 @@ uint16_t GroupID() const override { return group_id_; } - bool Offer(CBB *out) override { + bool Generate(CBB *out) override { assert(!private_key_); // Generate a private key. private_key_.reset(BN_new()); @@ -66,8 +66,16 @@ return true; } - bool Finish(Array<uint8_t> *out_secret, uint8_t *out_alert, - Span<const uint8_t> peer_key) override { + bool Encap(CBB *out_ciphertext, Array<uint8_t> *out_secret, + uint8_t *out_alert, Span<const uint8_t> peer_key) override { + // ECDH may be fit into a KEM-like abstraction by using a second keypair's + // public key as the ciphertext. + *out_alert = SSL_AD_INTERNAL_ERROR; + return Generate(out_ciphertext) && Decap(out_secret, out_alert, peer_key); + } + + bool Decap(Array<uint8_t> *out_secret, uint8_t *out_alert, + Span<const uint8_t> ciphertext) override { assert(group_); assert(private_key_); *out_alert = SSL_AD_INTERNAL_ERROR; @@ -79,9 +87,9 @@ return false; } - if (peer_key.empty() || peer_key[0] != POINT_CONVERSION_UNCOMPRESSED || - !EC_POINT_oct2point(group_, peer_point.get(), peer_key.data(), - peer_key.size(), /*ctx=*/nullptr)) { + if (ciphertext.empty() || ciphertext[0] != POINT_CONVERSION_UNCOMPRESSED || + !EC_POINT_oct2point(group_, peer_point.get(), ciphertext.data(), + ciphertext.size(), /*ctx=*/nullptr)) { OPENSSL_PUT_ERROR(SSL, SSL_R_BAD_ECPOINT); *out_alert = SSL_AD_DECODE_ERROR; return false; @@ -133,14 +141,22 @@ uint16_t GroupID() const override { return SSL_CURVE_X25519; } - bool Offer(CBB *out) override { + bool Generate(CBB *out) override { uint8_t public_key[32]; X25519_keypair(public_key, private_key_); return !!CBB_add_bytes(out, public_key, sizeof(public_key)); } - bool Finish(Array<uint8_t> *out_secret, uint8_t *out_alert, - Span<const uint8_t> peer_key) override { + bool Encap(CBB *out_ciphertext, Array<uint8_t> *out_secret, + uint8_t *out_alert, Span<const uint8_t> peer_key) override { + // X25519 may be fit into a KEM-like abstraction by using a second keypair's + // public key as the ciphertext. + *out_alert = SSL_AD_INTERNAL_ERROR; + return Generate(out_ciphertext) && Decap(out_secret, out_alert, peer_key); + } + + bool Decap(Array<uint8_t> *out_secret, uint8_t *out_alert, + Span<const uint8_t> ciphertext) override { *out_alert = SSL_AD_INTERNAL_ERROR; Array<uint8_t> secret; @@ -148,8 +164,8 @@ return false; } - if (peer_key.size() != 32 || - !X25519(secret.data(), private_key_, peer_key.data())) { + if (ciphertext.size() != 32 || // + !X25519(secret.data(), private_key_, ciphertext.data())) { *out_alert = SSL_AD_DECODE_ERROR; OPENSSL_PUT_ERROR(SSL, SSL_R_BAD_ECPOINT); return false; @@ -181,7 +197,7 @@ uint16_t GroupID() const override { return SSL_CURVE_CECPQ2; } - bool Offer(CBB *out) override { + bool Generate(CBB *out) override { uint8_t x25519_public_key[32]; X25519_keypair(x25519_public_key, x25519_private_key_); @@ -205,8 +221,8 @@ return true; } - bool Accept(CBB *out_public_key, Array<uint8_t> *out_secret, - uint8_t *out_alert, Span<const uint8_t> peer_key) override { + bool Encap(CBB *out_ciphertext, Array<uint8_t> *out_secret, + uint8_t *out_alert, Span<const uint8_t> peer_key) override { Array<uint8_t> secret; if (!secret.Init(32 + HRSS_KEY_BYTES)) { return false; @@ -230,9 +246,9 @@ if (!HRSS_encap(ciphertext, secret.data() + 32, &peer_public_key, entropy) || - !CBB_add_bytes(out_public_key, x25519_public_key, + !CBB_add_bytes(out_ciphertext, x25519_public_key, sizeof(x25519_public_key)) || - !CBB_add_bytes(out_public_key, ciphertext, sizeof(ciphertext))) { + !CBB_add_bytes(out_ciphertext, ciphertext, sizeof(ciphertext))) { return false; } @@ -240,8 +256,8 @@ return true; } - bool Finish(Array<uint8_t> *out_secret, uint8_t *out_alert, - Span<const uint8_t> peer_key) override { + bool Decap(Array<uint8_t> *out_secret, uint8_t *out_alert, + Span<const uint8_t> ciphertext) override { *out_alert = SSL_AD_INTERNAL_ERROR; Array<uint8_t> secret; @@ -249,15 +265,15 @@ return false; } - if (peer_key.size() != 32 + HRSS_CIPHERTEXT_BYTES || - !X25519(secret.data(), x25519_private_key_, peer_key.data())) { + if (ciphertext.size() != 32 + HRSS_CIPHERTEXT_BYTES || + !X25519(secret.data(), x25519_private_key_, ciphertext.data())) { *out_alert = SSL_AD_DECODE_ERROR; OPENSSL_PUT_ERROR(SSL, SSL_R_BAD_ECPOINT); return false; } if (!HRSS_decap(secret.data() + 32, &hrss_private_key_, - peer_key.data() + 32, peer_key.size() - 32)) { + ciphertext.data() + 32, ciphertext.size() - 32)) { return false; } @@ -276,20 +292,19 @@ uint16_t GroupID() const override { return SSL_CURVE_X25519KYBER768; } - bool Offer(CBB *out) override { + bool Generate(CBB *out) override { // There is no implementation on Kyber in BoringSSL. BoringSSL must be - // patched for this key agreement to be workable. It is not enabled by - // default. + // patched for this KEM to be workable. It is not enabled by default. return false; } - bool Accept(CBB *out_public_key, Array<uint8_t> *out_secret, - uint8_t *out_alert, Span<const uint8_t> peer_key) override { + bool Encap(CBB *out_ciphertext, Array<uint8_t> *out_secret, + uint8_t *out_alert, Span<const uint8_t> peer_key) override { return false; } - bool Finish(Array<uint8_t> *out_secret, uint8_t *out_alert, - Span<const uint8_t> peer_key) override { + bool Decap(Array<uint8_t> *out_secret, uint8_t *out_alert, + Span<const uint8_t> ciphertext) override { return false; } }; @@ -300,20 +315,19 @@ uint16_t GroupID() const override { return SSL_CURVE_P256KYBER768; } - bool Offer(CBB *out) override { + bool Generate(CBB *out) override { // There is no implementation on Kyber in BoringSSL. BoringSSL must be - // patched for this key agreement to be workable. It is not enabled by - // default. + // patched for this KEM to be workable. It is not enabled by default. return false; } - bool Accept(CBB *out_public_key, Array<uint8_t> *out_secret, - uint8_t *out_alert, Span<const uint8_t> peer_key) override { + bool Encap(CBB *out_ciphertext, Array<uint8_t> *out_secret, + uint8_t *out_alert, Span<const uint8_t> peer_key) override { return false; } - bool Finish(Array<uint8_t> *out_secret, uint8_t *out_alert, - Span<const uint8_t> peer_key) override { + bool Decap(Array<uint8_t> *out_secret, uint8_t *out_alert, + Span<const uint8_t> ciphertext) override { return false; } }; @@ -359,13 +373,6 @@ } } -bool SSLKeyShare::Accept(CBB *out_public_key, Array<uint8_t> *out_secret, - uint8_t *out_alert, Span<const uint8_t> peer_key) { - *out_alert = SSL_AD_INTERNAL_ERROR; - return Offer(out_public_key) && - Finish(out_secret, out_alert, peer_key); -} - bool ssl_nid_to_group_id(uint16_t *out_group_id, int nid) { for (const auto &group : kNamedGroups) { if (group.nid == nid) {