H2 (Hosted HSM) API documentation version \1.0.2

host/api/v1

Introduction

H2 API allows interaction with a private hosted HSM instance. An Hosted HSM instance acts like a really simple smart card with off-card hashing, meaning the caller is responsible for hashing the Data To Be Signed.

Flow

A typical PDF signature flow:

  1. Client reserves spaces in the PDF to accomodate for the signature.
  2. Client gathers elements required to calculate hash (PDF byte range, certificates, CRL, OCSP, etc)
  3. Client calculate hash over these elements.
  4. Client post the hash to Hosted HSM.
  5. Hosted HSM signs the hash.
  6. Client incorporates the signature into the PDF.
  7. Optionnaly, the client timestamps the signature/document.

API resources

/certs

Accessor to the certificate chain.

get

get

Accessor to the certificate chain where each element is a Base64-encoded X.509 certificate (DER format). The chain has the following order:

  1. End Entity Certificate
  2. Issuing Certificate Authority
  3. Root Certificate Authority

/signatures

Signs the provided data using the Hosted HSM instance signature key.

post

post

Calls the actual signature function. The request body MUST be a JWS (Json Web Signature) Object (as defined in RFC7515) computed over the Json representation of the request parameters documented below. The JWS algorithm must be HMAC-SHA256 and signed using the signature key provided by Notarius.

Calls the actual signature function. The request body MUST be a JWS (Json Web Signature) Object (as defined in RFC7515) computed over the Json representation of the request parameters documented below. The JWS algorithm must be HMAC-SHA256 and signed using the signature key provided by Notarius.

Body

Media type: application/json

Type: object

Properties
  • digestInfo: required(string)

    Base64 encoded DigestInfo object (ASN.1 encoded). For proper formatting refer to the following ASN.1 schema:

    DigestInfo::=SEQUENCE{
digestAlgorithm  AlgorithmIdentifier,
digest OCTET STRING}

    For example, the following string:

    this is a digestinfo asn.1 object

    will produce the following SHA-256 digest:

    SHA-256(this is a digestinfo asn.1 object) = 13be50bde28ec523c1b8f1d05b0ef9ea4345b3489098b839067272d59e091d3c

    The ASN.1 digest info can be build form the concatenation of the OID_SHA256 with the SHA-256 HASH in hexadeximal:

    OID_SHA256 = 3031300d060960864801650304020105000420
digest = 13be50bde28ec523c1b8f1d05b0ef9ea4345b3489098b839067272d59e091d3c

concatanation = 3031300d06096086480165030402010500042013be50bde28ec523c1b8f1d05b0ef9ea4345b3489098b839067272d59e091d3c

    which converted from hexadecimal to binary to base64 will result in the following ASN.1 DigestInfo:

    MDEwDQYJYIZIAWUDBAIBBQAEIBO+UL3ijsUjwbjx0FsO+epDRbNIkJi4OQZyctWeCR08

    The format can be validated with the following site: https://www.marben-products.com/asn.1/services/decoder-asn1-security.html

  • nonce: required(string)

    Random and unique value assigned by caller. The same nonce value is returned in the response and must be validated by caller to ensure the response is for the request made.

  • version: required(integer)

    Must be 1.

Example:

JWS_SIGNATURE(
 {
   "digestInfo": "MDEwDQYJYIZIAWUDBAIBBQAEIBO+UL3ijsUjwbjx0FsO+epDRbNIkJi4OQZyctWeCR08",
   },
  "nonce": "1234",
  "version": 1            
 }
)

HTTP status code 201

Body

Media type: application/json

Type: object

Properties
  • sig: required(string)

    Base64 encoded signature result.

  • nonce: required(string)

    Same value as nonce specified in request. Caller MUST compare this value with the request and make sure they are the same.

Example:

{
  "nonce": "12345",
  "sig": "o7jvEbS8uEm4jtmDq65HMcOmpapXbMw/zKw6p26qNFEKD5pEvzD63rWcSta6xfIBVXsJlD4cxN/PTy3dlWLk/n1fIVINAwAhHNo4H2cI0YkN9I385r+zuZtu8duEYr4I4UqxoAzkLGaG0HbGkOnoRXDA3CMU0LI+tM6mppTR0uYf0V171vAy+Ybb2/XhubDuGVEpyn6zn0ATEvvJiZ0TJPFB/o4h5CZUBeg+Cz/776t3qXFHyO6mWMSuQl/iQqnfKKf8MLLaCmf8LvpTjDZLBDSUeqeAjf9xSzDTVFuonhJEepkhEHlZHz0FUPWp2mcmaBLbV1OU9Dn7LQLNwZuU6w=="
}

HTTP status code 400

Bad request. Make sure the input digestInfo was correctly formatted. Make sure the required fields were correctly filled.