Built-in cryptographic provider

The BuiltIn cryptographic provider enables access to the cryptographic functions of the local operating system. For example, to sign a document. No cryptographic hardware or external service is required, except for the optional TimestampUrl used when appling a time-stamp.

You can load signing certificates with private keys directly from a PFX (PKCS#12) file using the CreateSignatureFromCertificate method.

Additional certificates (for example, issuer certificates) are stored in the Certificates directory. These certificates are required when adding validation information to signatures that do not have the full trust chain embedded. The Certificates directory may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form.

In this example, a BuiltIn cryptographic provider is used to apply a document approval signature to a PDF document. The PFX certificate is read from a local file. Information required for long-term signature validation (LTV) is embedded in the output PDF.

Steps to sign a document:

1. Initialize the cryptographic provider.
2. Read the PFX or P12 certificate.
3. (Optional) Add long-term validation information
4. Open and sign the document.

---

Before you begin

You need to initialize the library.

Initializing the cryptographic provider

When using the BuiltIn cryptographic provider, you start the digital signing process by instantiating the Provider object. The Provider object exposes the methods of the local operating system's cryptographic provider. The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms.

.NET

// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();

Java

// Create a session to the built-in cryptographic provider
Provider session = new Provider();

Reading the PFX or P12 certificate

PFX certificate files can be loaded directly into the BuiltIn cryptographic provider from the file system. The certificate file is opened as a stream and loaded into the provider to prepare it to apply a digital signature.

.NET

// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);

Java

// Create signature configuration from PFX (or P12) file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY));
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);

tip

If you are using a Java KeyStore that has already been loaded, for example ks, you can use a MemoryStream to create the SignatureConfiguration.

// Create an OutputStream to write the KeyStore to (into memory)
ByteArrayOutputStream os = new ByteArrayOutputStream();
// Write the KeyStore to the OutputStream
ks.store(os, password.toCharArray());
// Put the OutputStream bytes into a MemoryStream
Stream certStr = new MemoryStream(os.toByteArray());
// Create signature configuration from that MemoryStream
SignatureConfiguration signature = session.createSignatureFromCertificate(certStr, password);

The KeyStore must be of type PKCS12. For more information on the KeyStore, please refer to the Java API Reference.

Adding long-term validation information

As an optional step, long-term validation information can be added to the output document. It embeds revocation information such as online certificate status response and certificate revocation lists. Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing.

.NET

// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;

Java

// Embed validation information to enable the long term validation (LTV) of the signature (default)
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);

Opening and signing the document

After instantiating the Provider and preparing the signature configuration, you are ready to apply the digital signature to a document.

The input and output PDF documents are created as streams (in this example, as file streams). The Signer object is used to apply the digital document signature.

Non-critical processing errors raise a Warning event. It is recommended to listen for these events, and review the WarningCategory to determine if further action is needed.

.NET

// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);

// Create a stream for the output file
using var outStr = File.Create(outPath);

// Create the Signer object
Signer signer = new Signer();

// (optionally) Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);

// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);

Java

// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);

// Create a stream for the output file
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);

// Create the Signer object
Signer signer = new Signer();

// (optionally) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });

// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr);

Full example

.NET

// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();

// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);

// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;

// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);

// Create stream for output file
using var outStr = File.Create(outPath);

// Create the Signer object
Signer signer = new Signer();

// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);

// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);

Java

try (
    // Create a session to the built-in cryptographic provider
    Provider session = new Provider();

    // Open certificate file
    FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY))
{
    // Create signature configuration from PFX (or P12) file
    SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);

    // Embed validation information to enable the long term validation (LTV) of the signature (default)
    signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);

    // Create the Signer object
    Signer signer = new Signer();

    // (optionally) Create an event listener to listen for warning events that are raised and write them to console
    signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });

    try (
        // Open input document
        FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
        Document inDoc = Document.open(inStr);

        // Create a stream for the output file
        FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);

        // Sign the input document
        Document outDoc = signer.sign(inDoc, signature, outStr))
    {
    }
}

Signing PDF/A documents

During the conversion process from PDF to PDF/A, any signatures are removed from the file before it is converted to PDF/A for archiving. Therefore, files that require archiving should be archived to PDF/A format before any digital signatures are applied.