Skip to main content

Quick Start

This quickstart assumes all the necessary requirements are fullfilled. For more information visit section Prerequisites.

  1. Generate your TLS certificate

    A prerequired step for this example is to generate a certificate for your domain. For the next steps you will require your *.ca, *.crt files and a private key (or simply using a self-signed certificate).

  • To generate a .jks from these files you need to combine your *.crt and *.ca files. Manually copy all data from *.ca into *.crt, and then you can use the following command. When prompted provide a password for the newly generated .p12 file.
openssl pkcs12 -export -in ca.crt -inkey ca.key -out keystore.p12

  1. Download the Securosys XKS Proxy files

    Follow the instructions provided in section Download

  2. Configure application.yaml (default file can be seen below), please adapt the parameters according to your environment:

NOTE

When utilizing CloudsHSM service, refer to Cloud Connectivity Details for accurate API-Endpoint URI. For on-premise deployments, verify API-Endpoint URI with your administrator. Contact your service administrator for authentication credentials in any setup (on-prem or cloud).

# All necessary credentials from hsm
hsm:
  attestationKeyName: 'attestation-key'
  # Make sure you allowed an outbound firewall rule, to allow traffic to the HSM
  # Hosts should be entered sequentially using the list as in the example below
  host:
    - 'your-proxy_host'
    - 'another-proxy_host'
  #Ports should be entered sequentially using the list just like hosts
  port:
    - 'your-proxy_port'
    - 'another-proxy_port'
  user: 'replace-me_hsm-username'
  setupPassword: 'replace-me_hsm-setupPassword'
  proxyUser: 'replace-me_proxy-username'
  proxyPassword: 'replace-me_proxy-password'

# All necessary credentials from AWS
aws:
  host: 'replace-me_domain-name'
  regionName: 'replace-me_aws-region-name'
  accessKeyID: 'replace-me_keyId'
  secretAccessKey: 'replace-me_secretAccessKey'
  #These parameters should not be modified
  serviceName: 'kms-xks-proxy'
  httpMethodName: 'POST'
  debug: 'false'

# Your dns credentials
server:
  port: 443
  address: 0.0.0.0
  ssl:
    key-store: file:/etc/app/config/keystore.p12
    key-store-password: replace-me_keystore-password
    key-alias: replace-me_keystore-keyname

# Logging configuration
logging:
  config: /etc/app/config/log/logback.xml

#Do not modify!
spring:
  mvc:
    throw-exception-if-no-handler-found: true
  1. Run the downloaded Securosys XKS Proxy image with the following command, replace the variables according to your configuration:
docker run [-d]-name <NameOfContainer> --add-host <YourHostDomain> :127.0.0.1 \
 --network=host -v /home/ec2-user/securosys\_xks\_1.0.0/config-files:/etc/app/config/ \
 securosys.jfrog.io/external-xks/securosys-xks:1.0.0.20230706T1936Z

If the command is successful, the Securosys XKS proxy will be started. If not already present, a new attestation key will be generated. The logs from the boot will output a healthy status.

After the Securosys XKS Proxy has started the connection between AWS Key Management Service (KMS) and your Primus HSM has been established. You can now use your custom key store to encrypt and decrypt your data on the AWS platform with keys generated and stored on your Primus HSM. You can try out the functionality by encrypting and decrypting data