Configuring volumes in the environment section

About environment volume configuration

The environment section of the contract contains the data seed for volume encryption. This seed is combined with the workload seed (provided by the Solution Provider) to encrypt the volume data. The data seed ensures that only authorized parties can access the encrypted storage.

Prerequisites

• You have the public.pem file from the Auditor.
• You have the encrypted-workload.yaml file from the Solution Provider.
• You have the device name used in the workload configuration.
• You have configured IBM Cloud Logs instance and obtained the public ingress endpoint and IAM API key.

Procedure

1. Set the device name that matches the workload configuration:

   export DEVICE_NAME="pvb_storage"

2. Generate a data seed for volume encryption:

   export DATA_SEED="$(openssl rand -base64 32)"

   Important: Store this seed securely. The data seed is required for every pod restart with the same storage. Losing this seed will result in permanent data loss, as the data in the block volume is encrypted using this seed.
3. Set the signing key value:

   export SIGNING_KEY=$(awk -vRS="\n" -vORS="\\\n" '1' public.pem)

4. Set the public ingress endpoint and IAM API key:

   export PUBLIC_INGRESS_ENDPOINT=<your_public_ingress_endpoint>
   export IAMAPIKEY=<your_ibm_cloud_iamapikey>

5. Create the env.yaml file with volume configuration:

   cat << EOF > env.yaml
   type: env
   logging:
     logRouter:
       hostname: ${PUBLIC_INGRESS_ENDPOINT}
       iamApiKey: ${IAMAPIKEY}
       port: 443
   volumes:
     ${DEVICE_NAME}:
       seed: "${DATA_SEED}"
   signingKey: "${SIGNING_KEY}"
   EOF

6. For multiple volumes, add additional volume entries:

   cat << EOF > env.yaml
   type: env
   logging:
     logRouter:
       hostname: ${PUBLIC_INGRESS_ENDPOINT}
       iamApiKey: ${IAMAPIKEY}
       port: 443
   volumes:
     ${DEVICE_NAME}:
       seed: "${DATA_SEED}"
     pvb_storage2:
       seed: "${DATA_SEED_2}"
   signingKey: "${SIGNING_KEY}"
   EOF

   Note: Each volume must have a corresponding entry in both the workload and environment sections with matching device names.
7. Set the contract key variable:

   export CONTRACT_KEY="ibm-confidential-computing-container-encrypt.crt"

8. Encrypt the environment section:

   export ENV="env.yaml"
   export PASSWORD="$(openssl rand 32 | base64 -w0)"
   export ENCRYPTED_PASSWORD="$(echo -n "$PASSWORD" | base64 -d | openssl rsautl -encrypt -inkey $CONTRACT_KEY -certin | base64 -w0)"
   export ENCRYPTED_ENV="$(echo -n "$PASSWORD" | base64 -d | openssl enc -aes-256-cbc -pbkdf2 -pass stdin -in "$ENV" | base64 -w0)"

9. Combine the encrypted workload and environment sections:

   cp encrypted-workload.yaml encrypted-contract.yaml
   echo "env: hyper-protect-basic.${ENCRYPTED_PASSWORD}.${ENCRYPTED_ENV}" >> encrypted-contract.yaml

10. Verify the encrypted contract file:

    cat encrypted-contract.yaml

    Example output:

    workload: hyper-protect-basic.d458ARMC89mB0ymq3we6LDHFaF8oWVB6Nn5fvbFhJvMm2xFDnF..........
    env: hyper-protect-basic.jV8dP1V7IX+IY6cjYeIBQc5xtAjR2jnMksQD8JLeswAR5YBPT1DnwwPfo..........

11. Share the encrypted-contract.yaml file with the Auditor for signing.

Volume seed management

Both the workload seed and data seed are critical for volume encryption:

• Workload seed: Provided by the Solution Provider in the workload section
• Data seed: Provided by the Data Owner in the environment section

The combination of both seeds encrypts the volume data. Both seeds must be preserved and used consistently across pod restarts to maintain access to the encrypted data.

Next steps

After configuring volumes in the environment section, proceed with the standard contract creation workflow:

1. The Auditor signs the contract as described in Creating a contract signature.
2. The Data Owner creates the boot section as described in Create a boot section.
3. The Data Owner deploys the pod with volume attachments as described in Verifying the contract.