Installation & Configuration

Create a directory in which the ocicrypt.conf configuration file will be stored.

mkdir ${HOME}/Securosys/skopeo

note

There are no default ${BINARY_PATH} and ${CONFIG_PATH} values. For this guide, they are set to be under ${HOME}/Securosys/skopeo/.

Install the plugin binary

Navigate to the directory where your previously downloaded and unzipped the installation files. Copy the skopeo-securosys binary file to the previously created directory.

cp skopeo-securosys ${BINARY_PATH}

Install and fill out the config file

The ocicrypt.conf file is used to configure the image encryption plugin. In particular, it tells the OCIcrypt CLI how it can reach the REST API to talk to the HSM. An example config file is included in the ZIP you downloaded in a previous step.

Navigate to the directory where the example configuration file was downloaded and unzipped. Copy the file to the previously created directory:

cp ocicrypt.conf ${CONFIG_PATH}

The format of the ocicrypt.conf file can be seen below. Adapt the parameters 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>"
                ]
            }
        }
    }
}

Please see below the configuration parameters:

Configuration Parameters:	Description
"path":"<pathToExecutable>/skopeo-securosys",	Replace the variable with your path to the securosys-encryption plugin binary, i.e. {BINARY_PATH}. The naming of the plugin must stay the same!
"-cipher-algorithm <yourCipherAlgorithm>",	Replace the variable with the Cipher Algorithm of your encryption key. Possible values: - RSA
"-tsb-api-endpoint <TSB_APIendpoint>",	Replace the variable with your TSB endpoint URI. Visit Securosys CloudHSM Connectivity Details for CloudHSM TSB as a Service deployments.
"-auth <TOKEN>",	Specifies the authentication type. Keep the value as: - TOKEN for JWT based authentication - CERT for mTLS
"-token <yourToken>"	Replace the variable with your TSB JWT authentication token. For "-auth TOKEN": Replace the variable with your own TSB JWT token. Omit entirely in case of "auth CERT" (mTLS)
"-certpath <PathToCrt>"	For "auth CERT": Provide the full path of the server certificate file. Omit entirely in case of "auth TOKEN"
"-keypath <PathToKey>"	For "auth CERT": Provide the full path of the client key file. Omit entirely in case of "auth TOKEN".
"-keyOperationToken <TSB-TOKEN>"	Additional authentication for TSB, set correct api key value for specific operation. This is optional and will not break existing deployments. For more info visit page
"-publicKey <PUBLIC_KEY>"	The public key (base64 encoded) that belongs to the private key used to calculate the signature.
"-privateKey <PRIVATE_KEY>"	Private key (base64 encoded) used to calculate the signature.

note

For connectivity details, see this page.

Example using JWT-based authentication, for key without password:

{
    "key-providers": {
        "securosys_encryption": {
            "cmd": {
                "path":"/home/securosys/skopeo/securosys_encryption",
                "args": [
                    "-key-label SecurosysEncKey01",
                    "-cipher-algorithm RSA",
                    "-tsb-api-endpoint https://sbx-rest-api.cloudshsm.com",
                    "-auth TOKEN",
                    "-token ergq0ejgadjlfkgjaldfjgaodf9gjad0f9hgadfhgadhfogiah…",
                    "-keyOperationToken <tsb-x-token_...>",
                    "-publicKey <MIIBIjANBgkqhk...>",
                    "-privateKey <MIIEvgIBADANBgkqhkiG9w0BAQE...>"
                ]
            }
        }
    }
}