Contained Digital Signatures on Android

PSPDFKit supports a workflow where the creation of a digital signature is split in two phases:

  • First, you can “prepare” a document with a signature form field by stamping a custom signature appearance and reserving space in the PDF for the digital signature.

  • Second, you can “embed” a custom PKCS#7 signature container in a document that was already “prepared” in the first step. The end result is a digitally signed document.

This workflow, which we call contained digital signatures, is especially useful when the cryptographic material to sign a document (keys, certificates) is not available on the platform that executes PSPDFKit.

For the first part, preparing a document, you may call prepareFormFieldForSigningAsync() on the Signer class. This preparation step allows customization for the raw content that will fill the digital signature contents before a real digital signature is applied: The SignatureContents interface is an abstraction for that. If you want to fill the digital signature contents with binary zeroes, pass an instance of the BlankSignatureContents class to signatureContents() when building SignerOptions used in prepareFormFieldForSigningAsync().

Note that the document generated by the prepareFormFieldForSigningAsync() API has two important properties: First, it’s not a valid digitally signed document yet, so it may show errors if you try to validate it with PSPDFKit or any other third-party tool. Second, this document must not be modified in any way, so as to prevent corrupting the digital signature that will be embedded in the final document. The process of embedding the real digital signature is explained next.

For embedding a real digital signature in a document generated by prepareFormFieldForSigningAsync(), you can call embedSignatureInFormFieldAsync() on the Signer class. You’re responsible for generating a valid digital signature in the cryptographic PKCS#7 format for the prepared document. To do that, pass a custom implementation of SignatureContents to the previously cited method. In your SignatureContents#signData() implementation, you’ll receive the part of the document that you need to hash, encrypt, and package into a digital signature. You can call getHashForDocumentRange() on a PdfDocument instance to help you calculate the hash value of some parts of a PDF document. You can generate the PKCS7 signature container with the help of our PKCS7 class or use PKCS7SignatureContents directly.

PSPDFKit also ships with the ready-to-use ContainedSignaturesSigner, which encapsulates the contained signatures flow. You can start using it by implementing its abstract method, prepareSignatureContents(). This method receives the document prepared for signing with the prepareFormFieldForSigningAsync(). You should return your custom implementation of SignatureContents from this method to embed it as a digital signature in the prepared document.

For a complete example, refer to ContainedDigitalSignaturesExample in the Catalog app.