Digital Signatures |
Sign(String, String, String, String, String, String, String, String, Int32, RectangleF, TimeStampAuthority) adds a digital signature to a PDF document. The signature proves who signed the document and that it was not changed after it was signed. PDF viewers show it in their signatures panel, with the signer, the reason, the location and the contact information you give.
The document is signed with a certificate and its private key from a PKCS#12 file (.pfx or .p12), opened with the password of the file. For documents that other people must trust, use a certificate issued for you by a certification authority. For tests you can make a self-signed certificate, for example with PowerShell:
$cert = New-SelfSignedCertificate -Subject "CN=Test Signer" -KeyUsage DigitalSignature -CertStoreLocation Cert:\CurrentUser\My Export-PfxCertificate -Cert $cert -FilePath test-signer.pfx -Password (ConvertTo-SecureString "password" -AsPlainText -Force)
PDF viewers show the signatures made with a self-signed certificate as valid (the document was not changed) but the signer as not trusted.
The signature is placed in a box on one page: the page index starts at 0, and the box is given in points (1/72 inch) from the top left corner of the page. There are three versions of the method: from a file to a file, from a stream to a stream, and from a byte array to a byte array.
using System.Drawing; using ExpertPdf.PDFSecurity; PdfSecurityManager securityManager = new PdfSecurityManager(); // securityManager.LicenseKey = "your license key"; // the bottom right of the first page of an A4 document RectangleF bounds = new RectangleF(345, 700, 200, 60); // file to file securityManager.Sign(@"C:\Documents\report.pdf", @"C:\Documents\signed-report.pdf", @"C:\Certificates\signer.pfx", "certificate password", "Approval", "I approve this report", "Head office", "signer@example.com", 0, bounds, null); // memory to memory byte[] signedBytes = securityManager.Sign(File.ReadAllBytes(@"C:\Documents\invoice.pdf"), @"C:\Certificates\signer.pfx", "certificate password", "Issuer", "Invoice issued", "Head office", "billing@example.com", 0, bounds, null);
Set SourcePdfPassword to the user or the owner password of a protected document. The signed document keeps its protection. When a document must be both protected and signed, protect it first and sign it after: a change made after signing invalidates the signature.
PdfSecurityManager securityManager = new PdfSecurityManager(); securityManager.SourcePdfPassword = "owner"; using (FileStream source = File.OpenRead(@"C:\Documents\secured.pdf")) using (FileStream destination = File.Create(@"C:\Documents\secured-signed.pdf")) { securityManager.Sign(source, destination, @"C:\Certificates\signer.pfx", "certificate password", "Approval", "Approved for distribution", "Head office", "signer@example.com", 0, new RectangleF(345, 700, 200, 60), null); }
Without a time stamp, the signing time comes from the clock of the computer that signed. A TimeStampAuthority adds a time stamp from a time stamp server (RFC 3161), which proves when the document was signed. Give the address of the server, and a user name and a password when the server requires them. Signing then needs a connection to the server.
TimeStampAuthority tsa = new TimeStampAuthority(new Uri("https://your-tsa-server/")); // tsa.UserName = "user"; // tsa.Password = "password"; new PdfSecurityManager().Sign(@"C:\Documents\report.pdf", @"C:\Documents\signed-report.pdf", @"C:\Certificates\signer.pfx", "certificate password", "Approval", "I approve this report", "Head office", "signer@example.com", 0, new RectangleF(345, 700, 200, 60), tsa);
A certification (author) signature also states the changes allowed after it. Set CertificationLevel before calling Sign: NoChangesAllowed, FormFillingAllowed (form filling and signing) or FormFillingAndAnnotationsAllowed. The default, None, makes an ordinary approval signature.
A document has at most one certification signature and it must be its first signature: certifying a signed document throws an exception, and so does signing a document certified with no changes allowed. When other people sign the document after it was certified, add their empty signature fields first with AddSignatureField(String, String, String, Int32, RectangleF): signing an existing field is form filling, which the certification allows, while some validators report a signature field added after the certification as a change it does not allow. A Sign call with the name of an empty field signs that field, at its position.
PdfSecurityManager securityManager = new PdfSecurityManager(); // 1. the empty field of the approver, on the first page securityManager.AddSignatureField(@"C:\Documents\report.pdf", @"C:\Documents\report-field.pdf", "Approval", 0, new RectangleF(40, 700, 200, 60)); // 2. the author certifies the document: form filling and signing remain allowed PdfSecurityManager author = new PdfSecurityManager(); author.CertificationLevel = PdfCertificationLevel.FormFillingAllowed; author.Sign(@"C:\Documents\report-field.pdf", @"C:\Documents\certified.pdf", @"C:\Certificates\author.pfx", "certificate password", "Author", "I am the author of this report", "Head office", "author@example.com", 0, new RectangleF(345, 700, 200, 60), null); // 3. the approver signs the empty field (its position comes from the field) new PdfSecurityManager().Sign(@"C:\Documents\certified.pdf", @"C:\Documents\approved.pdf", @"C:\Certificates\approver.pfx", "certificate password", "Approval", "Approved", "Branch office", "approver@example.com", 0, RectangleF.Empty, null);
ValidateSignatures(String) checks every signature of a document and returns a SignatureValidationResult for each: the field name, the signer, the signing time, the reason, location and contact information, whether the document was changed after signing in a way the signature does not allow (IsDocumentModified), whether the certificate was valid at the signing time and its chain ends in a trusted root certificate, the time stamp, the revocation status, the certification level, and the overall Status: Valid, Unknown (the document is intact but the signer could not be verified, for example a self-signed certificate) or Invalid. Messages explains a status that is not Valid. A password protected document is opened with SourcePdfPassword.
SignatureValidationOptions adds root certificates to trust (your own certification authority, or a test certificate), can limit the trust to them (UseSystemTrustStore), and turns on the online revocation check (CheckRevocation, off by default), which asks the revocation lists and OCSP servers named in the certificates. The operating system checks the revocation of a certificate chain that ends in a root certificate the computer trusts; for a chain trusted only through TrustedRootCertificates the revocation status of a certificate that is not revoked is reported as Unknown.
SignatureValidationOptions options = new SignatureValidationOptions(); options.CheckRevocation = true; // options.TrustedRootCertificates.Add(new X509Certificate2(@"C:\Certificates\our-root-ca.cer")); foreach (SignatureValidationResult result in new PdfSecurityManager().ValidateSignatures(@"C:\Documents\approved.pdf", options)) { Console.WriteLine("{0}: {1}, signed by {2} on {3}", result.FieldName, result.Status, result.SignerName, result.SigningTime); Console.WriteLine(" changed after signing: {0}, trusted: {1}, time stamp: {2}, certification: {3}", result.IsDocumentModified, result.IsCertificateChainTrusted, result.HasTimeStamp, result.CertificationLevel); foreach (string message in result.Messages) Console.WriteLine(" " + message); }
A signature followed by later changes (another signature, for example) does not cover the whole file (CoversWholeDocument is false); IsDocumentModified tells whether those changes are allowed.
The PdfDigitalSignature sample (C# and VB.NET, .NET Framework 4.6.2, .NET 10 and .NET 11) signs the documents that come with it from a file, from memory and, protected with a password, from a stream. It uses certificate.pfx, a self-signed test certificate (password: expertpdf). Run it with /tsa:server_url to add time stamps. It also certifies a document with an empty field that an approver signs, and validates all the signatures.