User-Controlled Encryption#

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

PDF.co API supports strong AES encryption and decryption for input and output files.

Supported AES algorithms:

  • AES128 - 128-bit encryption

  • AES192 - 192-bit encryption

  • AES256 - 256-bit encryption

Note

The AES encryption mode which is used is CBC.

With user-controlled encryption you can implement the following scenarios:

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

  2. Auto-decrypt input files generated by 3rd party service or apps like SalesForce, Zapier, Make, or custom Javascript/PHP/NET/Java apps where files were encrypted previously. PDF.co provides a set of encryption and decryption params for compatibility with 3rd party services.

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

Note

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

User-Controlled Encryption#

User-controlled encryption 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 API).

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 a 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 encrypting 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 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 API).

Sample Profile

{
    'DataDecryptionAlgorithm': 'AES128',
    'DataDecryptionKey': 'HelloThisKey1234',
    'DataDecryptionIV': '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.

Example

How to tell the API to decrypt an input file, which was encrypted using AES128 encryption with a 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 the content of an input file and encrypt the content of the 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' }"
}