Skip to content

Signature lines and stamps

Introduction

In addition to Digital Signatures EPPlus, from version 8 and up, 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:

SignatureLineExamples

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.Signatures.Add();

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

Using pck As New ExcelPackage("C:\temp\DigitalSignatureLineSimple.xlsx")
    Dim wb = pck.Workbook
    Dim ws = wb.Worksheets.Add("SignatureLinesEmpty")

    'From a worksheet you can create a signatureline
    'A visual representation via a vmldrawing object for signing.
    Dim signatureLine = ws.Signatures.Add()

    'If opened in Excel someone can now double-click and sign this signatureline.
    pck.Save()
End Using

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

Result:

EmptySignatureLine

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:

image

With EPPlus you can add these options via properties, like this:

var signatureLine = ws.Signatures.Add();
signatureLine.Signer = "FirstName LastName";
signatureLine.Title = "Engineer";
signatureLine.Email = "FirstName@epplussoftware.com";
signatureLine.SigningInstructions = "Please mr.LastName check and approve this document.";
signatureLine.AllowComments = true;
signatureLine.ShowSignDate = true;

Dim signatureLine = ws.Signatures.Add()
signatureLine.Signer = "FirstName LastName"
signatureLine.Title = "Engineer"
signatureLine.Email = "FirstName@epplussoftware.com"
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;

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

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();

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

Dim 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.DigitalSignatures.AddSignature() method:

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

Dim 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");

Dim 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);

'Your image MUST be of .bmp file format
'(Excel internally converts any format it is given image to .bmp format for digital signatures.)
Dim imagePath As String = "YourImagePath\file.bmp"

Dim 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.Signatures.AddStamp();

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

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

Dim stamp = ws.Signatures.AddStamp()

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

Dim imagePath As String = "YourImagePath\file.bmp"
Dim signatureImage = New ExcelImage(imagePath)
stamp.Sign(cert, signatureImage)

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 ExcelSignatureLine which allows for signing with text easily you can do so as described below:

//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");
}

'If you know a signature line stamp with index 0 is a signature line
Dim 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:
Dim allSignatureLines = ws.SignatureLines
For i As Integer = 0 To allSignatureLines.Count() - 1
    If allSignatureLines(i).SignatureLineType = eSignatureLineType.SignatureLine Then
        allSignatureLines(i).AsSignatureLine.Sign(cert, "FirstName LastName")
    End If
Next

'Alternatively via a LINQ expression
Dim filteredSignatureLines = ws.SignatureLines.Where(Function(x) x.SignatureLineType = eSignatureLineType.SignatureLine)
For Each sLine In filteredSignatureLines
    sLine.AsSignatureLine.Sign(cert, "FirstName LastName")
Next

Security concerning Hashing and DigestMethods

By default Excel and thus also EPPlus uses the SHA1 hashing method for digital signatures. For safety reasons it is recommended to switch to a safer digest algorithm, see below:

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);

Dim 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