Skip to main content

REST-API & Transaction Security Broker

HSM Integration Guide​

Rest-API​

The Securosys REST API, encapsulated within a Docker container, seamlessly interfaces with Primus HSM clusters and CloudHSM, providing a versatile, language-agnostic solution for robust hardware security module (HSM) integration. This API serves as a bridge for secure key management, enabling cryptographic operations such as signing and encryption with the highest level of protection. Leveraging the power of HSMs, it ensures the confidentiality and integrity of sensitive data, making it an indispensable tool for applications demanding advanced security measures.

How it works​

The Rest-API, deployed as a Docker container, establishes a direct connection to a single HSM partition (User), enabling secure cryptographic operations. To enhance scalability and distribute the workload, multiple Docker containers can communicate with a shared HSM partition, facilitating effective load balancing. Additionally, the Rest-API's flexible architecture supports a 1:n configuration, allowing one API interface (one Docker container) to connect with multiple HSMs or partitions using JWT-Token's for authentication, while a second container manages states and credential information in a dedicated database for comprehensive system management.

Try it out​

On this page it is shown how to:

  • create an RSA Key
  • sign a payload with the previously created key

Create an RSA Key​

POST: /v1/key

Key Parameters
ParameterDescription
labelThe email address of the Approver, e.g., officer1@securosys.com.
algorithmThe algorithm of the key. Supported algorithms: /Algorithms
keySizeThe size of the Key. Applicable for RSA, DSA, ISS and Symmetric algorithms.
curveOidNeeded if Alrogithm==EC
decryptcheck Key-Attributes
signcheck Key-Attributes
unwrapcheck Key-Attributes
destroyablecheck Key-Attributes
Connectivity Details

You may replace the endpoint https://tsb-demo.cloudshsm.com/ below by a TSBaaS - Connectivity Details for accurate API-Endpoint URI.

  1. Open the Swagger documentation to interact directly with the API using your browser: https://tsb-demo.cloudshsm.com/swagger-ui/index.html

  2. Request: Replace <keyname>

    {
      "label": "<keyname>",
      "algorithm": "RSA",
      "keySize": 2048,
      "attributes": {
          "sign": true,
          "extractable": false,
          "modifiable": true,
          "destroyable": true,
          "sensitive": true,
          "decrypt": false,
          "unwrap": false
      }
    }

    Response:

    {
    "xml": "<xml-formatted attributes of the key>",
    "json": {
        "label": "...",
        "id": null,
        "algorithm": "RSA",
        "algorithmOid": "1.2.840.113549.1.1.1",
        "curveOid": null,
        "keySize": 2048,
        "createTime": "2021-02-24T15:10:03Z",
        "attestTime": "2021-02-24T15:10:03Z",
        "publicKey": "MIIBIj...AB",
        "addressTruncated": null,
        "attributes": {
        "decrypt": false,
        "sign": true,
        "ekaSign": null,
        "unwrap": false,
        "derive": false,
        "sensitive": true,
        "alwaysSensitive": true,
        "extractable": false,
        "neverExtractable": true,
        "modifiable": true,
        "copyable": true,
        "destroyable": true
        },
        "policy": null
    },
    "xmlSignature": "<base64-encoded-signature>",
    "attestationKeyName": "attestation-key"
    }

Sign a Payload with the Key​

POST: /v1/synchronousSign

Description:

Request: Replace <keyname>

{
    "signRequest": {
        "payload": "UGF5bG9hZA==",
        "signKeyName": "<keyname>",
        "signatureAlgorithm": "SHA224_WITH_RSA_PSS"
    }
}
payloadThe data for which you want to create a digital signature. It should be encoded using base64.
signKeyNameThe label or identifier of the key stored within the HSM. This key is used for generating the digital signature.
signatureAlgorithmSpecifies the algorithm used for generating the digital signature. In this case, it's SHA224_WITH_RSA_PSS, indicating that SHA224 is used for hashing the payload and RSA with PSS padding scheme is used for signing.

Response:

{
"signature": "A4Jw63iLqG4gj6lyxi+BxDA4QtlN3PHQGk6BeCmd0zrt4OFn56v0XKQqa4sZ73ukeNSa0c1VcMPT0U6fe1Lt7DCNK9CTeerbanwtEkvGnmTFXt8FyOMABppeNCbLdcDzr7u7in+9jDdQzw0/Q+lVF/4lLFA9QykTtYNh7p+7a9QSv2ZucNCjAK0ief95Kb9KuJ6SjyV4jeiI8yIsliH/TLjfMswCa+Bmyq53c3QdcHkJDypm3riUHOCXAPn1YpwjwNPy9KFR+0Hyhf2MI2ar051J4F+/zooYjYJHYggYBnJ6LyOShudXOIH4UKjsgt2tkrMHSCHcnsappRgq4oRQ+Q=="
}

What's next?​

Crypto Operations

Deployment Guides

Transaction Security Broker

More

Last updated on