Skip to content

Commit f8146b4

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: Support KEY_ENCAPSULATION purpose and quantum-safe algorithms ML_KEM_768, ML_KEM_1024 and KEM_XWING
feat: Add PublicKeyFormat enums XWING_RAW_BYTES (used for KEM_XWING) and DER PiperOrigin-RevId: 805449810
1 parent 0ef98bc commit f8146b4

2 files changed

Lines changed: 131 additions & 0 deletions

File tree

‎google/cloud/kms/v1/resources.proto‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,12 @@ message CryptoKey {
100100
// [CryptoKeys][google.cloud.kms.v1.CryptoKey] with this purpose may be used
101101
// with [MacSign][google.cloud.kms.v1.KeyManagementService.MacSign].
102102
MAC = 9;
103+
104+
// [CryptoKeys][google.cloud.kms.v1.CryptoKey] with this purpose may be used
105+
// with
106+
// [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey]
107+
// and [Decapsulate][google.cloud.kms.v1.KeyManagementService.Decapsulate].
108+
KEY_ENCAPSULATION = 10;
103109
}
104110

105111
// Output only. The resource name for this
@@ -469,6 +475,16 @@ message CryptoKeyVersion {
469475
// Algorithm representing symmetric encryption by an external key manager.
470476
EXTERNAL_SYMMETRIC_ENCRYPTION = 18;
471477

478+
// ML-KEM-768 (FIPS 203)
479+
ML_KEM_768 = 47;
480+
481+
// ML-KEM-1024 (FIPS 203)
482+
ML_KEM_1024 = 48;
483+
484+
// X-Wing hybrid KEM combining ML-KEM-768 with X25519 following
485+
// datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/.
486+
KEM_XWING = 63;
487+
472488
// The post-quantum Module-Lattice-Based Digital Signature Algorithm, at
473489
// security level 3. Randomized version.
474490
PQ_SIGN_ML_DSA_65 = 56;
@@ -719,10 +735,18 @@ message PublicKey {
719735
// (https://tools.ietf.org/html/rfc7468#section-13) for more information.
720736
PEM = 1;
721737

738+
// The returned public key will be encoded in DER format (the
739+
// PrivateKeyInfo structure from RFC 5208).
740+
DER = 2;
741+
722742
// This is supported only for PQC algorithms.
723743
// The key material is returned in the format defined by NIST PQC
724744
// standards (FIPS 203, FIPS 204, and FIPS 205).
725745
NIST_PQC = 3;
746+
747+
// The returned public key is in raw bytes format defined in its standard
748+
// https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem.
749+
XWING_RAW_BYTES = 4;
726750
}
727751

728752
// The public key, encoded in PEM format. For more information, see the

‎google/cloud/kms/v1/service.proto‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,18 @@ service KeyManagementService {
390390
option (google.api.method_signature) = "name,data,mac";
391391
}
392392

393+
// Decapsulates data that was encapsulated with a public key retrieved from
394+
// [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey]
395+
// corresponding to a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]
396+
// with [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose]
397+
// KEY_ENCAPSULATION.
398+
rpc Decapsulate(DecapsulateRequest) returns (DecapsulateResponse) {
399+
option (google.api.http) = {
400+
post: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*}:decapsulate"
401+
body: "*"
402+
};
403+
}
404+
393405
// Generate random bytes using the Cloud KMS randomness source in the provided
394406
// location.
395407
rpc GenerateRandomBytes(GenerateRandomBytesRequest)
@@ -1544,6 +1556,47 @@ message MacVerifyRequest {
15441556
[(google.api.field_behavior) = OPTIONAL];
15451557
}
15461558

1559+
// Request message for
1560+
// [KeyManagementService.Decapsulate][google.cloud.kms.v1.KeyManagementService.Decapsulate].
1561+
message DecapsulateRequest {
1562+
// Required. The resource name of the
1563+
// [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] to use for
1564+
// decapsulation.
1565+
string name = 1 [
1566+
(google.api.field_behavior) = REQUIRED,
1567+
(google.api.resource_reference) = {
1568+
type: "cloudkms.googleapis.com/CryptoKeyVersion"
1569+
}
1570+
];
1571+
1572+
// Required. The ciphertext produced from encapsulation with the
1573+
// named [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] public
1574+
// key(s).
1575+
bytes ciphertext = 2 [(google.api.field_behavior) = REQUIRED];
1576+
1577+
// Optional. A CRC32C checksum of the
1578+
// [DecapsulateRequest.ciphertext][google.cloud.kms.v1.DecapsulateRequest.ciphertext].
1579+
// If specified,
1580+
// [KeyManagementService][google.cloud.kms.v1.KeyManagementService] will
1581+
// verify the integrity of the received
1582+
// [DecapsulateRequest.ciphertext][google.cloud.kms.v1.DecapsulateRequest.ciphertext]
1583+
// using this checksum.
1584+
// [KeyManagementService][google.cloud.kms.v1.KeyManagementService] will
1585+
// report an error if the checksum verification fails. If you receive a
1586+
// checksum error, your client should verify that
1587+
// CRC32C([DecapsulateRequest.ciphertext][google.cloud.kms.v1.DecapsulateRequest.ciphertext])
1588+
// is equal to
1589+
// [DecapsulateRequest.ciphertext_crc32c][google.cloud.kms.v1.DecapsulateRequest.ciphertext_crc32c],
1590+
// and if so, perform a limited number of retries. A persistent mismatch may
1591+
// indicate an issue in your computation of the CRC32C checksum. Note: This
1592+
// field is defined as int64 for reasons of compatibility across different
1593+
// languages. However, it is a non-negative integer, which will never exceed
1594+
// 2^32-1, and can be safely downconverted to uint32 in languages that support
1595+
// this type.
1596+
google.protobuf.Int64Value ciphertext_crc32c = 3
1597+
[(google.api.field_behavior) = OPTIONAL];
1598+
}
1599+
15471600
// Request message for
15481601
// [KeyManagementService.GenerateRandomBytes][google.cloud.kms.v1.KeyManagementService.GenerateRandomBytes].
15491602
message GenerateRandomBytesRequest {
@@ -2047,6 +2100,60 @@ message MacVerifyResponse {
20472100
ProtectionLevel protection_level = 6;
20482101
}
20492102

2103+
// Response message for
2104+
// [KeyManagementService.Decapsulate][google.cloud.kms.v1.KeyManagementService.Decapsulate].
2105+
message DecapsulateResponse {
2106+
// The resource name of the
2107+
// [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] used for
2108+
// decapsulation. Check this field to verify that the intended resource was
2109+
// used for decapsulation.
2110+
string name = 1;
2111+
2112+
// The decapsulated shared_secret originally encapsulated with the matching
2113+
// public key.
2114+
bytes shared_secret = 2;
2115+
2116+
// Integrity verification field. A CRC32C checksum of the returned
2117+
// [DecapsulateResponse.shared_secret][google.cloud.kms.v1.DecapsulateResponse.shared_secret].
2118+
// An integrity check of
2119+
// [DecapsulateResponse.shared_secret][google.cloud.kms.v1.DecapsulateResponse.shared_secret]
2120+
// can be performed by computing the CRC32C checksum of
2121+
// [DecapsulateResponse.shared_secret][google.cloud.kms.v1.DecapsulateResponse.shared_secret]
2122+
// and comparing your results to this field. Discard the response in case of
2123+
// non-matching checksum values, and perform a limited number of retries. A
2124+
// persistent mismatch may indicate an issue in your computation of the CRC32C
2125+
// checksum. Note: receiving this response message indicates that
2126+
// [KeyManagementService][google.cloud.kms.v1.KeyManagementService] is able to
2127+
// successfully decrypt the
2128+
// [ciphertext][google.cloud.kms.v1.DecapsulateRequest.ciphertext]. Note: This
2129+
// field is defined as int64 for reasons of compatibility across different
2130+
// languages. However, it is a non-negative integer, which will never exceed
2131+
// 2^32-1, and can be safely downconverted to uint32 in languages that support
2132+
// this type.
2133+
optional int64 shared_secret_crc32c = 3;
2134+
2135+
// Integrity verification field. A flag indicating whether
2136+
// [DecapsulateRequest.ciphertext_crc32c][google.cloud.kms.v1.DecapsulateRequest.ciphertext_crc32c]
2137+
// was received by
2138+
// [KeyManagementService][google.cloud.kms.v1.KeyManagementService] and used
2139+
// for the integrity verification of the
2140+
// [ciphertext][google.cloud.kms.v1.DecapsulateRequest.ciphertext]. A false
2141+
// value of this field indicates either that
2142+
// [DecapsulateRequest.ciphertext_crc32c][google.cloud.kms.v1.DecapsulateRequest.ciphertext_crc32c]
2143+
// was left unset or that it was not delivered to
2144+
// [KeyManagementService][google.cloud.kms.v1.KeyManagementService]. If you've
2145+
// set
2146+
// [DecapsulateRequest.ciphertext_crc32c][google.cloud.kms.v1.DecapsulateRequest.ciphertext_crc32c]
2147+
// but this field is still false, discard the response and perform a limited
2148+
// number of retries.
2149+
bool verified_ciphertext_crc32c = 4;
2150+
2151+
// The [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] of the
2152+
// [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] used in
2153+
// decapsulation.
2154+
ProtectionLevel protection_level = 5;
2155+
}
2156+
20502157
// Response message for
20512158
// [KeyManagementService.GenerateRandomBytes][google.cloud.kms.v1.KeyManagementService.GenerateRandomBytes].
20522159
message GenerateRandomBytesResponse {

0 commit comments

Comments
 (0)