HSM

The Hardware Security Module (HSM) offers an additional layer of security for encrypting data. While AES is preferred for its balance of security and performance, using HSM for encryption is an option within the Vortex Crypto API for scenarios requiring hardware-based security features. The API supports direct encryption with HSM using either a specific version or an alias for the latest implementation.

In this guide, you’ll find:

• How to encrypt data using the HSM, with options for specific versions or the latest implementation.
• Instructions for using your own custom HSM key in the encryption process.
• A breakdown of encrypting encoded data with HSM for non-UTF8 text.

Using HSM for Encryption

Encrypting with hsmv1

For users who require specific control over the encryption method, hsmv1 allows for encryption directly against a dedicated Hardware Security Module. This method ensures that data encryption processes are executed within a physically secure environment.

Using the HSM Alias

The hsm alias points to the most current version of the HSM encryption algorithm implemented by the API. This ensures that your encryption is always up to date with the latest hardware security standards.

Using a Custom HSM Key for Encryption

Vortex supports data encryption using custom HSM keys. You can specify the encryption method, payload encoding, and optionally select a specific key alias. This guide demonstrates how to use each option in a POST /dispatch request.

Encrypting with hsmv1 Method

Use the hsmv1 method to explicitly request the first-generation HSM encryption algorithm.

POST /dispatch HTTP/1.1
Host: localhost:9200
Request-ID: MY REQUEST ID
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "dispatch": {
    "operation": "encrypt",
    "method": "hsmv1"
  },
  "payload": "my test data"
}

Encrypting with hsm Alias

The hsm alias refers to the latest version of the HSM encryption method currently supported by the system.

POST /dispatch HTTP/1.1
Host: localhost:9200
Request-ID: MY REQUEST ID
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "dispatch": {
    "operation": "encrypt",
    "method": "hsm"
  },
  "payload": "my test data"
}

Encrypting Base64-Encoded Payloads

When sending non-UTF-8 data, you can indicate the encoding used in the request. In this example, the payload is Base64-encoded.

POST /dispatch HTTP/1.1
Host: localhost:9200
Request-ID: MY REQUEST ID
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "dispatch": {
    "operation": "encrypt",
    "method": "hsm",
    "encoding": "base64"
  },
  "payload": "bXkgdGVzdCBkYXRh"
}

Encrypting with a Specific Key Alias

To use a specific, pre-configured HSM key, set the keyAlias parameter. This key must exist in the CRYPTO_CONFIG table.

POST /dispatch HTTP/1.1
Host: localhost:9200
Request-ID: MY REQUEST ID
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "dispatch": {
    "operation": "encrypt",
    "method": "hsm",
    "keyAlias": "MY KEY HERE"
  },
  "payload": "my test data"
}

Summary