Digital Signature Lines And Stamps

Introduction

In addition to Digital Signatures Epplus also supports all types of digital signature lines that Excel supports. Including 'Signature Line Stamps'.

A digital signature line is a visual representation (in this case vml drawing) within a worksheet of a digital signature. These need not be signed immediately but can be signed by someone opening the file and double-clicking it. Once signed they may look like this for example:

Examples of signed digital signatures. The top two are digital signatures and the bottom drawing is a signature line stamp

Creating a Digital Signature in Epplus

To create the most simple version of a signature line one may write:

using (var pck = new ExcelPackage(@"C:\temp\DigitalSignatureLineSimple.xlsx"))
{
    var wb = pck.Workbook;
    var ws = wb.Worksheets.Add("SignatureLinesEmpty");

    //From a worksheet you can create a signatureline
    //A visual representation via a vmldrawing object for signing.
    var signatureLine = ws.AddSignatureLine();

    //If opened in Excel someone can now double-click and sign this signatureline.
    pck.Save();
}

This signature line can then be signed via the Sign() method. Which returns the Digital Signature object from Digital Signatures

Result:

When inserting a signature line in Excel you first get prompted for Signature Setup. Where you can imply who is expected to sign the document and some other details:

In Epplus you can add these options via properties, like this:

var signatureLine = ws.AddSignatureLine();
signatureLine.Signer = "FirstName LastName";
signatureLine.Title = "Engineer";
signatureLine.Email = "[email protected]";
signatureLine.SigningInstructions = "Please mr.LastName check and approve this document.";
signatureLine.AllowComments = true;
signatureLine.ShowSignDate = true;

Epplus doesn't have a UI but you can still move and re-size the signature line via columns and rows (0-indexed).:

// Keep in mind that both From and To properties must be set to size the object properly. 
// (A signature line from column 4 to column 4 is not visible)
signatureLine.From.Column = 5;
signatureLine.To.Column = 9;
signatureLine.From.Row = 0;
signatureLine.To.Row = 6;

Signing a digital signature

Just like in Digital Signatures and when signing VBA To sign a signature line you will need to provide a valid X509Certificate2 containing a private key.

Signing with text

You can sign the signature line from the example above via the sign method:

// Store your certificate safely in a real production environment. 
// This example uses an unsafe local .pfx file.

cert = new X509Certificate2(FileUtil.GetRootDirectory() + "\\21-VBA\\SampleCertificate.pfx", "EPPlus");
signatureLine.Sign(cert, "FirstName LastName");

//Workbook is not truly signed until after save.
pck.Save();

The sign method returns the digital signature and has the same optional parameters as the package.Workbook.DigitialSignatures.AddSignature() method:

var digitalSignature = signatureLine.Sign(cert, "FirstName LastName", CommitmentType.CreatedAndApproved, "To demonstrate");
digitalSignature.Details.Address1 = "ExampleStreet 2";

For more info on the ExcelDigitalSignature methods and properties see the Digital Signatures article.

Signing with an existing signature

You can also sign with an already existing digital signature:

var previousDigitalSignature = wb.DigitalSignatures[0]
signatureLine.SignWithExistingText(previousDigitalSignature , "FirstName LastName");

Keep in mind that a the signature line is stored within the digital signature if it is to be signed. An ExcelDigitalSignature object can only ever be connected to One signatureline at the time. You can however use the same certificate for multiple signatures.

Signing with an image

A signature line doesn't have to be signed with text. It can also be signed with an image (It MUST be of .bmp file format)

//Your image MUST be of .bmp file format
//(Excel internally converts any format it is given image to .bmp format for digital signatures.)
string imagePath = @"YourImagePath\file.bmp";

var signatureImage = new ExcelImage(imagePath);
signatureLine.Sign(cert, signatureImage);

Signature Line Stamps

Epplus also allows for reading and creating signature line stamps. These feature a slightly different look and can Only be signed with an image.

var stamp = ws.AddSignatureLineStamp();

stamp.Signer = "FirstName LastName";
stamp.Title = "Engineer";

string imagePath = @"YourImagePath\file.bmp";
var signatureImage = new ExcelImage(imagePath);
stamp.Sign(cert, image);

Reading a Signature Line

When reading in a signature line from a file or from the worksheet collection keep in mind that it is a collection of the base class ExcelSignatureLineStamp which only allows for signing with images. To differentiate, all ExcelSignatureLineStamp objects have an eSignatureLineType property. To cast to a ExcelSignatureLinewhich allows for signing with text easily you can do so via e.g.

//If you know a signature line stamp with index 0 is a signature line
var signatureLineRead = ws.SignatureLines[0];
//You can simply use the .AsSignatureLine property.
signatureLineRead.AsSignatureLine.Sign(cert, "FirstName LastName");

//Or to find out all signature lines type you may do something like this:
var SignatureLines = ws.SignatureLines;
for (int i = 0; i < SignatureLines.Count(); i++)
{
    if (SignatureLines[i].SignatureLineType == eSignatureLineType.SignatureLine)
    {
        SignatureLines[i].AsSignatureLine.Sign(cert, "FirstName LastName");
    }
}

//Alternatively via a LINQ expression
var signatureLines = ws.SignatureLines.Where
    (x => x.SignatureLineType == eSignatureLineType.SignatureLine);
foreach (var sLine in signatureLines)
{
    sLine.AsSignatureLine.Sign(cert, "FirstName LastName");
}

Security concerning Hashing and DigestMethods

Keep in mind that SHA-1 is the default signing method. For safety reasons it is recommended to switch to a safer digest algorithm. You can do so by e.g.

var digitalSignature = signatureLine.Sign(cert, "FirstName LastName", CommitmentType.CreatedAndApproved, "To demonstrate");
//Note: This sets the hashing method for all digital signatures in the package
digitalSignature.SetDigestMethod(DigitalSignatureHashAlgorithm.SHA512);

See also

See Digital Signatures. For basic information on how to sign your workbook.

We have also made a samples that show multiple ways to create digital signatures in Epplus: See Sample 8.3-C# or Sample 8.3-VB