Cloud Direct e-Sealing API

Cloud Direct e-Sealing is a simplified server-to-server API for enabled clients. It lets your server submit CAdES file digests, full XML files, or XAdES document reference digests and receive signatures without redirecting an end user to a signing flow.

Request types

Choose the request type for your integration:

CAdES: send file digests and receive detached signatures.
XAdES full file: send original XML files and receive complete signed XML.
XAdES reference digest: send canonicalized XML digests and receive signature fragments to insert into the original XML.

All three use the endpoint and authentication described below.

Setup

To use Cloud Direct e-Sealing, you need a client_id and an e-seal HMAC key.

For the test environment:

Create an account at https://test.eideasy.com.
Go to My Webpages and add a webpage.
Open My Webpages again and copy the client_id from the webpage you created.
Click EDIT for that webpage and scroll to Eseal Settings.
Click Generate to create the e-seal HMAC key.
Copy the generated HMAC key into a safe location. It is shown only once.
Send the client_id to eID Easy so test e-seal credentials can be configured for your client.

Endpoint

Send a server-side POST request to:

https://id.eideasy.com/api/signatures/e-seal

For the test environment, use:

https://test.eideasy.com/api/signatures/e-seal

Authentication

Cloud Direct e-Sealing uses HMAC authentication only.

Send these headers with each request:

Header	Description
Content-Type	Must be `application/json`.
X-Timestamp	UNIX timestamp in seconds. Maximum leeway is 5 minutes.
X-HMAC-Signature	Base64-encoded HMAC.

The HMAC input must be exactly:

METHOD + PATH + X-Timestamp + RAW_REQUEST_BODY

For example:

POST/api/signatures/e-seal1710000000{"client_id":"client-id","files":[{"fileName":"document.pdf","fileContent":"rxr4oMRqMAjrAdhgXjjYeLlh285M9UU1wxj+ksg3efY=","mimeType":"application/pdf"}],"signature_form":"CAdES","signature_profile":"CAdES_BASELINE_T"}

Calculate the signature as:

base64(hmac_sha256(message, eseal_hmac_key))

IMPORTANT

Sign the exact raw JSON body that is sent over the wire. Do not pretty-print, reorder, or reserialize the JSON after signing it.

Postman HMAC example

You can use the following Postman pre-request script to generate the HMAC signature with the native Web Crypto API. Set the hmac_key variable to your e-seal HMAC key before sending the request.

const secretKey = pm.variables.get('hmac_key');
const httpMethod = pm.request.method;
const url = pm.request.url.getPath();
const timestamp = Math.floor(Date.now() / 1000);
const body = pm.variables.replaceIn(pm.request.body.toString());

async function createHmac(key, value) {
  const encoder = new TextEncoder();
  const cryptoKey = await crypto.subtle.importKey(
    'raw',
    encoder.encode(key),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );
  const signature = await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(value));

  return btoa(String.fromCharCode(...new Uint8Array(signature)));
}

const message = `${httpMethod}${url}${timestamp}${body}`;
const signature = await createHmac(secretKey, message);

pm.request.headers.upsert({ key: 'X-HMAC-Signature', value: signature });
pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });
pm.request.headers.upsert({ key: 'Content-Type', value: 'application/json' });

console.log('Message:', message);
console.log('Signature:', signature);
console.log('Timestamp:', timestamp);

# Cloud Direct e-Sealing API

# Request types

# Setup

# Endpoint