Quickstart with Docker Encryption

This quickstart guide provides a brief overview of the steps to download, setup and use the Securosys Docker Image Encryption plugin.

1. Download and install Skopeo.

   Linux

   sudo apt-get -y update
   sudo apt-get -y install skopeo

   MacOS

   brew install skopeo

2. Download the Securosys Docker Image Encryption Plugin files and unzip them.

3. Create an encryption key on the HSM (unless you already have a key):

   curl -X 'POST' \
       '<TSB_APIendpoint>/v1/key' \
       -H 'accept: application/json' \
       -H 'Authorization: Bearer <bearer_token>'\
       -H 'Content-Type: application/json' \
       -d '{
       "label": "SecurosysEncKey01",
       "algorithm": "RSA",
       "keySize": 2048,
       "attributes": {
         "encrypt": true,
         "decrypt": true
       }
   } '

4. Copy the plugin binary skopeo-securosys and the ocicrypt.conf to ${HOME}/Securosys/skopeo. Adapt the parameters in ocicrypt.conf according to your environment:

   {
       "key-providers": {
           "securosys_encryption": {
               "cmd": {
                 "path": "/<pathToExecutable>/Skopeo-securosys",
                 "args":  [
                     "-cipher-algorithm <yourCipherAlgorithm>",
                     "-tsb-api-endpoint <TSB_APIendpoint>",
                     "-auth <TOKEN>",
                     "-token <yourToken>",
                     "-certpath <PathToCrt>",
                     "-keypath <PathToKey>",
                     "-keyOperationToken <TSB-TOKEN>",
                     "-publicKey <PUBLIC_KEY>",
                     "-privateKey <PRIVATE_KEY>"
                   ]
               }
           }
       }
   }

5. Choose an image you want to encrypt. The image needs to be OCI-compliant. This can either be an image that you have built locally, or an image that you have pulled from a remote image registry. For example, take the Alpine Linux image from docker.io and copy it locally:

   skopeo copy docker://docker.io/amd64/alpine:latest oci:alpine

6. Encrypt the image:

   [KEY_PASSWORD=password] OCICRYPT_KEYPROVIDER_CONFIG=<pathToConfig>/ocicrypt.conf skopeo --override-os linux copy --encryption-key provider:skopeo-securosys:<keyLabel> oci:alpine oci:apline-encrypted

7. Decrypt the image:

   [KEY_PASSWORD=<password>] OCICRYPT_KEYPROVIDER_CONFIG=/<pathToConfig>/ocicrypt.conf skopeo --override-os linux copy --decryption-key provider:skopeo-securosys:<keyLabel> oci:alpine-encrypted oci:alpine-decrypted