Cloud Direct e-Sealing API

Cloud Direct e-Sealing is a simplified server-to-server API for enabled clients. It lets your server submit one or more base64-encoded SHA-256 file digests and receive signatures without redirecting an end user to a signing flow.

Setup

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

For the test environment:

1. Create an account at https://test.eideasy.com.
2. Go to My Webpages and add a webpage.
3. Open My Webpages again and copy the client_id from the webpage you created.
4. Click EDIT for that webpage and scroll to Eseal Settings.
5. Click Generate to create the e-seal HMAC key.
6. Copy the generated HMAC key into a safe location. It is shown only once.
7. 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);

Request Body

The request body below shows a CAdES example. Use the signature_form and signature_profile values enabled for your client.

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

Property	Type	Description
client_id	string	Required. Your eID Easy API client ID.
files	array	Required. File digests to e-seal.
files[].fileName	string	Required. File name of the original file.
files[].fileContent	string	Required. Base64-encoded SHA-256 digest of the original file.
files[].mimeType	string	Required. MIME type of the original file.
signature_form	string	Required. Signature form to produce.
signature_profile	string	Required. Signature profile to produce.

Request constraints:

• files must contain at least 1 file and at most 30 files.
• files[].fileName must be at least 3 characters long.
• Each files[].fileName must be unique within the request.
• files[].fileContent must be the base64-encoded SHA-256 digest of the original file.
• files[].mimeType must be a valid MIME type.

Response

If the request succeeds, the API returns one signature for each input file digest. For example, a CAdES response looks like this:

{
  "status": "OK",
  "signatures": [
    {
      "fileName": "document.pdf.p7s",
      "mimeType": "application/pkcs7-signature",
      "fileContent": "base64-encoded-signature"
    }
  ]
}

Property	Type	Description
status	string	OK when the request succeeded.
signatures	array	Signatures for the submitted file digests.
signatures[].fileName	string	Signature file name. For CAdES, the file name usually ends with .p7s.
signatures[].mimeType	string	Signature MIME type, e.g. application/pkcs7-signature.
signatures[].fileContent	string	Base64-encoded signature content.