Skip to main content

REST-API & Transaction Security Broker

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.

Authentication​

  • Select your API service-url:

    • https://sbx-rest-api.cloudshsm.com/v1/
    • https://rest-api.cloudshsm.com/v1/
    • https://primusdev.cloudshsm.com/v1/
    • http://localhost:8081/v1

    Unsure? refer to the connectivity details page or use the connectivity details in the credentials file (CloudHSM only)

  • Replace <JWT_TOKEN> (CloudHSM only, remove otherwise)

curl -X "GET" "https://sbx-rest-api.cloudshsm.com/v1/versionInfo" \
-H "accept: application/json" \
-H "Authorization: Bearer <JWT_TOKEN>"

Response:

{
  "Version": "2.4.0",
  "Vendor": "Securosys SA"
}

Create an RSA Key​

This section explains how to:

  • create an RSA Key
  • sign a payload with the previously created 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
  1. Navigate to the API-Section Keys
  2. Click on POST /v1/key
  3. Click the button Try it out
  4. Set the request-body:

Request:

{
  "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​

Sign-Payload Parameters
ParameterDescription
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.
  1. Navigate to the API-Section Synchronous Key Operations
  2. Click on POST /v1/synchronousSign
  3. Click the button Try it out
  4. Set the request-body

Request:

{
    "signRequest": {
        "payload": "UGF5bG9hZA==",
        "signKeyName": "<keyname>",
        "signatureAlgorithm": "SHA224_WITH_RSA_PSS"
    }
}

Response:

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

What's next?​

Encryption

Transaction Security Broker

Certificate Management

Import Key

  • Import a locally generated Key Sample

More

Last updated on