Section:

Add a DocTimeStamp signature using JavaScript

Adding Trusted Certificate

When providing trusted certificate(s) through the VerificationOptions.AddTrustedCertificate method, ensure that it is the root certificate corresponding to the chain used by the timestamp authority to sign the timestamp token.

Check your Certificate Authority's website for a list of root certificates they have publicly available, and choose the root certificate corresponding to the set of certificates that have been signed by that root certificate for your usage.

To add a DocTimeStamp signature:

JavaScript

1async function main() {
2	const doc = await PDFNet.PDFDoc.createFromFilePath(in_docpath);
3	doc.initSecurityHandler();
4	const doctimestamp_signature_field = await doc.createDigitalSignatureField();
5	const tst_config = await PDFNet.TimestampingConfiguration.createFromURL("URL_to_timestamp_authority");
6	const opts = await PDFNet.VerificationOptions.create(PDFNet.VerificationOptions.SecurityLevel.e_compatibility_and_archiving);
7	/* It is necessary to add to the VerificationOptions a trusted root certificate corresponding to 
8	the chain used by the timestamp authority to sign the timestamp token, in order for the timestamp
9	response to be verifiable during DocTimeStamp signing. */
10	await opts.addTrustedCertificateUString(in_trusted_cert_path);
11	/* By default, we only check online for revocation of certificates using the newer and lighter 
12	OCSP protocol as opposed to CRL, due to lower resource usage and greater reliability. However, 
13	it may be necessary to enable online CRL revocation checking in order to verify some timestamps
14	(i.e. those that do not have an OCSP responder URL for all non-trusted certificates). */
15	await opts.enableOnlineCRLRevocationChecking(true);
16
17	const widgetAnnot = await PDFNet.SignatureWidget.createWithDigitalSignatureField(doc, new PDFNet.Rect(0, 100, 200, 150), doctimestamp_signature_field);
18	await (await doc.getPage(1)).annotPushBack(widgetAnnot);
19
20	// (OPTIONAL) Add an appearance to the signature field.
21	const img = await PDFNet.Image.createFromFile(doc, in_appearance_img_path);
22	await widgetAnnot.createSignatureAppearance(img);
23
24	console.log('Testing timestamping configuration.');
25	const config_result = await tst_config.testConfiguration(opts);
26	if (await config_result.getStatus()) {
27		console.log('Success: timestamping configuration usable. Attempting to timestamp.');
28	} else {
29		// Print details of timestamping failure.
30		console.log(await config_result.getString());
31		if (await config_result.hasResponseVerificationResult()) {
32			const tst_result = await config_result.getResponseVerificationResult();
33			console.log('CMS digest status: ' + await tst_result.getCMSDigestStatusAsString());
34			console.log('Message digest status: ' + await tst_result.getMessageImprintDigestStatusAsString());
35			console.log('Trust status: ' + await tst_result.getTrustStatusAsString());
36		}
37		return false;
38	}
39
40	await doctimestamp_signature_field.timestampOnNextSave(tst_config, opts);
41
42	// Save/signing throws if timestamping fails.
43	await doc.save(in_outpath, PDFNet.SDFDoc.SaveOptions.e_incremental);
44}
45PDFNet.runWithCleanup(main);

Digital signatures
Full code sample which demonstrates using the digital signature API to digitally sign, certify, and/or verify PDF documents.

About DocTimeStamp (DTS)

If it is important that a signature in a document have a timestamp that is verifiable with a third-party entity (i.e. Certificate Authority), then performing DTS would allow verification of when the document was signed. A Certificate Authority that hosts a timestamp server publicly is known as a Timestamp Authority (TSA). Timestamping a signature can be achieved by sending a hash of the signature data to the TSA's timestamping server ( which is what is achieved with the above code sample). If the request is deemed valid, the server will combine the hash provided by the client and an authoritative date-time of timestamping, signed by a private key from the Certificate Authority. The Timestamp Token is then recorded into the document alongside the signature.

If future viewers that open the timestamped and signed document have the same TSA as part of their trust list, then the viewer's PDF viewing application will acknowledge that the signature has been verifiably timestamped.

Definition of Terms

Chain of Trust

A chain of certificates, starting with a root certificate, an intermediate certificate and an end-entity certificate, forming a linked path of validation and verification from a trust anchor (i.e. Certificate Authority) down to an end-entity certificate. As the name implies, a root certificate is analogous to the root of a tree, where each branch of the tree is it's own chain of trust.

Note that "chain of trust" is also sometimes known as a "trust path"

Root Certificate

A root certificate is the top-most certificate in a chain of trust/trust path, the private key of which is used to "sign" other certificates. All certificates signed by the root certificate inherit the trustworthiness of the root certificate.

Intermediate Certificate

Act as a middle-man between the protected root certificate and the end-entity certificate. Note there is always at least one intermediate certificate in a chain of trust, but there could be more than one.

End-entity Certificate

The last in a chain of trust (i.e. a leaf node of the tree) that identifies either a business, a website, or a person. With respect to digital signatures, identifying the individuals who signed a document is where the trust worthiness of the chain(s) (i.e. where the end-entity certificates originated from) is important.

Timestamp Authority (TSA)

A trusted third party acting as the authoratative entity providing a timestamp, via a timestamp token. Clients who contact a TSA server will create a hashed value (as a unique identifier of the data or file that needs to be timestamped), and send the hashed value to the TSA.

More information about TSAs can be read about in the Time-Stamp Protocol (RFC 3161) industry standard.

Timestamp Token

A combination of the hash provided by the client and the authoritative date-time of timestamping, digitally signed with the TSA's private key, that is received by the client, and recorded into the document.

Future client applications who open the document will use the TSA's public key to

  1. Authenticate the TSA
  2. Re-calculate the hash of the original data

This new hash is compared to the originally created hash, and if any changes to the data has been made since the timestamp was originally created, then a warning should be raised by the client application.

Did you find this helpful?

Trial setup questions?

Ask experts on Discord

Need other help?

Contact Support

Pricing or product questions?

Contact Sales