API

Enum Definitions

Crypto.Mode

🥚🥚🥚

• Type: number

Name	Value	Description
RC4_40	0	40bit RC4 Encryption
RC4_128	1	128bit RC4 Encryption
AES_128	2	128bit AES Encryption
AES_256	3	256bit AES Encryption

Type Definitions

DSSInfo

🌮🌮🌮

Name	Type	Attributes	Description
certs	Array<forge.pki.Certificate>	optional	An array of necessary certificates.
ocsps	Array<Uint8Array>	optional	An array of OCSPs' response.
crls	Array<Uint8Array>	optional	The array of CRLs.

EncryptOption

🌮🌮🌮

Name	Type	Attributes	Description
mode	Crypto.Mode	required	The mode of encryption
permissions	Array<string>	optional	The set of permissions to be blocked 1️⃣
userpwd	string	optional	User password. Used when opening the pdf.
ownerpwd	string	optional	Owner password. If not specified, a random value is used.
pubkeys	Array<PubKeyInfo>	optional	An array of recipients containing public-key certificates ('c') and permissions ('p').

1️⃣ permissions can be the values listed blow.

• copy: (Only valid on public-key mode) Copy text and graphics from the document;
• print: Print the document;
• modify: Modify the contents of the document by operations other than those controlled by 'fill-forms', 'extract' and 'assemble';
• copy-extract: Copy or otherwise extract text and graphics from the document;
• annot-forms: Add or modify text annotations, fill in interactive form fields, and, if 'modify' is also set, create or modify interactive form fields (including signature fields);
• fill-forms: Fill in existing interactive form fields (including signature fields), even if 'annot-forms' is not specified;
• extract: Extract text and graphics (in support of accessibility to users with disabilities or for other purposes);
• assemble: Assemble the document (insert, rotate, or delete pages and create bookmarks or thumbnail images), even if 'modify' is not set;
• print-high: Print the document to a representation from which a faithful digital copy of the PDF content could be generated. When this is not set, printing is limited to a low-level representation of the appearance, possibly of degraded quality.

PubKeyInfo

🌮🌮🌮

Name	Type	Attributes	Description
c	Array<number> 🍴Uint8Array 🍴ArrayBuffer 🍴string 🍴forge.pki.Certificate	optional	A certificate.
p	Array<string>	optional	An array of permissions you want to block. Valid values see EncryptOption

SignAreaInfo

🌮🌮🌮

Name	Type	Attributes	Description
x	number	required	Distance from left
y	number	required	Distance from top
w	number	optional	Width
h	number	optional	Height

SignTextInfo

🌮🌮🌮

Name	Type	Attributes	Description
text	string	required	A text to draw.
size	number	required	Font size
fontData	Array<number> 🍴Uint8Array 🍴ArrayBuffer 🍴PDFLib.StandardFonts	optional	The font's data for drawing text. See PdfFonts.getEmbeddedFont for the default font.
subset	boolean	optional	Create font subset or not. Set to true to reduce the size of pdf file.
color	string	optional	A Hex string of font color. 1️⃣ Default: #000
opacity	number	optional	Valid value is from 0 to 1. Default: 1 🚫Not implemented yet
blendMode	string	optional	Valid value is one of the values in PDFLib.BlendMode 🚫Not implemented yet
lineHeight	number	optional	Default is the height of the font at the given size.
xOffset	number	optional	An offset from SignAreaInfo's x.
yOffset	number	optional	An offset from SignAreaInfo's y.
wMax	number	optional	The max width for drawing text.
align	number	optional	Alignment of text. 2️⃣ Default is 0.
noBreaks	string	optional	A regular expression string that indicates which characters should not be used to break a word. Default: [A-Za-z0-9]

1️⃣ Value of color can be 6-digit or 3-digit. And # can be omitted.

2️⃣ align can be the values listed blow.

• 0: left
• 1: center
• 2: right

SignImageInfo

🌮🌮🌮

Name	Type	Attributes	Description
imgData	Array<number> 🍴Uint8Array 🍴ArrayBuffer 🍴string	required	The image's data.
imgType	string	required	The image's type, only support jpg and png
opacity	number	optional	Valid value is from 0 to 1. Default: 1 🚫Not implemented yet
blendMode	string	optional	Valid value is one of the values in PDFLib.BlendMode 🚫Not implemented yet

SignDrawInfo

🌮🌮🌮

Name	Type	Attributes	Description
area	SignAreaInfo	required	The signature's drawing area, these numbers are dots on 72dpi.
pageidx	number 🍴string	optional	The index of a page where the signature will be placed. A string can be used to indicate placing the signature on multiple pages. 1️⃣ Default is 0.
imgData	Array<number> 🍴Uint8Array 🍴ArrayBuffer 🍴string	optional	The image's data. ❌Deprecated, use imgInfo instead.
imgType	string	optional	The image's type, only support jpg and png ❌Deprecated, use imgInfo instead.
imgInfo	SignImageInfo	optional	Image's informations for drawing.
textInfo	SignTextInfo	optional	Text's informations for drawing.

1️⃣ For example: A pdf contains 17 pages and specify "-3,5-7,9,12,15-" to pageidx means [0,1,2,3,5,6,7,9,12,15,16].

Important

For placing signature on multiple pages, all target pages must have the same dimensions and the same rotation angle.

SignOption

🌮🌮🌮

Name	Type	Attributes	Description
p12cert	Array<number> 🍴Uint8Array 🍴ArrayBuffer 🍴string	optional	Certificate's data. In the case of adding a document timestamp, it must be omitted.
pwd	string	optional	The passphrase of the certificate. In the case of adding a document timestamp, it must be omitted.
permission	number	optional	The modification permissions granted for this document. 1️⃣
reason	string	optional	The reason for signing
location	string	optional	Your location
contact	string	optional	Your contact information
signdate	TsaServiceInfo 🍴string 🍴Date	optional	In the case of adding a document timestamp, it can't be omitted and can't be a Date. 2️⃣
signame	string	optional	The name of the signature
drawinf	SignDrawInfo	optional	Visible signature's information
ltv	number	optional	The method of how to enable LTV 3️⃣
debug	boolean	optional	To output debug informations or not

1️⃣ permission is a setting of DocMDP. Valid values are:

• 1: No changes to the document are permitted; any change to the document invalidates the signature.
• 2: Permitted changes are filling in forms, instantiating page templates, and signing; other changes invalidate the signature.
• 3: Permitted changes are the same as for 2, as well as annotation creation, deletion, and modification; other changes invalidate the signature.

2️⃣ signdate

• When it is a Date, it means the date and time of signing.
• When it is a string, it can be an url of TSA or an index of the preset TSAs as below:
  • "1": http://ts.ssl.com
  • "2": http://timestamp.digicert.com
  • "3": http://timestamp.sectigo.com
  • "4": http://timestamp.entrust.net/TSS/RFC3161sha2TS
  • "5": http://timestamp.apple.com/ts01
  • "6": http://www.langedge.jp/tsa
  • "7": https://freetsa.org/tsr
• When it is a TsaServiceInfo, it means a full customized information of a TSA.
• When it is omitted, the system timestamp will be used.

3️⃣ ltv's valid values are:

• 1: auto; Try using OCSP only to enable the LTV first; If can't, try using CRL to enable the LTV.
• 2: crl only; Only try using CRL to enable the LTV.

TsaServiceInfo

🌮🌮🌮

Name	Type	Attributes	Description
url	string	required	The url of TSA.
len	number	optional	The length of signature's placeholder.
headers	Object<string, *>	optional	The customized headers for sending to tsa server.

Function Definitions

u8arrToRaw

🫕🫕🫕
u8arrToRaw(uarr) ➡️ string
Converts an Uint8Array to a raw string.

Name	Type	Attributes	Description
uarr	Uint8Array	required	The target Uint8Array

rawToU8arr

🫕🫕🫕
rawToU8arr(raw) ➡️ Uint8Array
Converts a raw string to an Uint8Array.

Name	Type	Attributes	Description
raw	string	required	The target string

Classes

CertsChain

🥐🥐🥐

Constructor

new CertsChain(certs_opt)

Name	Type	Attributes	Description
certs	Array<forge.pki.Certificate> 🍴Array<forge.asn1> 🍴Array<string>	optional	An array of certificates.

Methods

buildChain

buildChain(cert) ➡️ Promise<boolean>
Build the certificates chain from the specified certificate, and returns true if this operation is successful.

Name	Type	Attributes	Description
cert	forge.pki.Certificate	required	A certificate to start build by looking for it's issuer.

getAllCerts

getAllCerts() ➡️ Array<forge.pki.Certificate>
Returns an array of all certificates.

getSignCert

getSignCert() ➡️ forge.pki.Certificate
Returns the certificate for signing.

isSelfSignedCert

isSelfSignedCert() ➡️ boolean
Returns true if the certificate for signing is a self-signed certificate.

prepareDSSInf

prepareDSSInf(crlOnly_opt) ➡️ Promise<DSSInfo>
Returns the informations of DSS.

Name	Type	Attributes	Description
crlOnly	boolean	optional	Query CRL only or try query OCSP first.

PdfCryptor

🥐🥐🥐

Constructor

new PdfCryptor(encopt)

Name	Type	Attributes	Description
encopt	EncryptOption	required	Infomations of encryption.

Methods

encryptObject

encryptObject(num, val)
Encrypts the content of the specified pdf object.

Name	Type	Attributes	Description
num	number	required	The object number.
val	PDFLib.PDFObject	required	The target object.

encryptPdf

encryptPdf(pdf, ref_opt) ➡️ Promise<PDFLib.PDFDocument>
Encrypts the contents in the pdf and returns the pdf document.

Name	Type	Attributes	Description
pdf	PDFLib.PDFDocument 🍴Array<number> 🍴Uint8Array 🍴ArrayBuffer 🍴string	required	The target pdf.
ref	PDFLib.PDFRef	optional	The unique reference will be assigned to the encryption information.

PdfSigner

🥐🥐🥐

Constructor

new PdfSigner(signopt)

Name	Type	Attributes	Description
signopt	SignOption	required	Infomations of signing.

Methods

sign

sign(pdf, cypopt_opt) ➡️ Promise<Uint8Array>
Sign the pdf and returns the binary data.

Name	Type	Attributes	Description
pdf	PDFLib.PDFDocument 🍴Array<number> 🍴Uint8Array 🍴ArrayBuffer 🍴string	required	The target pdf.
cypopt	EncryptOption	optional	The informations of encryption.

TsaFetcher

🥐🥐🥐

Constructor

new TsaFetcher(inf)

Name	Type	Attributes	Description
inf	TsaServiceInfo	required	Infomations of TSA.

Properties

Name	Type	Description
url	string	The url of TSA.
len	number	The length of signature which is generated by the TSA.

Methods

getCertsChain

getCertsChain() ➡️ CertsChain
Get the certificates' chain from the response of TSA.

getToken

getToken(forP7_opt) ➡️ forge.asn1
Get the token data in response from TSA.

Name	Type	Attributes	Description
forP7	boolean	optional	To create an asn1 for appending to a pkcs#7 signature or not.

queryTsa

queryTsa(data) ➡️ Promise<string>
Query TSA to sign the data and returns error message if error occured.

Name	Type	Attributes	Description
data	string	required	The data needs to be signed.

PdfFonts

🥐🥐🥐

Static Methods

from

from(pdfdoc) ➡️ Promise<PdfFonts>
Load embedded fonts from pdf document.

Name	Type	Attributes	Description
pdfdoc	PDFLib.PDFDocument	required	The target pdf document.

Methods

getEmbeddedFont

getEmbeddedFont(fontData_opt, subset_opt) ➡️ Promise<PDFLib.PDFFont>
Get the embedded font or create one if not exists.

Name	Type	Attributes	Description
fontData	Array<number> 🍴Uint8Array 🍴ArrayBuffer 🍴PDFLib.StandardFonts	optional	Data of font. If omitted, the default font is PDFLib.StandardFonts.Helvetica if there is no existing embedded font. Or the default font is the first existing embedded font.
subset	boolean	optional	Create font subset or not.

Note

• CRL📢 Certificate Revocation List
• DSS📢 Document Security Store
• DocMDP📢 Document Modification Detection and Prevention
• LTV📢 Long-Term Validation
• OCSP📢 Online Certificate Status Protocol
• TSA📢 Time Stamp Authority