Link Search Menu Expand Document

User-controlled encryption of input files and decryption of output files.

PDF.co API supports additional layer of strong AES encryption and decryption for input and output files content. You can encrypt files on your own and pass them to PDF.co API for processing. Or you can decrypt files on your own after PDF.co API processing.

While PDF.co stores files on the server for a short period of time (we do not have access to the files content) in the encrypted-at-rest cloud storage, but it may be a good idea to additionally encrypt files on your own before sending them to PDF.co API for processing. This way you can have an additional measure to make sure no one can access files content without having your own encryption key.

Processing sensitive data? Review this checklist.

What is AES?

AES is a symmetric-key algorithm for the encryption of electronic data. It is an advanced encryption standard that is used worldwide for protecting sensitive data. AES is based on a design principle known as a Feistel cipher, which uses a round function F that operates on pairs of bits, called "plaintext" and "ciphertext". The round function is applied to each pair of bits separately, and the result is combined to form the final output. The number of rounds is an important parameter of the cipher. The AES algorithm has three key lengths: 128, 192, and 256 bits. The algorithm is also known by its original name Rijndael, which was chosen in 1997 by the Belgian cryptographer Joan Daemen and the Dutch cryptographer Vincent Rijmen to commemorate the 100th birthday of their teacher, the cryptographer Rijndael.

PDF.co supports the following AES modes for user-controlled encryption/decryption:

  • AES128 - 128-bit encryption.
  • AES192 - 192-bit encryption.
  • AES256 - 256-bit encryption.

Common scenarios for using user-controlled encryption:

  1. Automatically encrypt output files for further storage locally or on public cloud services like Dropbox, Google Drive, or similar. Even if a middleman obtains the link to this encrypted file, they cannot open the file content without having your encryption key.

  2. Automatically decrypt input files generated by third-party services or apps like SalesForce, Zapier, Integromat, or custom JavaScript/PHP/.NET/Java apps where files were encrypted previously. PDF.co provides a set of encryption and decryption parameters for compatibility with third-party services.

  3. Automatically decrypt input files and encrypt output files for compatibility with HIPAA or other compliance requirements.

Notes:

  • Encryption and decryption options are auto-redacted from API logs for security reasons.

User-Controlled Encryption

User-controlled encryption/decryption parameters must be set via the profiles parameter in JSON format (as a string if you use Zapier or a similar plugin, or as an escaped JSON string if you use direct calls to the API).

IMPORTANT: User-controlled encryption requires an additional 2 credits per page. User-controlled decryption also adds an additional 2 credits per page.

Sample Profile:

{ 
    'DataEncryptionAlgorithm': 'AES128', 
    'DataEncryptionKey': 'HelloThisKey1234', 
    'DataEncryptionIV': 'TreloThisKey1234' 
}
  • DataEncryptionAlgorithm (string) defines AES algorithm to use. Supported values: AES128, AES192, AES256.
  • DataEncryptionKey (string) defines AES encryption key to use. Must use 16 characters for AES128, 24 characters for AES192, 32 characters for AES256.
  • DataEncryptionIV (string) defines AES initialization vector (IV). An initialization vector is used to avoid repetition during the data encryption process, making it impossible for hackers who use dictionary attack to decrypt the exchanged encrypted message by discovering a pattern. You may think of it as an additional password. Must use 16 characters for AES128, 24 characters for AES192, 32 characters for AES256.

Example

Running PDF to JPG and encrypts output JPG files with AES-128 encryption:

POST [https://api.pdf.co/v1/pdf/convert/to/jpg](https://api.pdf.co/v1/pdf/convert/to/jpg)

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-to-image/sample.pdf",
    "profiles": "{ 'DataEncryptionAlgorithm': 'AES128', 'DataEncryptionKey': 'HelloThisKey1234', 'DataEncryptionIV': 'TreloThisKey1234' }"
}

User-Controlled Decryption

User-controlled encryption parameters must be set via profiles parameter in JSON format (as a string if you use Zapier or similar plugin or as escaped JSON string if you use direct calls to API).

Sample Profile:

{ 
    'DataEncryptionAlgorithm': 'AES128', 
    'DataEncryptionKey': 'HelloThisKey1234', 
    'DataEncryptionIV': 'TreloThisKey1234' 
}
  • DataDecryptionAlgorithm (string) defines AES algorithm to use. Supported values: AES128, AES192, AES256.
  • DataDecryptionKey (string) defines AES decryption key to use. Must use 16 characters for AES128, 24 characters for AES192, 32 characters for AES256.
  • DataDecryptionIV (string) defines AES initialization vector (IV). An initialization vector is used to avoid repetition during the data encryption process, making it impossible for hackers who use dictionary attack to decrypt the exchanged encrypted message by discovering a pattern. You may think of it as an additional password. Must use 16 characters for AES128, 24 characters for AES192, 32 characters for AES256.

How to tell API to decrypt input file which was encrypted by AES128 encryption with some 3rd party tool:

POST [https://api.pdf.co/v1/pdf/convert/to/jpg](https://api.pdf.co/v1/pdf/convert/to/jpg)

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/encryption/sample_encrypted_aes128.pdf",
    "profiles": "{ 'DataDecryptionAlgorithm': 'AES128', 'DataDecryptionKey': 'HelloThisKey1234', 'DataDecryptionIV': 'TreloThisKey1234' }"
}

Decrypting input file and encrypting output file

You can also set options to decrypt content of input file and also encrypt content of output file simultaneously.

Sample Profile

{ 
    'DataDecryptionAlgorithm': 'AES256', 
    'DataDecryptionKey': 'HelloThisKeyForDecrypting1234', 
    'DataDecryptionIV': 'UniqueVectorForDecryption1234', 
    'DataEncryptionAlgorithm': 'AES128', 
    'DataEncryptionKey': 'HelloThisKeyForEncryptingOutput1234', 
    'DataEncryptionIV': 'TreloThisUniqueKeyForEncryptingOutput1234' }"

Example:

POST [https://api.pdf.co/v1/pdf/merge](https://api.pdf.co/v1/pdf/merge)

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/encryption/sample_encrypted_aes128.pdf, [https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/encryption/sample_encrypted_aes128.pdf",](https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/encryption/sample_encrypted_aes128.pdf",)

    "profiles": "{ 'DataDecryptionAlgorithm': 'AES128', 'DataDecryptionKey': 'HelloThisKey1234', 'DataDecryptionIV': 'TreloThisKey1234', 'DataEncryptionAlgorithm': 'AES128', 'DataEncryptionKey': 'HelloThisKey1234', 'DataEncryptionIV': 'TreloThisKey1234' }"
}