Key purposes and algorithms

Each Cloud Key Management Service key has a purpose, which defines the cryptographic capabilities of the key. The purpose also determines which algorithms are supported for the key's versions. Each algorithm defines what parameters must be used for each cryptographic operation. Each key also has a protection level that indicates whether cryptographic operations are performed 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. You can change the algorithm when you create new key versions, subject to the scope of its purpose. The purpose cannot be changed.

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

Symmetric encryption algorithms

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

Symmetric encryption algorithms such as AES-256 are generally considered quantum-safe. You can continue to use symmetric encryption.

Asymmetric signing algorithms

The ASYMMETRIC_SIGN key purpose enables asymmetric signing. Keys with key purpose ASYMMETRIC_SIGN use different algorithms, depending on whether the key supports elliptic curve signing or RSA signing.

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

Asymmetric signing algorithms that use elliptic curves and RSA are susceptible to attacks by future quantum computers. For long-term non-repudiation of your signatures, choose a post-quantum asymmetric signing algorithm instead.

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 with purpose ASYMMETRIC_SIGN. Use the lowercase algorithm names with the gcloud command, and the uppercase 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 signing that 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 purpose ASYMMETRIC_SIGN. Use the lowercase algorithm names with the gcloud command, and the uppercase ones with the Cloud Key Management Service API.

For Probabilistic Signature Scheme (PSS), the salt length used is equal to the length of the digest algorithm. For example, RSA_SIGN_PSS_2048_SHA256 will use PSS with a salt length of 256 bits. In addition, for PSS the digest algorithm specified 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 submit a SHA-256 hash of the data to be signed, and Cloud KMS will internally use SHA-256 as the hash algorithm for MGF1 when computing the signature.

PQC signing algorithms

Post-quantum cryptography (PQC) signing algorithms start with the prefix PQ_SIGN_. The following table lists the PQC algorithms that Cloud KMS can use for keys with purpose ASYMMETRIC_SIGN. The pure algorithms take raw data 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 an ASYMMETRIC_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

Asymmetric encryption using RSA algorithms is susceptible to quantum computing, including "harvest now, decrypt later" (HNDL) attacks. In an HNDL attack, a bad actor intercepts a ciphertext that they can't decrypt, and then stores it in the hopes that they can eventually decrypt it using quantum computing. If you are transmitting data that must remain confidential long term despite advances in quantum computing, choose a key encapsulation algorithm instead.

The following table lists the possible algorithms for RSA keys with purpose ASYMMETRIC_DECRYPT. Use the lowercase algorithm names with the gcloud command, and the uppercase ones with the Cloud Key Management Service API.

All of these algorithms use Optimal Asymmetric Encryption Padding (OAEP) with the mask generation function MGF1. MGF1 requires a digest algorithm. In Cloud KMS, the digest function to be used with MGF1 is specified as part of the key algorithm name. For example, if you are using the RSA_DECRYPT_OAEP_3072_SHA256 algorithm, you should use SHA-256 with MGF1 when encrypting data.

Key encapsulation algorithms

The KEY_ENCAPSULATION key purpose is used to establish shared secrets using key encapsulation mechanisms.

The following table lists the possible algorithms for keys with purpose KEY_ENCAPSULATION. All of these algorithms are designed to be post-quantum secure. Use the lowercase algorithm names with the gcloud command, and the uppercase ones with the Cloud Key Management Service API.

MAC signing algorithms

The MAC key purpose enables symmetric MAC signing. Keys with key purpose MAC only support HMAC signing.

HMAC signing algorithms

The format of an HMAC signing algorithm is

HMAC_HASH_ALGORITHM

where

• HASH_ALGORITHM is the hash algorithm

Most symmetric algorithms are generally considered quantum-safe. However, the HMAC-SHA1 algorithm is not quantum-safe. If you need your symmetric signatures to remain trustworthy long-term despite developments in quantum computing, choose an HMAC key with a larger digest size.

The following table lists the HMAC algorithms available for keys with purpose MAC. Use the lowercase algorithm names with the gcloud command, and the uppercase ones with the Cloud Key Management Service API.

Algorithm recommendations

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

For asymmetric encryption, RSA_DECRYPT_OAEP_3072_SHA256 is the recommended algorithm.

For MAC signing, HMAC_SHA256 is the recommended algorithm.

For key encapsulation, we recommend using KEM_XWING, which is a hybrid algorithm that can provide layered defense against both classical and potential 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. After you create a key, you cannot change the protection level.

               : cluster of HSM partitions, exclusively created for a
               : single-tenant Cloud HSM instance.

EXTERNAL | Cryptographic operations are performed using a key stored : in an external key manager connected to : Cloud de Confiance by S3NS using the internet. Limited to symmetric : encryption and asymmetric signing. EXTERNAL_VPC | Cryptographic operations are performed using a key stored : in an external key manager connected to Cloud de Confiance by S3NS over : Virtual Private Cloud (VPC). Limited to symmetric encryption : and asymmetric signing.

All key purposes are supported for keys with protection level SOFTWARE or HSM.