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

Purpose
Examples
Installation
Documentation
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

AckerApple / pdfbox-cli-wrap

readme

pdfbox-cli-wrap

Table of Contents

Purpose

Examples

PDF to One Image

PDF To Images

Add Images

Read Acroform

Fill Acroform

Advanced Fill Acroform

Embed Timestamp Signature

Encrypt Decrypt by Password

Encrypt Decrypt by Certificate

Installation

Install Java

Certificate Based Encrypt Decrypt Install Requirements

Add BouncyCastle into Java Security Extensions

Generate Certificates and KeyStore

MAY Need Java Cryptography

Test Installation

Documentation

getFormFields

getFormFieldsAsObject

embedFormFields

embedFormFieldsByObject

sign

signToBuffer

signByBuffer

encrypt

decrypt

pdfToImages

pdfToImage

addImages

Resources

Credits