pdfbox-cli-wrap

A wrapper for making PDFBox CLI commands

This package allows for the following PDF functionality:

• pages to images
• insert images into pages
• read and fill Acroforms
• certificate and passward security
• timesstamp signing

Table of Contents

• Purpose
• Examples
  • PDF to One Image
  • PDF to Images
  • Add Images
  • Read Acroform
  • Fill Acroform
  • Embed Timestamp Signature
  • Advanced Fill Acroform
  • Encrypt Decrypt by Password
  • Encrypt Decrypt by Certificate
• Installation
  • Install Java
  • Certificate Based Encrypt Decrypt Install Requirements
    • Generate Certificates and KeyStore
    • MAY Need Java Cryptography
  • Test Installation
• Documentation
  • getFormFields
  • getFormFieldsAsObject
  • embedFormFields
  • embedFormFieldsByObject
  • sign
  • encrypt
  • decrypt
  • pdfToImages
  • pdfToImage
  • addImages
• Resources
• Credits

Purpose

Connect to Java and the PDFBox library to allow Node code to perform perfected PDF management techinques.

If you've looked into documentation for secure storage of PDFs, you know you need certificate based security for your PDFs. Next to no public Node libraries have certificate based PDF encryption software.

Examples

PDF to One Image

Create one image for the first page of a PDF document. Use pdfToImages to makes images of other pages

const pdfboxCliWrap = require('pdfbox-cli-wrap')
const readablePdf = path.join(__dirname,'readable.pdf')

pdfboxCliWrap.pdfToImage(readablePdf)
.then(imgPath=>{
  console.log('jpg image created at: '+imgPath)
})
.catch(e=>console.error(e))

PDF To Images

const pdfboxCliWrap = require('pdfbox-cli-wrap')
const readablePdf = path.join(__dirname,'readable.pdf')

pdfboxCliWrap.pdfToImages(readablePdf)
.then(pathArray=>{
  console.log('pdf rendered to files here:', pathArray)
})
.catch(e=>console.error(e))

Add Images

Insert one image at one specific location, or append multiple images, and more...

Example Insert Image File into Page

const pdfboxCliWrap = require('pdfbox-cli-wrap')
const readablePdf = path.join(__dirname,'readable.pdf')
const options = {x:200, y:200, page:0, width:100, height:100}

pdfboxCliWrap.addImages(readablePdf, imgPath0, options)
.then(()=>{
  console.log("Image Inserted")
})
.catch(e=>console.error(e))

Example Insert Image Base64 into Page

const pdfboxCliWrap = require('pdfbox-cli-wrap')
const readablePdf = path.join(__dirname,'readable.pdf')
const options = {x:200, y:200, page:0, width:100, height:100}

pdfboxCliWrap.addImages(readablePdf, 'data:image/png;base64,...', options)
.then(()=>{
  console.log("Base64 Image Inserted")
})
.catch(e=>console.error(e))

Example Append Images as Pages

const pdfboxCliWrap = require('pdfbox-cli-wrap')
const readablePdf = path.join(__dirname,'readable.pdf')
const options = {
  y:-1,//very top of page
  page:-1,//a new page will be created for image insert
  width:'100%'//width of page to image width will be calclated into a constrained size
}

pdfboxCliWrap.addImages(readablePdf,[imgPath0, imgPath1], options)
.then(()=>{
  console.log("Images Added as Pages to Original PDF File")
})
.catch(e=>console.error(e))

Read Acroform

Read PDf form fields as an array of objects

const pdfboxCliWrap = require('pdfbox-cli-wrap')
const readablePdf = path.join(__dirname,'readable.pdf')

pdfboxCliWrap.getFormFields(readablePdf)
.then(fields=>{
  console.log(fields)
})
.catch(e=>console.error(e))

The result of getFormFields will look like the following JSON

[{
  "fullyQualifiedName": "form1[0].#subform[6].FamilyName[0]",
  "isReadOnly": false,
  "partialName": "FamilyName[0]",
  "type": "org.apache.pdfbox.pdmodel.interactive.form.PDTextField",
  "isRequired": false,
  "page": 6,
  "cords": {
    "x": "39.484",
    "y": "597.929",
    "width": "174.00198",
    "height": "15.119995"
  },
  "value": "Apple"
}]

Fill Acroform

Fill PDf form fields from an array of objects

const pdfboxCliWrap = require('pdfbox-cli-wrap')
const readablePdf = path.join(__dirname,'readable.pdf')
const outPdfPath = path.join(__dirname,'filled.pdf')

//array of field values
const data = [{
  "fullyQualifiedName": "Your_FirstName",
  "value": "Acker"
}]

pdfboxCliWrap.embedFormFields(readablePdf, data, outPdfPath, {flatten:true})
.then(()=>{
  console.log("success")
})
.catch(e=>console.error(e))

Advanced Fill Acroform

The JSON file below will fill two fields:

• First field is a plain text field
• Second field will be replaced by a base64 image of a hand-signature
  • remove was added to delete field from pdf
  • base64Overlay was added to insert hand-signature image where field was
    • uri specifies jpg or png image data
    • forceWidthHeight forces image to fit with-in field coordinates

const pdfboxCliWrap = require('pdfbox-cli-wrap')
const readablePdf = path.join(__dirname,'readable.pdf')
const outPdfPath = path.join(__dirname,'filled.pdf')

//array of field values
const data = [{
  "fullyQualifiedName": "form1[0].#subform[6].FamilyName[0]",
  "isReadOnly": false,
  "partialName": "FamilyName[0]",
  "type": "org.apache.pdfbox.pdmodel.interactive.form.PDTextField",
  "isRequired": false,
  "page": 6,
  "cords": {
    "x": "39.484",
    "y": "597.929",
    "width": "174.00198",
    "height": "15.119995"
  },
  "value": "Apple"
},{
  "fullyQualifiedName": "form1[0].#subform[6].EmployeeSignature[0]",
  "isReadOnly": true,
  "partialName": "EmployeeSignature[0]",
  "type": "org.apache.pdfbox.pdmodel.interactive.form.PDTextField",
  "isRequired": false,
  "page": 6,
  "cords": {
    "x": "126.964",
    "y": "227.523",
    "width": "283.394",
    "height": "15.12001"
  },
  "remove": true,
  "base64Overlay": {
    "uri": "data:image/png;base64,iVBOR......................=",
    "forceWidthHeight": true
  }
}]

pdfboxCliWrap.embedFormFields(readablePdf, data, outPdfPath)
.then(()=>{
  console.log("success")
})
.catch(e=>console.error(e))

Embed Timestamp Signature

const pdfboxCliWrap = require('pdfbox-cli-wrap')

//create paths to pdf files
const path = require('path')
const inPath = path.join(__dirname,'unencrypted.pdf')
const key = path.join(__dirname,'pdfbox-test.p12')

pdfboxCliWrap.signToBuffer(inPath)
.then(buffer=>console.log('signed!'))
.catch(e=>console.error('failed to sign'))

Encrypt Decrypt by Password

A great place to start before moving on to certificate based cryptography

const pdfboxCliWrap = require('pdfbox-cli-wrap')

//create paths to pdf files
const path = require('path')
const inPath = path.join(__dirname,'unencrypted.pdf')
const toPath = path.join(__dirname,'encrypted.pdf')
const decryptTo = path.join(__dirname,'unencrypted2.pdf')

//encrypt
let promise = pdfboxCliWrap.encrypt(inPath, toPath, {'password':'123abc'})
.then( ()=>console.log('encryption success!') )

//decrypt
promise.then( ()=>pdfboxCliWrap.decrypt(toPath, , {'password':'123abc'}) )
.then( ()=>console.log('decryption success!') )
.catch( e=>console.log(e) )

Encrypt Decrypt by Certificate

This is where the money is

const pdfboxCliWrap = require('pdfbox-cli-wrap')

//create paths to pdf files
const path = require('path')
const readablePdf = path.join(__dirname,'unencrypted.pdf')
const encryptTo = path.join(__dirname,'encrypted.pdf')
const decryptTo = path.join(__dirname,'unencrypted2.pdf')

//create paths to secret files
const cert = path.join(__dirname,'pdfbox-test.crt')
const key = path.join(__dirname,'pdfbox-test.p12')

//encrypt from readable pdf to unreadable pdf
let promise = pdfboxCliWrap.encrypt(readablePdf, encryptTo, {'certFile':cert})
.then( ()=>console.log('encryption success!') )

//how to decrypt
const decOptions = {
  keyStore:key,//Special file that is password protected. The contents are both the certificate and privatekey.
  password:'password'//unlocks the keyStore file
}

promise.then( ()=>pdfboxCliWrap.decrypt(encryptTo, decryptTo, decOptions) )
.then( ()=>console.log('decryption success!') )
.catch( e=>console.log(e) )

Learn how to generate .crt and .p12 files here

Installation

This package is a wrapper for making CLI commands to Java. A few things are going to be needed.

An updated version of NodeJs that supports ecma6 syntax is required. I believe version 4.0.0 or greater will do. I am in Node 7.0.0, as of this writing, my how time and version numbers can fly.

Install Java

Download and Install Java and be sure the following command works without error in a command terminal:

java -version

Certificate Based Encrypt Decrypt Install Requirements

Are you going to be encrypting and possibly decrypting PDF documents?

This is a 1 step process (maybe 2):

• Generate Certificates and KeyStore
• MAY Need Java Cryptography

Add BouncyCastle into Java Security Extensions

BouncyCastle is the big daddy of cryptography libraries, for Java and PDFBox

This step is no longer necessary, IN MOST CASES, as BouncyCastle is now bundled with pdfbox-cli-wrap. If you need the BouncyCastle installation documentation, it can be found here

Bouncy Castle is not a registered provider, when errors like the following occur: java.io.IOException: Could not find a suitable javax.crypto provider

Generate Certificates and KeyStore

Get ready to run terminal commands against Java's keytool. Fun fun

In a terminal command prompt window, run the following in a folder where certificate files can live

Step #1 Create keyStore

keytool -genkey -keyalg RSA -alias pdfbox-test-alias -keystore pdfbox-test-keystore.jks -storepass pdfbox-test-password -validity 360 -keysize 2048

creates file pdfbox-test-keystore.jks

Step #2 Create a selfsigned certificate

keytool -export -alias pdfbox-test-alias -file pdfbox-test.crt -keystore pdfbox-test-keystore.jks

creates file pdfbox-test.crt

Step #3 Marry the certificate and keyStore together as a .p12 file

keytool -importkeystore -srckeystore pdfbox-test-keystore.jks -destkeystore pdfbox-test.p12 -srcstoretype JKS -deststoretype PKCS12 -deststorepass pdfbox-test-password -srcalias pdfbox-test-alias -destalias pdfbox-test-p12

creates file pdfbox-test.p12

You should now have the following files in targeted folder:

• pdfbox-test.crt
  • used to encrypt
• pdfbox-test-keystore.jks
  • used to create p12 file below
• pdfbox-test.p12
  • used to decrypt

MAY Need Java Cryptography

Depending on your level of advanced encryption needs, you (may) need to install Java Cryptography

Test Installation

In the root folder of pdfbox-cli-wrap, in a terminal command window, you can test your installation

Step 1, Install the Test Dependencies (Mocha)

npm install

The pdfbox-cli-wrap folder should now have a folder named "node_modules" with a folder named "mocha"

Step 2, Run the Test

npm test

Documentation

getFormFields

• Returns array of objects
• pdfPath - The PDF file to read form fields from

examples

getFormFieldsAsObject

Read Acroform fields from a PDF as object-of-objects where each key is the fullyQualifiedName of input field

• pdfPath - The PDF file to read form fields from

examples

embedFormFields

Takes array-of-objects and sets values of PDF Acroform fields

• pdfPath - The PDF file to read form fields from
• fieldArray - Array of PDF field definitions
• outPdfPath - Where to write PDF that has been filled
• options
  • flatten - false. When true, Acroform will no longer be editable

examples

embedFormFieldsByObject

Fill Acroform fields from a PDF with an array-of-objects to set the values of input fields

• pdfPath - The PDF file to read form fields from
• fieldArray - Array of PDF field definitions
• outPdfPath - Where to write PDF that has been filled

examples

sign

Will embed timestamp signature with optional TSA option

• pkcs12_keystore - keystore the pkcs12 keystore containing the signing certificate (typically a .p12 file)
• password - the password for recovering the key
• pdf_to_sign - the PDF file to sign
• options
  • tsa - url - sign timestamp using the given TSA server
  • out - path - pdf output path
  • e - sign using external signature creation scenario

examples

signToBuffer

See sign

pdfboxCliWrap.signToBuffer(path,outPath,options).then(buffer).catch()

signByBuffer

See sign

pdfboxCliWrap.signByBuffer(buffer,options).then(buffer).catch()

encrypt

Will encrypt a PDF document

• pdfPath - The PDF file to encrypt
• outputPathOrOptions - The file to save the decrypted document to. If left blank then it will be the same as the input file || options
• options - {}
  • password: The user password to the PDF, ignored if -certFile is specified. (alias of argument U)
  • O: The owner password to the PDF, ignored if -certFile is specified.
  • U: The user password to the PDF, ignored if -certFile is specified. (alias of argument password)
  • certFile: Path to X.509 cert file.
  • canAssemble: true Set the assemble permission.
  • canExtractContent: true Set the extraction permission.
  • canExtractForAccessibility: true Set the extraction permission.
  • canFillInForm: true Set the fill in form permission.
  • canModify: true Set the modify permission.
  • canModifyAnnotations: true Set the modify annots permission.
  • canPrint: true Set the print permission.
  • canPrintDegraded: true Set the print degraded permission.
  • keyLength: 40, 128 or 256 The number of bits for the encryption key. For 128 and above bits Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files must be installed.

examples

decrypt

Will decrypt a PDF document

• pdfPath - The PDF file to decrypt
• outputPathOrOptions - The file to save the decrypted document to. If left blank then it will be the same as the input file || options
• options - {}
  • password: Password to the PDF or certificate in keystore.
  • keyStore: Path to keystore that holds certificate to decrypt the document (typically a .p12 file). This is only required if the document is encrypted with a certificate, otherwise only the password is required.
  • alias: The alias to the certificate in the keystore.

examples

pdfToImages

Will create an image for any or every page in a PDF document.

• pdfPathOrBuffer - A buffer-of-pdf or pdf-file-path to work with
• options
  • password - The password to the PDF document.
  • imageType=jpg - The image type to write to. Currently only jpg or png.
  • outputPrefix - Name of PDF document The prefix to the image file.
  • startPage=1 - The first page to convert, one based.
  • endPage - The last page to convert, one based.
  • nonSeq - false Use the new non sequential parser.
  • mode - "files" or "base64-array" or "buffer-array"

examples

pdfToImage

Will create one image for the first page of a PDF document. Use pdfToImages to makes images of other pages

examples

addImages

Insert a single image into a PDF or append multi images as individual pages

• pdfPathOrBuffer - A buffer-of-pdf or pdf-file-path to work with
• imagesPath - The file image(s) to append to document. Allows multiple image arguments, which is great for appending photos as pages. Allows base64 strings.
• options
  • out - The file to save the decrypted document to. If left blank then it will be the same as the input file || options
  • page - The page number where to drop image. Use -1 to append on a new page
  • x - The x cord where to drop image
  • y - The y cord where to drop image. Use -1 for top
  • width - default is image width. Accepts percent width
  • height - default is image height

examples

Resources

• This whole package is based on PDFBox CLI documentation
• I had to report and have PDFBox fix a CLI issue to get this package to even work. A version of PDFBox with this fix has been included
  • Link to fixed issued
• PDF form read and fill is performed by the Java library ack-pdfbox

Credits

• Production Support : caringpeopleinc.com