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 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 deploys a Docker container as a Hyper Protect Virtual Server for VPC. Inside the /example-files
folder,
you can find the following materials:
- A
docker-compose.yaml
file under the/compose
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 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. Thisexample.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 will show an example of generating a key pair encrypted via AES with a passphrase using openssl. - The
volumes:
instruction tells Docker to mount thecompose
volume with the public key and the simple logging application to/var/logging
inside the container. The Ubuntu image will start as a container later and runexample.sh
as its main application.
The contract is a YAML file to specify the Hyper Protect Virtual Server for VPC 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.pub
is stored under the/example-files
folder along with thedocker-compose.yml
file. As mentioned in the preparation of theworkload
section of the contract, thearchive
subsection contains thebase64
encoded TGZ file archive ofdocker-compose.yml
. Thelogging.pub
file 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 env.yaml
, workload.yaml
, 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 will get 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 will 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-14
. The file hpcr.crt
is already available inside example-files
.
Follow the steps to obtain the simple contract:
-
Get the hostname and the ingestion key of your Log Analysis instance. See Logging for Hyper Protect Virtual Servers for VPC.
-
Create and encrypt the
env
section. Refer to theenv.yaml
file in theexample-files
folder for the correct schema. Replace the content with your logging hostname and ingestion key. Run theencrypt-basic.sh
script to obtain the encryptedenv
section of the contract.cat env.yaml | ./encrypt-basic.sh hpcr.crt
-
Create the
workload
section. Refer to theworkload.yaml
sample file in theexample-files
folder for the correct schema. In this example, the docker compose file in theexample-files
folder will be used for thecompose
subsection.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
logEncrypt
is 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
compose
folder underexample-files
. Keep in mind that thelogging.pub
file containing the public key must be stored in thecompose
folder along withdocker-compose.yml
.Compress and encrypt the folder, as the
compose
subsection requires this for thearchive
value. Use the following command to obtain thebase64
encoded archive as a file namedcompose.b64
. Use the raw content ofcompose.b64
for the value ofarchive
under thecompose
subsection.tar czvf compose.tgz docker-compose.yml logging.pub bin/ base64 -w0 compose.tgz > compose.b64
-
Run the
encrypt-basic.sh
script to obtain the encryptedworkload
section of the contract.cat workload.yaml | ./encrypt-basic.sh hpcr.crt
-
Complete the
user-data.yaml
with the output of Step 2 and 5. Refer to the sampleuser-data.yaml
for the correct schema. Note thehyper-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 Log Analysis 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