Encrypting and signing digital files before sending them to the Pismo platform is crucial for ensuring both security and authenticity. Encryption protects the data by converting it into a format that can only be read by someone who has the appropriate decryption key, thereby safeguarding it from unauthorized access and potential breaches. This ensures that sensitive information, such as personal details, financial data, or confidential business documents,

remains private and secure during transmission.

Digital signatures, on the other hand, provide a means to verify the authenticity and integrity of the files. By signing a file, the sender attaches a unique cryptographic signature that can be verified by the recipient to confirm that the file has not been altered in transit and that it indeed comes from the purported sender. This helps prevent tampering, forgery, and impersonation, thereby establishing trust and confidence in the communication process.

To this end, Pismo provides features for both signing and encrypting your files. These features meet the following criteria:

• Authenticity: They confirm that the file originates from the customer, verifying the sender's identity.
• Integrity: They ensure that the file remains unchanged and untampered from the moment it was signed.
• Confidentiality: They use managed encryption keys, allowing customers to encrypt files before sending, protecting their data from unauthorized access.

💡

Note

Before uploading your bulk file, you must sign and encrypt it.

To verify the authenticity of your signature, Pismo requires your public key. Upload it using the Upload public key endpoint.

To submit a bulk file, choose one of the following:

• Use the Upload bulk file endpoint.
• Upload the file directly to Pismo’s AWS S3 bucket.

If you use the AWS S3 option, you must also include a signature envelope containing the key ID and the signature data, sent alongside the bulk file.

📘

About signature envelope

A signature envelope is a small companion file that carries the information needed to verify a digitally signed payload (your bulk file). It typically travels alongside the file and includes the signature and metadata about how it was produced.

File signature

Digital signatures use asymmetric cryptography: a public key and a private key. Before sending your bulk file:

• Generate an RSA‑3072 key pair.
• Use your private key to sign the unencrypted bulk file with RSA and a SHA‑384 digest.
• Upload your public key via the Upload public key endpoint to enable signature verification during bulk file processing.

📘

What is RSA-3072?

RSA-3072 refers to an RSA encryption key size that is 3072 bits long. RSA (Rivest-Shamir-Adleman) is an asymmetric cryptographic algorithm used for secure data transmission. The key size, in this case 3072 bits, determines the strength of the encryption. A larger key size generally means stronger security, but it also requires more computational power.

RSA-3072 is considered secure for most purposes and provides a higher level of security compared to shorter key sizes like RSA-2048. It's often used in applications requiring long-term security, such as digital signatures, SSL/TLS certificates, and secure email communication.

Before you begin

There are caveats you must follow before you begin creating your signature file.

• When sending a bulk file, include both the encrypted original file and the signature envelope file.
  Exception: If you use Pismo’s Upload Bulk File endpoint, the signature envelope is not required. Instead, you can provide the key ID and signature data in the dedicated Signature header, as explained in Upload bulk file.
• The original file refers to the input bulk file.
• The original file must be signed first, then encrypted using an AES key provided by Pismo. You can request this AES key via the Create AES key endpoint.
• The encrypted original file and the signature envelope file must use the extensions .original and .sign, respectively.

Create public and private keys

Create a RSA-3072 key pair to digitally sign the bulk file. Here is how to generate a key pair, extract the public key, and upload it.

1. Run this command to generate an RSA‑3072 private key. In this example, private-key.pem is the output file. PEM (Privacy‑Enhanced Mail) is a standard format for storing and exchanging cryptographic keys and certificates.

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out private-key.pem

2. Create a public key (public-key.der) from the private key.

openssl pkey -in private-key.pem -outform der -out public-key.der -pubout 

📘

About DER

All key materials are in the DER format and encoded in base64. DER (Distinguished Encoding Rules) is a binary format for encoding data structures described by ASN.1 (Abstract Syntax Notation One). It is commonly used in cryptography for encoding certificates, keys, and other data.

3. Generate key material from the public key.

base64 -i public-key.der

📘

About key material

Key material represents the actual key data used for performing cryptographic operations such as encryption, decryption, signing, and verification.

4. Copy and paste the generated key material in the key_material field in Upload public key to upload your public key to Pismo.

The following is a sample request for uploading a public key:

curl --request POST \
     --url https://api-sandbox.pismolabs.io/corporate/v1/bulk-payments/keys \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "id": "<key_id>",
  "key_material": "<key_material>",
  "expired_at": "2025-05-21T12:27:00Z"
}
'

For details about the fields in the request, see Upload public key.

When the request is processed successfully, a 201 Created response is returned confirming the key you sent previously.

{
  "id": "<key_id>"
}

Retrieve a public key using the key ID

If you need to retrieve a public key you've sent, you can use the Get public key endpoint with the public key ID. This endpoint allows you to query a Pismo public key to validate a signature or to retrieve a public key that you uploaded.

Prepare signature envelope file

The signature envelope file is a text file containing a JSON object with the signature data, it contains the following fields.

• org_id: Tenant identification.
• signing_key_id: ID of the public key corresponding to the private key used to sign the file.
• bulk_id: Bulk ID specified in the original file.
• signature: Signature encoded in base64.

The following is an example of the JSON object in a signature envelope file.

{
  "org_id": "<your_org_id>", 
  "signing_key_id": "<your_signing_key_id>",
  "bulk_id": "<your_bulk_id>",
  "signature": "<signature_encoded_in_base64>"
}

Note that the signature envelope format is identical for client-submitted signatures and Pismo‑generated output signatures. The public key corresponding to the signing private key must be uploaded in advance via the Upload public key endpoint.

Before you proceed, there are some key points to consider regarding the format of the signature envelope file.

• Without the key ID (the id parameter in Upload public key), it is impossible to identify the public key that must be used to verify the signature. To pass the signature verification step during bulk processing, you must provide Pismo with three components: the bulk file, a digital signature, and the corresponding public key. There are two ways to do this. One, you can use the Upload bulk file endpoint. In this scenario, you specify the key ID (id) and the signature in the request header. Another way is to create a signature envelope file that contains the key ID and the signature data, then upload it to a Pismo-designated AWS S3 bucket.
• The actual key material is uploaded and securely stored in Pismo’s database. It can be submitted only through the Upload public key endpoint, which uses mutual authentication over a private network to ensure only the authorized client can transmit the key and to prevent unauthorized submissions.
• Only the key ID (id) is sent to Pismo, not the actual key.

Sign the bulk file

These steps show how to sign the unencrypted bulk file and generate the signature envelope. Run this command to sign the unencrypted bulk file with your client‑generated private key.

openssl dgst -sha384 -sign private-key.pem -out signature.tmp  2024-05-21-15-55-00-<bulk_id>.plain

In this example:

• private-key.pem is the file containing your private key.
• 2024-05-21-15-55-00-<bulk_id>.plain is the unencrypted version of the bulk file you intend to send to Pismo.
• signature.tmp is a temporary file used to store the generated signature data.

Generate the base64-encoded signature

Generate base64-encoded content for the signature file.

base64 -i signature.tmp

This command outputs the base64 string that goes into the signature attribute of the signature envelope file.

Signature envelope file output

A signature envelope file is generated, it contains a JSON object with three attributes: bulk_id, key_id, and signature.

• bulk_id: The bulk identifier as specified in the bulk file. This ID is client-generated. You must generate this ID and provide it to Pismo.
• key_id: The identifier of the public key corresponding to the private key used to sign the file.
• signature: The signature encoded in base64 that you generated in the Generate the base64-encoded signature section.

This format is used for both the bulk file you send and the output file generated by Pismo.

After the bulk file is processed, Pismo returns an output file along with a corresponding signature envelope. The example below shows the envelope generated by Pismo. The key_id refers to Pismo’s public key used to sign the output file and is different from the customer’s signing key.

{
  "bulk_id": "<bulk_id>",
  "key_id": "<key_id>",
  "signature": "<Pismo-signature>"
}

Verify Pismo's signature envelope file

After processing a bulk file, Pismo generates an output file containing the results of the bulk processing. This file is digitally signed by Pismo, and the corresponding signature is provided to the customer in a signature envelope file. This envelope follows the same JSON format used by the customer when uploading a file via the AWS S3 bucket approach. The following example illustrates a manual verification process that can serve as a basis for implementation. The example contains the following steps:

1. Decode the base64 into a temporary file.
2. Retrieve Pismo's public key.
3. Create a DER file to contain the public key material.
4. Verify signature.

Decode the base64 into a temporary file

To decode the base64 of the signature data into a temporary file, follow these steps:

Create a file named pismo-signature.base64, then copy and paste the value of the signature attribute from the Pismo's signature envelope file.

Use this command to create a pismo-signature.data file.

base64 -i pismo-signature.base64 -D > pismo-signature.data

Retrieve Pismo's public key

Use Get public key to retrieve the Pismo's public key, this step is essential because you need the key_material value to create a der file in the subsequent step. Once successful, the following response is returned.

200 Ok
{
  "id": "<key_id>",
  "key_material": "<key_material>",
  "expires_at": "2025-05-21T12:27:00Z"
}

Create a der file

The key_material attribute in the returned response represents the public key. Copy and save it to a file (pismo-key.base64). Then use the following command to decode the string and output it to a der file (pismo-key.der).

base64 -i pismo-key.base64 -D > pismo-key.der

Verify signature

To verify the signature, you need the DER file (pismo-key.der), the signature file (pismo-signature.sign), and the Pismo-signed bulk file. Use the following command to proceed with the verification.

To verify the signature, you need the DER file (pismo-key.der), the signature file (pismo-signature.data), and the Pismo-signed output file. Use this command to proceed with the verification.

openssl dgst -sha384 -verify pismo-key.der -keyform DER -signature pismo-signature.data 2024-05-21-15-55-00-<bulk_id>-out.original

If the verification is successful, a Verified OK message is returned in the command window

File encryption

Encryption specification

After signing the bulk file, it must be encrypted using an AES-256 symmetric key. You can obtain this key using the Get AES key endpoint. Keep in mind that each key is single-use, so every time you want to encrypt a bulk file, you must send a new request using a different client-generated bulk ID. The encryption must adhere to these specifications.

• Algorithm: AES-256-CBC
• Key-type: Symmetric

📘

About the AES key and the symmetric key type

• An AES key is a cryptographic key used in the Advanced Encryption Standard (AES) algorithm, which is a symmetric encryption algorithm. The suffix 256 in AES-256 refers to the bit length of the key used in the algorithm. AES is widely used for securing data due to its efficiency and strong security properties.
• The key type “symmetric” refers to a cryptographic system where the same key is used for both encryption and decryption.

If the request is successfully processed (200 ok), you should receive a response in this format.

{
  "aes_key": "<your_aes_key>",
  "iv": "<your_iv>"
}

For details about aes_key and iv in the response, see Get AES key.

Run the following command using the values returned for aes_key and ivin the response to encrypt a bulk file.

openssl enc -aes-256-cbc -in 2024-05-21-15-55-00-<bulk_id>.plain -out 2024-05-21-15-55-00-<bulk_id>.original -K "<your_aes_key>" -iv "<your_iv>"