years
2020, 2026

lastupdated

2026-08-11

keywords

encryption, decryption, encrypted image, public-private key pair, encrypt, decrypt, key, registry, image, private key, public key

subcollection

Registry

content-type

tutorial

services

key-protect

account-plan

lite

completion-time

Encrypting images for confidentiality in {{site.data.keyword.registryshort_notm}}

{: #registry_encrypt} {: toc-content-type="tutorial"} {: toc-services="key-protect"} {: toc-completion-time="2h"}

Protect the confidentiality of your {{site.data.keyword.registryshort_notm}} images by encrypting them with an RSA public-private key pair so that only trusted hosts can run them. {: shortdesc}

Create an encrypted image so that people without the private key{: term} can't access the content. Create the encrypted image by using an RSA public-private key pair to encrypt and decrypt the image. A public key is not a secret and anyone can use it to encrypt an image. A private key is a secret, and only users that have that private key can use it to decrypt the image.

Encryption is supported in {{site.data.keyword.registrylong_notm}} and complies with the following standards:

opencontainers/image-spec{: external}
opencontainers/artifacts{: external}

For more information about encrypting images, see Encrypted container images for container image security at rest{: external} and Advancing image security and compliance through Container Image Encryption{: external}.

Before you begin

{: #registry_encrypt_prereqs}

Complete the instructions in Getting started with {{site.data.keyword.registrylong_notm}}.
Ensure that you have the most recent version of the container-registry command-line interface (CLI) plug-in for the {{site.data.keyword.cloud_notm}} CLI, see Updating the container-registry CLI plug-in.
Ensure that you have a private namespace to push your encrypted image to, see Set up a namespace.
Install Buildah version 1.15{: external} or later, so that you can build encrypted images. Buildah works in the Linux® environment only. As an alternative to Linux®, you can use a virtual machine or Docker image to run Buildah to build images.
Install Podman.

Create the public-private key pair

{: #registry_encrypt_create} {: step}

Create a public-private key pair by using OpenSSL commands.

Create a work directory, for example, USER_KEYS, in which to store the keys and change to that directory:
```
mkdir USER_KEYS; cd USER_KEYS
```
{: pre}
Use OpenSSL to create a private key, where USER_KEY is the name for your key's identity:
```
openssl genrsa --out USER_KEYPrivate.pem
```
{: pre}
Create a public key:
```
openssl rsa -in USER_KEYPrivate.pem -pubout -out USER_KEYPub.pem
```
{: pre}

To use the private key in production, you must safely store and protect the private key in a suitable store. You might also want to manage the public key in the same way. For more information, see Storing keys. {: requirement}
List the keys to ensure that they are created:
```
ls -l
```
{: pre}

To use this key pair to encrypt images, display the public key by running the following cat command:

cat USER_KEYPub.pem

{: pre}

You get a response similar to the following output:

{: screen}

Encrypt the image

{: #registry_encrypt_image} {: step}

Encrypt the image by using the public key and then build a container image by using a Dockerfile{: term}.

Go to the directory where you store your apps, for example MY_APP.
```
cd MY_APP
```
{: pre}

Create the Dockerfile by running the following command:

cat << EOF >> Dockerfile
FROM nginx:latest
RUN echo "some secret" > /secret-file
EOF

{: pre}

Use Buildah to create an unencrypted image by running the following command, where NAMESPACE is your namespace:
```
buildah bud -t us.icr.io/NAMESPACE/MY_APP .
```
{: pre}

us.icr.io/NAMESPACE/MY_APP is committed to the local image store.
Encrypt the image by using the public key and upload the image to the registry by running the following commands and by specifying the JSON Web Encryption (jwe) protocol to encrypt the image, where USER_KEYS/USER_KEYPub.pem is the encryption key.
```
buildah push --encryption-key jwe:..USER_KEYS/USER_KEYPub.pem us.icr.io/NAMESPACE/MY_APP
```
{: pre}

Buildah version 1.15 or later, uses Docker’s login credentials to authenticate. If these credentials don't work or you want to use an API key{: term}, you can supply the —-creds <username> option, where <username> is the username. If you use the —-creds <username> the option, when requested, type in the password of the registry credential. {: tip}

You get a response that informs you that the manifest is written to the image destination, which is the registry.
Check in your registry to make sure that the image is there.

Pull and decrypt the image

{: #registry_encrypt_pull} {: step}

Pull the image from the registry and decrypt it by using the private key.

To ensure that you are pulling from the registry and that you are not using the local cache, remove the image locally:
```
buildah rmi -f us.icr.io/NAMESPACE/MY_APP
```
{: pre}

(Optional) You can try to pull the image without providing the decryption key to confirm that the image can't be decrypted:

buildah pull us.icr.io/NAMESPACE/MY_APP

{: pre}

The output contains a message similar to the following message:

...<truncated>...
Error decrypting layer sha256:ab4ea03582e08a8e8fc35b778cc6f1a1fa797469fa9cc61cee85f703b316bb12: missing private key needed for decryption
ERRO exit status 125

{: screen}

Use Buildah to pull the image with the decryption key, where USER_KEYS/USER_KEYPrivate.pem is the decryption key and us.icr.io/NAMESPACE/MY_APP is the registry:
```
buildah pull --decryption-key ../USER_KEYS/USER_KEYPrivate.pem us.icr.io/NAMESPACE/MY_APP
```
{: pre}

The encrypted image is retrieved from the registry, decrypted, and stored in the local image store.
Confirm that the image is stored by running Podman:
```
podman run -it us.icr.io/NAMESPACE/MY_APP /bin/bash
```
{: pre}

Storing keys

{: #registry_encrypt_keys}

To use the private key in production, you must safely store and protect the private key. You might also want to manage the public key in the same way to control who can build images. You can use {{site.data.keyword.keymanagementservicelong_notm}} to store and protect your keys.

{{site.data.keyword.keymanagementservicelong_notm}} stores symmetric keys rather than the asymmetric PKI keys that are used for image encryption. You can add your keys separately as two {{site.data.keyword.keymanagementservicelong_notm}} standard keys by using the dashboard, CLI, or API. {{site.data.keyword.keymanagementservicelong_notm}} requires that only Base64 data is imported. To obtain pure Base64 data, you can encode the PEM files by running "openssl enc -base64 -A -in USER_KEYPrivate.pem -out USER_KEYPrivate.b64" before you load the Base64 content, and reverse this action to obtain the usable key again by running "openssl enc -base64 -A -d -in USER_KEYPrivate..b64 -out USER_KEYPrivate.pem".

For more information about how to use {{site.data.keyword.keymanagementservicelong_notm}} to store and protect your keys, see Bringing your encryption keys to the cloud and Importing your own keys.

As an alternative, you can protect your keys in your own store by using an {{site.data.keyword.keymanagementservicelong_notm}} root key to wrap them. This action means that you must unwrap them again by using {{site.data.keyword.keymanagementservicelong_notm}} and the valid root key.

For example, to wrap keys by using the CLI, run the command "ibmcloud kp key wrap ROOT_KEY_ID -p <base64 encoded image key>" and to unwrap keys, run the command "ibmcloud kp key unwrap ROOT_KEY_ID -p <base64 cyphertext>, where ROOT_KEY_ID is the ID of the root key that you are using.

For more information about how you can protect your keys in your own store by using an {{site.data.keyword.keymanagementservicelong_notm}} root key to wrap them, see Wrapping keys.

Encrypted images are not scanned by Vulnerability Advisor. {: note}

Next steps

{: #registry_encrypt_next}

Run your encrypted image in a {{site.data.keyword.openshiftlong}} cluster by using the Image Key Synchronizer cluster add-on.

Navigation Menu

Uh oh!

Encrypting images for confidentiality in {{site.data.keyword.registryshort_notm}}

Before you begin

Create the public-private key pair

Encrypt the image

Pull and decrypt the image

Storing keys

Next steps

Uh oh!

FilesExpand file tree

registry_encrypt_images.md

Latest commit

History

registry_encrypt_images.md

File metadata and controls

Encrypting images for confidentiality in {{site.data.keyword.registryshort_notm}}

Before you begin

Create the public-private key pair

Encrypt the image

Pull and decrypt the image

Storing keys

Next steps