# Digital signatures

## Introduction

A digital signature is an authenticated and encrypted electronic stamp for digital information. It verifies that what has been signed originated from the signer and has not been changed.

In Excel you can add a digital signature in the following way:

## EPPlus Example

As of EPPlus 8.0 You can also add a Digital Signature in EPPlus via the workbook. To add a minimal digital signature you, [much like when signing VBA](<https://epplussoftware.com/docs/vba-and-protection/vba/#sign-your-vba-code>) must supply a `System.Security.Cryptography.X509Certificates.X509Certificate2` that refers to a private key to sign with.

In code, if your current user has valid certificates it can be as simple as:

```csharp
using(var pck = new ExcelPackage())
{
    var wb = pck.Workbook;
    var ws = wb.Worksheets.Add("SomeWorksheet");

    X509Store store = new X509Store(StoreLocation.CurrentUser);
    store.Open(OpenFlags.ReadOnly);
    var cert = store.Certificates[0];    

    //Add a digital signature and sign it with the certificate
    var digitalSignature = wb.DigitalSignatures.Add(cert);

    pck.SaveAs(@"C:\temp\DigitalSignatureSimple.xlsx");
}
```

```vbnet
Using pck As New ExcelPackage()
    Dim wb = pck.Workbook
    Dim ws = wb.Worksheets.Add("SomeWorksheet")

    Dim store As New X509Store(StoreLocation.CurrentUser)
    store.Open(OpenFlags.ReadOnly)
    Dim cert = store.Certificates(0)

    'Add a digital signature and sign it with the certificate
    Dim digitalSignature = wb.DigitalSignatures.Add(cert)

    pck.SaveAs("C:\temp\DigitalSignatureSimple.xlsx")
End Using
```

In order to create the digital signature in the images above we can create it like this:

```csharp
//The method to add a signature also includes optional parameters for the comments commitment type and reason for signing
//That represent the 'commitment type' and 'purpose for signing this document' fields from Excel.
var digitalSignature = wb.DigitalSignatures.AddSignature(cert, CommitmentType.CreatedAndApproved, "To demonstrate");

//You can also add signer details via the Details property.
//This represents the 'details' button in excel:
var details = digitalSignature.Details;

details.SignerRoleTitle = "Developer";
details.Address1 = "ExampleStreet 2";
details.Address2 = "Floor 2";
details.ZipOrPostalCode = "114 51";
details.City = "Stockholm";
details.CountryOrRegion = "Sweden";
details.StateOrProvince = "Stockholm";

pck.SaveAs(@"C:\temp\DigitalSignatureSimple.xlsx");
```

```vbnet
'The method to add a signature also includes optional parameters for the comments commitment type and reason for signing
'That represent the 'commitment type' and 'purpose for signing this document' fields from Excel.
Dim digitalSignature = wb.DigitalSignatures.AddSignature(cert, CommitmentType.CreatedAndApproved, "To demonstrate")

'You can also add signer details via the Details property.
'This represents the 'details' button in excel:
Dim details = digitalSignature.Details

details.SignerRoleTitle = "Developer"
details.Address1 = "ExampleStreet 2"
details.Address2 = "Floor 2"
details.ZipOrPostalCode = "114 51"
details.City = "Stockholm"
details.CountryOrRegion = "Sweden"
details.StateOrProvince = "Stockholm"

pck.SaveAs("C:\temp\DigitalSignatureSimple.xlsx")
```

Keep in mind that the actual digital signature will be created when the workbook is saved, not before. Digital Signatures in EPPlus has an `IsValid` property. It will only be valid after saving and when reading a signature.

## Security concerning Hashing and DigestMethods

By default Excel and thus also EPPlus uses the SHA1 hashing method for digital signatures. This hashing method has been [considered unsafe for some time](<https://security.googleblog.com/2015/12/an-update-on-sha-1-certificates-in.html>) thus it is recommended to set a more secure hashing method using `SetDigestMethod()`

```csharp
var digitalSignature = wb.DigitalSignatures.Add(cert);
//Note: This sets the hashing method for all digital signatures in the package
digitalSignature.SetDigestMethod(DigitalSignatureHashAlgorithm.SHA512);
```

```vbnet
Dim digitalSignature = wb.DigitalSignatures.Add(cert)
'Note: This sets the hashing method for all digital signatures in the package
digitalSignature.SetDigestMethod(DigitalSignatureHashAlgorithm.SHA512)
```

## See also

- EPPlus also supports [Digital Signature Lines](<https://epplussoftware.com/docs/vba-and-protection/digital-signatures/digital-signature-lines-and-stamps/index.md>), which visualizes a digital signature on a worksheet.
- We have made samples that show multiple ways to create digital signatures in EPPlus: See [Sample 8.3-C\#](<https://github.com/EPPlusSoftware/EPPlus.Samples.CSharp/tree/master/08-Encryption protection and VBA/03-DigitalSignatures>) or [Sample 8.3-VB](<https://github.com/EPPlusSoftware/EPPlus.Samples.VB/tree/master/08-Encryption protection and VBA/03-DigitalSignatures>)