@syncfusion/ej2-pdf
Version:
Feature-rich JavaScript PDF library with built-in support for loading and manipulating PDF document.
663 lines (662 loc) • 27.8 kB
TypeScript
import { PdfCertificationFlags, CryptographicStandard, DigestAlgorithm } from '../../../enumerator';
import { PdfSignatureField } from '../../../form/field';
import { _PdfCrossReference } from '../../../pdf-cross-reference';
import { PdfDocument } from '../../../pdf-document';
import { PdfPage } from '../../../pdf-page';
import { _PdfDictionary, _PdfReference } from '../../../pdf-primitives';
import { _PdfCertificate } from './../pdf-certificate';
import { _PdfX509Certificate } from '../x509/x509-certificate';
import { _PdfSignatureDictionary } from './signature-dictionary';
import { PdfCertificateInformation, PdfSignatureOptions } from './signature-properties';
import { ExternalSignatureCallback, Rectangle, TimestampCallback } from './../../../pdf-type';
/**
* 'PdfSignature' class represents a digital signature used for signing a PDF document.
*
* ```typescript
* // Load the document
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', {x: 10, y: 10, width: 100, height: 50});
* // Create a new signature using PFX data and private key
* const sign: PdfSignature = PdfSignature.create({ cryptographicStandard: CryptographicStandard.cms, digestAlgorithm: DigestAlgorithm.sha256 }, certData, password);
* // Sets the signature to the field
* field.setSignature(sign);
* // Add the field into PDF form
* form.add(field);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*/
export declare class PdfSignature {
/**
* The underlying signature dictionary representing the PDF signature object.
*
* @private
*/
_signatureDictionary: _PdfSignatureDictionary;
/**
* The signature field associated with this signature.
*
* @private
*/
_signatureField: PdfSignatureField;
/**
* Reference used for catalog permission updates when certifying.
*
* @private
*/
_reference: _PdfReference;
/**
* The certificate wrapper parsed from provided PFX or signature dictionary.
*
* @private
*/
_certificate: _PdfCertificate;
/**
* Reason text supplied for the signature.
*
* @private
*/
_reason: string;
/**
* The page the signature applies to.
*
* @private
*/
_page: PdfPage;
/**
* Location information supplied for the signature.
*
* @private
*/
_locationInfo: string;
/**
* Contact information supplied for the signature.
*
* @private
*/
_contactInfo: string;
/**
* The digest algorithm used for the signature.
*
* @private
*/
_digestAlgorithm: DigestAlgorithm;
/**
* The cryptographic standard in use (CMS/CAdES).
*
* @private
*/
_cryptographicStandard: CryptographicStandard;
/**
* Whether the signature should be visible in the document.
*
* @private
*/
_visible: boolean;
/**
* Document permissions applied when certifying the document.
*
* @private
*/
_documentPermissions: PdfCertificationFlags;
/**
* The date when the document was signed.
*
* @private
*/
_signedDate: Date;
/**
* The name used for the signature (signed name).
*
* @private
*/
_signedName: string;
/**
* External certificate chain provided for external signing scenarios.
*
* @private
*/
_externalChain: Array<_PdfX509Certificate>;
/**
* Whether the field is locked (signature lock dictionary present).
*
* @private
*/
_isLocked: boolean;
/**
* Whether the signature has been applied.
*
* @private
*/
_signed: boolean;
/**
* Whether certificates should be appended to existing certificate collection.
*
* @private
*/
_appendCertificates: boolean;
/**
* Cross reference table for the PDF document being signed.
*
* @private
*/
_crossReference: _PdfCrossReference;
/**
* Bounds for the visible signature appearance.
*
* @private
*/
_bounds: Rectangle;
/**
* Whether this signature certifies the document.
*
* @private
*/
_certify: boolean;
/**
* Parsed certificate information for display and inspection.
*
* @private
*/
_certificateInfo: PdfCertificateInformation;
/**
* Callback used for external signing operations.
*
* @private
*/
_externalSignatureCallback: ExternalSignatureCallback;
/**
* Indicates whether a timestamp token is present on the signature.
*
* @private
*/
_hasTimeStamp: boolean;
/**
* Raw timestamp token bytes when present.
*
* @private
*/
_timeStampTokenBytes: Uint8Array;
/**
* When true, the signature represents timestamp-only content.
*
* @private
*/
_isTimestampOnly: boolean;
/**
* Callback used to request a timestamp from a TSA.
*
* @private
*/
_timestampCallback: TimestampCallback;
/**
* Initializes a new instance of the `PdfSignature` class.
*
* @private
*/
constructor();
/**
* Creates a new PDF signature using a callback function for external signing.
*
* @example
* ```typescript
* // Load the document
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', { x: 10, y: 10, width: 100, height: 50 });
* // Define a callback function used for external signing
* const externalSignatureCallback = (data: Uint8Array,
* options: {
* algorithm: DigestAlgorithm,
* cryptographicStandard: CryptographicStandard,
* }): {signedData: Uint8Array, timestampData?: Uint8Array} => {
* // Implement external signing logic here
* return new Uint8Array(); // Placeholder return
* };
* // Create a new signature using external signing
* const signature: PdfSignature = PdfSignature.create(externalSignatureCallback, {
* cryptographicStandard: CryptographicStandard.cms,
* algorithm: DigestAlgorithm.sha256
* });
* // Set the signature to the field
* field.setSignature(signature);
* // Add the field into PDF form
* form.add(field);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {Function} callBack - A callback function that computes the signed document hash for external signature.
* @param {PdfSignatureOptions} options - Configuration options for the signature.
* @returns {PdfSignature} - The created PDF signature instance.
*/
static create(callBack: ExternalSignatureCallback, options: PdfSignatureOptions): PdfSignature;
/**
* Creates a new PDF signature using a callback function for external signing.
*
* @example
* ```typescript
* // Load the document
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', { x: 10, y: 10, width: 100, height: 50 });
* // Define a callback function used for external signing
* const externalSignatureCallback = (data: Uint8Array,
* options: {
* algorithm: DigestAlgorithm,
* cryptographicStandard: CryptographicStandard
* }): {signedData: Uint8Array, timestampData?: Uint8Array} => {
* // Implement external signing logic here
* return new Uint8Array(); // Placeholder return
* };
* // Create a new signature using external signing with public certificate collection
* const signature: PdfSignature = PdfSignature.create(externalSignatureCallback,
* publicCertificates, { cryptographicStandard: CryptographicStandard.cms,
* algorithm: DigestAlgorithm.sha256
* });
* // Set the signature to the field
* field.setSignature(signature);
* // Add the field into PDF form
* form.add(field);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {Function} callBack - A callback function that computes the signed document hash for external signature.
* @param {Uint8Array[]} publicCertificates - An array of public certificates.
* @param {PdfSignatureOptions} options - Configuration options for the signature.
* @returns {PdfSignature} - The created PDF signature instance.
*/
static create(callBack: ExternalSignatureCallback, publicCertificates: Uint8Array[], options: PdfSignatureOptions): PdfSignature;
/**
* Creates a new PDF signature using PFX certificate data and a password.
*
* @example
* ```typescript
* // Load the document
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', {x: 10, y: 10, width: 100, height: 50});
* // Create a new signature using PFX data and private key
* const sign: PdfSignature = PdfSignature.create(certData, password, { cryptographicStandard: CryptographicStandard.cms, digestAlgorithm: DigestAlgorithm.sha256 });
* // Sets the signature to the field
* field.setSignature(sign);
* // Add the field into PDF form
* form.add(field);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {Uint8Array | string} pfxData - The PFX certificate data.
* @param {string} password - The password for the certificate.
* @param {PdfSignatureOptions} options - Configuration options for the signature.
* @returns {PdfSignature} - The created PDF signature instance.
*/
static create(pfxData: Uint8Array | string, password: string, options: PdfSignatureOptions): PdfSignature;
/**
* Creates a new PDF signature with timestamp using a PFX certificate and timestamp callback.
*
* @example
* ```typescript
* // Load the document
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', {x: 10, y: 10, width: 100, height: 50});
* // Create a timestamp callback
* async function timestampCallback(request: Uint8Array): Promise<{ response: Uint8Array }> {
* // Implement timestamp response logic here
* return new Uint8Array(); // Placeholder return
* }
* // Create a new signature using PFX data, private key and call back function for timestamp
* const sign: PdfSignature = PdfSignature.create(certData, password, { cryptographicStandard: CryptographicStandard.cms, digestAlgorithm: DigestAlgorithm.sha256 }, timestampCallback);
* // Sets the signature to the field
* field.setSignature(sign);
* // Add the field into PDF form
* form.add(field);
* // Save the document
* await document.saveAsync('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {Uint8Array | string} pfxData - The PFX certificate data.
* @param {string} password - The password for the certificate.
* @param {PdfSignatureOptions} options - Configuration options for the signature.
* @param {Function} timestamp Callback function that accesses TSA server and returns timestamp response for the request bytes.
* @returns {PdfSignature} - The created PDF signature instance.
*/
static create(pfxData: Uint8Array | string, password: string, options: PdfSignatureOptions, timestamp: TimestampCallback): PdfSignature;
/**
* Creates a new PDF timestamp signature using the provided signature and timestamp callback.
*
* @remarks
* This creates a timestamp signature (also known as a document timestamp) for the PDF document.
* Callback function is used to obtain the timestamp from a trusted timestamp authority (TSA) server.
*
* @example
* ```typescript
* // Load the document
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', {x: 10, y: 10, width: 100, height: 50});
* // Create a timestamp callback
* async function timestampCallback(request: Uint8Array): Promise<{ response: Uint8Array }> {
* // Implement timestamp response logic here
* return new Uint8Array(); // Placeholder return
* }
* // Create a new signature using signature options and call back function for timestamp
* const sign: PdfSignature = PdfSignature.create({ cryptographicStandard: CryptographicStandard.cms, digestAlgorithm: DigestAlgorithm.sha256 }, timestampCallback);
* // Sets the signature to the field
* field.setSignature(sign);
* // Add the field into PDF form
* form.add(field);
* // Save the document
* await document.saveAsync('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {PdfSignatureOptions} options - Configuration options for the signature.
* @param {Function} timestampCallback Callback function that accesses TSA server and returns timestamp response for the request bytes.
* @returns {PdfSignature} - The created PDF signature instance.
*/
static create(options: PdfSignatureOptions, timestampCallback: TimestampCallback): PdfSignature;
/**
* Gets the date when the PDF was signed.
*
* ```typescript
* // Load the document
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', {x: 10, y: 10, width: 100, height: 50});
* // Create a new signature using PFX data and private key
* const sign: PdfSignature = PdfSignature.create({ cryptographicStandard: CryptographicStandard.cms, digestAlgorithm: DigestAlgorithm.sha256 }, certData, password);
* // Sets the signature to the field
* field.setSignature(sign);
* // Gets the signed date
* sign.getSignedDate();
* // Add the field into PDF form
* form.add(field);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @returns {Date} - The signed date.
*/
getSignedDate(): Date;
/**
* Gets the certificate information associated with the PDF signature.
*
* ```typescript
* // Load the document
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', {x: 10, y: 10, width: 100, height: 50});
* // Create a new signature using PFX data and private key
* const sign: PdfSignature = PdfSignature.create({ cryptographicStandard: CryptographicStandard.cms, digestAlgorithm: DigestAlgorithm.sha256 }, certData, password);
* // Sets the signature to the field
* field.setSignature(sign);
* // Gets the certificate information of the signature
* const certificateInfo: PdfCertificateInformation = sign.getCertificateInformation();
* // Add the field into PDF form
* form.add(field);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @returns {PdfCertificateInformation} - The certificate information.
*/
getCertificateInformation(): PdfCertificateInformation;
/**
* Gets the options for configuring a digital signature in a PDF document.
*
* ```typescript
* // Load the document
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Gets the signature field
* let field: PdfSignatureField = form.fieldAt(0) as PdfSignatureField;
* // Gets the PDF signature
* let signature: PdfSignature = field.getSignature();
* // Gets the signature options
* let options: PdfSignatureOptions = signature.getSignatureOptions();
* // Gets the cryptographic standard of the signature
* let cryptographicStandard: CryptographicStandard = options.cryptographicStandard;
* // Destroy the document
* document.destroy();
* ```
*
* @returns {PdfSignatureOptions} The options for configuring a digital signature in a PDF document.
*/
getSignatureOptions(): PdfSignatureOptions;
/**
* Replaces an empty signature field in a PDF document with externally signed data.
*
* @example
* ```typescript
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', { x: 10, y: 10, width: 100, height: 50 });
* // placeholder for signed data
* let signedData: Uint8Array;
* // Define a callback function used for external signing
* const externalSignatureCallback = (data: Uint8Array,
* options: {
* algorithm: DigestAlgorithm,
* cryptographicStandard: CryptographicStandard
* }): Void => {
* // Implement external signing logic here
* signedData = new Uint8Array(); // Placeholder return
* };
* // Create a new signature using external signing with public certificate collection
* const signature: PdfSignature = PdfSignature.create({
* cryptographicStandard: CryptographicStandard.cms,
* algorithm: DigestAlgorithm.sha256
* }, externalSignatureCallback,
* publicCertificates);
* // Set the signature to the field
* field.setSignature(signature);
* // Add the field into PDF form
* form.add(field);
* // Save the document data
* const data: Uint8Array = document.save();
* // Destroy the document
* document.destroy();
* // Replace the empty signature with externally signed hash and certificates
* const signedDocumentData: Uint8Array = PdfSignature.replaceEmptySignature(data,
* 'Signature',
* signedData,
* DigestAlgorithm.sha256,
* publicCertificates);
* // Destroy the document
* document.destroy();
* ```
*
* @param {Uint8Array} inputPdfData - The PDF document data.
* @param {string} signatureName - The name of the signature field to replace.
* @param {Uint8Array} signedData - The externally signed content to embed.
* @param {DigestAlgorithm} algorithm - The digest algorithm used to hash the PDF content.
* @param {Uint8Array[]} publicCertificates - Optional array of public certificate data used for signing.
* @param {object} options - Configuration options for signature replacement.
* @param {string} options.password - Optional password to open the PDF if it's encrypted.
* @param {Uint8Array} options.timestampData - Optional timestamp token data to embeded in the signature.
* @param {boolean} options.skipSignatureEncoding - Skips encoding the signature.
* @returns {Uint8Array} The modified PDF document as a byte array.
*/
static replaceEmptySignature(inputPdfData: Uint8Array, signatureName: string, signedData: Uint8Array, algorithm: DigestAlgorithm, publicCertificates: Uint8Array[], options?: {
password?: string;
timestampData?: Uint8Array;
skipSignatureEncoding?: boolean;
}): Uint8Array;
/**
* Replaces an empty signature field in a PDF document with externally signed data.
*
* @example
* ```typescript
* let document: PdfDocument = new PdfDocument(data);
* // Gets the first page of the document
* let page: PdfPage = document.getPage(0);
* // Access the PDF form
* let form: PdfForm = document.form;
* // Create a new signature field
* let field: PdfSignatureField = new PdfSignatureField(page, 'Signature', { x: 10, y: 10, width: 100, height: 50 });
* // Define a callback function used for external signing
* // placeholder for signed PDF data
* let signedData: Uint8Array;
* const externalSignatureCallback = (data: Uint8Array,
* options: {
* algorithm: DigestAlgorithm,
* cryptographicStandard: CryptographicStandard
* }): Void => {
* // Implement external signing logic here
* signedData = new Uint8Array(); // Placeholder return
* };
* // Create a new signature using external signing with public certificate collection
* const signature: PdfSignature = PdfSignature.create({
* cryptographicStandard: CryptographicStandard.cms,
* algorithm: DigestAlgorithm.sha256
* }, externalSignatureCallback,
* publicCertificates);
* // Set the signature to the field
* field.setSignature(signature);
* // Add the field into PDF form
* form.add(field);
* // Save the document
* const data: Uint8Array = document.save();
* // Destroy the document
* document.destroy();
* // Replace the empty signature with externally signed hash and certificates
* PdfSignature.replaceEmptySignature(data,
* 'Signature',
* signedData,
* DigestAlgorithm.sha256
* 'signed_output.pdf'
* publicCertificates);
* ```
*
* @param {Uint8Array} inputPdfData - The PDF document data.
* @param {string} signatureName - The name of the signature field to replace.
* @param {Uint8Array} signedData - The externally signed content to embed.
* @param {DigestAlgorithm} algorithm - The digest algorithm used to hash the PDF content.
* @param {Uint8Array[]} publicCertificates - Optional array of public certificate data used for signing.
* @param {string} outputPdfName - The name of the output file where the signed PDF will be saved.
* @param {object} options - Configuration options for signature replacement.
* @param {string} options.password - Optional password to open the PDF if it's encrypted.
* @param {Uint8Array} options.timestampData - Optional timestamp token data to embed in the signature.
* @param {boolean} options.skipSignatureEncoding - If true, skips encoding the signature; defaults to false.
* @returns {void} Returns nothing.
*/
static replaceEmptySignature(inputPdfData: Uint8Array, signatureName: string, signedData: Uint8Array, algorithm: DigestAlgorithm, publicCertificates: Uint8Array[], outputPdfName: string, options?: {
password?: string;
timestampData?: Uint8Array;
skipSignatureEncoding?: boolean;
}): void;
/**
* Applies provided signature options to this signature instance.
*
* @private
* @param {PdfSignatureOptions} [options] Options for signature configuration.
* @returns {void} nothing.
*/
_applySignatureOptions(options?: PdfSignatureOptions): void;
/**
* Initializes internal state from an existing signature dictionary and field.
*
* @private
* @param {_PdfDictionary} dictionary The signature dictionary object.
* @param {PdfSignatureField} field The signature field associated with the dictionary.
* @returns {void} nothing.
*/
_initializeInternals(dictionary: _PdfDictionary, field: PdfSignatureField): void;
/**
* Converts an array-like object into a number array if possible.
*
* @private
* @param {any} arr The array-like input to convert.
* @returns {number[]} The converted number array or `undefined` when conversion is not possible.
*/
_toNumberArray(arr: any): number[];
/**
* Checks whether the provided object id corresponds to a certificated signature in the document.
*
* @private
* @param {any} objId Object identifier to check.
* @returns {boolean} True when the object id refers to a certificated signature.
*/
_checkCertificated(objId: any): boolean;
/**
* Ensures catalog permissions are updated when beginning a save operation for certified signatures.
*
* @private
* @returns {void} nothing.
*/
_catalogBeginSave(): void;
/**
* Adds a lock dictionary to the signature field to lock form fields when signing.
*
* @private
* @returns {void} nothing.
*/
_lockSignature(): void;
/**
* Creates a new signature dictionary for the provided document and signature instance.
*
* @private
* @param {PdfDocument} document The PDF document the dictionary belongs to.
* @param {PdfSignature} signature The signature instance to back the dictionary.
* @returns {_PdfSignatureDictionary} The created signature dictionary.
*/
_createDictionary(document: PdfDocument, signature: PdfSignature): _PdfSignatureDictionary;
}