PDF-Signatures

Sign PDFs with PKCS7 signatures like a boss!

Dependencies

• UNIX-like OS
• Java runtime >= 1.8
• Nodejs >= 8.10

License

This library is distributed under the AGPL license. However, some dependencies may be licenced under different licence types.

See https://www.gnu.org/licenses/agpl-3.0.en.html.

Testing

• npm run lint
• npm run test
• ./gradlew checkstyleMain
• ./gradlew test

Building (Before publishing an npm package)

• gradle build
• gradle copyJarToLibs
• gradle clean (optional)

Usage (Nodejs)

Add signature placeholder

const { addSignaturePlaceholderToPdf, CertificationLevels } = require('pdf-signatures');

const outputPath = await addSignaturePlaceholderToPdf({
  file: '/path/to/file.pdf',                   // Path to file, Required
  out: '/path/to/out.pdf',                     // Output file path, Required
  estimatedsize: 30000,                        // Estimated signature size, Optional, Default is 30000
  certlevel: CertificationLevels.NotCertified, // Certification level, Optional, Default is CertificationLevels.NotCertified
  password: '123456',                          // Document password, Optional
  reason: 'I want to sign the document',       // Signing reason, Optional, Default is undefined
  location: 'Moon',                            // Signing location, Optional, Default is undefined
  contact: 'John Doe',                         // Signing contact, Optional, Default is undefined
  date: '2019-09-26T20:54:41.426Z',            // Signing date in ISO-8601 format, Optional, Default is undefined
});

Calculate document digest

const { preparePdf, HashAlgorithms } = require('pdf-signatures');

const base64EncodedDigest = await pdfDigest({
  file: '/path/to/file.pdf',                   // Path to file, Required
  password: '123456',                          // Document password, Optional
  algorithm: HashAlgorithms.Sha512,            // Hash algorithm, Optional, Default is HashAlgorithms.Sha512
});

Sign PDF with external signature

const outputPath = await signPdf({
  file: '/path/to/file.pdf',                   // Path to file, Required
  out: '/path/to/out.pdf',                     // Output file path, Required
  signature: 'base64',                         // Base64-encoded external signature
  password: '123456',                          // Document password, Optional
});

Embed LTV (Long Time Validation) information

const outputPath = await addLtvToPdf({
  file: '/path/to/file.pdf', // Path to file, Required
  out: '/path/to/out.pdf',   // Output file path, Required
  crl: [                     // Certificate revocation list (bbase64-encoded), Required
    'base64',
    'base64',
    '...'
  ],
  ocsp: [                    // Online certificate status protocol responses list, (base64-encoded), Required
    'base64',
    'base64',
    '...'
  ],
});

Usage (Jar)

General invokation format:

$ java -jar <path-to-jar> <arguments>

Where <arguments> is one of the following:

Advanon PKCS7 document signer

Usage:
  help                                        Show this help
  version                                     Display current version number
  --version                                   Display current version number
  -v                                          Display current version number
  placeholder                                 Add a signature placeholder
    --file <path>                             Path to the document
    --out <path>                              Path where to save a new document
    [--estimatedsize <int>]                   Estimated signature size, default is 30000 bytes
    [--certlevel <int>]                       Desired certification level, default is 0
      * 0                                     Not certified
      * 1                                     Certified, no changes allowed
      * 2                                     Certified, form filling
      * 3                                     Certified, form filling and annotations
    [--password <string>]                     Document password
    [--reason <reason>]                       Signing reason
    [--location <location>]                   Signing location
    [--contact <contact>]                     Signing contact
    [--date <contact>]                        Date of signing in ISO 8601 format
  digest                                      Calculate document digest excluding signatures
    --file <path>                             Path to the document
    [--password <string>]                     Document password
    [--algorithm <SHA-256|SHA-384|SHA-512>]   Encryption algorithm, default is SHA-512
  sign                                        Sign the document with external signature
    --file <path>                             Path to the document
    --out <path>                              Path where to save a new document
    --signature <base64 string>               Base64-encoded signature
    [--password <string>]                     Document password
  ltv                                         Add LTV information to the document
    --file <path>                             Path to the document
    --out <path>                              Path where to save a new document
    --crl <base64 string>...                  Base64-encoded CRL (each single CRL should be prepended with -crl)
    --ocsp <base64 string>...                 Base64-encoded OCSP (each single OCSP should be prepended with -ocsp)
    [--password <string>]                     Document password

Example
  placeholder --file file.pdf --out placeholdered.pdf                                                                   Add signature placeholder
  digest --file placeholdered.pdf --algorithm sha512                                                                    Calculate document digest
  sign --file placeholdered.pdf --out signed.pdf --signature abb4rjfh=                                                  Sign the document with external signature
  ltv --file signed.pdf --out signedltv.pdf --crl abb4rjfh= --crl fgsllldj5kg= --oscp abb4rjfh= --ocsp fgsllldj5kg=     Insert LTV information into signed document

Notes

Pdf objects, their encoding, position and length

You may notice in the source code a some "magic" conversions, like (N + 2) / 2, or (X - 2 / 2), this is because PDF objects are HEX-encoded, which means that every two bytes of the PDF object you read is actually one HEX-digit.

For example, if you are writing byte 255 into PDF, you should bare in mind that this will (or at least that should) be actually written as FF which is now TWO! bytes.

Now you may wonder what does +2 or -2 mean. The answer is pretty straightforward - content of PDF objects begins with < and ends with >, and sometimes you simply don't need these markers taken into account.

Signature byte range and document hash

Every signature has a byte range information, which contains... a byte range of the signature and of the document content surrounding it.

For instance, consider the next byte range: [ 0, 200, 400, 250 ]:

|----------------------------|  0
| /Content <                 |
|----------------------------|  200
| signature HEX              |
|----------------------------|  400
| >                          |
|----------------------------|  650 (400 + 250)

When calculating hash of a signed document, signature bytes are exluded from the calculation. From the example, these are 200 bytes 200 -> 400.