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
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
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.