Encrypting log messages
This tutorial walks you through how to encrypt log messages that are generated by your container workload in your IBM Hyper Protect Virtual Server instance.
Every IBM Hyper Protect Virtual Server instance is created with a valid contract. One section of the contract stores your logging configuration. The logs produced by your deployed workload are sent via TLS to your designated logging service and are later displayed on the logging dashboard.
If your workload produces sensitive information, you can take similar steps as in this tutorial to make selected log messages display as ciphertext on the logging dashboard. To retrieve the deciphered messages, you can download the logs from your Log Analysis instance and decrypt them locally.
In this tutorial, we use Log Analysis as the logging service. The process also applies to a syslog server.
This tutorial deploys a Docker container as a Hyper Protect Virtual Server. Inside the
you can find the following materials:
docker-compose.yamlfile under the
/composedirectory, which deploys and manages the container application to be used in this tutorial. The image that we use is the official Ubuntu image from DockerHub.
- Within the Docker Compose file, there is a
command:instruction to tell Docker to run a Shell script that prints a line of plain text, and a line of encrypted message to the standard output. This
example.shfile exists in the
- A public key
logging.pubis required for encrypting the log message. This file must exist in the
/composefolder. This tutorial will show an example of generating a key pair encrypted via AES with a passphrase using openssl.
volumes:instruction tells Docker to mount the
composevolume with the public key and the simple logging application to
/var/logginginside the container. The Ubuntu image will start as a container later and run
example.shas its main application.
The contract is a YAML file to specify the Hyper Protect Virtual Server instance that you want to create. In this tutorial, a dedicated public and private key pair is used to encrypt and decrypt the selected log messages.
- The private key is kept by you to decrypt the downloaded logs later.
- The public key must be embedded into the contract, which is a special approach for our case. The public key
logging.pubis stored under the
/example-filesfolder along with the
docker-compose.ymlfile. As mentioned in the preparation of the
workloadsection of the contract, the
archivesubsection contains the
base64encoded TGZ file archive of
logging.pubfile in our example will undergo the same encoding and compression since it's stored in the same folder. As a result, the created instance will acquire the public key for subsequent log encryption.
This tutorial also provides sample files such as
user-data.yaml. They are only meant as references for correct schema.
Before you begin
- Install OpenSSL for encryption. This tutorial uses version 3.0 or later.
- Set up your logging instance by following the documentation.
- Read the system requirements. The following example is tested on an IBM z16 logical partition (LPAR) with secure execution enabled as the Kernel-based Virtual Machine (KVM) host.
Prepare your contract
This tutorial will get you started with a simple Hyper Protect Virtual Server contract that only has an
env section and a
As recommended in the documentation, we will encrypt both sections. When the instance boots, the bootloader decrypts the contract if it's encrypted. Download the certificate
to be used to encrypt the contract by following the instructions in Downloading the IBM Hyper Protect Container Runtime image. Follow the steps there to extract the
*.gz file. Look for the certificate
config/certs directory. By the time this tutorial is designed, the certificate is
ibm-hyper-protect-container-runtime-23.3.0-encrypt.crt. You might see a different version number. The file
hpcr.crt is already available inside
/example-files. This will serve the purpose of encrypting the contract. Follow the steps to obtain the simple contract:
Get the hostname and the ingestion key of your Log Analysis instance. See Logging for IBM Hyper Protect Virtual Servers.
Create and encrypt the
envsection. Refer to the
env.yamlfile in the
example-filesfolder for the correct schema. Replace the content with your logging hostname and ingestion key. Run the
encrypt-basic.shscript to obtain the encrypted
envsection of the contract.
cat env.yaml | ./encrypt-basic.sh hpcr.crt
workloadsection. Refer to the
workload.yamlsample file in the
example-filesfolder for the correct schema. In this example, the docker compose file in the
example-filesfolder will be used for the
In addition, provide the public key for encrypting the log messages. Run the following commands to generate a key pair. We will proceed with the public key. Note that
logEncryptis the passphrase to generate keys, you may use your own.
openssl genrsa -aes128 -passout pass:logEncrypt -out logging 4096
openssl rsa -in logging -passin pass:logEncrypt -pubout -out logging.pub
A sample output can be found in the
example-files. Keep in mind that the
logging.pubfile containing the public key must be stored in the
composefolder along with
Compress and encrypt the folder, as the
composesubsection requires this for the
archivevalue. Use the following command to obtain the
base64encoded archive as a file named
compose.b64. Use the raw content of
compose.b64for the value of
tar czvf - -C <COMPOSE_FOLDER> . | base64 -w0 > compose.b64
encrypt-basic.shscript to obtain the encrypted
workloadsection of the contract.
cat workload.yaml | ./encrypt-basic.sh hpcr.crt
user-data.yamlwith the output of Step 2 and 5. Refer to the sample
user-data.yamlfor the correct schema. Note the
hyper-protect-basictoken approach to implement hybrid encryption, as it's used throughout Hyper Protect Virtual Servers.
Create your Hyper Protect Virtual Server instance
With the contract (user data) available, we go ahead to create an instance. Follow instructions in Setting up and configuring IBM Hyper Protect Virtual Servers to create an IBM Hyper Protect Virtual Server on a KVM host. Use the contract you created in this tutorial for step 3.c in the Procedure section.
Decrypt log messages
When the virtual server instance is up and running, go to the Log Analysis instance that you provisioned. Open the dashboard and find the ciphertext, which is your encrypted log message.
decrypt-basic.sh along with the private key you generated to decipher the encrypted log message.
echo hyper-protect-basic.rdf...EqM | decrypt-basic.sh logging