Some test text!

Hamburger Icon

iOS / Guides

Add a DocTimeStamp signature on iOS

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:

PTPDFDoc* doc = [[PTPDFDoc alloc] initWithFilepath: in_docpath];
PTDigitalSignatureField* doctimestamp_signature_field = [doc CreateDigitalSignatureField: @""];
PTTimestampingConfiguration* tst_config = [[PTTimestampingConfiguration alloc] initWithIn_url: @"URL_to_timestamp_authority"];
PTVerificationOptions* opts = [[PTVerificationOptions alloc] initWithLevel:e_ptcompatibility_and_archiving];

/* It is necessary to add to the VerificationOptions a trusted root certificate corresponding to 
the chain used by the timestamp authority to sign the timestamp token, in order for the timestamp
response to be verifiable during DocTimeStamp signing. */
[ opts AddTrustedCertificateWithFilePath: in_trusted_cert_path];
/* By default, we only check online for revocation of certificates using the newer and lighter 
OCSP protocol as opposed to CRL, due to lower resource usage and greater reliability. However, 
it may be necessary to enable online CRL revocation checking in order to verify some timestamps
(i.e. those that do not have an OCSP responder URL for all non-trusted certificates). */
[ opts EnableOnlineCRLRevocationChecking: YES];

PTSignatureWidget* widgetAnnot = [PTSignatureWidget CreateWithDigitalSignatureField: doc pos: [[PTPDFRect alloc] initWithX1: 0 y1: 100 x2: 200 y2: 150] field: doctimestamp_signature_field];
[[doc GetPage: 1] AnnotPushBack: widgetAnnot];

// (OPTIONAL) Add an appearance to the signature field.
PTImage* img = [PTImage CreateWithFile: [doc GetSDFDoc] filename: in_appearance_img_path encoder_hints: [[PTObj alloc]init]];

[widgetAnnot CreateSignatureAppearance: img];

NSLog(@"Testing timestamping configuration.");
PTTimestampingTestResult* config_result = [tst_config TestConfiguration:opts];
if([ config_result GetStatus])
	NSLog(@"Success: timestamping configuration usable. Attempting to timestamp.");
	// Print details of timestamping failure.
	NSLog(@"%@", [config_result GetString]);
	if ([config_result HasResponseVerificationResult])
		PTEmbeddedTimestampVerificationResult* tst_result = [config_result GetResponseVerificationResult];
		NSLog(@"CMS digest status: %@\n", [tst_result GetCMSDigestStatusAsString]);
		NSLog(@"Message digest status: %@\n", [tst_result GetMessageImprintDigestStatusAsString]);
		NSLog(@"Trust status: %@\n", [tst_result GetTrustStatusAsString]);
	return NO;

[doctimestamp_signature_field TimestampOnNextSave: tst_config in_timestamp_response_verification_options: opts];

// Save/signing throws if timestamping fails.
[doc SaveToFile: in_outpath flags: e_ptincremental];

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.

Get the answers you need: Chat with us