Securing your data

The data volume that you attach to your IBM Hyper Protect Virtual Server instance is protected by a Linux Unified Key Setup (LUKS) encryption passphrase derived from seeds provided during deployment. You can add a higher level of encryption protection and control to your data at rest by using your own key from Hyper Protect Crypto Services.

How your data volume is encrypted

Without your own key, the data volume that you attach to your instance is encrypted automatically with two seeds that are provided in the workload - volumes and env - volumes sections of the contract. The seeds are internally converted to UTF8 sequences and then concatenated. The hash (SHA256) of the concatenated sequence is computed as a hexdigest, which is used as the LUKS passphrase to encrypt the data volume. For more information, see About contract.

Protecting your sensitive data with your own key

Starting from 2.1.5, Hyper Protect Virtual Servers support integration with the key management service (KMS) Hyper Protect Crypto Services. Hyper Protect Crypto Services generates a random value as the third seed and wraps it with the CRK (customer root key). The wrapped seed is stored in the metadata partition of your data volume. The LUKS passphrase is generated by using three seeds - the seed in the metadata partition (unwrapped first) and the two seeds from the contract.

Background knowledge: From Hyper Protect Virtual Servers 2.1.4, for new Hyper Protect Virtual Server instances, the data volume is partitioned into two parts. The first partition (100 Mib) is reserved for internal metadata only (not to be accessed by a workload); the second partition remains as the data volume for workload. Only new volumes are partitioned.

Integration with key management service

Note: Currently, only Hyper Protect Crypto Services is supported as the key management service.

The following table is a summary of the seeds. The third seed is the one provided by your key management service.

Table 1. Seeds that are used to generate the LUKS encryption passphrase
Seed Provider From Required or optional
seed1 Deployer persona env - volumes section of the contract Required
seed2 Workload persona workload - volumes section of the contract Required
seed3 Hyper Protect Crypto Services Hyper Protect Crypto Services generates the third seed and wraps it with the CRK only if kms details are provided in the contract. This is done by Hyper Protect Virtual Servers calling a wrap API. The wrapped seed is stored in the metadata partition of the data volume. Optional

LUKS passphrase generation

The key daemon is started if the volume is secured with protection from the KMS instance. It's responsible for reacting to status changes of the CRK (which will be introduced later in this documentation).

About customer-managed keys

Hyper Protect Virtual Servers use envelope encryption to implement customer-managed keys. Envelope encryption describes encrypting (wrapping) one encryption key with another encryption key. In our case, the wrapped key is the third seed, and the key that's used to wrap the seed is the CRK from Hyper Protect Crypto Services.

You own the CRK in Hyper Protect Crypto Services. Hyper Protect Virtual Servers never see the CRK. Its storage, management, and use to wrap and unwrap the seed is performed entirely within the key management service.

Hyper Protect Crypto Services is backed by FIPS 140-2 Level 4-certified hardware, which is the highest offered by any cloud provider in the industry. For more information, see Getting started with Hyper Protect Crypto Services. The table shows the behavior of a virtual server during startup, the number of volumes that are attached to the partition during the startup, and the input that is specified in the contract file.

Enabling customer-managed keys for Hyper Protect Virtual Servers

Whether you can enable the feature depends on the history of the Hyper Protect Virtual Server instance (partition layout and LUKS encryption) and the contract information. See the following table for possible scenarios and results. If you don't know what kms details in the contract mean, see the instructions in Steps.

Table 1. Scenarios
Number of partitions in the data volume Metadata partition Contract Whether the partition/second partition is LUKS encrypted Behavior of Hyper Protect Virtual Server
0 N/A Has kms details Not LUKS encrypted The instance creates two partitions in the data volume, calls Hyper Protect Crypto Services to generate a third seed and wrap it with the CRK. The wrapped seed is stored in the metadata partition. Then the instance generates a LUKS passphrase with the seed (unwrapped first) and the two seeds from the contract to encrypt the second partition.
0 N/A Has kms details LUKS encrypted The instance shuts down. You need to remove the kms details in the contract.
1 N/A Not supported. The instance shuts down.
2 No encrypted seed Has kms details (one entry) Not LUKS encrypted The instance calls Hyper Protect Crypto Services to generate a third seed and wrap it with the CRK. The wrapped seed is stored in the metadata partition. Then the instance generates a LUKS passphrase with the seed (unwrapped first) and the two seeds from the contract to encrypt the second partition.
2 No encrypted seed Has kms details (one entry) LUKS encrypted Similar flow as the previous one to re-encrypt the second partition. The old LUKS passphrase is replaced. Note that the two seeds from env and workload need to be the same as before; otherwise the re-encryption fails and the instance shuts down. Provide the correct seeds and retry.
2 No encrypted seed Has kms details (multiple entries) Not LUKS encrypted Similar flow as the previous scenarios to wrap the third seed and encrypt the second partition. Only the configuration in the first entry is used to wrap the third seed.
2 Has an encrypted seed Has kms details (one entry) Not LUKS encrypted It's possible that you used the volume in previous provisioning but the encryption was unsuccessful, or you provided the volume with two partitions and manually created a random value as the third seed, wrapped it, and stored it in the metadata partition. In either case, the instance checks if the partitioning is correct. If not, the instance shuts down. If the partitioning is correct, the instance calls Hyper Protect Crypto Services to unwrap the encrypted seed and generates a LUKS passphrase with the seed and the two seeds from the contract to encrypt the second partition.
2 Has an encrypted seed Has kms details (one entry) LUKS encrypted The instance calls Hyper Protect Crypto Services to unwrap the encrypted seed and opens the LUKS layer on the data partition.
2 Has an encrypted seed Has kms details (multiple entries) The instance calls Hyper Protect Crypto Services to unwrap the encrypted seed with the first kms entry. If it fails, it uses the next entry. When it succeeds, it uses the first configuration to rewrap the seed. If all the entries don't work, the instance shuts down.
2 Has an encrypted seed No kms details The instance shuts down. You need to provide kms details in the contract.

Note: Check logs in Log Analysis if your instance shuts down.

Steps

  1. Provision a Hyper Protect Crypto Services instance and create a root key. For more information, see Creating root keys.

    To enhance security, it's recommended to use virtual private endpoints with Hyper Protect Crypto Services.

  2. When you prepare the contract, add kms details in the env - volumes section, and then use the contract to create a Hyper Protect Virtual Server instance. For example:

    env: |
      logging:
      logDNA:
        hostname: syslog-a.eu-gb.logging.cloud.ibm.com
        ingestionKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        port: 6514
    volumes:
     test:
       kms:
         - apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
           crn: "crn:v1:bluemix:public:hs-crypto:us-south:a/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
           type: "public"
         - apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
           crn: "crn:v1:bluemix:public:hs-crypto:us-south:a/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
           type: "private"
       seed:"seed1"
       kmsTimeout: 10
    signingKey: "xxxxxxxxx"
    
    workload: |
    volumes:
      test:
        mount: "/mnt/data"
        seed: "seed2"
        filesystem: "ext4"
    

Important: To avoid misuse of the KMS details by an attacker, it's strongly recommended for the deployer (who provides the env section) to encrypt and sign the contract. For more information about encryption, see Contract encryption. For the signature, add a public signing key (signingKey field) to your env section and sign the entire contract by adding a envWorkloadSignature section to the contract. The purpose of the signature is to ensure that the workload and env sections are always used together and are not tampered with by a third party. For more information, see Contract signature.

  • kms

    In the kms field, always put the KMS configuration that you want to use as the first entry. The entries that follow are older KMS configurations (used to decrypt the wrapped seed before you migrate to the current configuration). A maximum of five entries are supported. For more information about changing KMS configurations, See Changing to a different Hyper Protect Crypto Service instance or root key.

    If the kms details from the contract are not valid, the instance shuts down immediately.

  • kmsTimeout

    You can specify kmsTimeout (between 0 - 1000 minutes) in the contract. If not specified, the default timeout value is 10 minutes. This value determines how long the instance will try to unwrap the seed during initial boot or reboot. When this timeout elapses, messages are logged and the instance shuts down.

  • type

    You use this field to specify the instances as "private" when it is in a private network and "public" when it is in the public network. This is used to support switching to a different Hyper Protect Crypto Services instance or CRK.

If your volume is new, the instance creates two partitions in the data volume, calls Hyper Protect Crypto Services to generate a third seed and wrap it with the CRK. The wrapped seed is stored in the metadata partition. Then the instance generates a LUKS passphrase with the seed (unwrapped first) and the two seeds from the contract to encrypt the second partition.

You can also choose to manually create two partitions in a volume, create a random value as the third seed, wrap it, and store it in the metadata partition:

  1. Create two partitions on the block device using the linux command parted.

    • 1st partition is labeled as metadata and is of length 100 MiB (note that the metadata partition is reserved for internal metadata only and not to be accessed by a workload). Create a file system (ext4) before using the partition. Create a file by the name keyfile.
    • 2nd partition is labeled as data and fills up the full disk space.
  2. Use the Hyper Protect Crypto Services KMS API Wrap a key to generate a random plain text that is rooted in an HSM and wrap it without passing the value.

  3. Copy the ciphertext returned from the response object to keyfile with linux commands.

  4. Prepare the contract with the KMS information and create a Hyper Protect Virtual Server instance with the manually partitioned volume that contains a wrapped seed.

When the instance is running, the key daemon periodically contacts the Hyper Protect Crypto Services instance. The same timeout kmsTimeout applies. If the Hyper Protect Crypto Services instance cannot be reached, the state of the CRK is not Active, or the access parameters (kms details) no longer match, the daemon will trigger a reboot.

Note: Check logs in Log Analysis if your instance shuts down.

Working with customer-managed keys for Hyper Protect Virtual Servers

Rotating the root key

If the CRK is rotated manually or automatically based on a key rotation policy, the key daemon detects the key rotation and rewraps the seed.

Changing to a different Hyper Protect Crypto Service instance or root key

If you want to use a different Hyper Protect Crypto Service instance or a different root key ID, put the new KMS configuration as the first entry in the contract and recreate a Hyper Protect Virtual Server instance. Leave the old KMS configuration (which is currently being used) in the contract. During instantiation, Hyper Protect Virtual Server unwraps the encrypted seed with the old configuration and uses the new configuration to rewrap the seed. A maximum of five entries are supported in the contract.

After the change is done, the old entries can be removed from the next interaction.

Disabling the root key

If you disable the root key, the state of the key becomes Suspended. The key daemon of Hyper Protect Virtual Servers for VPC periodically checks the state of the CRK. If the state is not Active, the virtual server reboots. During the reboot, the Key Daemon keeps checking the state by polling, and when the time it takes exceeds kmsTimeout, the virtual server shuts down. You need to enable the root key to bring the key back to Active.

Important: Make sure that your CRK is not expired. Otherwise, its state becomes Deactivated, and the virtual server reboots and eventually shuts down. For more information about key states, see Monitoring the lifecycle of encryption keys.