Skip to main content

Integrations

This document provides the necessary information to set up the Key Providers that CYBERCRYPT K1 support. These are currently:

Google Cloud KMS​

Follow these steps to set up Google Cloud KMS for use with K1:

  1. Enable the Cloud Key Management Service (KMS) API. Follow KMS quickstart tutorial or run gcloud services enable cloudkms.googleapis.com from Cloud Shell.
  2. Follow instructions from section Create a Keyring and Cryptokey or create a Keyring and CryptoKey using Cloud Console UI by going to the Navigation menu > Security > Key management. Choose protection level Software or HSM. Specify the purpose of a key: Symmetric encrypt/decrypt. Alternatively, you can import your own key.
  3. Create a service account by going to the Navigation menu > IAM & Admin > Service Accounts. Create a Service Account and assign one of the below:
    • Cloud KMS Crypto Operator role (grants all necessary permissions)
    • custom role from Cloud KMS CryptoKey Encrypter/Decrypter with additional cloudkms.locations.generateRandomBytes permission
  4. Create a key pair for the service account by selecting a newly created account and going to Keys section. You can create a new key or import an existing one. Choose a recommended JSON format. The private key will be automatically downloaded to your device.
  5. Place this file in secure location and refer to it in GOOGLE_APPLICATION_CREDENTIALS env variable (see section below).
  6. To view the logs for performed operations, follow instructions from section View Cloud Audit Logs.

To enable Google Cloud KMS in K1 you need to:

  1. Set/uncomment gcloudkms settings in the config file.

    • location - the project-specific location of Google Cloud HSM; it is used only for key generation, and because generating random bytes supports only HSM protection level, this location must also support Cloud HSM; example: projects/projectID/locations/europe-north1
    • keyname - the resource name of CryptoKeyVersion to use for symmetric encryption/decryption; example: projects/projectID/locations/europe-north1/keyRings/keyRingName/cryptoKeys/keyName

    Since location and keyname are used for different API calls, the locations do not have to be common for both.

  2. Set environment variable for Google credentials imported in previous step.

    export GOOGLE_APPLICATION_CREDENTIALS="your-location/{projectId}-{privateKeyIdPrefix}.json"

Azure Key Vault​

Follow these steps to set up Azure Key Vault for use with K1:

  1. Create a key vault as per quickstart tutorial. Choose Premium pricing tier as it includes support for HSM backed keys. Assign a previously created resource with chosen subscription.
  2. Create a key in a key vault. It is essential to choose RSA-HSM key type with 4096 key size!
  3. Register an application and add a client secret. Remember to copy the value of a secret to the safe location.
  4. Add access policy in the key vault. Select registered app as a principal and assign key permissions: wrap key, unwrap key, sign, verify.

To enable Azure Key Vault in K1 you need to:

  1. Set/uncomment azurekeyvault settings in the config file.

    • vaulturi - key vault URI, example: https://keyVaultName.vault.azure.net/
    • keyname - name of the key created in Azure Key Vault; must allow wrap key, unwrap key, sign, verify operations
    • keyversion - version of the key specified above; optional, will use current version if not specified

  2. Set environment variables. You can find tenant ID and client ID in the overview of the app registered in step 3 above.

    export AZURE_TENANT_ID="{tenantId}"
    export AZURE_CLIENT_ID="{applicationId}"
    export AZURE_CLIENT_SECRET="{secretValue}"

AWS KMS​

Follow these steps to set up AWS KMS for use with K1:

  1. Go to Key Management Service and choose the region closest to your location.
  2. Create a symmetric key. The KEY_SPEC should be SYMMETRIC_DEFAULT. Save the key ID or ARN.
  3. Create IAM policy. Choose service KMS, actions: Encrypt, Decrypt, GenerateRandom from Write access level. Add the key details to restrict access to a single key.
  4. Create IAM user. Choose Access key - Programmatic access as the AWS access type. Attach existing policies directly -> choose a newly created policy. Save the credentials.

The default setting is to use a standalone key wrapper. To enable AWS KMS you need to:

  1. Set/uncomment awskms settings in the config file.

    • region - an AWS Region, in which the KMS resource was created; all regions examples e.g. eu-north-1
    • keyid - ID of a symmetric KMS key; example: 1234abcd-12ab-34cd-56ef-1234567890ab

  2. Set access credentials. The order of loading credentials can be found here.

    • By default the application will look for environment variables
      export AWS_ACCESS_KEY_ID="{keyID}"
      export AWS_SECRET_ACCESS_KEY="{secretKey}"
    • If no env variables are set, the app will look for $HOME/.aws/credentials file. You can configure it with aws configure command or set it up manually. You can also change location of the file by setting
      export AWS_SHARED_CREDENTIALS_FILE=$HOME/my_shared_credentials

OASIS KMIP​

The OASIS KMIP version that is currently supported is 1.4.

To enable OASIS KMIP, you need to:

  1. Set/uncomment kmip settings in the config file.

    • endpoint - the KMIP server endpoint given as "host:port"
    • cacertpath - path to Certificate Authority certificate file
    • certpath - path to client certificate file
    • keypath - path to client certificate key file
    • keyid - ID of a symmetric key given as a string; example: "1". The key must be activated after it has been created.