Attestation

Attestation is a process that starts by default at virtual instance creation, ensures that the virtual server instance image is indeed built by IBM, and that it was not modified. This process also provides information and allows validation of any data that is provided to the instance at the time of deployment.

When you create a virtual server instance by using the IBM Hyper Protect Container Runtime image, the image uses an initial file system that is protected by encryption and signed by IBM Secure Execution. For more information, see Confidential computing with LinuxONE. To know more about the attestation process, see this video.

The boot process creates a unique root disk encryption key to ensure protection of the root disk. To perform attestation, the virtual server instance image contains an attestation-signing key and the hash of the root partition at build time. The boot process validates the root partition. If the hash of the root partition does not match, the boot process does not continue because it assumes that the image was modified before boot. The attestation signing key is a random RSA 4 K key that is signed by an IBM root key that is maintained in Hyper Protect Crypto Services. The IBM root key is signed by Digicert.

During deployment of the virtual server instance in the cloud, an attestation record is created. It contains hashes of the following items:

• The original base image
• The root partition at the moment of the first boot
• The root partition at build time
• The cloud initialization options

The attestation record is signed by the attestation key. As an extra protection layer, you can provide a public key during deployment, against which the attestation record is encrypted. The hash of this public key is added to the attestation record to ensure that the record can be viewed only by the compliance authority, and the expected authority can be easily identified through that hash.

Before you upload any workload to your instance, you need to validate the attestation record. After an instance is created, you can validate the attestation record within the created instance. Your instance must have access to the /var/hyperprotect directory. If so, follow these procedures:

• The attestation record is signed by the attestation signing key.
• The attestation signing key can be confirmed by the IBM intermediate certificate. The IBM intermediate certificate is signed by DigiCert, which is proven by the root certificate of DigiCert, thus completing the chain of trust.

The encryption and attestation certificates are signed by the IBM intermediate certificate and this has been signed by the IBM Digicert intermediate cert (which in turn is signed by DigiCert Trusted Root G4). For more information about the certificates, see DigiCert Trusted Root Authority Certificates.

Use the following procedure to validate the attestation record and hashes:

• Obtain the attestation record se-checksums.txt and the signature file se-signature.bin from your Hyper Protect Virtual Servers for VPC instance. To do so, you can implement your container to provide the attestation record and the signature file. The attestation record and the signature file are made available to your container in the /var/hyperprotect directory.

• Get the IBM attestation certificate. The following table lists the expiry dates for the attestation certificates based on the version of the image.

  Attestation certificate expiry dates

  Image version	Certificate link	Expiry date
  ibm-hyper-protect-container-runtime-1-0-s390x-19	certificate	19 September 2025
  ibm-hyper-protect-container-runtime-1-0-s390x-18	certificate	01 August 2025
  ibm-hyper-protect-container-runtime-1-0-s390x-17	certificate	04 July 2025
  ibm-hyper-protect-container-runtime-1-0-s390x-16	certificate	11 June 2025
  ibm-hyper-protect-container-runtime-1-0-s390x-15	certificate	8 March 2025
  ibm-hyper-protect-container-runtime-1-0-s390x-14	certificate	29 November 2024
  ibm-hyper-protect-container-runtime-1-0-s390x-13	certificate	02 November 2024

• Validate the attestation certificate by following the instructions here.

• Extract the encryption public key from the encryption certificate by using the following command:

  openssl x509 -pubkey -noout -in ibm-hyper-protect-container-runtime-1-0-s390x-19-attestation.crt > contract-public-key.pub
  

• Verify the signature of the attestation record:

  openssl sha256 -verify contract-public-key.pub -signature se-signature.bin se-checksums.txt
  

  Signature verification must be done on a decrypted attestation file.

• You can now use the hashes from the attestation record for validation.

In case you provided a public key for encrypting the attestation record, the following script might help in decrypting the record.

#!/bin/bash
#
# Example script to decrypt attestation document.
#
# Usage:
#   ./decrypt-attestation.sh <rsa-priv-key.pem> [file]
#
# Token Format:
#   hyper-protect-basic.<ENC_AES_KEY_BASE64>.<ENC_MESSAGE_BASE64>


RSA_PRIV_KEY="$1"
if [ -z "$RSA_PRIV_KEY" ]; then
    echo "Usage: $0 <rsa-priv-key.pem>"
    exit 1
fi
INPUT_FILE="${2:-se-checksums.txt.enc}"
TMP_DIR="$(mktemp -d)"
#trap 'rm -r $TMP_DIR' EXIT


PASSWORD_ENC="${TMP_DIR}/password_enc"
MESSAGE_ENC="${TMP_DIR}/message_enc"


# extract encrypted AES key and encrypted message
cut -d. -f 2 "$INPUT_FILE"| base64 -d > "$PASSWORD_ENC"
cut -d. -f 3 "$INPUT_FILE"| base64 -d > "$MESSAGE_ENC"

# decrypt password
PASSWORD=$(openssl pkeyutl -decrypt -inkey "$RSA_PRIV_KEY" -in "$PASSWORD_ENC")

# decrypt message
echo -n "$PASSWORD" | openssl aes-256-cbc -d -pbkdf2 -in "$MESSAGE_ENC" -pass stdin --out se-checksums.txt

In the case of a docker container, the decrypt-attestation.sh file can be accessed by mounting /var/hyperprotect in the docker container. For example,

 volumes:
      - "/var/hyperprotect/:/var/hyperprotect/:ro"

In the case of a Podman container, the decrypt-attestation.sh file can be accessed by mounting /var/hyperprotect in the Podman container. For example,

 volumeMounts:
     - name: attestation
       readOnly: true
       mountPath: /var/hyperprotect:Z,U

/var/hyperprotect/
|-- cidata
|   |-- meta-data
|   |-- vendor-data
|-- se-checksums.txt
|-- se-signature.bin
|-- se-version
|-- user-data.decrypted

sha256sum <file>

24.8.0
Machine Type/Plant/Serial: 8562/02/4C578
4802242b82dce78d11c4b02129a9b9c1e62598b1cb8073f8e7b097449644bbb4 root.tar.gz
f9940321d043d133ddf2f22cd4794bc56be9d54b2e9c7893a6d6a4813635024c baseimage
41e32bac07e1eac019b40707f1cedf8356830a690108dc35dc07aa160a61a09e /dev/disk/by-label/cidata
6e78289af3fd2d265e0ee06289b46b9692046fa8af0f25711ee11cc6c5b0a45a cidata/meta-data
194d230a7d0d0fa5657a963d21e3291064f988e9df719b4f2b4db4de2746eccd cidata/user-data
ab65daacc8ca30ddbfe2fbdd5a93b8b6f9f92b7145fcae42fc61f4501f361658 cidata/vendor-data
38e1f81c213d93d3ff39a94de47cfebb6f7309528da3249546439c1de7683874 contract:env 
de4178e749c6ab0ee9af8610d0615cfd004d7d488dfdc0d5aa87e0b75fdff7fc contract:envWorkloadSignature 
8bfaf247e3f3936c446de151da1613d2e7e5440ba0d95065e7048e14626f4e2f contract:workload

b3fb54a3bb57fcbba070c456d7394fb5e7a4f9b1febaec0efc32c5aa0e325071 baseimage

f9940321d043d133ddf2f22cd4794bc56be9d54b2e9c7893a6d6a4813635024c baseimage

f9940321d043d133ddf2f22cd4794bc56be9d54b2e9c7893a6d6a4813635024c baseimage

4330056bbbf5d53d48fa167f0f46bf4501b8ee42bd926e1a8b6c25d210cd1baf baseimage

d8e069345618143ce0948044cab27ba52ffc53eaba987d353bb5ab59f3ad2390 root.tar.gz

4802242b82dce78d11c4b02129a9b9c1e62598b1cb8073f8e7b097449644bbb4 root.tar.gz

4802242b82dce78d11c4b02129a9b9c1e62598b1cb8073f8e7b097449644bbb4 root.tar.gz

0bf377eea1136f03cbd5fbb1f2d12bb9a40a3e9f97a8438196b549fdafd0786e root.tar.gz

6e78289af3fd2d265e0ee06289b46b9692046fa8af0f25711ee11cc6c5b0a45a cidata/meta-data
194d230a7d0d0fa5657a963d21e3291064f988e9df719b4f2b4db4de2746eccd cidata/user-data
ab65daacc8ca30ddbfe2fbdd5a93b8b6f9f92b7145fcae42fc61f4501f361658 cidata/vendor-data

bb66b161d095e4cf336ebef4f7bd000ff9631ca2d1f427dd1f88e8ba6cfa0baf contract: attestationPublicKey

 volumes:
      - "/var/hyperprotect/:/var/hyperprotect/:ro"

 volumeMounts:
     - name: attestation
       readOnly: true
       mountPath: /var/hyperprotect:Z,U

Understanding attestation flows

The following diagram shows two scenarios for attestation from the point of view of the auditor to validate that the deployment is the expected one. The left side of the diagram shows the establishment of trust by the auditor who is rooted on a third-party certificate authority. Any key used is kept in a Hyper Protect Crypto Service and signed in a certificate chain based on the third-party authority. The Build environment that is used by Hyper Protect is running in a trusted execution environment by using IBM Secure Execution Technology.

The result is a secure execution image that is seen at the end of the diagram, which is an encrypted secure execution image. To the right of the diagram, the validation of the deployment is outlined. For this, the auditor includes into the encrypted workload contract of the IBM Hyper Protect instance, the public key of a secret, which only the auditor has control over. Such secrets might be protected by appropriate means, like a Hyper Protect Crypto Service, HSM or just a random key. Only the Hyper Protect bootloader that is executed in the trusted execution environment provided through IBM Secure Execution for Linux on IBM LinuxONE, can run the secure execution image of IBM Cloud Hyper Protect Virtual Servers for IBM Cloud® Virtual Private Cloud. The bootloader contains the secret to decrypt the contract.

During boot several hashes of components and measures of code are taken and added to the attestation record. To further protect this attestation record, the record is encrypted with the public key that the auditor provided. By doing so, only the auditor is in the position to decrypt the attestation record and can validate that the workload that is deployed in the enclave is the expected and untampered version of the workload that is expected to be deployed into the Hyper Protect Virtual Servers for VPC instance.