Creating an encrypted custom image

How encrypted custom images work

After you encrypt a custom image with your own passphrase, you upload it to IBM Cloud Object Storage. Before you import the encrypted image to IBM Cloud VPC, you need to set up a key management service (KMS) and create a customer root key (CRK). Then, use your CRK to protect the passphrase that you use to encrypt your image. By wrapping your secret passphrase with your CRK, you create what the KMS refers to as a wrapped data encryption key (WDEK). Wrapping your passphrase data encrypts it and secures it so that you never need to share your passphrase in plain text.

When you import the image, you must specify the cloud resource name (CRN) for your customer root key (CRK) that is stored in your KMS. You must also specify the ciphertext for your wrapped data encryption key (WDEK). The passphrase is stored encrypted in the WDEK always. It is only unwrapped when a virtual server that uses the encrypted image is started.

When you're ready to provision a virtual server with the encrypted image, the encryption information isn't needed. The WDEK and the CRN of the CRK are stored as metadata with the image. For more information, see About encrypted custom images.

Overview of encrypted image process

The following steps summarize the high-level process that you need to complete to be successful with creating and importing an encrypted image. Subsequent sections provide details on how to complete the steps.

1. Create an encrypted image by using QEMU and a passphrase of your choice to encrypt a qcow2 file with LUKS encryption.
2. Upload the encrypted image file to IBM Cloud Object Storage.
3. Provision a key management service, create a customer root key (CRK), and then wrap your passphrase with the CRK to generate a wrapped data encryption key (WDEK).
4. Ensure that you have the required IBM Cloud Identity and Access Management authorizations so that you can import the image from IBM Cloud Object Storage and so that your WDEK can be used for data encryption.
5. Import the image to IBM Cloud VPC. You must specify IBM Cloud Object Storage location, the CRK that is stored in your KMS, and your WDEK ciphertext.

Encrypting the image

In this step, you use QEMU to specify your own passphrase and encrypt your custom image with LUKS encryption.

The custom image that you plan to encrypt must meet the custom image requirements for IBM Cloud VPC infrastructure. Confirm that you completed the image preparation requirements in the following topics:

• Getting started with custom images
• Creating a Linux custom image
• Creating a Windows custom image

To complete the encryption task, you must have QEMU version 2.12 or later installed.

You must use a Linux or Windows operating system to complete the QEMU encryption instructions. Mac operating system is not supported.

Complete the following steps by using QEMU to create a second encrypted qcow2 file of your custom image.

1. Determine your own passphrase to use for encrypting your image. The sample commands in this task use the passphrase abc123. Keep your passphrase available. Later you need to wrap the passphrase to create a wrapped data encryption key (WDEK). The WDEK is required when you import the image to IBM Cloud VPC.

2. Verify your current qcow2 custom image by using the following command:

   qemu-img info my_100G_custom_image.qcow2
   

   For this example, you'd see a response similar to the following output:

   image: my_100G_custom_image.qcow2
   file format: qcow2
   virtual size: 100 GiB (107374182400 bytes)
   disk size: 1.28 GiB
   cluster_size: 65536
   Format specific information:
       compat: 1.1
       lazy refcounts: false
       refcount bits: 16
       corrupt: false
   

3. Create a new, empty qcow2 file of the exact same size and encrypt it with LUKS encryption. Use the passphrase that you choose, for example, abc123, to encrypt the file:

   qemu-img create --object secret,id=sec0,data=abc123 -f qcow2 -o encrypt.format=luks,encrypt.key-secret=sec0 my_100G_custom_image-encrypted.qcow2 100G
   

4. Convert your qcow2 image, my_100G_custom_image.qcow2 to the encrypted image, my_100G_custom_image-encrypted.qcow2.

   qemu-img convert --object secret,id=sec0,data=abc123 --image-opts driver=qcow2,file.filename=my_100G_custom_image.qcow2 --target-image-opts driver=qcow2,encrypt.key-secret=sec0,file.filename=my_100G_custom_image-encrypted.qcow2 -n -p
   

5. Compare the two files to verify that they are identical.

   qemu-img compare --object secret,id=sec0,data=abc123 --image-opts driver=qcow2,file.filename=my_100G_custom_image.qcow2  driver=qcow2,encrypt.key-secret=sec0,file.filename=my_100G_custom_image-encrypted.qcow2 -p
   

6. Check the file for errors.

   qemu-img check --object secret,id=sec0,data=abc123 --image-opts driver=qcow2,encrypt.key-secret=sec0,file.filename=my_100G_custom_image-encrypted.qcow2 
   

   For this example, you'd see a response similar to the following output:

   No errors were found on the image.
   16343/1638400 = 1.00% allocated, 0.00% fragmented, 0.00% compressed clusters
   Image end offset: 1074790400
   

7. Run info on your new, encrypted file to verify that it is the size and encryption level you expect.

   qemu-img info my_100G_custom_image-encrypted.qcow2
   

   For this example, you'd see a response similar to the following output:

   image: my_100G_custom_image-encrypted.qcow2
   file format: qcow2
   virtual size: 100 GiB (107374182400 bytes)
   disk size: 1.27 GiB
   cluster_size: 65536
   Format specific information:
       compat: 1.1
       lazy refcounts: false
       refcount bits: 16
       corrupt: false
   

Upload the encrypted image to IBM Cloud Object Storage

When your image file is encrypted with LUKS encryption and your unique passphrase, you can upload it to IBM Cloud Object Storage by completing the following steps:

1. Make sure that your customized image file has a descriptive name so that you can easily identify it later.
2. On the Objects page of your IBM Cloud Object Storage bucket, click Upload. You can use the Aspera high-speed transfer plug-in to upload images larger than 200 MB.

Setting up your key management service and keys

To import an encrypted custom image to IBM Cloud VPC, you need a key management service provisioned. You also need a customer root key (CRK) and a wrapped data encryption key (WDEK). The WDEK is the passphrase that you used to encrypt your image wrapped with your CRK so that your passphrase remains known only to you. The WDEK is used to access the encrypted image when a virtual server instance that uses the encrypted image is started.

The following list is a summary of the key management prerequisites:

• Provision a supported key management service, either Key Protect or Hyper Protect Crypto Services.
• Import a customer root key (CRK) to the key management service or create one in the key management service.
• Wrap (protect) the passphrase that you used to encrypt your image with your customer root key to create a wrapped data encryption key (WDEK).

The following example steps are specific to Key Protect, but the general flow also applies to Hyper Protect Crypto Services. If you're using Hyper Protect Crypto Services, see the Hyper Protect Crypto Services information for corresponding instructions.

1. Provision the Key Protect service.

   Provisioning a new Key Protect service instance ensures that it includes the most recent updates that are required for customer-managed encryption.

2. Create or import a customer root key (CRK) in IBM Key Protect.

   Plan ahead for importing keys by reviewing your options for creating and encrypting key material. For added security, you can enable the secure import of the key material by using an import token to encrypt your key material before you bring it to the cloud.

3. Use your customer root key (CRK) to wrap, or protect, the unique passphrase that you used to encrypt your image with LUKS encryption. In the image encryption example, we used the passphrase abc123.

   1. Make sure that the Key Protect CLI plug-in is installed so that you can generate a WDEK. For more information, see Installing the Key Protect CLI plug-in.

   2. Encode your passphrase with Base64 encoding to prepare it for wrapping with your CRK. Run the following command, substituting your passphrase for abc123. The -n parameter is required so that you don't encode a new line character, which causes the wrapped passphrase to not work.

      echo -n "abc123"|base64
      

      For this example, you'd see a response similar to the following output:

      YWJjMTIz
      

   3. Wrap your encoded passphrase with your CRK by running the ibmcloud kp key wrap command. While the passphrase that is used to generate the encrypted image is not technically a data encryption key, it is the terminology that Key Protect uses for data in wraps and unwraps. The data that is returned from Key Protect is referred to as the WDEK. For more information, see kp key wrap.

      ibmcloud kp key wrap KEY_ID -i INSTANCE_ID -p PLAINTEXT
      

      Where KEY_ID is the ID of the root key that you want to use for wrapping, INSTANCE_ID is the instance ID that identifies your Key Protect service instance, and PLAINTEXT is your encoded passphrase. For example, YWJjMTIz.

      For this example, you'd see a response similar to the following output:

      Wrapping key...
      SUCCESS
      Ciphertext
      eyJjaXBoZXJ0ZXh0IjoiKzhjbHVqcUNP ...<redacted>... NmY3MTJjNGViIn0=
      

   4. Save, or persist to storage, the ciphertext for the WDEK. You must specify the WDEK ciphertext when you import your encrypted image to IBM Cloud VPC.

IAM authorization prerequisites

Make sure that you created the required authorizations in IBM Cloud Identity and Access Management.

1. From IBM Cloud Identity and Access Management (IAM), create an authorization between Cloud Block Storage (source service) and your key management service (target service). The authorization permits the IBM Cloud backplane services to use your WDEK for data encryption.
2. Make sure that you created an IAM authorization between the Image Service for VPC and IBM Cloud Object Storage. Specify Infrastructure Services as the source service. Specify Image Service for VPC as the resource type. Specify IBM Cloud Object Storage as the target service. The authorization is so that the Image Service for VPC can access images in IBM Cloud Object Storage. For more information, see Granting access to IBM Cloud Object Storage to import images.

Next steps

When your image is successfully encrypted, your KMS is set up, and you created the required keys, you can import the image to IBM Cloud VPC. When the image is available in IBM Cloud VPC, you can use it to provision instances. Make sure that you have Granted access to IBM Cloud Object Storage to import images.

When you are ready to provision a new virtual server instance with the encrypted image, no encryption information is needed. The wrapped data encryption key (WDEK) and the CRN of the customer root key (CRK) are stored as metadata with the image.