Using Image Encryption

Dependencies

The image encryption feature in the Warp engine requires libgcrypt 1.6+ and its dependency libgpg-error 1.11+ to be installed on the system. These libraries are widely used. On major Linux distributions they either come pre-installed or are available through the default packet manager.

Depending on your system, you can use one of these tools to check and install these dependencies:

 
# Check if installed with package manager
# On Ubuntu/Debian
dpkg -l | grep -E "libgcrypt|libgpg-error"
# On RHEL/CentOS/Fedora/AL2
rpm -qa | grep -E "libgcrypt|libgpg-error"

# Install if missing
# On Ubuntu/Debian
sudo apt install libgcrypt20 libgpg-error0
# On RHEL/CentOS/AL2
sudo yum install libgcrypt libgpg-error
# On Fedora
sudo dnf install libgcrypt libgpg-error

For example:

 
$ dpkg -l | grep -E "libgcrypt|libgpg-error"
ii  libgcrypt20:amd64     1.10.3-2build1  amd64   LGPL Crypto library - runtime library
ii  libgpg-error0:amd64   1.47-3build2.1  amd64   GnuPG development runtime library

Usage Instructions

With the dependencies in place, an encrypted checkpoint can be created and restored using an encryption key. For example, if you want to provide the key via a file:

 
# Generate a key (default algorithm uses 16 bytes)
openssl rand -hex 16 > image.key

# Start the application to create a checkpoint
java -XX:CRaCCheckpointTo=cr \
    -XX:CRaCEngine=warp \
    -XX:CRaCEngineOptions=encryption.key.file=image.key \
    -jar my_app.jar

# Restore from checkpoint
java -XX:CRaCRestoreFrom=cr \
    -XX:CRaCEngine=warp \
    -XX:CRaCEngineOptions=encryption.key.file=image.key

The Warp engine options allow you to select different encryption algorithms and ways to provide the key.

Generating and Using an Encryption Key

To use encryption, you need an encryption key, which is a sequence of random bits. The size of the key depends on the encryption algorithm you plan to use. You must provide a key of exactly the required size.

Currently, all ways of providing a key to the Warp engine require it to be hex-encoded.

Generate an appropriate key using various existing tools. For example, if you need a key of N bytes, use one of the following commands:

 
# GnuPG
gpg --gen-random 1 N | hexdump -v -e '/1 "%02x"'

# OpenSSL (version 3+)
openssl rand -hex N

Save the key and store it privately, separately from the image it was used to encrypt.