Signature Library (SignLib) Programmer's Manual

How to create and verify digital signatures from .NET code: PDF (PAdES), CAdES / PKCS#7 (.p7m, .p7s), XMLDSig and XAdES, Office documents and ASiC-E containers, with time stamps, long term validation data and certificates from files, from the Windows store, from smart cards and from HSMs.

1. Introduction

1.1 What the library is

SignLib, the Signature Library, is a single managed assembly (SignLib.dll) that creates and verifies electronic signatures. It does not need Adobe software, Microsoft Office, the Windows cryptographic UI or any native component: the documents are processed in memory, by your own process. The library is written in C#; the structure of the PDF documents is read and written with a modified version of iTextSharp 4.1.6 (iTextSharp-4.1.6.dll, delivered with the library).

The classes of the library, grouped by what they do:

1.2 Supported platforms

The library is built from one source tree for these targets:

• .NET Framework 4.6.2 and .NET Framework 4.8 (the .NET Framework builds of SignLib.dll; the 4.6.2 build runs on every later version of .NET Framework 4);
• .NET 8, .NET 9 and .NET 10 (the .NET builds of SignLib.dll).

Use the assembly that matches the target framework of your project. All the builds have the same public API.

The signing and verification code is managed and it does not depend on the operating system. Some functions use the Windows APIs and they are available only on Windows:

1.3 How the manual is organized

1. section 2 shows how to add the library to a project and how to register it. section 3 signs and verifies a PDF document in a few lines.
2. section 4 describes what is common to all the signature classes: the usage pattern, the hash algorithms, the signature levels, what “valid” means, the exceptions, the threads and the network access. Read it once.
3. section 5 explains the certificates; then one chapter for every kind of document: section 6, section 7, section 8, section 9, section 10.
4. section 11, section 12 and section 13 are about the features that every format shares.
5. section 14 explains what the library gives for eIDAS signatures. section 15 shows complete solutions: services, batches, parallel signing, two-phase signing over HTTP. section 16 lists the sample projects.
6. section 17 lists the errors you can meet and what to do. section 18 is the reference of all the public types and members.

1.4 Conventions

• The examples are in C#, with the exceptions that say otherwise. They use the namespaces of the library (SignLib, SignLib.Pdf, SignLib.Cades, SignLib.Xml, SignLib.Office, SignLib.Asic, SignLib.Certificates, SignLib.Timestamping) and the namespaces of .NET that appear in the first lines of the example.
• Two names are assumed by the short examples: the constant LibrarySerialNumber (the serial number string, section 2.4) and the variable signingCertificate, an X509Certificate2 with a private key (section 5.2). The examples that are complete programs define everything they use.
• Names in this font link to the API reference when the library has such a member. Types are written without the namespace.
• Property and method names are the real ones. Defaults are written as in the documentation of the library; a property that is not mentioned has the default of its type (false, null, 0).
• Indexes of signatures are 0-based in the whole library.
• Example files (source.pdf, cert.pfx with the password 123456, test.txt) are the ones of the sample projects (section 16).

1.5 Resources

• The library page: https://www.signfiles.com/signature-library/
• The download (library, sample projects, scripts): https://www.signfiles.com/sdk/SignatureLibrary.zip
• This manual online: https://www.signfiles.com/manuals/signature-library/

2. Installation and project setup

2.1 What is delivered

The library has no installer and no native files. To install it, copy the files into a folder of your solution and reference SignLib.dll.

2.2 A .NET 8, .NET 9 or .NET 10 project

Reference the assembly with a HintPath and add the NuGet packages that the library uses. The library is referenced as a file, so the packages that it uses are not added automatically: add them to your project (the versions are the ones the library was built with; they are the same for .NET 8, .NET 9 and .NET 10, and the build for your target framework is the one in the folder net8.0, net9.0 or net10.0 of the library):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
  <ItemGroup>
    <!-- Used by every signature class -->
    <PackageReference Include="System.Security.Cryptography.Pkcs" Version="10.0.12" />
    <PackageReference Include="System.Security.Cryptography.Xml" Version="10.0.12" />
    <PackageReference Include="System.Windows.Extensions" Version="10.0.12" />
    <!-- Office signatures (and the images of the signature lines), and the LDAP downloads of CRLs -->
    <PackageReference Include="System.IO.Packaging" Version="10.0.12" />
    <PackageReference Include="System.Drawing.Common" Version="10.0.12" />
    <PackageReference Include="System.DirectoryServices" Version="10.0.12" />
  </ItemGroup>
  <ItemGroup>
    <Reference Include="SignLib">
      <HintPath>..\SignLib\SignLib.dll</HintPath>
    </Reference>
  </ItemGroup>
</Project>

In Visual Studio the same is done with Project > Add Project Reference > Browse, selecting SignLib.dll, and with Manage NuGet Packages.

2.3 A .NET Framework 4.6.2 project

Add the reference to the .NET Framework build of SignLib.dll and the framework assemblies that the features need:

<ItemGroup>
  <Reference Include="SignLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=ffdaa12fb4cf4a55, processorArchitecture=MSIL">
    <SpecificVersion>False</SpecificVersion>
    <HintPath>..\SignLib\SignLib.dll</HintPath>
  </Reference>
  <Reference Include="System" />
  <Reference Include="System.Core" />
  <Reference Include="System.Drawing" />
  <Reference Include="System.Security" />
  <Reference Include="System.Xml" />
  <!-- Office signatures: WindowsBase; ASiC-E containers: System.IO.Compression -->
  <Reference Include="WindowsBase" />
  <Reference Include="System.IO.Compression" />
  <Reference Include="System.IO.Compression.FileSystem" />
</ItemGroup>

The source code of the library is C# 7.3, so every public member can be used from a .NET Framework 4.6.2 project with the language version of that framework. No NuGet package is needed on .NET Framework.

2.4 The serial number

Every class that creates or verifies signatures takes the serial number of the library as the parameter of its constructor:

const string LibrarySerialNumber = "YourSerialNumber";

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
CadesSignature cadesSignature = new CadesSignature(LibrarySerialNumber);
XadesSignature xadesSignature = new XadesSignature(LibrarySerialNumber);

• Replace YourSerialNumber with the serial number that you received when you purchased the library. The serial number is checked when the first object is created; a valid serial number registers the library for the whole process, so the objects created later work in the licensed mode, whatever serial number they receive.
• An invalid or missing serial number is not an error: the library runs as the demo version. The demo version has the same functions as the licensed one, with these limits:
  • a message is written to the console (Console is not required: the message is skipped when the process has no console);
  • the PDF documents loaded for signing, that have no signature yet, get the text SignLib.dll DEMO VERSION on the first page;
  • every signature creation or verification of CAdES, XML, XAdES, Office and ASiC-E documents and every time-stamp request wait 10 seconds before it starts;
  • the certificates created with X509CertificateGenerator are valid for 30 days at most (the validity is cut to 30 days; the call waits 10 seconds when it has to cut it).
• The demo version is meant for the evaluation of the library: the results are correct signatures, only the demonstration marks are added.

string serialNumber = Environment.GetEnvironmentVariable("SIGNLIB_SERIAL");   // null: the demo version
PdfSignature pdfSignature = new PdfSignature(serialNumber);

2.5 Check the installation

A program that prints the version of the assembly and signs nothing:

using System;
using SignLib.Pdf;

class Program
{
    static void Main()
    {
        // The assembly of any public class of the library.
        System.Reflection.AssemblyName name = typeof(PdfSignature).Assembly.GetName();
        Console.WriteLine(name.Name + " " + name.Version);
        Console.WriteLine("Runtime: " + Environment.Version);
    }
}

If the program starts, the assembly and its dependencies are found. The most frequent mistakes at this point are in section 17 (a missing iTextSharp-4.1.6.dll, the wrong build for the target framework).

2.6 Deployment

• Deploy SignLib.dll and iTextSharp-4.1.6.dll with your application (both are copied by the build when they are in the same folder).
• The 32-bit or 64-bit process is not a constraint of the library. It matters only for the PKCS#11 modules and for the smart card middleware: a 64-bit process needs the 64-bit module (section 13.3).
• The library does not write files by itself and it does not keep the documents after the call returns. The signed document is returned as byte[]; you decide where it is stored.
• Allow the outgoing HTTP and HTTPS connections of the process to the time-stamping servers, to the OCSP responders and to the CRL addresses of the certificates, when you use these features (section 4.10).

The library includes parts of the Bouncy Castle C# API (MIT license), see Appendix D.

3. Quick start

This chapter signs a PDF document with a certificate from a PFX file and verifies the result, in C#, in VB.NET and in PowerShell. It uses the files of the sample projects: source.pdf and cert.pfx (a self-signed test certificate, the password is 123456). Replace YourSerialNumber with your serial number (section 2.4).

3.1 Sign and verify a PDF document

using System;
using System.IO;
using System.Security.Cryptography.X509Certificates;
using SignLib.Certificates;
using SignLib.Pdf;

class Program
{
    private const string LibrarySerialNumber = "YourSerialNumber";

    static void Main()
    {
        // 1. The signing certificate, with its private key, from a PFX file.
        X509Certificate2 certificate = DigitalCertificate.LoadCertificate("cert.pfx", "123456");

        // 2. Load the document and set the signature.
        PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
        pdfSignature.LoadPdfDocument("source.pdf");
        pdfSignature.DigitalSignatureCertificate = certificate;
        pdfSignature.SigningReason = "I approve this document";
        pdfSignature.SignaturePosition = SignaturePosition.TopLeft;

        // 3. Sign: the result is the signed PDF document.
        byte[] signedPdf = pdfSignature.ApplyDigitalSignature();
        File.WriteAllBytes("source[signed].pdf", signedPdf);

        // 4. Verify: load the signed document and read its signatures.
        PdfSignature verifier = new PdfSignature(LibrarySerialNumber);
        verifier.LoadPdfDocument(signedPdf);

        foreach (PdfSignatureInfo info in verifier.DocumentProperties.DigitalSignatures)
        {
            Console.WriteLine(info.SignatureName + ": signed by " + info.SignatureCertificate.GetNameInfo(X509NameType.SimpleName, false)
                + ", intact: " + info.SignatureIsValid);
        }
    }
}

What the code does:

1. DigitalCertificate.LoadCertificate(file, password) returns an X509Certificate2 with the private key. Other sources are in section 5.2.
2. A PdfSignature object holds the settings of the signature. You load the document, set the certificate and the options of the visible signature.
3. ApplyDigitalSignature() returns the signed document as a byte[]. The library never overwrites the input file.
4. The verification is done with the same class. SignatureIsValid says that the document was not changed after it was signed and that the signature value matches the certificate in the signature. It does not say that you can trust the signer: see section 4.5.

3.2 The same in VB.NET

Imports System
Imports System.IO
Imports System.Security.Cryptography.X509Certificates
Imports SignLib.Certificates
Imports SignLib.Pdf

Module Program
    Private Const LibrarySerialNumber As String = "YourSerialNumber"

    Sub Main()
        Dim certificate As X509Certificate2 = DigitalCertificate.LoadCertificate("cert.pfx", "123456")

        Dim pdfSignature As New PdfSignature(LibrarySerialNumber)
        pdfSignature.LoadPdfDocument("source.pdf")
        pdfSignature.DigitalSignatureCertificate = certificate
        pdfSignature.SigningReason = "I approve this document"
        pdfSignature.SignaturePosition = SignaturePosition.TopLeft

        Dim signedPdf As Byte() = pdfSignature.ApplyDigitalSignature()
        File.WriteAllBytes("source[signed].pdf", signedPdf)

        Dim verifier As New PdfSignature(LibrarySerialNumber)
        verifier.LoadPdfDocument(signedPdf)

        For Each info As PdfSignatureInfo In verifier.DocumentProperties.DigitalSignatures
            Console.WriteLine(info.SignatureName & ": intact: " & info.SignatureIsValid.ToString())
        Next
    End Sub
End Module

All the examples of this manual are in C#; the VB.NET code is the same calls with the syntax of the language. The sample set for .NET Framework contains a complete VB.NET project (section 16).

3.3 The same in PowerShell

Windows PowerShell 5.1 runs on .NET Framework, so it uses the .NET Framework build of the library. Load iTextSharp-4.1.6.dll before SignLib.dll (the loader of PowerShell does not search the folder of the script for the dependencies):

$dir = $PSScriptRoot
[Reflection.Assembly]::LoadFrom("$dir\iTextSharp-4.1.6.dll") | Out-Null
[Reflection.Assembly]::LoadFrom("$dir\SignLib.dll") | Out-Null

$serial      = "YourSerialNumber"
$certificate = [SignLib.Certificates.DigitalCertificate]::LoadCertificate("$dir\cert.pfx", "123456")

$signature = New-Object SignLib.Pdf.PdfSignature($serial)
$signature.LoadPdfDocument("$dir\source.pdf")
$signature.DigitalSignatureCertificate = $certificate
$signature.SigningReason = "I approve this document"
[IO.File]::WriteAllBytes("$dir\source[signed].pdf", $signature.ApplyDigitalSignature())

$check = New-Object SignLib.Pdf.PdfSignature($serial)
$check.LoadPdfDocument("$dir\source[signed].pdf")
foreach ($info in $check.DocumentProperties.DigitalSignatures) {
    "{0}: intact = {1}" -f $info.SignatureName, $info.SignatureIsValid
}

Run it with powershell.exe -File sign.ps1. Enumerations are written [SignLib.Pdf.SignaturePosition]::TopLeft. PowerShell 7 runs on .NET: use the .NET build of the library and the same loading lines.

3.4 Sign any file as .p7m

The same pattern with CadesSignature signs a file of any type; the result is a .p7m file that contains the file and its signature. CadesVerify verifies it and returns the signers and the original file:

CadesSignature cadesSignature = new CadesSignature(LibrarySerialNumber);
cadesSignature.DigitalSignatureCertificate = signingCertificate;

File.WriteAllBytes("test.txt.p7m", cadesSignature.ApplyDigitalSignature("test.txt"));

CadesVerify cadesVerify = new CadesVerify("test.txt.p7m", LibrarySerialNumber);

foreach (CadesSignatureInfo signer in cadesVerify.Signatures)
    Console.WriteLine(signer.SignatureCertificate.Subject + ", intact: " + signer.SignatureIsValid);

File.WriteAllBytes("test.txt.verified", cadesVerify.UnsignedDocument);   // the signed file, extracted

The XML, Office and ASiC-E classes follow the same pattern: set the certificate and the level, call ApplyDigitalSignature, and verify with VerifyDigitalSignature (section 8, section 9, section 10).

4. Concepts common to all the signature classes

This chapter describes what you need to know once, before the chapters about the formats: the usage pattern of the classes, the hash algorithms, the signature levels, what a verification result means, the exceptions, the threads and the network access.

4.1 The usage pattern

Every format has a class that signs (and, for most formats, verifies) with the same steps:

1. create the object with the serial number of the library;
2. set the signing certificate (DigitalSignatureCertificate) and the options of the signature (properties);
3. call ApplyDigitalSignature;
4. to verify, call VerifyDigitalSignature, or read the information of the signatures.

The objects keep their settings between the calls, so you can set the certificate and the options once and sign many documents with the same object (but not from several threads at the same time, section 4.9). The signing methods return the signed document or write it to the output you give; they never change the input.

The classes that sign XML and Office documents write the result to the output file, and delete a partially written output file when the signature fails (the input file is never deleted: the input and the output can be the same file).

4.2 Formats and standards

4.3 Hash algorithms

The enumeration HashAlgorithm has SHA1, SHA256, SHA384 and SHA512. Every signature class has a HashAlgorithm property; the default is SHA-256. The time-stamp requests have their own setting (TimestampSettings.HashAlgorithm, default SHA-256).

• SHA-1 is not considered secure for new signatures. The PDF and CMS signature classes still accept it, to interoperate with old systems. The XML, XAdES, Office and ASiC-E classes do not create SHA-1 signatures (NotSupportedException); they verify them.
• The signature algorithm follows the key of the certificate: RSA (PKCS#1 v1.5) or ECDSA (the curve of the key). The key size or the curve are not set by the signature classes. They are chosen when the certificate is created (section 5.5).

4.4 Signature levels

The ETSI standards define profiles of increasing durability. They are called B-B (basic), B-T (with a time-stamp), B-LT (with long term validation data) and B-LTA (with archival time-stamps). The names of the levels differ in the libraries of the classes, but the idea is the same:

• B-B proves who signed and that the document was not changed. Its validity depends on the certificate of the signer at the moment of the verification: after the certificate expires or is revoked, a B-B signature cannot be validated any more.
• B-T adds a time-stamp (RFC 3161) from a time-stamping authority: it proves that the signature existed at that time. The signing time written by the signer is only a claim of the signer; the time of the time-stamp is a proof.
• B-LT embeds the certificates of the chain and the revocation information (CRLs and OCSP responses) that existed when the signature was made, so the signature can be validated after the servers of the certification authority are no longer available.
• B-LTA adds a time-stamp over the signature and its validation data. It is renewed periodically with a new time-stamp, before the previous one becomes weak or its certificate expires (section 12.4).

4.5 What “valid” means

The verification methods of the library (PdfSignatureInfo.SignatureIsValid, CadesSignatureInfo.SignatureIsValid, XmlSignature.VerifyDigitalSignature, XadesSignature.VerifyDigitalSignature, OfficeSignature.VerifyDigitalSignature, AsicSignature.VerifyDigitalSignature) answer one question: is the signature intact? They verify that

• the signed data was not changed after it was signed (the digests of the signed content and of the signed attributes);
• the signature value was created with the private key of the certificate that is in the signature.

They do not verify that you can trust the signer. A complete verification has more questions, and each one has its own tool:

4.6 The time of a signature

Signatures have two different times, and the property names say which one you read:

• the signing time declared by the signer: it is the clock of the computer that signs (UTC). PdfSignature.SignatureDate is the value that is written in the PDF signature; CadesSignatureInfo.SignatureTime and OfficeSignatureInfo.SigningTime read it. Anyone can set the clock of a computer: this time is not a proof;
• the time-stamp time: the time put in the signature by a time-stamping authority (TimestampInfo.SignatureTime). It is a proof that the signature existed at that moment.

PdfSignatureInfo.SignatureTime returns the time of the time-stamp when the signature has one, and the time declared by the signer otherwise (check SignatureIsTimestamped).

4.7 Files, byte arrays and streams

The library works in memory. A document is read completely, processed and returned as byte[] (or written to the output you give). Plan the memory of your process for the size of the documents and for the number of documents that you sign in parallel. The classes that sign XML and Office documents and the ASiC-E container have overloads for files, byte arrays and streams; use the byte array or the stream version in a web application, so that the documents do not touch the disk.

PdfSignature.LoadPdfDocument(Uri) downloads the document with an HTTP request; the time-out of the download is DigitalCertificate.Timeout.

4.8 Exceptions

The methods of the library throw the standard .NET exceptions; the message describes the cause. These are the ones that you should expect, with their usual causes:

Catch the exceptions at the level where you can act on them, and show or log ex.Message. The library reports the original failure as the message or as the inner exception. When the signing of a file fails, the partial output file is deleted (the original is never deleted).

try
{
    PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
    pdfSignature.LoadPdfDocument("source.pdf");
    pdfSignature.DigitalSignatureCertificate = signingCertificate;

    File.WriteAllBytes("source[signed].pdf", pdfSignature.ApplyDigitalSignature());
}
catch (WebException ex)
{
    // The time-stamping server (when TimeStamping.ServerUrl is set) is not reachable: retry later or use another server.
    Console.WriteLine("Time-stamp: " + ex.Message);
}
catch (CryptographicException ex)
{
    // The key, the certificate or the document cannot be used.
    Console.WriteLine("Signature: " + ex.Message);
}

4.9 Threads and static state

• The signature objects (PdfSignature, CadesSignature, XadesSignature, OfficeSignature...) are not thread-safe. Use one object for every thread (or every request) and never share an object between threads that run at the same time. Creating an object is cheap.
• An X509Certificate2 with a private key from a PFX file can be shared by the threads. A certificate on a smart card cannot, usually: the sessions of the token are limited.
• DigitalCertificate.UseExternalSignatureProvider and DigitalCertificate.SmartCardPin are thread-local and the library releases them after every signing operation. Set them on the thread that signs, immediately before the call, every time (section 13.1).
• The license is process-wide: a valid serial number switches the whole process to the licensed mode (section 2.4).
• DigitalCertificate.Timeout is a static field: it applies to all the threads.

A complete example of parallel signing is in section 15.3.

4.10 Network access

The library opens network connections only for these functions:

The time-out of the downloads (CRL, OCSP, documents) is DigitalCertificate.Timeout (milliseconds, 20000 by default). The requests use the proxy settings of the platform; the user agent is SignLib. A server that requires authentication is supported for the time-stamping (TimestampSettings.UserName, Password, AuthenticationCertificate). The signing and verification of a signature without these functions do not use the network.

5. Digital certificates

A signature is created with the private key of a certificate. This chapter shows how to get an X509Certificate2 for the signature classes, how to inspect and validate certificates, and how to create certificates for tests and for internal use. The classes are DigitalCertificate (static methods, no serial number needed) and X509CertificateGenerator.

5.1 What the signature classes need

• An X509Certificate2 with a private key (HasPrivateKey is true), set in the property DigitalSignatureCertificate of the signature class. Exception: when the key is outside the process (a PKCS#11 token, an HSM, a key vault, a remote service) the certificate has only the public part and an external signature provider creates the signature value (section 13).
• An RSA or an ECDSA key. The XML, XAdES, Office and ASiC-E classes accept only these two key types.
• The library does not check the key usages of the certificate when it signs. The validators do: a certificate used for document signing should have the key usage digitalSignature and/or nonRepudiation (content commitment). A certificate issued for a person or an organization by a certification authority has them.
• The signing does not check that the certificate is valid or trusted, either. Check it before you sign when your application must not sign with an expired or a revoked certificate (section 5.4).

5.2 Loading a certificate

From a PFX (PKCS#12) file

DigitalCertificate.LoadCertificate(string file, string password) and LoadCertificate(byte[] content, string password) load the certificate with its private key. On .NET the library asks the platform to keep the private key in memory (an ephemeral key set), so that it is not written to the disk; on .NET Framework the key is kept in a temporary key container that is deleted when the certificate is disposed.

X509Certificate2 fromFile  = DigitalCertificate.LoadCertificate("cert.pfx", "123456");
X509Certificate2 fromBytes = DigitalCertificate.LoadCertificate(File.ReadAllBytes("cert.pfx"), "123456");

Console.WriteLine(fromFile.Subject + ", private key: " + fromFile.HasPrivateKey);

// Dispose the certificate when you do not need it any more (it releases the private key).
fromFile.Dispose();
fromBytes.Dispose();

A wrong password, or a file that is not a PFX file, throws CryptographicException; a missing file throws FileNotFoundException.

From the Windows certificate store

The certificates of the current user (or of the local computer) are available to the library, together with the certificates that a smart card or a USB token makes available through its Windows driver (the “minidriver”). The overloads of LoadCertificate either show a selection window or find the certificate by code:

// With a window: the user selects the certificate.
X509Certificate2 selected = DigitalCertificate.LoadCertificate(false, string.Empty, "Select Certificate", "Select the certificate for the digital signature");

// Without a window (services, batch programs): by thumbprint, by serial number or by a field of the subject.
X509Certificate2 byThumbprint = DigitalCertificate.LoadCertificate(true, DigitalCertificateSearchCriteria.Thumbprint, "FAC4D3EF766A59BB068DD90877267EBC56B4232A");
X509Certificate2 byName       = DigitalCertificate.LoadCertificate(true, DigitalCertificateSearchCriteria.CommonNameCN, "John Smith");

// The certificates of the local computer (a service account has no user store).
X509Certificate2 machineCert  = DigitalCertificate.LoadCertificate(true, DigitalCertificateSearchCriteria.Thumbprint, "FAC4D3EF766A59BB068DD90877267EBC56B4232A", true);

if (byThumbprint == null)
    throw new InvalidOperationException("The certificate was not found in the store.");

A certificate on a smart card or on a USB token

A token whose certificate is in the Windows store is used like any other certificate of the store. The driver of the token asks for the PIN in a window the first time the key is used. To avoid the window, give the PIN to the library:

X509Certificate2 tokenCertificate = DigitalCertificate.LoadCertificate(true, DigitalCertificateSearchCriteria.Thumbprint, "FAC4D3EF766A59BB068DD90877267EBC56B4232A");
string pin = Environment.GetEnvironmentVariable("TOKEN_PIN");     // read the PIN from a protected source

// The PIN is used for the next signing operation of this thread, then the library forgets it.
DigitalCertificate.SmartCardPin = pin;

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = tokenCertificate;

byte[] signedPdf = pdfSignature.ApplyDigitalSignature();

• DigitalCertificate.SmartCardPin is thread-local and it is cleared as soon as the signing operation uses it, so a PIN is never applied to another card by mistake. Set it again before the next signature. A wrong PIN that is sent again and again can block the token.
• The same can be done when the certificate is loaded (the smartCardPin overloads), or for a certificate you already have with the extension method certificate.SetPinForPrivateKey(pin) (SmartCardPinExtensions).
• Not every token accepts the PIN from the application; for the tokens that do not, and for non-Windows systems, use the PKCS#11 module of the token with an external signature provider (section 13.3).
• Never store the PIN in the source code or in a configuration file that is not protected.

5.3 Reading the certificate

The X509Certificate2 class has the common properties (Subject, Issuer, NotBefore, NotAfter, Thumbprint, SerialNumber). DigitalCertificate adds the checks that the .NET class does not have:

// The key usages: null when the certificate has no key usage extension.
List<CertificateKeyUsage> usages = DigitalCertificate.GetKeyUsage(signingCertificate);
bool canSignDocuments = usages == null || usages.Contains(CertificateKeyUsage.DigitalSignature) || usages.Contains(CertificateKeyUsage.NonRepudiation);

// A certificate that declares itself qualified (the qcStatements extension, ETSI EN 319 412-5).
// The qualified status itself is given by the EU trusted lists, not by this extension.
bool declaresQualified = DigitalCertificate.IsQualifiedCertificate(signingCertificate);

// The chain of the certificate is built with the standard .NET class.
X509Chain chain = new X509Chain();
chain.ChainPolicy.RevocationMode = X509RevocationMode.NoCheck;
bool chainBuilt = chain.Build(signingCertificate);

foreach (X509ChainElement element in chain.ChainElements)
    Console.WriteLine(element.Certificate.Subject);

5.4 Validating a certificate

DigitalCertificate.VerifyDigitalCertificate(certificate, type) returns a CertificateStatus. The type of the verification selects how the status is obtained:

DigitalCertificate.Timeout = 20000;   // milliseconds, for the downloads of the CRL and of the OCSP responses

if (DigitalCertificate.VerifyDigitalCertificate(signingCertificate, VerificationType.LocalTime) != CertificateStatus.Valid)
    throw new InvalidOperationException("The certificate is expired or not yet valid.");

CertificateStatus ocsp = DigitalCertificate.VerifyDigitalCertificate(signingCertificate, VerificationType.OCSP);

if (ocsp == CertificateStatus.Revoked)
{
    // The date of the revocation is read from the CRL of the certificate.
    DateTime revokedOn = DigitalCertificate.GetCertificateRevocationDate(signingCertificate);
    Console.WriteLine("Revoked on " + revokedOn);
}
else if (ocsp == CertificateStatus.NotPresent)
{
    // The certificate has no OCSP responder: try the CRL.
    CertificateStatus crl = DigitalCertificate.VerifyDigitalCertificate(signingCertificate, VerificationType.CRL);
    Console.WriteLine("CRL: " + crl);
}

• Unknown is not Valid: the server could not be reached, or it did not answer. Decide, for your application, if an unknown status blocks the operation.
• The method checks one certificate. It does not build the chain and it does not check the certificates of the issuers: validate the certificates of the chain, or use X509Chain with the revocation mode that you need. It does not decide that a root is trusted.
• The self-signed test certificates and the certificates created by X509CertificateGenerator have no CRL and no OCSP responder, unless you add them to the certificate (section 5.5): the revocation checks return NotPresent.

5.5 Creating certificates

X509CertificateGenerator creates X.509 certificates with RSA or ECDSA keys, in memory, and returns them as PFX (PKCS#12) bytes protected by a password. Use it for tests, for internal use, for the signing of your own documents, and in a small internal certification authority. The certificates are not trusted by the other computers until the root certificate is installed on them. A certificate for the legal signature of documents is issued by a certification authority, after the identification of the person.

The generator needs the serial number of the library. The certificates created by the demo version are valid for 30 days at most (section 2.4).

A self-signed certificate

X509CertificateGenerator generator = new X509CertificateGenerator(LibrarySerialNumber);

generator.ValidFrom = DateTime.Now;
generator.ValidTo = DateTime.Now.AddYears(2);
generator.KeySize = KeySize.KeySize2048Bit;
generator.SignatureAlgorithm = SignatureAlgorithm.SHA256WithRSA;

// The subject as one string, or attribute by attribute with AddToSubject(SubjectType.CN, "...").
generator.Subject = "CN=John Smith, O=Example Ltd, C=RO, E=john@example.com";

// What the certificate can be used for.
generator.Extensions.AddKeyUsage(CertificateKeyUsage.DigitalSignature);
generator.Extensions.AddKeyUsage(CertificateKeyUsage.NonRepudiation);
generator.Extensions.AddEnhancedKeyUsage(CertificateEnhancedKeyUsage.DocumentSigning);

// The PFX file: the certificate and the private key, protected by the password.
byte[] pfx = generator.GenerateCertificate("123456", false);

File.WriteAllBytes("john.pfx", pfx);

// The public part, to give to the people who verify the signatures.
X509Certificate2 certificate = new X509Certificate2(pfx, "123456");
File.WriteAllBytes("john.cer", certificate.RawData);

The second parameter of GenerateCertificate(password, isRootCertificate) is false for an end-entity certificate and true for a CA certificate. When no root certificate is loaded, the certificate is signed with its own key (self-signed).

Settings of the generator

An ECDSA certificate

X509CertificateGenerator generator = new X509CertificateGenerator(LibrarySerialNumber);

generator.KeyAlgorithm = KeyAlgorithm.ECDSA;
generator.EllipticCurve = EllipticCurve.NistP384;
generator.SignatureAlgorithm = SignatureAlgorithm.SHA384WithECDSA;     // the hash; the algorithm follows the key of the issuer
generator.Subject = "CN=ECDSA signer, O=Example Ltd";
generator.Extensions.AddKeyUsage(CertificateKeyUsage.DigitalSignature);

byte[] pfx = generator.GenerateCertificate("123456", false);

The key usages of an ECDSA key are checked against RFC 5480: KeyEncipherment and DataEncipherment are not allowed for these keys.

A root certificate and a certificate that it issues

// 1. The root (CA) certificate.
X509CertificateGenerator root = new X509CertificateGenerator(LibrarySerialNumber);
root.ValidTo = DateTime.Now.AddYears(10);
root.KeySize = KeySize.KeySize4096Bit;
root.Subject = "CN=Example Root CA, O=Example Ltd";
root.Extensions.AddKeyUsage(CertificateKeyUsage.CertificateSigning);
root.Extensions.AddKeyUsage(CertificateKeyUsage.CRLSigning);
root.Extensions.PathLengthConstraint = 0;      // the CA issues only end-entity certificates
byte[] rootPfx = root.GenerateCertificate("rootPassword", true);

// 2. An end-entity certificate issued by the root.
X509CertificateGenerator user = new X509CertificateGenerator(LibrarySerialNumber);
user.LoadRootCertificate(rootPfx, "rootPassword");
user.ValidTo = DateTime.Now.AddYears(2);
user.Subject = "CN=Mary Jones, O=Example Ltd";
user.Extensions.AddKeyUsage(CertificateKeyUsage.DigitalSignature);
user.Extensions.AddKeyUsage(CertificateKeyUsage.NonRepudiation);
user.Extensions.KeyUsageIsCritical = true;
byte[] userPfx = user.GenerateCertificate("userPassword", false);

// The PFX of the user also contains the root certificate: a signature that is created with it can include the chain.
X509Certificate2 userCertificate = new X509Certificate2(userPfx, "userPassword");

To install the root certificate on the computers that must trust the certificates (the Windows store Trusted Root Certification Authorities), distribute its public part (rootCertificate.RawData, a .cer file), never the PFX.

Extensions: revocation addresses, policies, qualified statements

The validators use the addresses in the certificate to check its revocation. A certificate that you issue for a test of the long term validation features needs them (and CRL and OCSP servers that answer at these addresses):

X509CertificateGenerator generator = new X509CertificateGenerator(LibrarySerialNumber);
generator.Subject = "CN=Test signer, O=Example Ltd";
generator.Extensions.AddKeyUsage(CertificateKeyUsage.DigitalSignature);

generator.Extensions.AddCrlDistributionPoint("http://crl.example.com/ca.crl");   // where the CRL is published
generator.Extensions.AddOcspUrl("http://ocsp.example.com");                     // the OCSP responder
generator.Extensions.AddCaIssuersUrl("http://www.example.com/ca.cer");          // where the certificate of the issuer is

// A certificate policy, with optional qualifiers (the address of the CPS and a user notice).
generator.Extensions.AddCertificatePolicy("1.2.3.4.5", "https://www.example.com/cps", "Certificate for tests");

generator.SubjectAlternativeNames = "john@example.com";

For the tests of an eIDAS application, the generator can write the QCStatements extension (ETSI EN 319 412-5), so that the certificate declares itself as qualified, with the private key in a qualified device. Such a certificate is not a qualified certificate (it is not issued by a qualified trust service provider): it exists to test the code that reads these statements (DigitalCertificate.IsQualifiedCertificate).

X509CertificateGenerator generator = new X509CertificateGenerator(LibrarySerialNumber);
generator.AddToSubject(SubjectType.CN, "Test Qualified Signer");
generator.AddToSubject(SubjectType.SERIALNUMBER, "PNORO-1234567890123");
generator.Extensions.AddKeyUsage(CertificateKeyUsage.NonRepudiation);

generator.Extensions.QcStatements = new QualifiedCertificateStatements
{
    QcCompliance = true,                                     // an EU qualified certificate
    QcSscd = true,                                           // the key is in a qualified signature creation device
    QcType = QualifiedCertificateType.ESign,                 // a certificate for electronic signatures
    SemanticsIdentifier = QcSemanticsIdentifier.NaturalPerson,
    RetentionPeriod = 10                                     // years
};
generator.Extensions.QcStatements.AddPdsLocation("https://www.example.com/pds_en.pdf", "en");
generator.Extensions.AddCertificatePolicy("0.4.0.194112.1.2");   // QCP-n-qscd

byte[] pfx = generator.GenerateCertificate("123456", false);

A certificate for a certificate signing request (CSR)

A small internal certification authority issues certificates for the keys that the users generate themselves: the user sends a PKCS#10 request (PEM text) and gets the certificate, without the private key leaving the user.

X509CertificateGenerator ca = new X509CertificateGenerator(LibrarySerialNumber);
ca.LoadRootCertificate(File.ReadAllBytes("root.pfx"), "rootPassword");
ca.ValidTo = DateTime.Now.AddYears(1);
ca.Extensions.AddKeyUsage(CertificateKeyUsage.DigitalSignature);
ca.Extensions.AddKeyUsage(CertificateKeyUsage.NonRepudiation);

string csrPem = File.ReadAllText("request.csr");       // -----BEGIN CERTIFICATE REQUEST----- ...
byte[] certificateDer = ca.GenerateCertificateFromCSR(csrPem);

File.WriteAllBytes("issued.cer", certificateDer);

5.6 Installing certificates in the Windows store

The certificates in the Windows store are used by the programs of the computer, and they are the way to make a certificate trusted (a root certificate) or available to a service (a signing certificate). The Windows tools are certmgr.msc (the current user) and certlm.msc (the local computer); a PFX file is installed by double-clicking it, or with the PowerShell cmdlet Import-PfxCertificate. From code, use the X509Store class of .NET:

// A PFX certificate (with its private key) in the Personal store of the current user.
X509Certificate2 signingCert = new X509Certificate2("cert.pfx", "123456", X509KeyStorageFlags.PersistKeySet);

using (X509Store personal = new X509Store(StoreName.My, StoreLocation.CurrentUser))
{
    personal.Open(OpenFlags.ReadWrite);
    personal.Add(signingCert);
}

// The same for the Local Computer store (needs administrator rights): a service account can then use the certificate.
using (X509Store machine = new X509Store(StoreName.My, StoreLocation.LocalMachine))
{
    machine.Open(OpenFlags.ReadWrite);
    machine.Add(signingCert);
}

// A root certificate (the public part only) in the Trusted Root Certification Authorities store.
// For the current user Windows asks the user to confirm; for the local computer it needs administrator rights.
using (X509Store roots = new X509Store(StoreName.Root, StoreLocation.CurrentUser))
{
    roots.Open(OpenFlags.ReadWrite);
    roots.Add(new X509Certificate2("root.cer"));
}

• The certificates that a smart card or a token publishes appear in the Personal store when its driver is installed and the card is inserted. They are not copied by the library.
• Windows (and the programs that use its trust, such as X509Chain) trusts a certificate when its chain ends in a certificate of the Trusted Root Certification Authorities store. Adobe Acrobat has its own list of trusted certificates (section 6.14).
• Installing a self-signed or a private root certificate on a computer makes all the certificates that it issues trusted by that computer: do it only for a root that you control, and never for a certificate of unknown origin.

6. PDF signatures

The class PdfSignature signs PDF documents. It creates the signatures that Adobe Acrobat and the other PDF readers show in the signature panel: the classic PKCS#7 signature (adbe.pkcs7.detached) and the PAdES signatures of ETSI EN 319 142-1 (ETSI.CAdES.detached), with a time-stamp, with the validation data for the long term (PAdES-B-LT) and with a document time-stamp for archiving (PAdES-B-LTA). The same class reads the signatures of a document and verifies them. Related classes: PdfEncrypt (encryption), PdfMerge and PdfInsertObject (merging and adding text and images).

6.1 How a PDF signature works

A PDF signature is a signature field in the document. The library does not rewrite the document: it appends a new revision to the end of the file (an incremental update) that contains the signature field, its appearance and the signature value. The bytes of the document that existed before are not changed, so the signatures that were already in the document remain valid (PdfSignature.AppendSignature is true by default). The signature value covers the whole file, except the space that holds the signature itself (the /ByteRange).

The steps of the code are always the same: LoadPdfDocument → set the certificate and the options → ApplyDigitalSignature() → the signed document as byte[].

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);

pdfSignature.LoadPdfDocument("source.pdf");               // or a byte[] or a Uri
pdfSignature.DigitalSignatureCertificate = signingCertificate;

byte[] signedPdf = pdfSignature.ApplyDigitalSignature();
File.WriteAllBytes("source[signed].pdf", signedPdf);

6.2 Loading the document

• LoadPdfDocument(string file), LoadPdfDocument(byte[] pdf) and LoadPdfDocument(Uri url) (an HTTP download).
• After the load, pdfSignature.DocumentProperties (PdfDocumentProperties) has the number of pages, the size of the file, the certification level, and the signatures of the document (DigitalSignatures). DocumentPageSize(page) returns the size of a page in points (1 point = 1/72 inch), with the rotation of the page applied.
• A document protected by a password is opened with the password: set DocumentProperties.Password before LoadPdfDocument. A document with an unknown password cannot be signed.
• A PDF file that is damaged can sometimes be rebuilt: PdfSignature.RepairPdf(file) or RepairPdf(bytes) returns the rebuilt document. A repair rewrites the file: do not repair a document that is already signed, its signatures would become invalid.

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);

// The password of an encrypted document: before the document is loaded.
pdfSignature.DocumentProperties.Password = "document password";
pdfSignature.LoadPdfDocument("encrypted.pdf");

PdfDocumentProperties properties = pdfSignature.DocumentProperties;
Console.WriteLine("Pages: " + properties.NumberOfPages + ", size: " + properties.FileSize + " bytes");
Console.WriteLine("Signatures: " + properties.DigitalSignatures.Count + ", certification: " + properties.CertificationLevel);

System.Drawing.Point firstPage = properties.DocumentPageSize(1);     // X = width, Y = height, in points
Console.WriteLine("Page 1: " + firstPage.X + " x " + firstPage.Y);

A document can be loaded from a web address and checked before it is signed, for example to sign only the documents that have no signature yet:

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument(new Uri("https://www.example.com/documents/contract.pdf"));      // an HTTP download

if (pdfSignature.DocumentProperties.DigitalSignatures.Count == 0)
{
    pdfSignature.DigitalSignatureCertificate = signingCertificate;
    File.WriteAllBytes("contract[signed].pdf", pdfSignature.ApplyDigitalSignature());
}
else
{
    Console.WriteLine("The document is already signed " + pdfSignature.DocumentProperties.DigitalSignatures.Count + " time(s).");
}

6.3 Signature formats

The property SignatureStandard (PdfSignatureStandard) selects the format. The default is the classic PKCS#7:

A time-stamp on the signature (B-T) is added with any of the formats when TimeStamping.ServerUrl is set (section 6.8).

The hash algorithm is HashAlgorithm (SignLib.HashAlgorithm: SHA256 by default, SHA384, SHA512, SHA1 for old systems). The algorithm of the signature follows the key of the certificate: RSA (PKCS#1 v1.5) or ECDSA.

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = signingCertificate;

pdfSignature.SignatureStandard = PdfSignatureStandard.Pades;
pdfSignature.HashAlgorithm = SignLib.HashAlgorithm.SHA384;

File.WriteAllBytes("source[pades].pdf", pdfSignature.ApplyDigitalSignature());

6.4 Visible and invisible signatures, position

A signature is visible by default: it has a rectangle on a page with the name of the signer, the date, the reason and the location. To sign without a visible appearance set VisibleSignature = false: the signature is only in the signature panel of the PDF reader.

Position by the corner of the page

SignaturePosition places a rectangle of 100 × 50 points at 50 points from the edges of the page. The default is TopRight; the other values are TopMiddle, TopLeft, BottomRight, BottomMiddle and BottomLeft.

Position by rectangle

SignatureAdvancedPosition (a System.Drawing.Rectangle, write-only) sets the rectangle. The coordinates are in points and the origin is the bottom left corner of the page: X and Y are the position of the bottom left corner of the rectangle, Width and Height its size. It replaces SignaturePosition.

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = signingCertificate;

// 400 x 150 points, 10 points from the left edge and from the bottom edge of the page.
pdfSignature.SignatureAdvancedPosition = new System.Drawing.Rectangle(10, 10, 400, 150);

File.WriteAllBytes("source[signed].pdf", pdfSignature.ApplyDigitalSignature());

The page

// pdfSignature: the PdfSignature object of the previous examples (certificate set, document loaded)
// The appearance on the first page and on the last page.
pdfSignature.SignaturePages = new List<int> { 1, int.MaxValue };

// Or on every page of the document.
pdfSignature.SignatureAppearsOnAllPages = true;

6.5 The appearance of the signature

Text

By default the rectangle shows, on separate lines, the name of the signer (the common name of the certificate), the date and time (yyyy.MM.dd HH:mm), the reason and the location. SignatureText replaces the whole text. SigningReason and SigningLocation are also written in the properties of the signature, where the PDF readers show them (the Reason and the Location of the signature panel).

// pdfSignature: the PdfSignature object of the previous examples (certificate set, document loaded)
pdfSignature.SigningReason = "I approve this document";
pdfSignature.SigningLocation = "Accounting department";

// A custom text (the lines are separated with a new line).
pdfSignature.SignatureText = "Signed by: " + signingCertificate.GetNameInfo(X509NameType.SimpleName, false)
    + Environment.NewLine + "Date: " + DateTime.Now.ToString("dd.MM.yyyy HH:mm");

Font

• FontName selects one of the standard PDF fonts (FontName.Helvetica by default, Courier, Times_Roman and their bold and italic variants). The standard fonts use a Latin (Central European) code page: they have the characters of the Western and Central European languages, and not Greek, Cyrillic, Hebrew, Arabic or Asian characters.
• FontFile is the path of a TrueType font file. The font is embedded in the document, so any script that the font has can be written. When it is set, FontName is not used. A path that does not exist throws FileNotFoundException.
• FontSize sets the size of the text.
• TextDirection (write-only) is TextDirection.Normal (left to right) or TextDirection.RightToLeft, for the Hebrew and Arabic texts.

// pdfSignature: the PdfSignature object of the previous examples (certificate set, document loaded)
// Greek and Cyrillic text, with an embedded TrueType font.
pdfSignature.FontFile = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.Fonts), "arial.ttf");
pdfSignature.FontSize = 11;
pdfSignature.SignatureText = "Υπογράφηκε ψηφιακά" + Environment.NewLine + "Подписано цифровой подписью";

// A right to left text.
pdfSignature.TextDirection = TextDirection.RightToLeft;

Image

SignatureImage (a byte[] with a JPG, PNG, GIF, BMP or TIFF image) adds a graphic to the signature. SignatureImageType says how it is shown:

// pdfSignature: the PdfSignature object of the previous examples (certificate set, document loaded)
pdfSignature.SignatureImage = File.ReadAllBytes("signature_image.jpg");
pdfSignature.SignatureImageType = SignatureImageType.ImageAndText;
pdfSignature.SignatureAdvancedPosition = new System.Drawing.Rectangle(10, 10, 400, 150);

Other properties of the appearance and of the signer

// pdfSignature: the PdfSignature object of the previous examples (certificate set, document loaded)
pdfSignature.SigningApplicationName = "Invoice Portal";
pdfSignature.SigningApplicationVersion = "3.2.1";

An invisible signature

// pdfSignature: the PdfSignature object of the previous examples (certificate set, document loaded)
pdfSignature.VisibleSignature = false;      // no rectangle on the page; the signature panel shows it

6.6 Certification signatures

A certification signature is the first signature of a document, made by the author, that says which changes are allowed after it (the DocMDP permission). The property CertifySignature (CertifyMethod) sets it:

A document has at most one certification signature and it must be the first. The certification level of a loaded document is DocumentProperties.CertificationLevel.

PdfSignature author = new PdfSignature(LibrarySerialNumber);
author.LoadPdfDocument("source.pdf");
author.DigitalSignatureCertificate = signingCertificate;
author.CertifySignature = CertifyMethod.AnnotationsAndFormFilling;
byte[] certified = author.ApplyDigitalSignature();

// A second signer approves the certified document.
PdfSignature approver = new PdfSignature(LibrarySerialNumber);
approver.LoadPdfDocument(certified);
approver.DigitalSignatureCertificate = signingCertificate;
approver.SignaturePosition = SignaturePosition.BottomLeft;
byte[] approved = approver.ApplyDigitalSignature();

6.7 Several signatures and signature fields

• Several signers. Load the signed document in a new PdfSignature and sign again. Each signature is a new revision; the previous ones remain valid. Give each signer another rectangle (SignaturePosition or SignatureAdvancedPosition), or the rectangles overlap.
• An existing signature field. A form can have empty signature fields (created in Acrobat or by AddSignatureField). ApplyDigitalSignature(string fieldName) signs that field: the signature has the position and the size of the field. With ApplyDigitalSignature() a new field is created.
• Signature fields created by code. AddSignatureField(name, page, rectangle) returns the document with an empty signature field (the rectangle has the semantics of SignatureAdvancedPosition). It is used to prepare a contract that is signed later by several people.

// 1. Prepare: a document with two empty signature fields.
PdfSignature prepare = new PdfSignature(LibrarySerialNumber);
prepare.LoadPdfDocument("source.pdf");
byte[] withField1 = prepare.AddSignatureField("Customer", 1, new System.Drawing.Rectangle(50, 100, 200, 60));

prepare = new PdfSignature(LibrarySerialNumber);
prepare.LoadPdfDocument(withField1);
byte[] withFields = prepare.AddSignatureField("Supplier", 1, new System.Drawing.Rectangle(300, 100, 200, 60));

// 2. Later, every signer signs the field with its name.
PdfSignature customer = new PdfSignature(LibrarySerialNumber);
customer.LoadPdfDocument(withFields);
customer.DigitalSignatureCertificate = signingCertificate;
byte[] signedByCustomer = customer.ApplyDigitalSignature("Customer");

PdfSignature supplier = new PdfSignature(LibrarySerialNumber);
supplier.LoadPdfDocument(signedByCustomer);
supplier.DigitalSignatureCertificate = signingCertificate;
byte[] signedByBoth = supplier.ApplyDigitalSignature("Supplier");

6.8 Time-stamps in PDF documents

A time-stamp proves the time. There are two kinds in a PDF document:

• The time-stamp of the signature (inside the signature): set TimeStamping.ServerUrl before ApplyDigitalSignature. The signature has then the level B-T, and PdfSignatureInfo.SignatureIsTimestamped is true.
• A document time-stamp (ETSI.RFC3161), an invisible signature of the time-stamping authority over the whole document: ApplyTimestampSignature(). It is the last element of a PAdES-LTA document, and it can be added alone, or again, to extend the protection of an archived document. It does not need a signing certificate.

// The signature is time-stamped.
PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = signingCertificate;
pdfSignature.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");
File.WriteAllBytes("source[signed-T].pdf", pdfSignature.ApplyDigitalSignature());

// A document time-stamp on the signed document.
PdfSignature stamper = new PdfSignature(LibrarySerialNumber);
stamper.LoadPdfDocument("source[signed-T].pdf");
stamper.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");
File.WriteAllBytes("source[stamped].pdf", stamper.ApplyTimestampSignature());

The settings of the time-stamping server (authentication, policy, hash, time-out) are in section 11. The time-stamp requests use SHA-256 by default.

6.9 PAdES-LT and PAdES-LTA

SignatureStandard = PdfSignatureStandard.PadesLT embeds, in the document security store of the PDF, the certificates of the chain and the revocation information that the library downloads when it signs. PdfSignatureStandard.PadesLTA adds the document time-stamp. The property PadesLtvLevel selects the revocation data:

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = signingCertificate;

pdfSignature.SignatureStandard = PdfSignatureStandard.PadesLTA;       // signature + validation data + document time-stamp
pdfSignature.PadesLtvLevel = PadesLtvLevel.IncludeCrlAndOcsp;
pdfSignature.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");
pdfSignature.TimeStamping.HashAlgorithm = SignLib.HashAlgorithm.SHA256;

File.WriteAllBytes("source[lta].pdf", pdfSignature.ApplyDigitalSignature());

The signing certificate must have a CRL or an OCSP responder for the revocation data to exist; a self-signed certificate has none, and then only the certificate is embedded. How the long term features work and how to renew the time-stamp is in section 12.

6.10 Encryption

Signing and encrypting in one operation

The property PdfSignature.Encryption (PdfEncryptionSettings) encrypts the document while it is signed. The signature is created over the encrypted document, so it stays valid. An encrypted document that is signed again is a problem: the encryption cannot be changed after a signature exists, and a document that is already signed (or certified) cannot be encrypted: it throws CryptographicException. Encrypt first, sign after, or do both together.

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = signingCertificate;

pdfSignature.Encryption.EncryptionMethod = PdfEncryptionMethod.PasswordSecurity;
pdfSignature.Encryption.EncryptionAlgorithm = PdfEncryptionAlgorithm.EnhancedEncryption128BitAES;
pdfSignature.Encryption.UserPassword = "user_passw0rd";        // opens the document
pdfSignature.Encryption.OwnerPassword = "owner_passw0rd";      // all the actions
pdfSignature.Encryption.DocumentRestrictions = PdfDocumentRestrictions.AllowPrinting;

File.WriteAllBytes("source[signed-encrypted].pdf", pdfSignature.ApplyDigitalSignature());

Encrypting a document: PdfEncrypt

PdfEncrypt encrypts a document (without signing it). The settings are the same:

// Passwords.
PdfEncrypt byPassword = new PdfEncrypt();
byPassword.LoadPdfDocument("source.pdf");
byPassword.EncryptionMethod = PdfEncryptionMethod.PasswordSecurity;
byPassword.EncryptionAlgorithm = PdfEncryptionAlgorithm.EnhancedEncryption128BitAES;
byPassword.UserPassword = "user_passw0rd";
byPassword.OwnerPassword = "owner_passw0rd";
byPassword.DocumentRestrictions = PdfDocumentRestrictions.AllowPrinting | PdfDocumentRestrictions.AllowFillingOfFormFields;
File.WriteAllBytes("source[encrypted].pdf", byPassword.EncryptPDFFile());

// A certificate: only the owner of its private key opens the document, without a password.
PdfEncrypt byCertificate = new PdfEncrypt();
byCertificate.LoadPdfDocument("source.pdf");
byCertificate.EncryptionMethod = PdfEncryptionMethod.CertificateSecurity;
byCertificate.EncryptionCertificate = new X509Certificate2(signingCertificate.RawData);   // the public part
File.WriteAllBytes("source[encrypted-cert].pdf", byCertificate.EncryptPDFFile());

6.11 Reading and verifying the signatures

After LoadPdfDocument, DocumentProperties.DigitalSignatures lists the signatures and the document time-stamps, sorted by signing time. Every item is a PdfSignatureInfo:

A complete verification of a document answers more than SignatureIsValid. These checks are a good minimum; the first one is the library, the others are your decision:

1. every signature is intact (SignatureIsValid);
2. the last signature covers the whole file: bytes added after the last signature are not signed, although the signature is still intact (the check reads the /ByteRange of the signatures);
3. the signing certificate was valid at the signing time (the time of the time-stamp when there is one), its chain ends in a root that the application trusts, and it was not revoked;
4. the time-stamps are not altered (TimestampInfo.IsTimestampAltered).

public static class PdfVerifier
{
    // Returns true when the signatures of the document are intact, the last signature covers the whole file,
    // the certificates were valid at the signing time and they are not revoked.
    public static bool Verify(byte[] pdf, string serialNumber)
    {
        PdfSignature pdfSignature = new PdfSignature(serialNumber);
        pdfSignature.LoadPdfDocument(pdf);

        List<PdfSignatureInfo> signatures = pdfSignature.DocumentProperties.DigitalSignatures;
        if (signatures.Count == 0)
            return false;

        long[] coveredEnds = GetSignedByteRangeEnds(pdf);
        bool passed = true;

        for (int index = 0; index < signatures.Count; index++)
        {
            PdfSignatureInfo info = signatures[index];
            Console.WriteLine(info.SignatureName + " (" + info.SignatureType + "), signer: " + info.SignatureCertificate.Subject);

            // 1. The integrity of the signature.
            passed &= info.SignatureIsValid;

            // 2. The last signature must cover the end of the file (a trailing line break is accepted).
            if (index == signatures.Count - 1 && index < coveredEnds.Length && coveredEnds[index] < pdf.Length)
            {
                Console.WriteLine("  Data was added after the last signature.");
                passed = false;
            }

            // 3. The certificate at the signing time.
            DateTime signingTime = info.SignatureTime.ToUniversalTime();
            bool inPeriod = signingTime >= info.SignatureCertificate.NotBefore.ToUniversalTime()
                         && signingTime <= info.SignatureCertificate.NotAfter.ToUniversalTime();
            passed &= inPeriod;

            using (X509Chain chain = new X509Chain())
            {
                chain.ChainPolicy.RevocationMode = X509RevocationMode.NoCheck;
                chain.ChainPolicy.VerificationTime = info.SignatureTime.ToLocalTime();
                bool trusted = chain.Build(info.SignatureCertificate);       // is the root trusted by this computer?
                Console.WriteLine("  Chain to a trusted root: " + trusted);
            }

            // The revocation status now: Valid, Revoked, Unknown (server not available) or NotPresent (no CRL/OCSP).
            // For the status at the signing time, use the validation data of a PAdES-LT document.
            CertificateStatus status = DigitalCertificate.VerifyDigitalCertificate(info.SignatureCertificate, VerificationType.OCSP);
            passed &= status != CertificateStatus.Revoked;

            // 4. The time-stamp of the signature.
            if (info.SignatureIsTimestamped)
                passed &= !info.TimestampInfo.IsTimestampAltered;
        }

        return passed;
    }

    // The end of the bytes covered by each signature: the last range of its /ByteRange (offset + length).
    private static long[] GetSignedByteRangeEnds(byte[] pdf)
    {
        string text = System.Text.Encoding.GetEncoding("ISO-8859-1").GetString(pdf);
        System.Text.RegularExpressions.MatchCollection ranges = System.Text.RegularExpressions.Regex.Matches(text,
            @"/ByteRange\s*\[\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s*\]");

        long[] ends = new long[ranges.Count];
        for (int i = 0; i < ranges.Count; i++)
            ends[i] = long.Parse(ranges[i].Groups[3].Value) + long.Parse(ranges[i].Groups[4].Value);

        if (ends.Length > 0 && pdf.Length - ends[ends.Length - 1] <= 2)
            ends[ends.Length - 1] = pdf.Length;

        return ends;
    }
}

The routine is a base to adapt: the decision about the trust of the root (trusted) and about an unknown revocation status belongs to your application. The sample project PDF Signature Verification is a complete program that also detects the format of the signature (PKCS#7 or PAdES, with a time-stamp, with validation data, with a document time-stamp). For the signatures that must be validated against the EU trusted lists, use the DSS validator (section 14.5).

6.12 Merging, adding texts and images

PdfMerge.MergePdfFiles(List<byte[]>) merges documents (the metadata of the first one is kept). PdfInsertObject adds images (over or under the content, as a stamp or a full-page watermark) and texts to the pages. Do it before the document is signed: a change after the signature invalidates it.

// Merge two documents.
byte[] merged = PdfMerge.MergePdfFiles(new List<byte[]>
{
    File.ReadAllBytes("contract.pdf"),
    File.ReadAllBytes("annex.pdf")
});

// Add a text and a stamp image.
PdfInsertObject insert = new PdfInsertObject();
insert.LoadPdfDocument(merged);

CustomText text = new CustomText();
text.Text = "APPROVED";
text.FontSize = 24;
text.PageNumber = 1;
text.StartingPointPosition = new System.Drawing.Point(100, 700);
insert.AddText(text);

insert.AddImage(File.ReadAllBytes("stamp.png"), new System.Drawing.Point(400, 50), 1, ImagePosition.ImageOverContent);   // page 1; page 0 = all the pages

byte[] stamped = insert.InsertObjects();

The page number 0 of an image means all the pages. An image can also cover the page (AddImage(image, page, position)), for a watermark under the content (ImagePosition.ImageUnderContent). A text can use a TrueType font (CustomText.FontFile), a color (TextColor, an iTextSharp color), an alignment (TextAlign) and a direction (TextDirection).

6.13 Signature policy

A regulation can require an explicit signature policy in the signature. SetSignaturePolicyInformation(oid, policyHash, hashAlgorithmOid, url) adds the signature-policy-identifier attribute to the signatures created by the object; the same method exists in CadesSignature, XadesSignature, OfficeSignature and AsicSignature. policyHash is the hash of the policy document that you published or got from the authority; calling the method with null removes the policy.

// pdfSignature: the PdfSignature object of the previous examples (certificate set, document loaded)
byte[] policyDocument = File.ReadAllBytes("policy.pdf");
byte[] policyHash = SHA256.Create().ComputeHash(policyDocument);

pdfSignature.SignatureStandard = PdfSignatureStandard.Pades;
pdfSignature.SetSignaturePolicyInformation("2.16.76.1.7.1.5.2.3", policyHash, "2.16.840.1.101.3.4.2.1", "http://ca.example.com/policy.pdf");

6.14 PDF readers and validators

• Trust. Adobe Reader shows a signature as valid (a green mark) when the certificate chain ends in a root that Adobe trusts (the Adobe Approved Trust List, or the Windows store when the user enables it), and as validity unknown (a yellow mark) when it does not. Signatures made with a self-signed certificate show “validity unknown” until the user adds the certificate to the trusted identities. This is the validation procedure of the reader, not a defect of the signature.
• The time-stamp is trusted when the certificate of the time-stamping authority is trusted by the reader.
• LTV. A signature is shown as an LTV-enabled signature when the document has the revocation information that is needed to validate it without the network.
• eIDAS. The EU DSS validator (section 14.5) validates the PAdES signatures against the trusted lists of the member states.

7. CAdES and PKCS#7 signatures (.p7m, .p7s)

CadesSignature signs any file or data (a PDF, an image, an archive, an XML file, text) as a CMS / PKCS#7 or CAdES signature. The result is a file with the extension .p7m when it contains the signed document (an attached signature) or .p7s when it contains only the signature (a detached signature). CadesVerify reads and verifies these files. CAdES (ETSI EN 319 122-1) is the format that the eIDAS Regulation uses for the signatures of files of any type.

7.1 Creating a signature

CadesSignature cadesSignature = new CadesSignature(LibrarySerialNumber);

cadesSignature.DigitalSignatureCertificate = signingCertificate;
cadesSignature.HashAlgorithm = SignLib.HashAlgorithm.SHA256;
cadesSignature.SignatureStandard = CadesSignatureStandard.CadesBes;

// A file: the result is the content of the .p7m file (the signed file is inside).
byte[] p7m = cadesSignature.ApplyDigitalSignature("contract.pdf");
File.WriteAllBytes("contract.pdf.p7m", p7m);

// Data in memory.
byte[] data = File.ReadAllBytes("contract.pdf");
byte[] p7mFromData = cadesSignature.ApplyDigitalSignature(data);

The method returns the bytes of the signature; the library writes nothing on the disk. The signature algorithm follows the key of the certificate (RSA, or ECDSA; for ECDSA certificates the signature value is converted to the DER form that CMS requires).

7.2 The levels of CAdES

The enumeration CadesSignatureStandard contains the formats that the older and the newer specifications define:

CAdES-EPES (explicit policy) is a CadesBes signature with a policy set by SetSignaturePolicyInformation. The validation data is collected from the addresses in the certificates; for a certificate without a CRL and an OCSP responder (a self-signed certificate) only the certificate is embedded. The idea of the levels and the renewal of the archive time-stamp are in section 12.

// The same file, signed with every level (the levels with a time-stamp need the server).
CadesSignatureStandard[] levels =
{
    CadesSignatureStandard.Cms, CadesSignatureStandard.CadesBes, CadesSignatureStandard.CadesC,
    CadesSignatureStandard.CadesXL, CadesSignatureStandard.CadesLT, CadesSignatureStandard.CadesA
};

foreach (CadesSignatureStandard level in levels)
{
    CadesSignature cadesSignature = new CadesSignature(LibrarySerialNumber);
    cadesSignature.DigitalSignatureCertificate = signingCertificate;
    cadesSignature.SignatureStandard = level;
    cadesSignature.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");

    File.WriteAllBytes("test.txt[" + level + "].p7m", cadesSignature.ApplyDigitalSignature("test.txt"));
}

7.3 Detached signatures (.p7s)

With IsDetachedSignature = true the result is only the signature. The signed file is not changed, and it is needed to verify the signature. This is the convenient form for large files or when the original must stay untouched; the attached form (.p7m) is one file that cannot lose its document.

CadesSignature cadesSignature = new CadesSignature(LibrarySerialNumber);
cadesSignature.DigitalSignatureCertificate = signingCertificate;
cadesSignature.IsDetachedSignature = true;

File.WriteAllBytes("contract.pdf.p7s", cadesSignature.ApplyDigitalSignature("contract.pdf"));

7.4 Co-signatures

When the data that you give to ApplyDigitalSignature is itself a CMS signature (a .p7m file), the library adds a new signature to it, instead of signing the signature again: the result is one file with all the signers, and the existing signatures stay valid. Call it once for every co-signer, with the certificate of that signer.

// The first signer.
CadesSignature first = new CadesSignature(LibrarySerialNumber);
first.DigitalSignatureCertificate = signingCertificate;
byte[] signed = first.ApplyDigitalSignature("contract.pdf");

// The second and the third signer add their signatures to the same file.
X509Certificate2 secondCertificate = DigitalCertificate.LoadCertificate("second.pfx", "123456");
X509Certificate2 thirdCertificate = DigitalCertificate.LoadCertificate("third.pfx", "123456");

foreach (X509Certificate2 coSigner in new[] { secondCertificate, thirdCertificate })
{
    CadesSignature next = new CadesSignature(LibrarySerialNumber);
    next.DigitalSignatureCertificate = coSigner;
    signed = next.ApplyDigitalSignature(signed);
}

File.WriteAllBytes("contract.pdf.p7m", signed);

7.5 Verifying a signature

The constructor of CadesVerify reads and verifies the signature; the object then has the result. A signature can be in binary (DER) form or in Base64 text, with or without the -----BEGIN ...----- lines.

CadesVerify cadesVerify = new CadesVerify("contract.pdf.p7m", LibrarySerialNumber);

Console.WriteLine("Format: " + cadesVerify.SignatureStandard + ", signers: " + cadesVerify.Signatures.Count);

foreach (CadesSignatureInfo signer in cadesVerify.Signatures)
{
    string name = signer.SignatureCertificate != null
        ? signer.SignatureCertificate.GetNameInfo(X509NameType.SimpleName, false)
        : "(the certificate is not in the signature)";

    Console.WriteLine(name + ", hash " + signer.HashAlgorithm.FriendlyName + ", intact: " + signer.SignatureIsValid
        + (signer.SignatureIsTimestamped ? ", time-stamped " + signer.TimestampInfo.SignatureTime.ToLocalTime() : string.Empty));
}

// Extract the signed document.
File.WriteAllBytes(cadesVerify.DocumentName ?? "document", cadesVerify.UnsignedDocument);

// A detached signature: the document is a parameter.
CadesVerify detached = new CadesVerify(File.ReadAllBytes("contract.pdf.p7s"), File.ReadAllBytes("contract.pdf"), LibrarySerialNumber);
bool allIntact = detached.Signatures.All(s => s.SignatureIsValid);

• A file that is not a CMS signature throws CryptographicException (Invalid or corrupt CAdES/PKCS#7 signed data.); a missing file, FileNotFoundException.
• The certificate check (the period of validity, the revocation, the trust) is your decision, section 4.5. Use the time of the time-stamp when the signature has one.
• In the demo version every CadesVerify constructor waits 10 seconds (section 2.4).

7.6 Signature policy

A policy that a regulation requires is added with SetSignaturePolicyInformation. The OID of the policy, the hash of the policy document and the hash algorithm (as an OID) are written in the signed attributes; the URL of the document is optional.

byte[] policyHash = SHA256.Create().ComputeHash(File.ReadAllBytes("policy.pdf"));

CadesSignature cadesSignature = new CadesSignature(LibrarySerialNumber);
cadesSignature.DigitalSignatureCertificate = signingCertificate;
cadesSignature.SetSignaturePolicyInformation("2.16.76.1.7.1.5.2.3", policyHash, "2.16.840.1.101.3.4.2.1", "http://ca.example.com/policy.pdf");

byte[] p7m = cadesSignature.ApplyDigitalSignature("contract.pdf");

7.7 Notes

• Time-stamps and the TSA. A signature with TimeStamping.ServerUrl contains the time-stamp token (signature-time-stamp) of the signature value. For the long term levels the time-stamp of the archive protects the validation data (section 12).
• ECDSA. RSA and ECDSA certificates are supported. A PKCS#11 token or an HSM that returns the raw signature value of ECDSA (r || s) is supported: the library converts it (section 13.4).
• Interoperability. The signatures can be validated with the EU DSS validator (section 14.5). Programs that expect .p7m files that contain a signed PDF, such as the Italian verification tools, open the attached signatures; a detached time-stamp is saved as .tsr or .tsd for them (section 11.2).
• Batch signing. One CadesSignature object can sign many files in a loop; see section 15.2 and section 15.3.

8. XML signatures: XMLDSig and XAdES

Two classes sign XML:

• XmlSignature creates XMLDSig signatures (W3C XML Signature), enveloped in the XML document, with RSA or ECDSA keys.
• XadesSignature creates XAdES signatures (ETSI EN 319 132-1): XMLDSig with signed properties (the signing time, the signing certificate) and the baseline levels B-B, B-T, B-LT and B-LTA. The signature can be enveloped in an XML document or detached, in a separate XML file, for a file of any type.

Both classes use the same technique for the signatures, which allows several signatures in the same document, and the same methods to read and verify them.

8.1 XMLDSig: sign and verify

XmlSignature xmlSignature = new XmlSignature(LibrarySerialNumber);

xmlSignature.DigitalSignatureCertificate = signingCertificate;
xmlSignature.HashAlgorithm = SignLib.HashAlgorithm.SHA256;

// The signed document: the signature element is added inside it.
xmlSignature.ApplyDigitalSignature("test.xml", "test[signed].xml");

// Verification.
Console.WriteLine("Signatures: " + xmlSignature.GetNumberOfSignatures("test[signed].xml"));
Console.WriteLine("Algorithm: " + xmlSignature.GetSignatureAlgorithm("test[signed].xml"));   // for example RSA-SHA256
Console.WriteLine("All valid: " + xmlSignature.VerifyDigitalSignature("test[signed].xml"));

The result is an XML document with a Signature element (shortened):

<Signature Id="Signature-c5ebc05f5292a6e2" xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
    <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
    <Reference URI="">
      <Transforms>
        <Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
          <XPath xmlns:ds="http://www.w3.org/2000/09/xmldsig#">not(ancestor-or-self::ds:Signature)</XPath>
        </Transform>
        <Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
      </Transforms>
      <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
      <DigestValue>ljCeDlHjth920eC4V7sbhf2ohGqrtkDXa4oQ/1ZerMs=</DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>eqfjZXq9igQEaxqs...</SignatureValue>
  <KeyInfo>
    <KeyValue><RSAKeyValue><Modulus>la21u9LP...</Modulus><Exponent>AQAB</Exponent></RSAKeyValue></KeyValue>
    <X509Data><X509Certificate>MIIDZTCCAk2gAwIB...</X509Certificate></X509Data>
  </KeyInfo>
</Signature>

The signature references the whole document (URI="") with an XPath transform that removes all the Signature elements, instead of the usual enveloped-signature transform that removes only the signature that contains it. This is the standard construction for parallel signatures: a signature that is added later is not part of the digest of the first one, so every signature stays valid.

Several signatures, reading and verifying

• To add a signature, sign again the signed document (the input and the output can be the same file). The existing signatures are not changed.
• If a signature that was created by another program with the enveloped-signature transform exists in the document, a new signature would invalidate it: the library refuses (CryptographicException, A new signature cannot be added because it would invalidate an existing XML signature).
• VerifyDigitalSignature(file) verifies all the signatures and returns true when they are all valid. VerifyDigitalSignature(file, index) verifies one (the indexes are 0-based, in the order of the document). VerifyDigitalSignature(file, certificate) is true when a valid signature of the document was created with that certificate: use it to check that the expected person signed.
• GetDigitalSignatureCertificate(file, index) returns the certificate of a signature.
• A document without signatures throws CryptographicException (No digital signature was found in the document).
• All the methods have Stream overloads, for web applications.

XmlSignature xmlSignature = new XmlSignature(LibrarySerialNumber);

// Add a second signer to the document that is already signed.
X509Certificate2 secondSigner = DigitalCertificate.LoadCertificate("second.pfx", "123456");
xmlSignature.DigitalSignatureCertificate = secondSigner;
xmlSignature.ApplyDigitalSignature("test[signed].xml", "test[signed].xml");

int count = xmlSignature.GetNumberOfSignatures("test[signed].xml");

for (int index = 0; index < count; index++)
{
    X509Certificate2 signer = xmlSignature.GetDigitalSignatureCertificate("test[signed].xml", index);
    Console.WriteLine(index + ": " + signer.GetNameInfo(X509NameType.SimpleName, false)
        + ", valid: " + xmlSignature.VerifyDigitalSignature("test[signed].xml", index));
}

// Was the document signed by the expected certificate?
bool signedBySecond = xmlSignature.VerifyDigitalSignature("test[signed].xml", secondSigner);

// In memory (a web application).
using (MemoryStream input = new MemoryStream(File.ReadAllBytes("test.xml")))
using (MemoryStream output = new MemoryStream())
{
    xmlSignature.DigitalSignatureCertificate = signingCertificate;
    xmlSignature.ApplyDigitalSignature(input, output);
    byte[] signedXml = output.ToArray();
}

8.2 XAdES

XadesSignature follows the same pattern as XmlSignature, with the properties of the ETSI standard:

XadesSignature xadesSignature = new XadesSignature(LibrarySerialNumber);

xadesSignature.DigitalSignatureCertificate = signingCertificate;
xadesSignature.SignatureStandard = XadesSignatureStandard.XadesB;
xadesSignature.SignaturePackaging = XadesSignaturePackaging.Enveloped;
xadesSignature.CommitmentType = XadesCommitmentType.ProofOfApproval;
xadesSignature.SignatureProductionPlace = new XadesProductionPlace { City = "Bucharest", CountryName = "RO" };

xadesSignature.ApplyDigitalSignature("test.xml", "test[xades].xml");
Console.WriteLine("Valid: " + xadesSignature.VerifyDigitalSignature("test[xades].xml"));

A time-stamp and the long term levels

XadesSignature xadesSignature = new XadesSignature(LibrarySerialNumber);
xadesSignature.DigitalSignatureCertificate = signingCertificate;

xadesSignature.SignatureStandard = XadesSignatureStandard.XadesLT;       // XadesT, XadesLT or XadesLTA
xadesSignature.LtvLevel = XadesLtvLevel.IncludeCrlAndOcsp;
xadesSignature.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");

xadesSignature.ApplyDigitalSignature("test.xml", "test[xades-lt].xml");

Detached signatures

The signature is saved in an XML file and the signed file is not changed. The signature file must be a different file from the signed one. To verify, give both the signature and the original file (the original can have been renamed: with a single signed file the data is matched whatever its name; its integrity is guaranteed by the digest of the reference).

XadesSignature xadesSignature = new XadesSignature(LibrarySerialNumber);
xadesSignature.DigitalSignatureCertificate = signingCertificate;
xadesSignature.SignaturePackaging = XadesSignaturePackaging.Detached;

xadesSignature.ApplyDigitalSignature("contract.pdf", "contract.pdf[signature].xml");

bool valid = xadesSignature.VerifyDigitalSignature("contract.pdf[signature].xml", "contract.pdf");
X509Certificate2 signer = xadesSignature.GetDigitalSignatureCertificate("contract.pdf[signature].xml");

Several signers of the same file create separate signature files. To put several signed files and their signatures in one file, use an ASiC-E container (section 10).

Verifying XAdES signatures

VerifyDigitalSignature, GetNumberOfSignatures, GetDigitalSignatureCertificate and GetSignatureAlgorithm work as for XmlSignature. The verification checks the digest of the signed data, the digest of the signed properties and the signature value, and that the signing certificate of the signed properties is the certificate of the signature. The method verifies the signature; it does not validate the time-stamp tokens, the revocation data or the trust of the certificates of the higher levels: that is a decision of your application, or of a validator (section 14.5).

8.3 ECDSA

RSA and ECDSA certificates are supported for XMLDSig and XAdES. The signature value of ECDSA in XML is the raw concatenation r || s (RFC 4051), different from the DER form of CMS; the library produces the right form for every format. The ECDSA signature methods of RFC 6931 are registered when the runtime does not have them.

8.4 Notes

• Encoding. The signed document is saved in the encoding that its XML declaration declares (UTF-8 without a byte order mark when no encoding is declared). Do not re-save the signed document with another encoding.
• Only XML. Enveloped signatures need an XML document. For other files use the detached XAdES signature, the CAdES signature (section 7) or an ASiC-E container.
• Interoperability. The XAdES signatures follow the baseline profiles of ETSI EN 319 132-1 and are validated by the EU DSS validator (section 14.5).
• Demo version. Every signing and verification call waits 10 seconds (section 2.4).

9. Office documents

OfficeSignature signs Office Open XML documents: Word (.docx, .docm), Excel (.xlsx, .xlsm) and PowerPoint (.pptx, .pptm). It creates the package signatures that Microsoft Office 2010 and later create and verify (File > Info > Protect Document > Add a Digital Signature): a XAdES signature in the part /_xmlsignatures/sigN.xml of the package. Office, and the library, show the signatures in the same way. The signature can be invisible, or visible in a Word document, as a signature line.

The library does not need Office installed. The documents are processed as Open Packaging Conventions packages (System.IO.Packaging).

9.1 Signing a document

OfficeSignature officeSignature = new OfficeSignature(LibrarySerialNumber);

officeSignature.DigitalSignatureCertificate = signingCertificate;
officeSignature.SignatureComments = "I approve this document";        // "Purpose for signing this document" in Office

officeSignature.ApplyDigitalSignature("contract.docx", "contract[signed].docx");   // the output can be the input file

Console.WriteLine("Signatures: " + officeSignature.GetNumberOfSignatures("contract[signed].docx"));
Console.WriteLine("Valid: " + officeSignature.VerifyDigitalSignature("contract[signed].docx"));

The signed parts of the package are the main part and all the parts that it uses, with their relationships. A document with signatures cannot be changed: any change invalidates them. A second signature does not invalidate the first.

// Several signers: the document is signed again; the previous signatures stay valid.
OfficeSignature secondSigner = new OfficeSignature(LibrarySerialNumber);
secondSigner.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate("second.pfx", "123456");
secondSigner.SignerRole = "Reviewer";
secondSigner.CommitmentType = XadesCommitmentType.ProofOfApproval;
secondSigner.ApplyDigitalSignature("contract[signed].docx", "contract[signed].docx");

A time-stamp and validation data

OfficeSignature officeSignature = new OfficeSignature(LibrarySerialNumber);
officeSignature.DigitalSignatureCertificate = signingCertificate;

officeSignature.SignatureStandard = XadesSignatureStandard.XadesLT;       // XadesT: the time-stamp only
officeSignature.LtvLevel = XadesLtvLevel.IncludeCrlAndOcsp;
officeSignature.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");

officeSignature.ApplyDigitalSignature("report.xlsx", "report[signed-lt].xlsx");

In memory

The byte array and the stream overloads avoid the files. A stream is signed in place: the signed document replaces its content, so the stream must be readable, writable, seekable and expandable: a MemoryStream created from a byte array has a fixed size, create an empty one and write the document in it.

OfficeSignature officeSignature = new OfficeSignature(LibrarySerialNumber);
officeSignature.DigitalSignatureCertificate = signingCertificate;

// A byte array.
byte[] signedArray = officeSignature.ApplyDigitalSignature(File.ReadAllBytes("contract.docx"));

// A stream (in place).
using (MemoryStream stream = new MemoryStream())
{
    byte[] unsigned = File.ReadAllBytes("contract.docx");
    stream.Write(unsigned, 0, unsigned.Length);
    stream.Position = 0;

    officeSignature.ApplyDigitalSignature(stream);
    File.WriteAllBytes("contract[signed].docx", stream.ToArray());
}

9.2 Visible signatures: signature lines (Word, Windows)

A signature line is the place in a Word document where a person signs: a rectangle with a line, the name and the title of the signer. When the document is signed, Word shows the signature on the line and marks it as invalid if the document is changed. OfficeSignatureLine describes it, and the property OfficeSignature.SignatureLine makes the signature visible. Signature lines work for Word documents only (.docx, .docm) and on Windows (the images are drawn with System.Drawing; PlatformNotSupportedException on the other systems); a visible signature on a workbook or a presentation throws NotSupportedException.

OfficeSignature officeSignature = new OfficeSignature(LibrarySerialNumber);
officeSignature.DigitalSignatureCertificate = signingCertificate;

officeSignature.SignatureLine = new OfficeSignatureLine
{
    Placement = OfficeSignatureLinePlacement.UseExistingOrAddNew,
    SuggestedSigner = "John Smith",
    SuggestedSignerTitle = "Accounting manager",
    SigningInstructions = "Sign only after the verification of the document.",
    SignatureText = "John Smith",
    SignatureImage = File.ReadAllBytes("signature_image.jpg"),
    ShowSignDate = true
};

officeSignature.ApplyDigitalSignature("contract.docx", "contract[signed].docx");

A document for several signers

Add the signature lines of all the signers before the first signature (a signed document cannot be changed: InvalidOperationException), then every signer signs the line with the identifier that was returned. The lines can also be created in Word (Insert > Signature Line).

OfficeSignature prepare = new OfficeSignature(LibrarySerialNumber);

string managerLine = prepare.AddSignatureLine("contract.docx", "contract[lines].docx", new OfficeSignatureLine
{
    SuggestedSigner = "John Smith", SuggestedSignerTitle = "Manager"
});
string accountantLine = prepare.AddSignatureLine("contract[lines].docx", "contract[lines].docx", new OfficeSignatureLine
{
    SuggestedSigner = "Mary Jones", SuggestedSignerTitle = "Accountant", Alignment = OfficeSignatureLineAlignment.Right
});

foreach (OfficeSignatureLineInfo line in prepare.GetSignatureLines("contract[lines].docx"))
    Console.WriteLine(line.SetupId + ": " + line.SuggestedSigner + ", signed: " + line.IsSigned);

// Every signer signs his line.
OfficeSignature manager = new OfficeSignature(LibrarySerialNumber);
manager.DigitalSignatureCertificate = signingCertificate;
manager.SignatureLine = new OfficeSignatureLine { Placement = OfficeSignatureLinePlacement.UseExisting, SetupId = managerLine, ShowSignDate = true };
manager.ApplyDigitalSignature("contract[lines].docx", "contract[lines].docx");

OfficeSignature accountant = new OfficeSignature(LibrarySerialNumber);
accountant.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate("accountant.pfx", "123456");
accountant.SignatureLine = new OfficeSignatureLine { Placement = OfficeSignatureLinePlacement.UseExisting, SetupId = accountantLine };
accountant.ApplyDigitalSignature("contract[lines].docx", "contract[lines].docx");

9.3 Reading and verifying the signatures

OfficeSignatureInfo: Index; Status (Success; ContentModified when the document was changed after it was signed; ReferenceNotFound when a signed part is missing; InvalidSignature); IsValid; Certificate, SignerName; SigningTime (UTC, declared by the signer); HasTimestamp, TimestampTime; HasValidationData (XAdES-LT); SignatureAlgorithm; SignatureComments, CommitmentType, SignerRole; IsVisible and SetupId of the signature line.

OfficeSignature officeSignature = new OfficeSignature(LibrarySerialNumber);

foreach (OfficeSignatureInfo info in officeSignature.GetSignatures("contract[signed].docx"))
{
    Console.WriteLine(info.Index + ": " + info.SignerName + ", " + info.Status + ", " + info.SignatureAlgorithm);

    if (info.SigningTime.HasValue)
        Console.WriteLine("   signed " + info.SigningTime.Value.ToLocalTime() + ", purpose: " + info.SignatureComments);

    if (info.HasTimestamp)
        Console.WriteLine("   time-stamp " + info.TimestampTime.Value.ToLocalTime() + ", validation data: " + info.HasValidationData);
}

9.4 Notes

• Macro-enabled documents (.docm, .xlsm, .pptm) are signed as the other documents.
• External keys. An external signature provider (a PKCS#11 token, an HSM, a key vault) is used as for the other classes, by setting DigitalCertificate.UseExternalSignatureProvider before the signing call (section 13).
• Only the Office Open XML formats are signed. The binary formats of Office 2003 and earlier (.doc, .xls, .ppt) are not packages and they are not supported.
• XPS documents cannot be signed by this version of the library.
• Packages and drawing. A project that signs Office documents needs the references of section 2.2 (System.IO.Packaging and System.Drawing.Common on .NET; WindowsBase and System.Drawing on .NET Framework).

10. ASiC-E containers

An ASiC-E container (Associated Signature Container, Extended; ETSI EN 319 162-1) is a single ZIP file (.asice) that holds any number of files, of any type, and their XAdES signatures. It is the container that the eIDAS regulation recommends and that many e-government systems use for e-invoicing, e-procurement, e-tax and court filings. AsicSignature creates the containers, adds signatures (co-signatures), verifies them, reads their contents and renews their time-stamps. Every signature covers all the files of the container.

10.1 Creating a container

CreateContainer signs the files and writes the container in one operation. The files are stored under their names; with the dictionary overload the name is the path inside the container (for example annexes/annex1.pdf), and no file touches the disk.

AsicSignature asicSignature = new AsicSignature(LibrarySerialNumber);
asicSignature.DigitalSignatureCertificate = signingCertificate;

// From files: the container is written to the output path (and deleted when the signature fails).
asicSignature.CreateContainer(new[] { "contract.pdf", "data.xml" }, "documents.asice");

// From memory: the names are the paths in the container.
IDictionary<string, byte[]> files = new Dictionary<string, byte[]>
{
    { "contract.pdf", File.ReadAllBytes("contract.pdf") },
    { "annexes/annex1.pdf", File.ReadAllBytes("annex1.pdf") }
};
byte[] container = asicSignature.CreateContainer(files);
File.WriteAllBytes("documents[memory].asice", container);

The names must be safe relative paths: no absolute path, no .., no backslash, no META-INF or mimetype, and unique (ArgumentException otherwise). A file that does not exist throws FileNotFoundException.

AsicSignature asicSignature = new AsicSignature(LibrarySerialNumber);
asicSignature.DigitalSignatureCertificate = signingCertificate;

asicSignature.SignatureStandard = XadesSignatureStandard.XadesLT;
asicSignature.LtvLevel = XadesLtvLevel.IncludeCrlAndOcsp;
asicSignature.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");
asicSignature.HashAlgorithm = SignLib.HashAlgorithm.SHA384;
asicSignature.CommitmentType = XadesCommitmentType.ProofOfApproval;
asicSignature.SignatureProductionPlace = new XadesProductionPlace { City = "Bucharest", CountryName = "RO" };

asicSignature.CreateContainer(new[] { "contract.pdf", "data.xml" }, "documents[lt].asice");

10.2 Co-signatures

AddSignature adds a signature of another signer. The new signature covers all the files and goes to a new signature file; the existing signatures are not changed. Set the certificate of the new signer on the object first.

AsicSignature secondSigner = new AsicSignature(LibrarySerialNumber);
secondSigner.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate("second.pfx", "123456");

// Files (the output can be the input container).
secondSigner.AddSignature("documents.asice", "documents[cosigned].asice");

// In memory.
byte[] cosigned = secondSigner.AddSignature(File.ReadAllBytes("documents.asice"));

10.3 Reading and verifying a container

The container is a path or a byte[] in all the methods.

AsicSignature asicSignature = new AsicSignature(LibrarySerialNumber);

int signatures = asicSignature.GetNumberOfSignatures("documents[cosigned].asice");
for (int index = 0; index < signatures; index++)
    Console.WriteLine("Signer " + index + ": " + asicSignature.GetDigitalSignatureCertificate("documents[cosigned].asice", index).Subject);

foreach (string name in asicSignature.GetDataFileNames("documents[cosigned].asice"))
    Console.WriteLine("File: " + name);

byte[] contract = asicSignature.ExtractDataFile("documents[cosigned].asice", "contract.pdf");
File.WriteAllBytes("extracted contract.pdf", contract);

Console.WriteLine("Valid: " + asicSignature.VerifyDigitalSignature("documents[cosigned].asice"));

The method verifies the integrity of the signatures and the coverage of the files; it does not decide that the signers can be trusted (section 4.5). A container that has signature files that are not XAdES (for example CAdES *.p7s files) is not verified by this class.

10.4 Renewing the archive time-stamp

An XadesLTA container is protected for the long term by an archive time-stamp. AddArchiveTimestamp adds a new archive time-stamp to every XAdES-LTA signature of the container, with the validation data that is needed to validate the previous time-stamps. Call it before the certificate of the time-stamping authority of the last time-stamp expires (section 12.4). It needs TimeStamping.ServerUrl and it does not need the certificate of the signers.

AsicSignature asicSignature = new AsicSignature(LibrarySerialNumber);

asicSignature.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");
asicSignature.LtvLevel = XadesLtvLevel.IncludeCrlAndOcsp;

asicSignature.AddArchiveTimestamp("documents[lta].asice", "documents[lta-renewed].asice");

10.5 Notes

• The container is created in memory. The size limit of the ZIP writer is 4 GB and 65535 entries (no ZIP64).
• An external signature provider (PKCS#11, HSM, remote service) is used as for the other classes: set DigitalCertificate.UseExternalSignatureProvider before the signing call (section 13).
• The container is a ZIP file written by the library: a .NET Framework project needs the reference System.IO.Compression (section 2.3); no extra package is needed on .NET.

11. Time-stamps

A time-stamp (RFC 3161) is a proof, signed by a time-stamping authority (TSA), that some data existed at a given time. The application sends the hash of the data to the TSA server (the data itself is never sent) and receives a signed time-stamp token. The library uses time-stamps in two ways:

• inside the signatures: PDF, CAdES, XAdES, Office and ASiC-E signatures with the level T and above get a time-stamp when you set TimeStamping.ServerUrl on the signature object (section 11.1);
• of a file: TimestampClient time-stamps any file or data and saves the result as a .tsr, .tst or .tsd file (section 11.2).

11.1 Time-stamping settings

Every signature class has a property TimeStamping (TimestampSettings), and TimestampClient has one too. When the signature classes find ServerUrl set, they time-stamp the signature; when it is null (the default), they do not use the network for the time.

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = signingCertificate;

pdfSignature.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");
pdfSignature.TimeStamping.HashAlgorithm = SignLib.HashAlgorithm.SHA256;
pdfSignature.TimeStamping.ServerTimeout = 30000;

// A server with authentication.
pdfSignature.TimeStamping.UserName = "account";
pdfSignature.TimeStamping.Password = "secret";

// Or a server that requires a TLS client certificate.
pdfSignature.TimeStamping.AuthenticationCertificate = DigitalCertificate.LoadCertificate("tsa-client.pfx", "123456");

// A policy that the server requires.
pdfSignature.TimeStamping.PolicyOid = new System.Security.Cryptography.Oid("1.3.6.1.4.1.13762.3");

File.WriteAllBytes("source[signed-T].pdf", pdfSignature.ApplyDigitalSignature());

• An unreachable server, a server that refuses the request or an invalid response throw WebException (Invalid time stamping response. with the status and the reason). The signature is not created without the time-stamp when one is requested.
• The address https://ca.signfiles.com/TSAServer.aspx is a free server for tests and for the samples of the library. For production use a time-stamping service that you choose and that has the service level that you need: a qualified time-stamping service for the eIDAS qualified signatures.
• The time-stamp requests of the library are sent with the platform HTTP client (section 4.10); the time-out of the certificate and revocation downloads is another setting (DigitalCertificate.Timeout).
• In the demo version every time-stamp operation waits 10 seconds.

11.2 Time-stamping a file: TimestampClient

TimestampClient returns the time-stamp of a file or of data. The property TimestampFormat chooses the format of the result:

TimestampClient timestampClient = new TimestampClient(LibrarySerialNumber);
timestampClient.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");

// A .tsr file.
timestampClient.TimestampFormat = TimestampFormat.DetachedTimestamp;
File.WriteAllBytes("contract.pdf.tsr", timestampClient.ObtainTimestamp("contract.pdf"));

// A .tsd file: the file and its time-stamp.
timestampClient.TimestampFormat = TimestampFormat.EmbeddedTimestamp;
File.WriteAllBytes("contract.pdf.tsd", timestampClient.ObtainTimestamp("contract.pdf"));

// Data in memory.
byte[] timestamp = timestampClient.ObtainTimestamp(File.ReadAllBytes("contract.pdf"));

A time-stamped file proves that the file existed at the time of the time-stamp. The time-stamp of a file is not a signature of a person: it does not say who created the file.

11.3 Reading and verifying a time-stamp

TimestampInfo.GetInfoFromTsaResponse(bytes) reads a .tsr, .tst or .tsd file. TimestampInfo.IsTsaReponseFileValid(originalFile, timestamp) verifies it against the original file and throws an exception when the file was changed or the time-stamp was altered; it returns true otherwise. The same TimestampInfo is the property TimestampInfo of the signatures that have a time-stamp (PdfSignatureInfo, CadesSignatureInfo).

byte[] timestampFile = File.ReadAllBytes("contract.pdf.tsr");

TimestampInfo info = TimestampInfo.GetInfoFromTsaResponse(timestampFile);
Console.WriteLine("Time: " + info.SignatureTime.ToLocalTime());
Console.WriteLine("Authority: " + info.TsaCertificate.Subject + ", hash " + info.HashAlgorithm.FriendlyName);
Console.WriteLine("Altered: " + info.IsTimestampAltered + ", qualified: " + info.IsQualifiedTimestamp);

try
{
    TimestampInfo.IsTsaReponseFileValid(File.ReadAllBytes("contract.pdf"), timestampFile);
    Console.WriteLine("The time-stamp matches the file.");
}
catch (Exception ex)
{
    Console.WriteLine("The verification failed: " + ex.Message);       // the file or the time-stamp was changed
}

The checks above verify the time-stamp token and its link with the data. As for the signatures, the decision that the time-stamping authority can be trusted is yours: check that the certificate of the authority was valid at the time of the time-stamp, that its chain ends in a root that you trust (or in the EU trusted list for qualified time-stamps), and its revocation status (section 5.4).

11.4 Time-stamps of the signatures

How the time-stamps make a signature last, and how to renew them, is in section 12.

12. Long term validation and archiving

A signature has to be validated when it is read, maybe years after it was made, and by then the certificate of the signer has expired, the certification authority may no longer publish the revocation information, and the algorithms of the time may be weak. The long term levels of the signatures (B-T, B-LT, B-LTA) keep the evidence that is needed to validate the signature as of the time when it was created. This chapter explains what the library embeds in the signatures, how to create the levels in every format, and how to renew the time-stamps of an archive.

12.1 What each level adds

• B-T. The time-stamp proves the signing time. With it, a validator can verify that the certificate was valid at that time, even if it expires later. A time-stamp is required by every long term level.
• B-LT. The certificates of the chain and the revocation information (CRL and OCSP responses) are embedded. A validator does not have to download them, and they exist when the servers are gone.
• B-LTA. An archive time-stamp over the signature and its validation data protects them against the weakening of the algorithms and against the expiry of the certificates of the validation data. It is renewed from time to time with a new time-stamp, over the previous ones.

12.2 Creating the levels

In every case TimeStamping.ServerUrl must be set for T, LT and LTA (section 11.1). Examples: section 6.9 (PDF), section 7.2 (CAdES), section 8.2 (XAdES), section 10.1 (ASiC-E), section 9.1 (Office).

12.3 The validation data

When it signs at the LT or LTA level, the library collects the revocation information from the addresses that are written in the certificates (the CRL distribution points and the Authority Information Access extension, for the CRLs, the OCSP responders and the certificates of the issuers). It embeds the data of the whole chain of the signing certificate and of the time-stamping authority. The selection of the revocation data is the same enumeration, with the same values, in the formats:

• The data that cannot be obtained is skipped: a server that does not answer, a CRL that is larger than MaxCrlSize or that cannot be read. The signature is created anyway, with what could be collected. If the validation data is important, check the result after the signing (see below), and retry later when it is missing.
• A certificate without a CRL address and without an OCSP responder, such as a self-signed certificate or a certificate that you generated without them, has no revocation data: only the certificate is embedded. For the tests of the long term features use a certificate issued by a certification authority that publishes its revocation information.
• The size of the signature grows with the validation data: the CRLs of some certification authorities have megabytes. MaxCrlSize (the property of XadesSignature, OfficeSignature, AsicSignature and CadesSignature) skips the CRLs that are larger than the limit (1 MB; for CAdES 20 MB), and IncludeOcspOnly avoids most of them.
• The downloads use DigitalCertificate.Timeout (section 4.10).

To check that a signed PDF document has the validation data, look for the document security store. For the other formats, read the format that the library detects (CadesVerify.SignatureStandard) or the information of the signature (OfficeSignatureInfo.HasValidationData):

byte[] signedPdf = File.ReadAllBytes("source[lta].pdf");

// The document security store (/DSS) holds the certificates and the revocation data of the PAdES-LT and PAdES-LTA signatures.
bool hasValidationData = Encoding.GetEncoding("ISO-8859-1").GetString(signedPdf).Contains("/DSS");

PdfSignature verifier = new PdfSignature(LibrarySerialNumber);
verifier.LoadPdfDocument(signedPdf);

bool hasDocumentTimestamp = verifier.DocumentProperties.DigitalSignatures.Any(s => s.SignatureType == SignatureType.TimestampSignature);
Console.WriteLine("Validation data: " + hasValidationData + ", document time-stamp: " + hasDocumentTimestamp);

// CAdES: the level that was detected from the attributes of the signature.
CadesVerify cades = new CadesVerify("contract.pdf.p7m", LibrarySerialNumber);
Console.WriteLine("CAdES level: " + cades.SignatureStandard);

12.4 Renewing the time-stamps of an archive

An archive time-stamp is valid while the certificate of the time-stamping authority is valid and while its algorithms are strong. Before one of them ends, a new time-stamp is added over the whole document and over the validation data of the previous time-stamp; the protection continues for another period. The operation is repeated for the whole archiving period. It does not need the certificates or the keys of the signers.

The decision when to renew is the policy of your archive. A usual rule: renew when the certificate of the time-stamping authority of the last time-stamp expires in less than a margin that gives you time to react (a year, for example), or immediately when an algorithm in use is no longer acceptable. A scheduled task reads every archived document, applies the rule and renews the documents that need it:

public static class ArchiveRenewal
{
    private static readonly TimeSpan RenewalMargin = TimeSpan.FromDays(365);

    // True when the certificate of the TSA of the last document time-stamp expires in less than the margin
    // (or the document has no time-stamp).
    public static bool IsRenewalNeeded(byte[] signedPdf, string serialNumber)
    {
        PdfSignature pdfSignature = new PdfSignature(serialNumber);
        pdfSignature.LoadPdfDocument(signedPdf);

        X509Certificate2 lastTsaCertificate = null;
        foreach (PdfSignatureInfo info in pdfSignature.DocumentProperties.DigitalSignatures)
        {
            if (info.SignatureType == SignatureType.TimestampSignature)
                lastTsaCertificate = info.SignatureCertificate;
        }

        return lastTsaCertificate == null || lastTsaCertificate.NotAfter - DateTime.Now < RenewalMargin;
    }

    // Adds a new document time-stamp: no signing certificate is needed.
    public static byte[] Renew(byte[] signedPdf, string serialNumber, Uri timestampServer)
    {
        PdfSignature pdfSignature = new PdfSignature(serialNumber);
        pdfSignature.LoadPdfDocument(signedPdf);
        pdfSignature.TimeStamping.ServerUrl = timestampServer;

        return pdfSignature.ApplyTimestampSignature();
    }
}

The same loop for XAdES and ASiC-E:

Uri timestampServer = new Uri("https://ca.signfiles.com/TSAServer.aspx");

// A XAdES-LTA XML document with an enveloped signature.
XadesSignature xades = new XadesSignature(LibrarySerialNumber);
xades.TimeStamping.ServerUrl = timestampServer;
xades.LtvLevel = XadesLtvLevel.IncludeCrlAndOcsp;
xades.AddArchiveTimestamp("invoice[lta].xml", "invoice[lta-renewed].xml");

// A detached XAdES-LTA signature: the signed file is also needed.
xades.AddArchiveTimestamp("contract.pdf[signature].xml", "contract.pdf[signature-renewed].xml", "contract.pdf");

// An ASiC-E container.
AsicSignature asic = new AsicSignature(LibrarySerialNumber);
asic.TimeStamping.ServerUrl = timestampServer;
asic.LtvLevel = XadesLtvLevel.IncludeCrlAndOcsp;
asic.AddArchiveTimestamp("documents[lta].asice", "documents[lta-renewed].asice");

Before the new archive time-stamp, the library adds the certificates and the current revocation data that are needed to validate the previous time-stamps (xades141:TimeStampValidationData). AddArchiveTimestamp throws when a signature is not valid or when the document has no XAdES-LTA signature, and ArgumentException when the time-stamping server is not set.

The complete sample Timestamp Renewal (section 16) renews the time-stamps of a PDF document, of an ASiC-E container and of an XAdES document.

12.5 Recommendations

• Sign with a time-stamp whenever the signature must be validated later than the validity of the certificate. A B-B signature of a certificate that expires in a year is not validated after that year, unless the validation data was preserved elsewhere.
• Use B-LT or B-LTA for the archives, and a certificate that has a CRL or an OCSP responder, so that there is validation data to embed.
• Check the result after the signing: the validation data is skipped when a server did not answer.
• Plan the renewal when the archive is created: the time (the margin), the owner of the task and the time-stamping service that will be used (a server that may not exist after the validity of its certificate).
• Use SHA-256 or stronger for the signatures and the time-stamps.
• Validate with an independent validator (section 14.5) when the signatures are meant for the eIDAS context.

13. External keys: tokens, HSMs and remote signing

In many deployments the private key cannot be loaded in the process of your application: it is on a smart card or a USB token, in a hardware security module (HSM), in a cloud key vault or in a remote signing service, and it never leaves that device. The library supports these keys with two mechanisms:

• An external signature provider (IExternalSignature): you give the library a small object that signs the data with the key. The library prepares the signature, calls the provider and completes the signature. Used with PdfSignature, CadesSignature, XmlSignature, XadesSignature, OfficeSignature and AsicSignature.
• Two-phase PDF signing (PrepareExternalSignature / FinalizeExternalSignature): the signature is split in two calls, and the signing of the data can happen hours later, in another process, on another computer, with a person. Used when the signer is not available during the call (section 13.5).

13.1 The signature provider

The interface has one method:

public interface IExternalSignature
{
    byte[] ApplySignature(byte[] message, Oid hashAlgorithm);
}

• message is the data to sign. It is not a hash: the provider (or the device) hashes it with the algorithm that it receives, then signs the hash. For the PDF and CAdES signatures it is the DER encoding of the signed attributes of the CMS signature; for the XML signatures (XMLDSig, XAdES, ASiC-E) it is the canonicalized SignedInfo. The document is not sent to the provider: the data contains its hash.
• hashAlgorithm is the OID of the hash algorithm that the library selected (for example 2.16.840.1.101.3.4.2.1 for SHA-256; 1.3.14.3.2.26 SHA-1; ...2.2 SHA-384; ...2.3 SHA-512).
• The return value is the signature value: PKCS#1 v1.5 for an RSA key; for an ECDSA key either the raw value r || s (what most PKCS#11 modules, HSMs and cloud services return) or the DER SEQUENCE { r, s }. The library converts it to the form that the format requires (section 13.4).

The certificate that you give to the signature object needs only the public part. The key stays in the device:

// A provider and the public certificate of the signer.
IExternalSignature provider = new CertificateKeyExternalSignature(signingCertificate);   // see the example below
X509Certificate2 publicCertificate = new X509Certificate2(File.ReadAllBytes("signer.cer"));

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = publicCertificate;        // no private key

// Bind the provider to the NEXT signature of this thread. The library releases it at the end of the operation.
DigitalCertificate.UseExternalSignatureProvider = provider;

File.WriteAllBytes("source[signed].pdf", pdfSignature.ApplyDigitalSignature());

The same property is used with the other classes: set it, then call CadesSignature.ApplyDigitalSignature, XmlSignature.ApplyDigitalSignature, XadesSignature.ApplyDigitalSignature, OfficeSignature.ApplyDigitalSignature, or the methods of AsicSignature that sign.

Rules of the provider

13.2 A provider with a .NET key

The simplest provider uses a key that .NET can use (a key that is not exportable, a CNG key, a key that another process holds). It shows what the method has to do and it is a model for the others:

public class CertificateKeyExternalSignature : IExternalSignature
{
    private readonly X509Certificate2 _certificateWithPrivateKey;

    public CertificateKeyExternalSignature(X509Certificate2 certificateWithPrivateKey)
    {
        _certificateWithPrivateKey = certificateWithPrivateKey;
    }

    public byte[] ApplySignature(byte[] message, Oid hashAlgorithm)
    {
        HashAlgorithmName hash = GetHashAlgorithmName(hashAlgorithm.Value);

        // RSA: PKCS#1 v1.5 over the hash of the message.
        using (RSA rsa = _certificateWithPrivateKey.GetRSAPrivateKey())
        {
            if (rsa != null)
                return rsa.SignData(message, hash, RSASignaturePadding.Pkcs1);
        }

        // ECDSA: the raw value r || s. The library converts it to the form of the signature format.
        using (ECDsa ecdsa = _certificateWithPrivateKey.GetECDsaPrivateKey())
        {
            if (ecdsa != null)
                return ecdsa.SignData(message, hash);
        }

        throw new CryptographicException("The private key of the certificate was not found or its algorithm is not supported.");
    }

    private static HashAlgorithmName GetHashAlgorithmName(string oid)
    {
        switch (oid)
        {
            case "1.3.14.3.2.26": return HashAlgorithmName.SHA1;
            case "2.16.840.1.101.3.4.2.1": return HashAlgorithmName.SHA256;
            case "2.16.840.1.101.3.4.2.2": return HashAlgorithmName.SHA384;
            case "2.16.840.1.101.3.4.2.3": return HashAlgorithmName.SHA512;
            default: throw new NotSupportedException("The hash algorithm " + oid + " is not supported.");
        }
    }
}

13.3 PKCS#11 tokens and HSMs

PKCS#11 (Cryptoki) is the standard programming interface of smart cards, USB tokens and HSMs. Every manufacturer supplies a module (a DLL on Windows, a .so file on Linux) that implements it, and the provider calls the module to sign with the key that stays on the device. This works on any operating system, without the Windows smart card minidriver and without the PIN window of Windows, and it is the way for services and servers.

A 64-bit process needs the 64-bit module and a 32-bit process the 32-bit one. The samples PDF Digital Signature with PKCS11 Smart Card, P7M P7S CAdES Digital Signature with PKCS11 Smart Card and PDF Digital Signature with PKCS11 Driver for HSM contain the class Pkcs11ExternalSignature, a complete provider written with the library Pkcs11Interop (NuGet Pkcs11Interop): copy it into your project. It does what a provider has to do:

1. loads the module, finds the slot of the token (SlotIndex: the index among the slots that have a token) and opens a session with the PIN;
2. finds the certificates that have a private key on the token (GetCertificatesFromToken()), and the private key of the signing certificate (the certificate and its key share the attribute CKA_ID);
3. in ApplySignature: for RSA, signs with the mechanism that hashes and signs (CKM_SHA256_RSA_PKCS and the like), and, for tokens that do not have it, hashes the data and signs the DigestInfo with CKM_RSA_PKCS; for ECDSA, hashes the data and signs the hash with CKM_ECDSA (the result is the raw r || s).

// Excerpt of the samples that use a token. The constants are set by the application; the PIN is read from a protected source.
private const string Pkcs11LibraryPath = @"C:\Windows\System32\eTPKCS11.dll";
private const string TokenPin = "";              // do not store a PIN in the source code of a real application
private const int SlotIndex = 0;                 // the index of the token among the slots that have a token present

// The thumbprint of the signing certificate. When it is set, the certificate is found on the token without a window
// (a service); when it is empty, the user selects the certificate when the token has several.
private const string CertificateThumbprint = "";

Pkcs11ExternalSignature externalSignature = new Pkcs11ExternalSignature(Pkcs11LibraryPath, TokenPin, SlotIndex);

externalSignature.SigningCertificate = SelectCertificate(externalSignature.GetCertificatesFromToken());   // by thumbprint or by window

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = externalSignature.SigningCertificate;        // the public part

DigitalCertificate.UseExternalSignatureProvider = externalSignature;                   // before every signature
File.WriteAllBytes("source[signed].pdf", pdfSignature.ApplyDigitalSignature());

• The token is opened for every signature (the session is closed after it). A token that can be used by one process at a time needs a lock around the signing calls in a service with several threads.
• A wrong PIN repeated can block the token: do not retry in a loop.
• A certificate that is also visible in the Windows store can be used without PKCS#11 (section 5.2): load it from the store and set DigitalCertificate.SmartCardPin. PKCS#11 is the choice for non-Windows systems, for services, for the tokens whose minidriver does not take the PIN from the application, and for HSMs.

13.4 ECDSA signature values

The ECDSA signature value has two encodings. CMS (PDF, CAdES) requires the DER form SEQUENCE { INTEGER r, INTEGER s } (RFC 5753); XMLDSig (XML, XAdES, ASiC-E) requires the raw form r || s (RFC 4051). PKCS#11 modules, HSMs and cloud services usually return the raw form, and .NET's ECDsa.SignData too. A provider returns either form: the library accepts both and writes the form that the signature format needs. It does not change the signatures of RSA keys.

13.5 Two-phase PDF signing

When the signer cannot sign during the call, the PDF signature is created in three steps, which can be in different processes and at different times:

1. PdfSignature.PrepareExternalSignature(fieldName) prepares the document exactly as ApplyDigitalSignature does (the signature field, the appearance, the space for the signature) and computes the data to sign. No private key is used. The result is a PendingExternalSignature: DataToSign (the DER signed attributes), DigestAlgorithmOid and everything that is needed to complete the signature. Pass null as the field name for a new field.
2. The signer hashes DataToSign with DigestAlgorithmOid and signs the hash. The value is the same that IExternalSignature.ApplySignature returns.
3. PdfSignature.FinalizeExternalSignature(pending, signatureValue) inserts the signature in the prepared document and returns the signed PDF. No private key is needed. If TimeStamping.ServerUrl is set on the object of this step, the signature is time-stamped; for PAdES-LT and PAdES-LTA the validation data and the document time-stamp are completed in this step.

The signature must be made over the signature settings that you choose in step 1 (the standard, the hash, the appearance): they are fixed by PrepareExternalSignature. PendingExternalSignature has no private data, and it can be serialized (for example as JSON: the byte arrays are written as Base64 text) and stored between the steps. Do not use BinaryFormatter.

// Step 1: prepare. Only the public certificate of the signer is needed.
PdfSignature prepare = new PdfSignature(LibrarySerialNumber);
prepare.LoadPdfDocument("source.pdf");
prepare.DigitalSignatureCertificate = new X509Certificate2(File.ReadAllBytes("signer.cer"));
prepare.SignatureStandard = PdfSignatureStandard.Pades;
prepare.SigningReason = "I approve this document";
prepare.SignaturePosition = SignaturePosition.TopLeft;

PendingExternalSignature pending = prepare.PrepareExternalSignature(null);
Console.WriteLine("Sign " + pending.DataToSign.Length + " bytes with the hash algorithm " + pending.DigestAlgorithmOid);

// Step 2: the signer signs the data. Here: a certificate with a private key, as a stand-in for a remote signer.
X509Certificate2 signerWithKey = DigitalCertificate.LoadCertificate("cert.pfx", "123456");
byte[] signatureValue = new CertificateKeyExternalSignature(signerWithKey)
    .ApplySignature(pending.DataToSign, new System.Security.Cryptography.Oid(pending.DigestAlgorithmOid));

// Step 3: finalize (the same or another process, later).
PdfSignature finalize = new PdfSignature(LibrarySerialNumber);
byte[] signedPdf = finalize.FinalizeExternalSignature(pending, signatureValue);

File.WriteAllBytes("source[signed].pdf", signedPdf);

13.6 Cloud key vaults and remote services

The pattern is the same for every service: the certificate (public) is read from the service, and the provider sends the data to the sign operation of the service.

• Azure Key Vault. The samples PDF Digital Signature with Azure Key Vault Certificate (a certificate with an exportable key, stored as a secret: the PFX is downloaded and loaded as any PFX certificate) and PDF Digital Signature with Azure Key Vault Nonexportable HSM Certificate (the key never leaves the vault: the provider calls CryptographyClient.SignData with the algorithm RS256, RS384 or RS512 that matches the hash OID).
• A remote signing web service. The samples PDF Remote External Digital Signature and P7M P7S CAdES Remote External Digital Signature call the demo service of the library vendor (a WCF client) from a provider: the service has a method that returns the public certificate and a method that signs the data. To use your own service, replace the calls of the provider.
• Other services (AWS KMS, Google Cloud KMS, signing services of qualified trust service providers). Implement ApplySignature with the signing operation of the service. Check what the service signs: some sign a digest that you compute (hash message with the OID that you received, then send the hash), others hash the data themselves. For RSA, use the PKCS#1 v1.5 scheme of the service (not PSS), and for ECDSA the algorithm of the hash that you were given.

// A provider for a service that signs a digest: the provider hashes the message, the service signs the hash.
public class DigestSigningServiceSignature : IExternalSignature
{
    private readonly Func<byte[], string, byte[]> _signDigest;     // the call of your service: (digest, hashAlgorithmOid) -> the signature value

    public DigestSigningServiceSignature(Func<byte[], string, byte[]> signDigest)
    {
        _signDigest = signDigest;
    }

    public byte[] ApplySignature(byte[] message, Oid hashAlgorithm)
    {
        byte[] digest;

        switch (hashAlgorithm.Value)
        {
            case "2.16.840.1.101.3.4.2.1": digest = SHA256.Create().ComputeHash(message); break;
            case "2.16.840.1.101.3.4.2.2": digest = SHA384.Create().ComputeHash(message); break;
            case "2.16.840.1.101.3.4.2.3": digest = SHA512.Create().ComputeHash(message); break;
            default: throw new NotSupportedException("The hash algorithm " + hashAlgorithm.Value + " is not supported.");
        }

        return _signDigest(digest, hashAlgorithm.Value);
    }
}

14. eIDAS signatures

The eIDAS Regulation (EU) No 910/2014 on electronic identification and trust services (as amended) defines the legal effect of electronic signatures in the European Union. This chapter explains, technically, what the library gives to an application that must create or check eIDAS signatures. It is a simplified explanation and it is not legal advice.

14.1 The levels and what produces them

A signature is advanced or qualified because of the certificate (who issued it and with which identification), the device (where the key is) and the validation (that the certificate was qualified when the signature was made, according to the trusted lists). The library creates the signature in the right format and gives you the data to validate it; the legal level is a property of the whole.

14.2 Which format for what

A national or sectorial regulation can require an explicit signature policy or a given level: set the policy with SetSignaturePolicyInformation (section 6.13) and use the level that it asks, usually B-LT or B-LTA with a time-stamp from a qualified provider.

14.3 Creating a qualified signature

1. The signatory has a qualified certificate on a QSCD: a token or a smart card from a qualified trust service provider (or a remote QSCD service). The qualified certificates have the qcStatements extension with QcCompliance and QcSSCD.
2. The application gets the certificate: from the Windows store (the driver of the card publishes it, section 5.2) or from the PKCS#11 module of the card (section 13.3). The PIN is entered by the signatory, or it is set from code only when the device and the policy of the provider allow it.
3. The signature is created with PAdES, CAdES or XAdES, SHA-256 or stronger, with a time-stamp. For a long term validity use the B-LT or B-LTA level.
4. The signature is validated with a validator that uses the EU trusted lists (section 14.5).

// A PAdES-B-LT signature with the certificate of a qualified token (the PIN window of the driver appears when the PIN is not set).
X509Certificate2 qualifiedCertificate = DigitalCertificate.LoadCertificate(true, DigitalCertificateSearchCriteria.Thumbprint, "FAC4D3EF766A59BB068DD90877267EBC56B4232A");

Console.WriteLine("The certificate declares itself qualified: " + DigitalCertificate.IsQualifiedCertificate(qualifiedCertificate));

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("contract.pdf");
pdfSignature.DigitalSignatureCertificate = qualifiedCertificate;
pdfSignature.SignatureStandard = PdfSignatureStandard.PadesLT;
pdfSignature.HashAlgorithm = SignLib.HashAlgorithm.SHA256;
pdfSignature.TimeStamping.ServerUrl = new Uri("https://tsa.example.com/qualified");   // the server of a qualified time-stamping provider

File.WriteAllBytes("contract[signed].pdf", pdfSignature.ApplyDigitalSignature());

14.4 Test certificates

For the development of an application that handles qualified certificates, X509CertificateGenerator can create a test certificate with the qcStatements, the certificate policies and the subject identifiers of ETSI EN 319 412 (section 5.5). The signatures made with it have the correct structure, and they are not qualified: a validator reports that the certificate is not on a trusted list.

14.5 Validation with the EU DSS validator

The European Commission publishes the DSS (Digital Signature Service) library and a web validator that checks the signatures against the EU trusted lists and reports the level of the signature (AdES, AdES-QC, QESig, ...), the indications (TOTAL_PASSED, INDETERMINATE, TOTAL_FAILED) and the details of every check (certificate chain, revocation, time-stamps, format). To test a signature that the library created:

1. Open the DSS demo validator: https://ec.europa.eu/digital-building-blocks/DSS/webapp-demo/validation.
2. Upload the signed document: the PDF, the .p7m, the XML, the .asice. For a detached signature (.p7s, detached XAdES) upload also the original file.
3. Read the simple report (the result of every signature) and the detailed report (every check, and why a check failed).

The results depend on the certificate: a signature with a qualified certificate on a QSCD, from a provider on the trusted list, is reported as a qualified signature (QESig); a signature with a certificate that is not on a trusted list, as the self-signed test certificates, has the indication INDETERMINATE (the signature is intact, the chain is not trusted); a document that was changed after it was signed has TOTAL_FAILED. The signatures of the long term levels (B-LT, B-LTA) show that the validation data and the time-stamps are present and valid.

• Do not send confidential documents to a public validator: use a copy without confidential data, or the DSS library on your own server.
• The DSS library (open source, Java) can be run on your own computer or server, with the same checks. A .NET application can call its REST service.

15. Recipes

Complete solutions for the usual deployments: services without a user, batches, parallel signing, web services, and the handling of the network errors.

15.1 Signing without user intervention

A service, a scheduled task or a web application has no user who can select a certificate or type a PIN. Rules:

• No windows. Do not use the overloads of LoadCertificate that show the selection window. Load the certificate from a PFX file or bytes, from the store by criterion (thumbprint, serial number, name), or take it from a PKCS#11 module by its thumbprint.
• The store of the service account. The certificates of the current user are those of the account that runs the process; a service account has its own (usually empty) store. Install the certificate for that account, or in the Local Computer store and load it with fromLocalMachine = true. The account needs the permission to use the private key (the key permissions in certlm.msc).
• The PIN of a token is given with DigitalCertificate.SmartCardPin (or in the overload of LoadCertificate) when the driver accepts it, otherwise use PKCS#11 (section 13.3). A token in a service must be dedicated to it, and its middleware must work without a user interface.
• No dialogs from the signature classes. The library shows none, except the PIN window of the smart card driver when the PIN was not given.

// A service: the certificate by its thumbprint from the Local Computer store, the PIN from a protected source.
X509Certificate2 certificate = DigitalCertificate.LoadCertificate(true, DigitalCertificateSearchCriteria.Thumbprint, "FAC4D3EF766A59BB068DD90877267EBC56B4232A", true);

if (certificate == null)
    throw new InvalidOperationException("The signing certificate was not found in the Local Computer store.");

DigitalCertificate.SmartCardPin = Environment.GetEnvironmentVariable("TOKEN_PIN");    // only when the certificate is on a token

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = certificate;

byte[] signedPdf = pdfSignature.ApplyDigitalSignature();

15.2 Signing a folder

One signature object signs many documents: the certificate and the options are set once. A document that cannot be signed (a damaged file, a password-protected file without the password) must not stop the batch: catch the exception for each file and report it.

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.DigitalSignatureCertificate = signingCertificate;
pdfSignature.SigningReason = "I approve this document";

string[] files = Directory.GetFiles("source_folder", "*.pdf");
Directory.CreateDirectory("destination_folder");

int signed = 0;
for (int index = 0; index < files.Length; index++)
{
    try
    {
        pdfSignature.LoadPdfDocument(files[index]);
        File.WriteAllBytes(Path.Combine("destination_folder", Path.GetFileName(files[index])), pdfSignature.ApplyDigitalSignature());
        signed++;
    }
    catch (Exception ex)
    {
        Console.WriteLine(Path.GetFileName(files[index]) + " was NOT signed: " + ex.Message);
    }

    Console.WriteLine("Progress: " + (index + 1) + " of " + files.Length);
}

Console.WriteLine("Signed: " + signed + " of " + files.Length);

The same loop signs any file as .p7m with a CadesSignature object: File.WriteAllBytes(name + ".p7m", cadesSignature.ApplyDigitalSignature(file)).

15.3 Signing in parallel

The signing of a document with a software key uses the processor, and the time-stamp and the validation data wait for the network: many documents are signed faster in parallel. The rules of section 4.9 apply:

• One signature object for every thread. The overload of Parallel.ForEach with localInit creates one PdfSignature per worker task and reuses it for all the files of the task.
• The certificate (a PFX) can be shared. A token or an HSM session cannot be shared: with a token use one thread, or one provider and session per thread.
• External providers and the PIN are thread-local: set DigitalCertificate.UseExternalSignatureProvider and SmartCardPin inside the body, before every file.
• Limit the threads (MaxDegreeOfParallelism): the number of processors for the software keys; the number that the HSM, the TSA and the CRL servers accept for the others.
• Count the progress with Interlocked, and collect the errors in a thread-safe collection.

X509Certificate2 certificate = DigitalCertificate.LoadCertificate("cert.pfx", "123456");    // shared by the threads
string[] files = Directory.GetFiles("source_folder", "*.pdf");
Directory.CreateDirectory("destination_folder");

ConcurrentQueue<string> errors = new ConcurrentQueue<string>();
int signed = 0;
int processed = 0;

ParallelOptions options = new ParallelOptions { MaxDegreeOfParallelism = Math.Min(4, Environment.ProcessorCount) };

Parallel.ForEach(
    files,
    options,

    // localInit: one PdfSignature object for every worker task.
    () =>
    {
        PdfSignature threadSignature = new PdfSignature(LibrarySerialNumber);
        threadSignature.DigitalSignatureCertificate = certificate;
        return threadSignature;
    },

    (file, loopState, index, threadSignature) =>
    {
        try
        {
            // With an external provider or a PIN, set them here, on the thread that signs, before every file:
            // DigitalCertificate.UseExternalSignatureProvider = provider;
            threadSignature.LoadPdfDocument(file);
            File.WriteAllBytes(Path.Combine("destination_folder", Path.GetFileName(file)), threadSignature.ApplyDigitalSignature());
            Interlocked.Increment(ref signed);
        }
        catch (Exception ex)
        {
            errors.Enqueue(Path.GetFileName(file) + ": " + ex.Message);
        }

        Console.WriteLine("Processed " + Interlocked.Increment(ref processed) + " of " + files.Length);
        return threadSignature;
    },

    threadSignature => { });

foreach (string error in errors)
    Console.WriteLine("NOT signed: " + error);

Stopping the loop: pass a CancellationToken in ParallelOptions (for example one that the user cancels with Ctrl+C); the files in progress are finished and the others are skipped. The sample Batch Signing with Parallelism shows the cancellation, the comparison with the sequential loop and the damaged file.

15.4 Network errors: retry and time limits

The time-stamp and the validation data depend on servers that you do not control. A server that does not answer throws WebException (a time-stamp) or yields a signature without validation data (a CRL or an OCSP response that could not be downloaded). A batch should retry the transient failures with a pause, and not retry the errors of the document or of the key:

public static class Retry
{
    // Runs the signing and retries it when the time-stamping server fails (a transient error), with a growing pause.
    public static byte[] SignWithRetry(Func<byte[]> sign, int attempts = 3)
    {
        for (int attempt = 1; ; attempt++)
        {
            try
            {
                return sign();
            }
            catch (WebException) when (attempt < attempts)
            {
                Thread.Sleep(TimeSpan.FromSeconds(2 * attempt));
            }
        }
    }
}

PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);
pdfSignature.LoadPdfDocument("source.pdf");
pdfSignature.DigitalSignatureCertificate = signingCertificate;
pdfSignature.SignatureStandard = PdfSignatureStandard.PadesLT;
pdfSignature.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");
pdfSignature.TimeStamping.ServerTimeout = 15000;     // milliseconds

byte[] signedPdf = Retry.SignWithRetry(() => pdfSignature.ApplyDigitalSignature());

The signing time of a document that is signed again in a retry is the time of the last attempt. CryptographicException (a key that cannot be used, a damaged document) and ArgumentException are not transient: do not retry them.

15.5 A signing web service

A web application receives documents, signs them and returns them, without temporary files: byte[] in, byte[] out. The rules: a signature object per request, the certificate loaded once and shared, the serial number and the certificate password from the configuration, and the authentication and the authorization of the callers: a signing endpoint that anyone can call signs for anyone. The sample PDF Signing Web Service ASP.NET Core (.NET 8) is a minimal API with these endpoints:

// Excerpt of the sample "PDF Signing Web Service ASP.NET Core" (the whole project is in the sample set for .NET 8).
X509Certificate2 serverCertificate = DigitalCertificate.LoadCertificate(Path.Combine(AppContext.BaseDirectory, "cert.pfx"), CertificatePassword);   // loaded once

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
WebApplication app = builder.Build();

app.MapPost("/api/sign-pdf", async (HttpRequest request) =>
{
    try
    {
        PdfSignature pdfSignature = new PdfSignature(LibrarySerialNumber);                  // an object per request
        pdfSignature.LoadPdfDocument(await ReadBodyAsync(request));
        pdfSignature.DigitalSignatureCertificate = serverCertificate;
        pdfSignature.SignatureStandard = PdfSignatureStandard.Pades;

        return Results.File(pdfSignature.ApplyDigitalSignature(), "application/pdf", "signed.pdf");
    }
    catch (Exception ex)
    {
        return Results.BadRequest("The document cannot be signed: " + ex.Message);
    }
});

app.Run();

The matching client (the sample PDF Signing Web Service Client, .NET 8 and .NET Framework 4.6.2) signs the data of the two-phase signature with its own key:

1. POST /api/prepare with the PDF and the public certificate; the response has a session identifier and the data to sign;
2. the client signs the data with its private key (a PFX file, a token) and sends the signature value;
3. POST /api/finalize with the identifier and the signature value; the response is the signed PDF.

In the sample the prepared signature is kept in the memory of the server (a session of ten minutes, used one time). A production service stores it in a database or a distributed cache (PendingExternalSignature is serializable as JSON), authenticates the callers, uses HTTPS and limits the size of the requests. Kestrel does not allow synchronous reads of the body: read it with CopyToAsync.

15.6 Linux and containers

• Load the certificate from a PFX file (DigitalCertificate.LoadCertificate(file, password)) or use a PKCS#11 module (section 13.3). The Windows store overloads, SmartCardPin and the selection window do not exist there.
• The 14 standard PDF fonts (FontName) need no files. A TrueType font set in FontFile must exist in the container, at the path that you give.
• The visible signature lines of Office documents need Windows; the invisible Office signatures, PDF, CAdES, XML, XAdES and ASiC-E signatures do not.
• Give the container the access to the time-stamping server and to the CRL and OCSP addresses of the certificates.

15.7 Check the certificate before signing

Many failures in production are a certificate that expired yesterday. A cheap check at the start of the application and before every batch avoids signing with a certificate that every validator will reject:

public static class CertificateGuard
{
    // Throws when the certificate cannot be used to sign today.
    public static void EnsureCanSign(X509Certificate2 certificate, TimeSpan warnBefore)
    {
        if (!certificate.HasPrivateKey)
            throw new InvalidOperationException("The certificate has no private key.");

        if (DigitalCertificate.VerifyDigitalCertificate(certificate, VerificationType.LocalTime) != CertificateStatus.Valid)
            throw new InvalidOperationException("The certificate is expired or not yet valid: " + certificate.NotBefore + " - " + certificate.NotAfter);

        if (certificate.NotAfter - DateTime.Now < warnBefore)
            Console.WriteLine("WARNING: the certificate expires on " + certificate.NotAfter.ToShortDateString());

        // Optional: the revocation status (an OCSP or CRL request).
        if (DigitalCertificate.VerifyDigitalCertificate(certificate, VerificationType.OCSP) == CertificateStatus.Revoked)
            throw new InvalidOperationException("The certificate was revoked.");
    }
}

16. Sample projects

The download of the library has two sets of sample projects with the same structure: .NET 8 (SDK-style projects, net8.0) and .NET Framework 4.6.2. Every project is a small program with a comment at the beginning that says what it shows, with the link of this manual. Every project has the input files that it needs (cert.pfx, source.pdf, test.txt...) in its output folder, and a solution file; the library is referenced from the folder SignLib of the set.

• To run a sample, replace the constant LibrarySerialNumber (YourSerialNumber) with your serial number, build and run. Without it the sample runs in the demo version (section 2.4).
• The samples that need a token, a vault or a remote service have constants (the module of the PKCS#11 driver, the PIN, the address of the vault) that you must set for your environment.
• The samples that use the network (time-stamps, revocation data, the remote services) need an internet connection.

16.1 PDF

16.2 CAdES / PKCS#7

16.3 XML

16.4 Office and ASiC-E

16.5 Time-stamps

16.6 Certificates

16.7 External keys

16.8 Batches and services

16.9 Applications with a user interface and VB.NET

The projects that exist in one set only were written for the platform of that set: the Azure samples, the web service and the two-phase sample use .NET 8 packages, and the Windows Forms applications and the VB.NET projects are in the .NET Framework set. The samples that exist in both sets do the same thing.

17. Problems and solutions

The messages are the ones that the library writes in the exception; part of a message is enough to find the line. When the cause is not in the table, read the inner exception (ex.InnerException) and the full text of ex.ToString().

17.1 Project and installation

17.2 Signing

17.3 Verification

17.4 Time-stamps, revocation data, network

17.5 Certificates

17.6 If the problem remains

• Reduce it to a small program with the sample document and the PFX certificate of the samples: if it works there, the cause is in the document, in the certificate or in the environment.
• Run the same signature with the demo version and a PFX certificate to separate the problems of the key (token, store, PIN) from the problems of the document.
• Send the exception text (ex.ToString()), the version of the library, the target framework, the operating system and, when possible, the document that fails, to the support of the library (section 1.5).

18. API reference

This reference lists the public types of the library by namespace. It is generated from the assembly and from its XML documentation (SignLib.xml), so it has the exact signatures. The members that are marked as hidden from IntelliSense in the library are not listed. In the guide chapters, a name written in this font is a link to its entry here; use the search box of the contents to find a member.

Conventions: the indexes of the signatures are 0-based; a default value is the value that a property has until you set it; time values are UTC unless the description says local time; the methods that have a Stream, byte[] and path overloads do the same with every kind of input.

18.1 Namespace SignLib

public class OfficeSignature

public enum HashAlgorithm

18.2 Namespace SignLib.Pdf

public class CustomImage

public class CustomText

public class PdfDocumentProperties

public class PdfEncrypt

public class PdfEncryptionSettings

public class PdfInsertObject

public class PdfMerge

public class PdfSignature