Securing your data

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 for VPC 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/xxxxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
           type: "public"
         - apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
           crn: "crn:v1:bluemix:public:hs-crypto:us-south:a/xxxxxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx:key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
           type: "private"
       seed:"seed1"
       kmsTimeout: 10
       apiKey: "L4SsSE32xxxxxjAgfHCVkdW8xl_CiqMn4Lpc1dzTD"
   signingKey: "xxxxxxxxx"
   
   workload: |
   volumes:
     test:
       mount: "/mnt/data"
       seed: "seed2"
       filesystem: "ext4"
   

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.

Check logs in Log Analysis if your instance shuts down.

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 for VPC 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.

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.