Encrypting log messages

This tutorial walks you through how to encrypt log messages that are generated by your container workload in your Hyper Protect Virtual Server for VPC instance.

Objective

Every Hyper Protect Virtual Server for VPC instance is created with a valid contract. One section of the contract stores your logging configuration. The logs that are 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.

Introduction

This tutorial explains how to deploy Docker Compose or Podman Play as a Hyper Protect Virtual Server instance. You can use one of the following approaches.

log-encryption is a sample repository folder.

Docker Compose approach

In the log-encryption folder, you have a docker-compose.yaml file under /compose directory, which deploys and manages the Docker Compose application. The image that we use is the official Ubuntu image from DockerHub.
Within the docker-compose.yaml file, there is a command that asks Docker Compose to run a shell script (example.sh) that prints a line of plain text and a line of encrypted message to the standard output. This example.sh file exists in the /compose/bin directory.
A public key logging.pub is required for encrypting the log message. This file must exist in the /compose folder. This tutorial shows an example of generating a key pair encrypted via AES with a passphrase by using openssl.
The volumes: instruction tells Docker Compose to mount the Docker Compose volume with the public key and the simple logging application to /var/logging inside the container. The Ubuntu image starts as a container later and run example.sh as its main application.

Podman Play approach

In the log-encryption folder, you have pods.yaml file under /pods directory, 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 Podman Play file, there is a command that asks Podman to run a shell script (example.sh) that prints a line of plain text and a line of encrypted message to the standard output. This example.sh file exists in the /pods/bin directory.
A public key logging.pub is required for encrypting the log message. This file must exist in the /pods folder. This tutorial shows an example of generating a key pair encrypted through AES with a passphrase by using openssl.
The volumes: instruction tells Podman to mount the Podman volume with the public key and the simple logging application to /var/logging inside the container. The Ubuntu image starts as a container later and run example.sh as 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.

You must abide to the following:

You must keep the private key 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.pub is stored under the /log-encryption/pods folder for Podman approach and /log-encryption/compose folder for Docker Compose along with the pods.yaml file and docker-compose.yaml respectively. As mentioned in the preparation of the workload section of the contract, the archive subsection contains the base64 encoded TGZ file archive of podman-play. The logging.pub file in our example undergoes the same encoding and compression, since it is stored in the same folder. As a result, the created instance acquires the public key for subsequent log encryption.

This tutorial also provides sample files such as env.yaml, workload.compose.yaml (for Docker Compose), workload.pods.yaml(for Podman Play), and 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.
The example runs on a Linux system.

Prepare your contract

This tutorial gets you started with a simple Hyper Protect Virtual Server for VPC contract that only has an env section and a workload section.

As recommended in contract encryption, we encrypt both sections. When the instance boots, the bootloader decrypts the contract if it's encrypted. Follow the instructions at Downloading the encryption certificate and extracting the public key. This tutorial uses the certificate for the IBM Hyper Protect Container Runtime image version ibm-hyper-protect-container-runtime-1-0-s390x-24. Downloaded the encryption certificate and rename it to hpcr.crt. Follow the steps to obtain the simple contract:

Get the hostname and the API key of your IBM Cloud Logs instance. For more information, see Logging for Hyper Protect Virtual Servers for VPC.
Create and encrypt the env section. Refer to the env.yaml file in the log-encryption folder for the correct schema. Replace the content with your logging hostname and API keys. Run the encrypt-basic.sh script to obtain the encrypted env section of the contract.
```
cat env.yaml | ./encrypt-basic.sh hpcr.crt
```
Create the workload section. Refer to the workload.pods.yaml (for Podman Play) or workload.compose.yaml (for Docker Compose) sample file in the log-encryption folder for the correct schema. In this example, the Podman play file in the log-encryption folder will be used for the podman subsection and Docker Compose uses the compose subsection..

In addition, provide the public key for encrypting the log messages. Run the following commands to generate a key pair. We proceed with the public key. Note that logEncrypt is the passphrase to generate keys, you can 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 pods folder (for Podman Play) or docker-compose folder (for Docker Compose) under log-encryption. Keep in mind that the logging.pub file that contains the public key must be stored in the pods (for Podman Play) or docker-compose folder (for Docker Compose) along with pods.yaml or docker-compose.yaml respectively.

Compress and encrypt the folder, as the play (for Podman Play) or compose (for Docker Compose) subsection requires this for the archive value. Use the following command to obtain the base64 encoded archive as a file named play.b64 (for Podman Play) or compose.b64 (for Docker Compose). Use the raw content of play.b64 (for Podman Play) or compose.b64 (for Docker Compose) for the value of archive under the play or compose subsection respectively.
- For Podman Play:
```
tar czvf pods.tgz pods/bin pods/pods.yaml pods/logging.pub bin/
base64 -w0 pods.tgz > pods.b64
```
- For Docker Compose:
```
tar czvf compose.tgz compose/bin compose/docker-compose.yaml compose/logging.pub bin/
base64 -w0 compose.tgz > compose.b64
```
Run the encrypt-basic.sh script to obtain the encrypted workload section of the contract.
- For Podman Play:
```
cat workload.pods.yaml | ./encrypt-basic.sh hpcr.crt
```
- For Docker Compose:
```
cat workload.pods.yaml | ./encrypt-basic.sh hpcr.crt
```
Complete the user-data.yaml with the output of Step 2 and 5. Refer to the sample user-data.yaml for the correct schema. Note the hyper-protect-basic token approach to implement hybrid encryption, as it's used throughout IBM Cloud Hyper Protect Virtual Server for VPC.

Create your Hyper Protect Virtual Server instance

With the contract (user data) available, we go ahead to create an instance.

The quickest way is to use the UI. For Operating system, choose IBM Hyper Protect to create a Hyper Protect Virtual Server for VPC instance. Paste your user data in the User data box. Click Create virtual server instance when you are ready.

Decrypt log messages

Monitor the serial console. When the virtual server instance is up and running, go to the IBM Cloud Log instance that you provisioned. Open the dashboard and find the ciphertext, which is your encrypted log message.

Use decrypt-basic.sh along with the private key that you generated to decipher the encrypted log message.

echo hyper-protect-basic.rdf...EqM | ./decrypt-basic.sh logging