Google Cloud KMS Keys

GCP CryptoKey

A GCP CryptoKey represents a group of keys that serve a specific cryptographic purpose. Members of the group are identified as CryptoKey versions. Each version represents a distinctive key material and the associated algorithm. For example, a CryptoKey created for cryptographic signing may contain unalike keys, such as RSA and ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields. In practice, cryptographic key rotation keeps all the rotated keys in one group.

A cryptographic operation in GCP must detail the CryptoKey's version. Yet, some management commands may address the whole group by specifying the CryptoKey's name only.

References:

GCP Key Types

The following table summarizes supported KMSClosedKey Management System key types and BYOKClosedBring Your Own Key/non-BYOKClosedBring Your Own Key key creation options.

  Key type   Size/Curve BYOK non-BYOK
RSA 2048, 3072, 4096 √ √
ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields P256, P384, SECP256K1 √ √
AES 256 √ √
HMACClosedHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key.      

Note
CORE does not support external HMACClosedHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key. keys.

GCP Crypto Operations and Algorithms

References:

The following table summarizes UID-based crypto operations supported by AWS KMSClosedKey Management System.

Key type Decrypt Encrypt Sign Verify
RSA √   √  
ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields     √  
AES √ √    

Note
To perform an operation that requires a public key (encrypt, verify), a GCP user must obtain the public key from the KMSClosedKey Management System and perform the required operation using tools available to the user.

Users of CORE can obtain a public key by using the export command in UI or UCLClosedUnbound Command Language. UCLClosedUnbound Command Language commands that require a public key (e.g., ucl encrypt) obtain the required public key by themselves without the exporting step.

The following list summarizes KMSClosedKey Management System algorithms that can be used via CORE . Algorithms not supported by CORE are [shaded].

RSA

rsa_decrypt_oaep_
2048_sha256
3072_sha256
4096_sha256
4096_sha512

rsa_sign_pss_
2048_sha256
3072_sha256
4096_sha256
4096_sha512

rsa_sign_pkcs1_
2048_sha256
3072_sha256
4096_sha256
4096_sha512

ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields

ec_sign_
p256_sha256
p384_sha384
secp256k1_sha256

AES

256. Mode: GCM. Padding: Cloud KMSClosedKey Management System-internal metadata.

HMACClosedHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key.

hmac_sha256

GCP CryptoKey Metadata

Metadata of a crypto key comprises the shared 'main' part and, for each version, its specific data. The main part specifies the group's purpose, its 'primary' key and rotation settings. While all group members share the purpose, each group member may be set to fulfill the goal using different cryptographic algorithm.

Main metadata Version-specific metadata

See the description here

See the description here

GCP Key Management Operations

The following table compares CORE and KMSClosedKey Management System key management options and references KMSClosedKey Management System documentation for further details.

Operation CORE GCP Comment / Differences Reference
Generate √ √

Create

 
Import √ √
  • Importing a key to GCP creates a key used to pull the imported material (Version 1) and a key containing the imported material (Version 2). A user will observe that importing a key material to GCP created two versions of a key, although the first one (Version 1) contains no imported material.
  • A key imported to GCP using the CORE Import interface first stores the imported material in CORE and then triggers GCP to perform its importing procedure. The key in CORE is tagged BYOKClosedBring Your Own Key. it's linked to Version 2 of the GCP key.

Import

 
Key Policy √  

  • CORE provides a fine-grain policy down to the level of specifying permitted and restricted operations and algorithmic parameters (size, hash, padding, mode). The policy is defined for each partition, and it applies to all keys in the partition.

  • There is no key-specific policy in GCP.
  
Delete/Destroy √ √
  • CORE provides three flavors of delete: Revoke, Discard and Delete. All actions are non-reversible.
  • GCP provides Delete and Destroy options. The command may be:
    • reversed within 24 hours
    • applied to the selected key version or all versions.

Destroy

 
Cancellation of Delete   √
  • If CORE initiated the deletion of a key, you would have to link to the restored key if it is a new key. In particular, BYOKClosedBring Your Own Key features of such key in CORE are lost.
  • If the deletion of a key was initiated by GCP and the key was not deleted from CORE, then everything returns to the pre-deletion state.

Activate / Revoke

 √  
  • GCP does not support delayed activation and keeps no record of revocation reasons. The destroyed key remains in its keyring as long as the keyring is not deleted.

Destroy

 
Enable √ √

 

Enable key version

Disable √ ≈

Disable key version

Rekey √ ≈
  • GCP supports rotation of AES keys only.
  • CORE doesn't support the rotation of an external key. Yet, CORE key-sync(ALL) shall establish a link to the new key.
  • Key Rotation
    • Get Info √ √
    • Returns metadata of a logical CryptoKey and specification of the primary version.
    • To obtain version-specific data, specify the key's version.

    Get Logical Metadata

    Get Versioned Metadata

    Get Public √ √

     

    		 Get Public Key
    Get Private √  
    • Exporting private or secret key material from GCP is not allowed.
    		  

    Note: The ≈ sign indicates the availability of alternatives.

    GCP Quickstart

    In this quickstart, we prepare GCP keyring and use it from CORE:

    1. In GCP:
      1. Create a service account and obtain its credentials.
      2. Create a keyring and obtain its ID.
    2. In CORE:
      1. Create a partition that allows linking to external keystores.
      2. Extend the partition by attaching to it the above keyring.
      3. Generate RSA key in the keyring.
      4. Use the key in the crypto command.

    Steps on GCP

    In this step, we create a new GCP project and enable it to use KMSClosedKey Management System API. Then, in the project, we create a service account that will serve our partition and permit it using key management and crypto commands.

    Create KMS Project

    1. Sign in to Google Cloud Console.
    2. Create a new project (name: ub-kms)
      1. In the Select a project dialog, click the NEW PROJECT button.
      2. Create a new project in your organization. We will call it ub-kms.
      3. Switch to the new project - you are presented with its dashboard. Examine its content:
        • The Project info shows your Project ID: ub-kms.
        • The list of API is empty. Notice the Explore and Enable APIs in the Getting Started box.
        • The list of Resources is empty. But notice the Manage Resources button in the Quick Access panel.
        • Also, notice the IAM Permissions button in the Quick Access panel.
    3. Enable use of KMSClosedKey Management System API in this project:
      1. Click Explore and Enable APIs in the Getting Started box.
      2. APIs and Services page is presented with APIs enabled by default. In the top panel, click +ENABLE APIS and SERVICES button.
      3. In the presented Search form, enter KMSClosedKey Management System.
      4. Click on the presented Cloud Key Management Service (KMSClosedKey Management System) API button and then click Enable.
      5. You are presented with the Cloud Key Management Service API page. In the top panel, you see the following note "To use this API, you may need credentials. Click 'Create credentials' to get started.". Follow the recommendation and click the 'Create credentials' button.

    Create Service Account

    1. Create a service account ID for this project ( test-ub@ub-kms.iam.gserviceaccount.com)
      1. You are forwarded to the Credentials topic on the APIs and Services page.
      2. In the Which API are you using? dialog, select Cloud Key Management Service (KMSClosedKey Management System) API.
      3. In the What data will you be accessing? , select "Application data".
      4. Answer "No" to the Are you planning to use this API with Compute Engine?, and click Next.
      • You are forwarded to the Service Accounts topic in the IAM and Admin page and prompted to name the service account. Let's name it test-ub. The given name produces the Service account ID:test-ub@ub-kms.iam.gserviceaccount.com

        1. In the Grant this service account access to project select the following roles (by typing KMSClosedKey Management System in the Filter field):
        2. Click Done, and you are returned to the API and Service page.

    Obtain the Account's Credentials

    1. In the Service Accounts section of the page, click the email address for the service account you created just now.
    2. Click Keys in the Top panel.
    3. Click ADD KEY and choose to Create new key option.
    4. Select the JSON option.
    5. The private key and the following metadata regarding this service account are saved to your computer.
    6. Convert credentials JSON file to the format required by CORE .
      1. Delete all new-line characters from this file.

        2. tr -d "\n" < ub-kms-3001679e9d16.json > ub-kms.json

      2. Encode the new file using Base-64 encoder without adding new-line chars (-w 0) .

        3. base64 -w 0 ub-kms.json > ub-kms-secret.b64

        Note
        On MacOS, use base64 ub-kms.json > ub-kms-secret.b64. See here.

    Create Keyring

    Create a keyring that will be linked from our partition:

    1. From your project console, select the Security tab and click Key Management.
    2. Click + CREATE KEY RING.
      • Enter the keyring name - for example, test-kr.
      • Enter its location - for example, us-east1.
    3. Click Create.
    4. You are instantly asked to create a key, so let's follow the recommendation and create a key by name "default", leaving all the rest of the parameters at their default settings.
    5. Click Create. We just added the symmetric encrypt and decrypt key that has the "Software" Protection level. By clicking on the key name, we can check its parameters.
    6. Click actions and select Copy resource name. The result is projects/ub-kms/locations/us-east1/keyRings/test-kr/cryptoKeys/default/cryptoKeyVersions/1. We will need to link to the key from CORE .

    Summary of What We Created in GCP

      Value
    Location us-east1
    Keyring name test-kr
    Example of a Key ("default") in the keyring projects/ub-kms/locations/us-east1/keyRings/test-kr/cryptoKeys/default/cryptoKeyVersions/1
    Service Account test-ub@ub-kms.iam.gserviceaccount.com
    Account's permissions

    Cloud KMSClosedKey Management System Admin, Cloud KMSClosedKey Management System Crypto Operator

    Account's credentials ub-kms-secret.b64

    Also, on your computer, you have a secret key for the account in the Base64 encoded file - ub-kms-secret.b64.

    Steps on CORE

    Create Partition

    The Root SOClosedSecurity officer - UKC partition administrator role.:

    1. Creates a partition (hereon named "test").
    2. Allows attaching external keystores to the partition. See Create New Partition.

    Attach the Keyring

    The partition's SOClosedSecurity officer - UKC partition administrator role.:

    1. Sign-in to "test" partition.
    2. Open the Keystores section. If you don't see this option, return to Create Partition.

    3. Click Add keystore
      1. Specify an arbitrary name. We will use the keyring's name.
      2. Use the description as needed.
      3. DO NOT checkmark "Deploy as an external service".
      4. Leave Sync policy at its default setting (NONE).
      5. Click Set new credentials
        • Skip Access key ID.
        • Secret key - Paste the content of the ub-kms-secret.b64 file.
      6. Click Add parameter to specify the keyring using key-value pairs:
        • Key-name - location.
          Value - us-east1.

          • Save this parameter and click Add parameter.

        • Key-name - keyring_id.
          Value - test-kr. Save this parameter.

      7. Click Create keystore.
        The expected result is: the keystore appears in the list of the keystores. Its status is RUNNING.

    Link to External Key

    Link to the key created in the keystore.

    1. Navigate to Keys and Certificates.
    2. Hover over the + Create button and select the Link option. The Link key dialog is presented.
      • Keystore name, in our case, is already preselected.
      • External ID - projects/ub-kms/locations/us-east1/keyRings/test-kr/cryptoKeys/default/cryptoKeyVersions/1 (see Summary of What We Created in GCP).
      • Skip other fields and click Link. A new key is created in the partition.
    3. Check the result. You should see that the GCP Symmetric key for encryption/decryption resulted in an AES 256 key with the same permissions.

    Run Crypto Command

    Test encryption and decryption of the linked UID.

    1. To test the linked key using CURL, create a user that has a password.
      Let's assume that the new user's name is user1 and its password is Password1!.
    2. Let's also assume that the hostname of EP is ep1.
    3. Use UID 312f736e6f697372 to encrypt "Hello GCP".

    curl -k -X POST 'https://ep1/api/v1/keys/312f736e6f697372/encrypt?partitionId=test'\
    -u user1@test:Password1! \
    -H 'Content-Type: application/json' -d '{"clearText": "Hello GCP"}'

    {"cipherTextBase64":"CiQADAKdArx39FSXGTefqYxQ4fr62/W1n7xBPjLMbqLcNOvxLu8SMgDV2+uuekM+IDCCKjMqWq7\
    TTytwp3tDFl1Lrsv26r5jG2XlYi30xPH7RXI0O8LtEOCa"}