Each Cloud Key Management Servicekey has apurpose, which defines thecryptographic capabilities of the key. The purpose also determines whichalgorithms are supported for the key's versions. Eachalgorithm defines whatparameters must be used for each cryptographic operation. Each key also has aprotection level that indicates whether cryptographic operations areperformed in software or in a Hardware Security Module (HSM).

Key purposes

Cloud KMS provides key purposes for the following scenarios:

When you create a key, you define the purpose and the algorithm of that key. Youcan change the algorithm when you create new key versions, subject to thescope of its purpose. The purpose cannot be changed.

Two keys with the same purpose may use different underlying algorithms, but theymust support the same set of cryptographic operations.

Symmetric encryption algorithms

The ENCRYPT_DECRYPT key purpose enables symmetric encryption. All keys with keypurpose ENCRYPT_DECRYPT use the GOOGLE_SYMMETRIC_ENCRYPTION algorithm. Noparameters are used with this algorithm. This algorithm uses 256-bit AdvancedEncryption Standard (AES-256) keys in Galois Counter Mode (GCM), padded withCloud KMS-internal metadata.

Asymmetric signing algorithms

The ASYMMETRIC_SIGN key purpose enables asymmetric signing. Keys with keypurpose ASYMMETRIC_SIGN use different algorithms, depending on whether the keysupportselliptic curve signing orRSA signing.

For a key that has purpose ASYMMETRIC_SIGN, you can switch between differentsize keys and different signature schemes via the algorithm.

Elliptic curve signing algorithms

The format of an elliptic curve signing algorithm is

EC_SIGN_[ELLIPTIC_CURVE]_[DIGEST_ALGORITHM]

where

• [ELLIPTIC_CURVE] is the elliptic curve
• [DIGEST_ALGORITHM] is the digest algorithm

The following table lists the possible algorithms for elliptic curve keys withpurpose ASYMMETRIC_SIGN. Use the lower-case algorithm names with thegcloudcommand, and the upper-case ones with the Cloud Key Management Service API.

RSA signing algorithms

The format of an RSA signing algorithm is

RSA_SIGN_[PADDING_ALGORITHM]_[MODULUS_BIT_LENGTH]_[DIGEST_ALGORITHM]

where

• [PADDING_ALGORITHM] is the padding algorithm
• [MODULUS_BIT_LENGTH] is the bit length of the key
• [DIGEST_ALGORITHM] is the digest algorithm

Note that some algorithms are formatted as

RSA_SIGN_RAW_[PADDING_ALGORITHM]_[MODULUS_BIT_LENGTH]

and omit the digest algorithm. These algorithms are a variant of PKCS #1 signingthat omits encoding into a DigestInfo. In the variant:

• a digest is computed over the message that will be signed
• PKCS #1 padding is applied to the digest directly
• a signature of the padded digest is computed, using the RSA private key

The following table lists the possible algorithms for RSA keys with purposeASYMMETRIC_SIGN. Use the lower-case algorithm names with thegcloudcommand, and the upper-case ones with the Cloud Key Management Service API.

For Probabilistic Signature Scheme (PSS), the salt length used is equal to thelength of the digest algorithm. For example, RSA_SIGN_PSS_2048_SHA256 will usePSS with a salt length of 256 bits. In addition, for PSS the digest algorithmspecified in the algorithm name is used for the mask generation function (MGF1)as well. For example, if you are using RSA_SIGN_PSS_2048_SHA256, you will submita SHA-256 hash of the data to be signed, and Cloud KMS willinternally use SHA-256 as the hash algorithm for MGF1 when computing thesignature.

PQC signing algorithms

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Post-quantum cryptography (PQC) signing algorithms start with the prefixPQ_SIGN_. The following table lists the PQC algorithms that Cloud KMScan use for keys with purposeASYMMETRIC_SIGN. The pure algorithms take rawdata as input, while the pre-hash algorithms accept a hash of the data.

Asymmetric encryption algorithms

The ASYMMETRIC_DECRYPT key purpose enables RSA encryption. The format of anASYMMETRIC_DECRYPT algorithm is

RSA_DECRYPT_[PADDING_ALGORITHM]_[MODULUS_BIT_LENGTH]_[DIGEST_ALGORITHM]

where

• [PADDING_ALGORITHM] is the padding algorithm
• [MODULUS_BIT_LENGTH] is the bit length of the key
• [DIGEST_ALGORITHM] is the digest algorithm

The following table lists the possible algorithms for RSA keys with purposeASYMMETRIC_DECRYPT. Use the lower-case algorithm names with thegcloudcommand, and the upper-case ones with the Cloud Key Management Service API.

All of these algorithms use Optimal Asymmetric Encryption Padding (OAEP) withthe mask generation function MGF1. MGF1 requires a digest algorithm. InCloud KMS, the digest function to be used with MGF1 is specified aspart of the key algorithm name. For example, if you are using theRSA_DECRYPT_OAEP_3072_SHA256 algorithm, you should use SHA-256 with MGF1 whenencrypting data.

Key encapsulation algorithms

TheKEY_ENCAPSULATION key purpose is used to establish shared secretsusingkey encapsulation mechanisms.

The following table lists the possible algorithms for keys with purposeKEY_ENCAPSULATION. All of these algorithms are designed to be post-quantumsecure. Use the lower-case algorithm names with thegcloudcommand, and the upper-case ones with the Cloud Key Management Service API.

MAC signing algorithms

The MAC key purpose enables symmetric MAC signing. Keys with key purpose MACcurrently only supportHMAC signing.

HMAC signing algorithms

The format of an HMAC signing algorithm is

HMAC_[HASH_ALGORITHM]

where

• [HASH_ALGORITHM] is the hash algorithm

The following table lists the currently available HMAC algorithms for keys withpurpose MAC. Use the lower-case algorithm names with thegcloud command, andthe upper-case ones with the Cloud Key Management Service API.

Algorithm recommendations

For digital signing, the recommendation is to use elliptic curve signingalgorithms. EC_SIGN_P256_SHA256 is the recommended elliptic curve algorithm. Ifyou are going to use RSA signing algorithms, the recommended RSA signingalgorithm is RSA_SIGN_PSS_3072_SHA256.

For asymmetric encryption, RSA_DECRYPT_OAEP_3072_SHA256 is the recommendedalgorithm.

For MAC signing, HMAC_SHA256 is the recommended algorithm.

For key encapsulation, we recommend usingKEM_XWING, which is a hybridalgorithm that can provide layered defense against both classical andpotential quantum adversaries.

For the list of supported algorithm values to be used with the gcloud CLI,see--default-algorithm.

Protection levels

The protection level indicates how cryptographic operations are performed. Afteryou create a key, you cannot change the protection level.

Allkey purposes are supported for keys with protection levelSOFTWARE orHSM.