Tinkey

This part describes how to generate a Tink Keyset and configure it in Horizon

Installation

RHEL
Debian
Docker

In order to install Tinkey, the server must have access to a repository (mirror, ISO file, …) of the linux distribution you are using in order to be able to install the dependencies of the software. Tinkey package has the following dependencies:

java-17-openjdk-headless

Please note that these packages may have their own dependencies.

Installation from the EverTrust repository

Create a /etc/yum.repos.d/tinkey.repo file containing the EverTrust repository info:

[tinkey]
enabled=1
name=Tinkey Repository
baseurl=https://repo.evertrust.io/repository/tinkey-rpm/
gpgcheck=0
username=<username>
password=<password>

Replace <username> and <password> with the credentials you were provided.

You can then run the following to install the latest Tinkey version:

# yum install tinkey

To prevent unattended upgrades when running yum update, you should pin the Tinkey version by adding

exclude=tinkey

at the end of the /etc/yum.repos.d/tinkey.repo file after installing Tinkey.

Installing from RPM

Download the latest RPM for Tinkey on the Official EVERTRUST repository.

Upload the file 'tinkey-<latest>.noarch.rpm' to the server;

Access the server with an account with administrative privileges;

Install the Tinkey package with the following command:

# yum localinstall /root/tinkey-<latest>.noarch.rpm

openjdk-17-jre-headless

Please note that these packages may have their own dependencies.

Installation from the EverTrust repository

If you haven’t already, to add the EVERTRUST repository to your APT repositories, run the following commands:

Install the required tools (gpg)
```
# sudo apt install gnupg
```

Download and install the EVERTRUST GPG key

# curl https://evertrust.io/.well-known/apt/gpg.pub | sudo gpg -o /usr/share/keyrings/evertrust.gpg --dearmor

Add the repository

# echo "deb [ arch=all signed-by=/usr/share/keyrings/evertrust.gpg ] https://repo.evertrust.io/repository/apt all main" | sudo tee /etc/apt/sources.list.d/evertrust.list

Once the repository has been added, authentication to it must be provided. To do so, edit the /etc/apt/auth.conf file and add the following lines:

machine repo.evertrust.io
login <your EVERTRUST login>
password <your EVERTRUST password>

Once the repository has been added, run the following command to update the APT repository list.

# sudo apt update

You can then run the following command to install the latest Tinkey version:

# sudo apt install tinkey

Installing from DEB

Download the latest DEB for Tinkey on the Official EVERTRUST repository.

Upload the file 'tinkey-<latest>_all.deb' to the server;

Access the server with an account with administrative privileges;

Install the Tinkey package with the following command:

# apt install /root/tinkey-<latest>_all.deb

The EVERTRUST Tinkey utility is available at:

registry.evertrust.io/tinkey

Usage

PlainText keyset

In this mode, the keyset directly contains an AES key without additional encryption. When Horizon starts, the keyset is loaded into memory and used for all encryption and decryption operations.

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out=horizon.keyset

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out=horizon.keyset

docker run registry.evertrust.io/tinkey create-keyset --key-template AES256_GCM --out=horizon.keyset

This is the equivalent to previous Horizon SSV encryption level.

PKCS#11 keyset

PKCS#11 templates enable integration with Hardware Security Modules (HSM) for enhanced security. Horizon supports three different PKCS#11 modes depending on your security requirements.

The following parameters are commonly used when generating the key-uri:

Parameter	Description
object	The label of the symmetric key. The key must already exist on the HSM.
type	The type of key (typically "secret-key")
slot-id	The HSM slot identifier to use
module-path	The path to the .so library required for HSM interaction
pin-value	The PIN required to authenticate with the HSM

Parameter

Description

object

The label of the symmetric key. The key must already exist on the HSM.

type

The type of key (typically "secret-key")

slot-id

The HSM slot identifier to use

module-path

The path to the .so library required for HSM interaction

pin-value

The PIN required to authenticate with the HSM

Wrapped mode

In this mode, a software-based AES key is encrypted (wrapped) with a master key stored in the HSM. The wrapped key is stored in the keyset file, while the master key remains securely in the HSM. When Horizon starts, the keyset is decrypted using the HSM’s master key, then loaded into memory and used for all subsequent encryption and decryption operations. This approach balances security with performance by minimizing HSM communication while keeping the master key protected in hardware.

To create a wrapped keyset using the GCM algorithm:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES128_GCM --out horizon.keyset --master-key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES128_GCM --out horizon.keyset --master-key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

docker run registry.evertrust.io/tinkey create-keyset --key-template AES128_GCM --out horizon.keyset --master-key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

To use the CBC algorithm instead, replace pkcs11:// with pkcs11-aes-cbc:// in the master-key-uri:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES128_GCM --out horizon.keyset --master-key-uri pkcs11-aes-cbc://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES128_GCM --out horizon.keyset --master-key-uri pkcs11-aes-cbc://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

docker run registry.evertrust.io/tinkey create-keyset --key-template AES128_GCM --out horizon.keyset --master-key-uri pkcs11-aes-cbc://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

When using wrapped mode, Horizon needs the master-key-uri to decrypt the keyset at startup. Please follow the configuration steps below.

Hardware protected mode

In this mode, the encryption key is stored directly in the HSM. All encryption and decryption operations are performed by the HSM itself, ensuring the key never leaves the hardware security boundary. This provides a high level of security but requires HSM communication for every cryptographic operation.

To create the keyset using the GCM algorithm:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template PKCS11_AES_GCM --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template PKCS11_AES_GCM --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

docker run registry.evertrust.io/tinkey create-keyset --key-template PKCS11_AES_GCM --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

To use the CBC algorithm instead, change the --key-template parameter to PKCS11_AES_CBC:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template PKCS11_AES_CBC --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template PKCS11_AES_CBC --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

docker run registry.evertrust.io/tinkey create-keyset --key-template PKCS11_AES_CBC --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

Derived hardware protected mode

In this mode, a master key stored in the HSM is used to derive encryption keys on demand. Each time Horizon needs to encrypt or decrypt data, it derives a unique key from the master key in the HSM using a random seed. This seed is then stored alongside the encrypted data. This provides the highest level of security but requires HSM communication for every cryptographic operation.

To create the keyset using the GCM algorithm:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template PKCS11_AES_GCM_DERIVED --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template PKCS11_AES_GCM_DERIVED --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

docker run registry.evertrust.io/tinkey create-keyset --key-template PKCS11_AES_GCM_DERIVED --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

To use the CBC algorithm instead, change the --key-template parameter to PKCS11_AES_CBC_DERIVED:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template PKCS11_AES_CBC_DERIVED --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template PKCS11_AES_CBC_DERIVED --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

docker run registry.evertrust.io/tinkey create-keyset --key-template PKCS11_AES_CBC_DERIVED --out keyset --key-uri pkcs11://object=AES1;type=secret-key;slot-id=-1?module-path=/usr/lib64/pkcs11/libsofthsm2.so&amp;pin-value=1234

The PKCS11_AES_CBC_DERIVED parameter is the equivalent to previous Horizon SHV encryption level.

AWS KMS keyset

AWS KMS (Key Management Service) enables secure key management using Amazon’s cloud infrastructure. In this mode, a software-based AES key is encrypted (wrapped) with a master key stored in AWS KMS. When Horizon starts, the keyset is decrypted using the KMS master key, then loaded into memory and used for all subsequent encryption and decryption operations.

The following parameters are required when generating the AWS KMS key-uri:

Parameter	Description
key-uri	The AWS KMS key ARN (Amazon Resource Name) or alias
credentials	Path to AWS credentials file (optional if using IAM roles or environment variables)

Parameter

Description

key-uri

The AWS KMS key ARN (Amazon Resource Name) or alias

credentials

Path to AWS credentials file (optional if using IAM roles or environment variables)

To create an AWS KMS wrapped keyset:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri aws-kms://arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri aws-kms://arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012

docker run registry.evertrust.io/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri aws-kms://arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012

If you need to specify AWS credentials explicitly:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri aws-kms://arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012 --credentials /path/to/credentials.json

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri aws-kms://arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012 --credentials /path/to/credentials.json

docker run registry.evertrust.io/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri aws-kms://arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012 --credentials /path/to/credentials.json

When using AWS KMS keyset, Horizon needs the master-key-uri to decrypt the keyset at startup. Please follow the configuration steps below. Additionally, ensure your AWS credentials are properly configured (via service account, application default credentials, or credentials file).

GCP KMS keyset

GCP KMS (Google Cloud Key Management Service) provides cloud-based key management using Google Cloud Platform. In this mode, a software-based AES key is encrypted (wrapped) with a master key stored in GCP KMS. When Horizon starts, the keyset is decrypted using the KMS master key, then loaded into memory and used for all subsequent encryption and decryption operations.

The following parameters are required when generating the GCP KMS key-uri:

Parameter Description

Parameter	Description
key-uri	The GCP KMS key resource name in the format: `projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME`
credentials	Path to GCP service account credentials JSON file (optional if using default application credentials)

key-uri

The GCP KMS key resource name in the format: projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME

credentials

Path to GCP service account credentials JSON file (optional if using default application credentials)

To create a GCP KMS wrapped keyset:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri gcp-kms://projects/my-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri gcp-kms://projects/my-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key

docker run registry.evertrust.io/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri gcp-kms://projects/my-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key

If you need to specify GCP credentials explicitly:

RHEL
Debian
Docker

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri gcp-kms://projects/my-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key --credentials /path/to/service-account.json

/opt/evertrust/tinkey/bin/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri gcp-kms://projects/my-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key --credentials /path/to/service-account.json

docker run registry.evertrust.io/tinkey create-keyset --key-template AES256_GCM --out horizon.keyset --master-key-uri gcp-kms://projects/my-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key --credentials /path/to/service-account.json

When using GCP KMS keyset, Horizon needs the master-key-uri to decrypt the keyset at startup. Please follow the configuration steps below. Additionally, ensure your GCP credentials are properly configured (via service account, application default credentials, or credentials file).

Horizon Configuration

Keyset

Once the keyset is created, it must be made available to Horizon:

RPM
Debian
Kubernetes

Move it to the expected location on the Horizon server:

mv horizon.keyset /opt/horizon/etc/horizon.keyset

Then set the appropriate ownership and permissions:

chown horizon:horizon /opt/horizon/etc/horizon.keyset
chmod 660 /opt/horizon/etc/horizon.keyset

Move it to the expected location on the Horizon server:

mv horizon.keyset /opt/horizon/etc/horizon.keyset

Then set the appropriate ownership and permissions:

chown horizon:horizon /opt/horizon/etc/horizon.keyset
chmod 660 /opt/horizon/etc/horizon.keyset

Create a Kubernetes secret containing the keyset on the Horizon namespace :

$ kubectl create secret generic horizon-keyset \
 --from-file=keyset="<path to your keyset file>" \
 --namespace horizon

Then reference the keyset in your values.yaml:

defaultVault:
  keyset:
    secretName: horizon-keyset
    secretKey: keyset

Master Key URI

If the keyset is wrapped, the master key URI must be made available to Horizon:

RPM
Debian
Kubernetes

Edit your /etc/horizon/default file and add the variable HORIZON_TINK_MASTER_KEY_URI with your master-key-uri value.

HORIZON_TINK_MASTER_KEY_URI=<master key URI>

Edit your /etc/horizon/default file and add the variable HORIZON_TINK_MASTER_KEY_URI with your master-key-uri value.

HORIZON_TINK_MASTER_KEY_URI=<master key URI>

Set the defaultVault.masterKeyURI key in your Helm values.yaml file:

defaultVault:
  masterKeyURI: "<master key URI>"

Credentials

If the keyset is wrapped using a KMS, the master key uses credentials that must be made available to Horizon. If your credentials are at the standard path for the KMS SDK, it will be found automatically. Otherwise, follow the steps below:

RPM
Debian
Kubernetes

Edit your /etc/horizon/default file and add the variable HORIZON_TINK_CREDENTIALS_PATH with the path to your credentials file.

HORIZON_TINK_CREDENTIALS_PATH=<path to credentials>

Then set the appropriate ownership and permissions:

chown horizon:horizon <path to credentials>
chmod 660 <path to credentials>

Edit your /etc/horizon/default file and add the variable HORIZON_TINK_CREDENTIALS_PATH with the path to your credentials file.

HORIZON_TINK_CREDENTIALS_PATH=<path to credentials>

Then set the appropriate ownership and permissions:

chown horizon:horizon <path to credentials>
chmod 660 <path to credentials>

Specify the path to the credentials file (which should be mounted into the container) in your values.yaml file:

environment:
  - name: VAULT_TINK_CREDENTIALS_PATH
    value: /mnt/sample/path