Specific Batch Operations

1.0 Overview

This article illustrates example use cases of Batch APIs to perform encryption, decryption, signing, and verifying operations.

For more information on how to use the specific Batch APIs for encryption, decryption, signing, and verifying, refer to the following:

1.1 Key Points

Multiple cryptographic operations may be executed in a single Batch API call.
Each request entry can use the same or different keys.
DSM automatically generates Initialization Vectors (IVs) for Advanced Encryption Standard (AES) modes, if not provided.

2.0 Batch Encrypt and Decrypt

The Batch Encrypt or Decrypt API allows you to perform multiple cryptographic operations in a single request, reducing overhead when dealing with multiple keys, plaintexts, or ciphertexts.

Instead of repeatedly calling /encrypt or /decrypt, you can use this API endpoint to process arrays of requests. Each request item is independent and specifies its own key, algorithm, mode, and input.

2.1 API Endpoint

Encrypt: POST /crypto/v1/batch/encrypt
Decrypt: POST /crypto/v1/batch/decrypt

2.2 Authorization

Depending on your Fortanix DSM application setup, you can provide either a Basic token or a Bearer token.

In the following example, a Basic token is used:

--header 'Authorization: Basic <APP_API_KEY>'

2.3 Request Body – Batch Encrypt

The request body is an array of objects. Each object represents a single encryption request and includes the following key fields:

kid (string, required) – The UUID of the key stored in Fortanix DSM.
request (object, required) – The encryption request object, which includes:
- alg (string, required) – Cryptographic algorithm. For example: AES.
- plain (string, required) – Plaintext data to be encrypted (base64-encoded).
- mode (string, required) – Cipher mode. For example: CBC, GCM.
- iv (string, optional) – Initialization vector. If not provided, Fortanix DSM generates a random IV.
- ad (string, optional) – Additional authenticated data, required for authenticated modes such as GCM.
- tag_len (integer, optional) – Length of authentication tag (used with GCM or CCM).
- label (string, optional) – Label for RSA OAEP encryption.

2.4 Response – Batch Encrypt

The API returns an array of results, with each item corresponding to a request in the batch. Each item includes:

status – Status code for the individual request (200 if successful).
body – The response body, which contains:
- kid – The key ID used.
- cipher – The encrypted ciphertext.
- iv – The initialization vector used.
- tag (only for GCM or CCM) – The authentication tag.

2.5 Request Body – Batch Decrypt

The request body is an array of objects. Each object represents a single decryption request and includes the following key fields:

kid (string, required) – The UUID of the key stored in Fortanix DSM.
request (object, required) – The decryption request object which includes:
- alg (string, required) – Cryptographic algorithm. For example, AES.
- cipher (string, required) – The ciphertext to be decrypted (base64-encoded).
- mode (string, required) – The cipher mode. For example: CBC, GCM.
- iv (string, required) – Initialization vector used during encryption.
- ad (string, optional) – Additional authenticated data, must be provided if it was used in encryption (for authenticated modes such as GCM).
- tag (string, required for GCM or CCM) – Authentication tag from encryption.
- label (string, optional) – Label for RSA OAEP decryption.

2.6 Response – Batch Decrypt

The API returns an array of results, with each item corresponding to a request in the batch. Each item includes:

status – Status code for the individual request (200 if successful).
body – The response body, which contains:
- kid – The key ID used.
- plain – The decrypted plaintext (base64-encoded).

3.0 Walkthrough: Encrypt Two Plaintexts with Two Different Keys and Decrypt the Ciphers

3.1 Prerequisites

Two AES keys have already been created in Fortanix DSM with Encrypt permission. For example, one key for AES-GCM and another for AES-CBC.
Your Fortanix DSM application must be configured with access to these keys.
The Fortanix DSM base URL and an authorization token (Basic or Bearer).

3.2 Build the Batch Encrypt Request Payload

The following example shows two items in a batch encryption request:

Item 1 uses AES-GCM with additional authenticated data.
Item 2 uses AES-CBC with an explicit IV.

[
  {
    "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
    "request": {
      "alg": "AES",
      "mode": "GCM",
      "plain": "c2hhc2hpCg==",
      "tag_len": 128
    }
  },
  {
    "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
    "request": {
      "alg": "AES",
      "mode": "CBC",
      "plain": "c2hhc2hpCg=="
    }
  }
]

3.2.1 Execute Batch Encrypt Call

curl --location 'https://apac.smartkey.io/crypto/v1/keys/batch/encrypt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <APP_API_KEY>' \
--data '[
  {
    "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
    "request": {
      "alg": "AES",
      "mode": "GCM",
      "plain": "c2hhc2hpCg==",
      "ad": "b3JkZXItMTIzCg==", 
      "tag_len": 128
    }
  },
  {
    "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
    "request": {
      "alg": "AES",
      "mode": "CBC",
      "plain": "c2hhc2hpCg=="
    }
  }
]'

3.2.2 Interpret the Response

You will receive an array of results. Each array item corresponds to the matching request item. Each item contains:

status – The HTTP status code for that item.
body.kid – The key ID used.
body.cipher – The base64-encoded ciphertext.
body.iv – The base64-encoded IV used.
body.tag – The base64-encoded authentication tag (returned only for GCM or CCM).

Example response for the above API call:

[
  {
    "status": 200,
    "body": {
      "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
      "cipher": "CmXr74+VTQ==",
      "iv": "0m2VSeO0dZewIBtn",
      "tag": "Q1pG6ADMHmw/3s7lHZYdKw=="
    }
  },
  {
    "status": 200,
    "body": {
      "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
      "cipher": "ZYDuktyRn/xs/g8DY8gCFQ==",
      "iv": "gGQEq28647/e4jmQXnXGCw=="
    }
  }
]

3.2.3 Handling Errors

Batch processing is performed per item. If one item fails, the others can still succeed.

An error item has the following structure:

{
  "status": 400,
  "error": "reason text"
}

3.3 Build Batch Decrypt Request Payload

To decrypt, you must provide:

The same kid that was used for encryption.
The cipher value returned by the encrypt call.
The mode used during encryption.
The corresponding iv (for CBC or GCM) and tag (for GCM or CCM).
Any ad that was used during encryption (for authenticated modes).

Example request payload (using the encrypt response above):

[
  {
    "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
    "request": {
      "alg": "AES",
      "mode": "GCM",
      "cipher": "CmXr74+VTQ==",
      "iv": "0m2VSeO0dZewIBtn",
      "tag": "Q1pG6ADMHmw/3s7lHZYdKw==",
      "ad": "b3JkZXItMTIzCg=="
    }
  },
  {
    "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
    "request": {
      "alg": "AES",
      "mode": "CBC",
      "cipher": "ZYDuktyRn/xs/g8DY8gCFQ==",
      "iv": "gGQEq28647/e4jmQXnXGCw=="
    }
  }
]

3.3.1 Execute the Batch Decrypt Call

curl --location 'https://apac.smartkey.io/crypto/v1/keys/batch/decrypt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <APP_API_KEY>' \
--data '[
  {
    "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
    "request": {
      "alg": "AES",
      "mode": "GCM",
      "cipher": "CmXr74+VTQ==",
      "iv": "0m2VSeO0dZewIBtn",
      "tag": "Q1pG6ADMHmw/3s7lHZYdKw==",
      "ad": "b3JkZXItMTIzCg=="
    }
  },
  {
    "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
    "request": {
      "alg": "AES",
      "mode": "CBC",
      "cipher": "ZYDuktyRn/xs/g8DY8gCFQ==",
      "iv": "gGQEq28647/e4jmQXnXGCw=="
    }
  }
]'

3.3.2 Interpret the Response

You will receive an array of results. Each array item corresponds to the matching request item. Each item contains:

status – The HTTP status code for that item.
body.kid – The key ID used.
body.plain – The decrypted plaintext (Base64-encoded).

Example response:

[
  {
    "status": 200,
    "body": {
      "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
      "plain": "c2hhc2hpCg=="
    }
  },
  {
    "status": 200,
    "body": {
      "kid": "bda1627f-fb05-471e-99f9-5a018153ce97",
      "plain": "c2hhc2hpCg=="
    }
  }
]

3.3.3 Handling Errors

As with encryption, batch decryption is processed per item. If one decryption fails (for example, due to an incorrect IV, tag mismatch, or invalid ciphertext), the other items can still succeed.

Example error response item:

{
  "status": 400,
  "error": "Authentication failed: invalid tag"
}

4.0 Batch Signing and Verifying

The Batch Sign/Verify API allows you to create and validate multiple digital signatures in a single request. This is especially useful when working with multiple messages or keys, as it minimizes the number of API calls.

Instead of repeatedly calling the /sign or /verify endpoints, you can use this API to process arrays of requests. Each request item is independent and specifies its own key, hash algorithm, and input hash.

4.1 API Endpoint

Sign - POST /crypto/v1/keys/batch/sign
Verify - POST /crypto/v1/keys/batch/verify

4.2 Authorization

You can provide either a Basic token or a Bearer token, depending on your Fortanix DSM application setup.

In the following example, a Basic token is used:

--header 'Authorization: Basic <APP_API_KEY>'

4.3 Request Body – Batch Sign

The request body is an array of objects. Each object represents a single signing request and includes the following fields:

key (object, required):
- kid (string, required) – The UUID of the key stored in Fortanix DSM (must be an asymmetric signing key such as RSA or ECDSA).
hash_alg (string, required) – Hash algorithm used. For example, SHA256, SHA384, SHA512.
hash (string, required) – The digest to be signed (base64-encoded).
NOTE
The hash length must match the hash algorithm. For example, SHA256 → 32 bytes, SHA512 → 64 bytes.

4.4 Response – Batch Sign

The API returns an array of results corresponding to each request in the batch. Each item includes:

status – Status code (200 if successful).
body – Response object containing:
- kid – The key ID used for signing.
- hash_alg – The hash algorithm applied.
- signature – The generated digital signature (base64-encoded).

4.5 Request Body – Batch Verify

The request body is an array of verification requests. Each object includes:

kid (string, required) – The UUID of the key stored in Fortanix DSM.
hash_alg (string, required) – The hash algorithm used. For example, SHA256.
hash (string, required) – The base64-encoded hash of the message.
signature (string, required) – The base64-encoded digital signature to be verified.

4.6 Response – Batch Verify

The API returns an array of results corresponding to each verification request. Each item includes:

status – Status code (200 if successful).
body – Response object containing:
- kid – The key ID used.
- result – Boolean value (true if the signature is valid, false otherwise).

5.0 Walkthrough: Sign and Verify Data with Fortanix DSM

5.1 Prerequisites

An RSA or EC key already created in Fortanix DSM with Sign or Verify permission.
Your Fortanix DSM application configured with access to this key.
The Fortanix DSM base URL and an authorization token (Basic or Bearer).

5.2 Build the Batch Sign Request Payload

Each signing request requires:

kid – The key ID of the signing key.
hash_alg – The hash algorithm. For example, SHA256, SHA384, and so on.
hash – A base64-encoded hash of the data or the raw base64-encoded data itself.

Example: Sign two different hashes using the same key.

[
  {
    "key": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab"
    },
    "hash_alg": "Sha256",
    "hash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="
  },
  {
 "key": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab"
    },
    "hash_alg": "Sha256",
    "hash": "c5Yj7KP3a91gvb3JDhN2ydsRo1u9GhdPT9RYnvWrG7Y="
  }
]

5.2.1 Execute the Batch Sign Call

curl --location 'https://apac.smartkey.io/crypto/v1/keys/batch/sign' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <APP_API_KEY>' \
--data '[
  {
    "key": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab"
    },
    "hash_alg": "Sha256",
    "hash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="
  },
  {
 "key": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab"
    },
    "hash_alg": "Sha256",
    "hash": "c5Yj7KP3a91gvb3JDhN2ydsRo1u9GhdPT9RYnvWrG7Y="
  }
]'

5.2.2 Interpret the Response

Each response item corresponds to one request. Each item includes:

status – The HTTP status code for that item.
body.kid – The key ID is used for signing.
body.signature – The base64-encoded digital signature.

Example response:

[
  {
    "status": 200,
    "body": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab",
      "signature": "BASE64_SIGNATURE_1"
    }
  },
  {
    "status": 200,
    "body": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab",
      "signature": "BASE64_SIGNATURE_2"
    }
  }
]

5.2.3 Handling Errors

If signing fails (for example, due to a hash size mismatch or an invalid key), only that request fails. Other requests in the batch may still succeed.

Example error response item:

{
  "status": 400,
  "error": "Hash size does not match the hash algorithm specified - Expected size (bytes): 32, Got: 48"
}

5.3 Build the Batch Verify Request Payload

Each verification request requires:

kid – The same key ID is used for signing.
hash_alg – The hash algorithm is used.
hash – The base64-encoded hash of the data.
signature – The signature returned by the sign API (base64-encoded).

Example payload:

[
  {
    "key": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab"
    },
    "hash_alg": "Sha256",
    "hash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
 "signature": "BASE64_SIGNATURE_1"
  },
  {
    "key": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab"
    },
    "hash_alg": "Sha256",
    "hash": "c5Yj7KP3a91gvb3JDhN2ydsRo1u9GhdPT9RYnvWrG7Y=",
 "signature": "BASE64_SIGNATURE_2"
  }
]

5.3.1 Execute the Batch Verify Call

curl --location 'https://apac.smartkey.io/crypto/v1/keys/batch/verify' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <APP_API_KEY>' \
--data '[
  {
    "key": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab"
    },
    "hash_alg": "Sha256",
    "hash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
 "signature": "BASE64_SIGNATURE_1"
  },
  {
    "key": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab"
    },
    "hash_alg": "Sha256",
    "hash": "c5Yj7KP3a91gvb3JDhN2ydsRo1u9GhdPT9RYnvWrG7Y=",
 "signature": "BASE64_SIGNATURE_2"
  }
]'

5.3.2 Interpret the Response

Each response item corresponds to one verification request. Each item includes:

status – The HTTP status code for that item.
body.kid – The key ID used for verification.
body.result – true if the signature is valid, false otherwise.

Example response:

[
  {
    "status": 200,
    "body": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab",
      "result": true
    }
  },
  {
    "status": 200,
    "body": {
      "kid": "680d1795-a896-44e7-a01a-82c6863b65ab",
      "result": true
    }
  }
]

5.3.3 Handling Errors

If verification fails (for example, due to a wrong signature or hash mismatch), only that request fails. Other requests in the batch may still succeed.

Example error response item:

{
  "status": 400,
  "error": "Signature verification failed"
}

Specific Batch Operations

1.0 Overview

1.1 Key Points

2.0 Batch Encrypt and Decrypt

2.1 API Endpoint

2.2 Authorization

2.3 Request Body – Batch Encrypt

2.4 Response – Batch Encrypt

2.5 Request Body – Batch Decrypt

2.6 Response – Batch Decrypt

3.0 Walkthrough: Encrypt Two Plaintexts with Two Different Keys and Decrypt the Ciphers

3.1 Prerequisites

3.2 Build the Batch Encrypt Request Payload

3.2.1 Execute Batch Encrypt Call

3.2.2 Interpret the Response

3.2.3 Handling Errors

3.3 Build Batch Decrypt Request Payload

3.3.1 Execute the Batch Decrypt Call

3.3.2 Interpret the Response

3.3.3 Handling Errors

4.0 Batch Signing and Verifying

4.1 API Endpoint

4.2 Authorization

4.3 Request Body – Batch Sign

4.4 Response – Batch Sign

4.5 Request Body – Batch Verify

4.6 Response – Batch Verify

5.0 Walkthrough: Sign and Verify Data with Fortanix DSM

5.1 Prerequisites

5.2 Build the Batch Sign Request Payload

5.2.1 Execute the Batch Sign Call

5.2.2 Interpret the Response

5.2.3 Handling Errors

5.3 Build the Batch Verify Request Payload

5.3.1 Execute the Batch Verify Call

5.3.2 Interpret the Response

5.3.3 Handling Errors

PLATFORM

Key Insight

Data Security Manager™

Confidential Computing Manager

Enclave Development Platform®

Request A demo

Contact Us

Free Trial

SOLUTIONS

AWS KMS External Key Store (XKS)

Google External Key Manager

Bring Your Own Key (BYOK)

HSM Modernization

Multicloud Key Management

Post Quantum Cryptography

Code Signing

Secrets Management

Tokenization Transparent

Database Encryption

Filesystem Encryption

Confidential Data Search

Confidential AI

Healthcare

Banking & Financial Services

Fintech

Manufacturing

Web 3.0

Federal Government

RESOURCES

Blog

Whitepapers

Datasheets

Solution Briefs

Ebooks

Reports

Case Studies

Webinars

University

Media Kit

Newsletters

COMPANY

About

Careerswe’re hiring