Create Encryption Key and Key Pair

B.4 Create Encryption Key and Key Pair

Perform this task only if you want to enable the authTokenPropagationEnabled and transactionTokenEnabled properties in the tcs-docker-swarm.yaml file. This file is located in the installation_directory/otmm-<version>/samples/docker folder.

If the authTokenPropagationEnabled and transactionTokenEnabled properties in the tcs-docker-swarm.yaml file need not be enabled, then you must comment a few lines in the two YAML files.

Comment the following lines in the tcs-docker-swarm.yaml file.

# secretKeys: '{"secretKeys":[{"secretKeyName":"TMMSECRETKEY", "version":"1"}]}'
# EncryptionSecretKeyVersion: 1
...
# keyPairs: '{"keyPairs":[{"privateKeyName":"TMMPRIKEY", "publicKeyName":"TMMPUBKEY", "version":"1", "privateKeyPasswordName":"TMMPRIKEYPASSWD"}]}'
# transactionTokenKeyPairVersion: 1

Comment the following lines in the tmm-stack-compose.yaml file. This file is located in the installation_directory/otmm-<version>/samples/docker folder.

# secrets:
# TMMSECRETKEY:
# external: true
# TMMPRIKEY:
# external: true
# TMMPUBKEY:
# external: true
# TMMPRIKEYPASSWD:
# external: true

...
#entrypoint: ['/bin/sh', '-c', 'export TMMSECRETKEY=$$(cat /run/secrets/TMMSECRETKEY); export TMMPRIKEY=$$(cat /run/secrets/TMMPRIKEY); export TMMPUBKEY=$$(cat /run/secrets/TMMPUBKEY); export TMMPRIKEYPASSWD=$$(cat /run/secrets/TMMPRIKEYPASSWD); /app/tcs' ]

# secrets:
    # - TMMSECRETKEY
    # - TMMPRIKEY
    # - TMMPUBKEY
    # - TMMPRIKEYPASSWD

Skip this section as you don't need to create encryption keys and transaction token as you have disabled these options.

You must generate an encryption key, and then add the key to a Docker secret if you have enabled the authTokenPropagationEnabled property under authorization in the tcs-docker-swarm.yaml file. The encryption key that you generate must have the following attributes.

Symmetric algorithm: AES-256
Cipher mode: AES in GCM mode
Key length: 32 bytes
Length of initialization vectors: 96 bits

You must generate a key pair for transaction token, when you set transactionTokenEnabled to true under transactionToken in the tcs-docker-swarm.yaml file. The transaction token that you generate must have the following attributes:

Asymmetric algorithm: RSA 3072
Key length: 3072 bits
Hash algorithm: SHA256

You can reuse an existing RSA key, if you know the pass phrase. Otherwise, create a new RSA key.

Before you begin, ensure that you have installed OpenSSL.

For details about how the encryption token and transaction token are used, see About Authentication and Authorization.

To create an encryption key and a RSA key pair:

Run the following command to generate an encryption key with a key length of 32 bytes, and then create a secret while using the encrypted key.
```
openssl rand -hex 16 | docker secret create TMMSECRETKEY
```
Where, TMMSECRETKEY is the name of the secret that you want to create. If there is existing key with the same name that key is overwritten.
Create an RSA private key with key length as 3072 bits. Use the following command:
```
openssl genrsa -aes256 -out private.pem 3072
```
Enter a pass phrase at the command prompt, and then press enter. Remember the pass phrase as you will have to provide it later.

A new file called private.pem is created in the current working folder. This file contains the RSA private key value.
Create a RSA public key for the private key that you have generated.
The following command creates a new file called public.pem in the current working folder. This file contains the RSA public key value.
```
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
```
Base-64 encode the private and public keys, and then add them to Docker secrets.
```
base64 private.pem | docker secret create TMMPRIKEY -
base64 public.pem | docker secret create TMMPUBKEY -
```
Where, TMMPRIKEY and TMMPUBKEY are the names of the Docker secrets that you want to create.
Store the pass phrase for the RSA key as a Docker secret. In the following command, replace pass_phrase with the pass phrase for RSA key.
```
printf "<pass_phrase>"| docker secret create TMMPRIKEYPASSWD -
```

View the names of the Docker secrets that you have created.

docker secret ls

Sample output

ID               NAME              DRIVER    CREATED        UPDATED
ricw56x6sehy...   TMMPRIKEY                   20 hours ago   20 hours ago
c0hw2nhu0sh1...   TMMPRIKEYPASSWD             20 hours ago   20 hours ago
mr91c79nwzne...   TMMPUBKEY                   20 hours ago   20 hours ago
wp112txjki46...   TMMSECRETKEY                20 hours ago   20 hours ago

Note down the names of the keys as you'll need to provide it later.

Update the tmm-stack-compose.yaml file which is located in the installation_directory/otmm-<version>/samples/docker folder. Export the secrets that you have created as environment variables within the Swarm by providing details just below the configs section as shown in the following example.
```
version: "3.9"
 
configs:
   my_tcs_config:
   file: ./tcs-docker-swarm.yaml
 
secrets:
  TMMPRIKEY:
     external: true
  TMMPRIKEYPASSWD:
     external: true
  TMMPUBKEY:
     external: true
  TMMSECRETKEY:
     external: true
```

Add the following to the services.otmm-tcs section in the tmm-stack-compose.yaml file:

Names of the secrets that you have created.
Create an entrypoint to export the secrets that you have created as environment variables. To improve readability the following example uses same name for the secret and the environment variable. You can provide any other name for the environment variable. Note down the names of the environment variables as you will have to provide it in the next step.

services:
   otmm-tcs:
     image: "127.0.0.1:5000/tmm"
     ports:
        - "9000:9000"
     entrypoint: ['/bin/sh', '-c', 'export TMMPRIKEY=$$(cat /run/secrets/TMMPRIKEY); export TMMPRIKEYPASSWD=$$(cat /run/secrets/TMMPRIKEYPASSWD); export TMMPUBKEY=$$(cat /run/secrets/TMMPUBKEY); export TMMSECRETKEY=$$(cat /run/secrets/TMMSECRETKEY); /app/tcs' ]
      deploy:
         replicas: 1
      configs:
        - source: my_tcs_config
          target: /tcs_config.yaml
      environment:
        - CONFIG_FILE=/tcs_config.yaml
      secrets:
        - TMMPRIKEY
        - TMMPRIKEYPASSWD
        - TMMPUBKEY
        - TMMSECRETKEY

Update the tcs-docker-swarm.yaml file with the names of the environment variables that you have created. This YAML file is located in the installation_directory/otmm-<version>/samples/docker folder.

Sample values for encryption and transactionToken properties

encryption:
     secretKeys: '{"secretKeys":[{"secretKeyName":"TMMSECRETKEY", "version":"1"}]}'
     #TMMSECRETKEY is the environment variable for the Docker secret that contains the encryption key
     EncryptionSecretKeyVersion: 1
transactionToken:
     transactionTokenEnabled: true
     keyPairs: '{"keyPairs":[{"privateKeyName":"TMMPRIKEY", "publicKeyName":"TMMPUBKEY", "version":"1", "privateKeyPasswordName":"TMMPRIKEYPASSWD"}]}'
     #TMMPRIKEY is the environment variable for the Docker secret that contains the base64-encoded private key
     #TMMPUBKEY is the environment variable for the Docker secret that contains the base64-encoded public key
     #TMMPRIKEYPASSWD is the environment variable for the Docker secret that contains the private key password
     transactionTokenKeyPairVersion: 1

Parent topic: Install on Docker Swarm