ASiC Signer User Manual

Sign files of any type in ASiC-E containers with XAdES signatures: eIDAS advanced and qualified electronic signatures and seals, qualified time stamps and archive time stamps for the long-term preservation of the signed files. Verify the containers with ASiC Viewer. No technical knowledge needed; developers find PowerShell, C# and VB.NET examples at the end.

1. What is ASiC Signer?

A file (a contract, an invoice, a report, a scan) can be changed by anyone who has it. A digital signature solves two problems:

• Who signed it? The signature is created with your personal digital certificate, so it proves your identity.
• Was it changed? If even one character of a file is modified after signing, the signature is reported as not valid.

ASiC Signer signs files of any type (PDF, Word, Excel, images, XML, archives...) and puts them, together with their signatures, in an ASiC-E container: a single file with the extension .asice (or .sce). The container is the format that is used in the European Union to send, submit and archive signed files, because the files and their proofs travel as one unit. The signature inside the container is a XAdES signature, one of the formats of the advanced and qualified electronic signatures of the eIDAS Regulation (EU) No 910/2014. ASiC Signer can also add the archive time stamps that keep the signatures verifiable for many years (section 7.5).

The product has two programs:

Who is this manual for?

• Users — sections 1 to 14 explain, step by step, how to install the product, register it, choose a certificate, sign files, keep the signatures valid for many years and check the containers. Section 7 explains the eIDAS concepts in simple words.
• Developers and administrators — sections 15 to 17 explain that ASiC Signer is built on the Signature Library (SignLib), and show how to create, co-sign, verify and renew the same containers from Windows PowerShell, C# or VB.NET. One of the purposes of ASiC Signer is to let you see what the library can do before you write a single line of code.

Useful links

2. Product installation

We recommend installing the product with an Administrator account. After the setup file is verified, the operating system might ask for your permission to install the program: click Yes.

What you need

• Windows 8 or later (including Windows 10, Windows 11 and Windows Server 2022).
• Microsoft .NET Framework 4.6.2 or newer. It is already part of the current versions of Windows 10 and Windows 11. If it is missing, the setup stops and sends you to the Microsoft download page.
• A digital certificate to sign with. If you do not have one yet, you can create a test certificate (section 11).

Installation steps

1. Download the setup file. Get ASiCSigner.msi from the product page and run it.
2. If Windows SmartScreen appears, allow the program to run. You may see the window Windows protected your PC. Click More info and then Run anyway. See the explanation below.
3. Read the license agreement. Read the EULA (End-User License Agreement). If you want to continue, select I Agree and click Next until the setup is finished.
4. Start the program. The setup installs ASiC Signer and ASiC Viewer. Start them from the Windows Start menu. By default the files are in the Secure Soft\ASiC Signer folder of Program Files (on a 64-bit Windows: C:\Program Files (x86)\Secure Soft\ASiC Signer).

What is Windows SmartScreen?

SmartScreen is a protection built into Windows. When you run a program you downloaded, Windows compares it with a list of programs that are known and were already downloaded by many people. A program that Windows does not know yet, for example a new version that was published recently, is shown as an unrecognized app, and the window below appears.

This message does not mean that the file contains a virus. It only means that Windows has no reputation data about it yet. To continue:

1. Click More info. The name of the file and of the publisher are displayed.
2. Click Run anyway and the setup starts.

3. Trial period and product registration

A new, unregistered installation works for a trial period of 31 days. The title of the window shows how much is left, for example ASiC Signer - Expires in 30 days, and the buttons Register Now and Buy Now! are visible.

How to register the product

1. Get a serial number. To register the product you need a serial number (also called license code). You can buy it online directly from the product page, https://www.signfiles.com/asic-signer/. You can also click Buy Now! in the program, which opens the same page.
2. Open the registration window. Open ASiC Signer and click the Register Now button (or Help → Register Now...).
3. Type the license code. Enter the received serial in the first box. The second box, Licensed to (optional), is for a name: if you type one, it is shown in the title of the window.
4. Click Register. If the serial number is correct, the product is successfully registered.

4. Sign your first container

This is the whole process. It takes less than a minute once you have a certificate.

1. Add the files to sign. Keep the operation Sign files - one container with the selected files. Click Add Files... and select the files (of any type). You can select several files together, with Ctrl + click or Shift + click, and you can add files from several folders. You can also drag the files from Windows Explorer onto the window.
2. Choose where to save the container. Click the ... button under Destination container and pick a folder and a file name (for example contract-001.asice). The extension is .asice (or .sce), and the container must be a different file from the signed files.
3. Select your digital certificate. Click Select the Digital Certificate.... Choose the certificate from the Windows store (the certificates of a smart card or of a token are there too), or a .pfx file, and click OK (details in section 6).
4. Leave the signature level on the recommended value. ASiC-E XAdES-B-B - basic (recommended) and SHA256 are already selected and are the right choice for most uses. For files that must stay verifiable for years, read section 7.5.
5. Click Sign. After a moment you see the message The container was signed successfully, with the name of the container. Open the container with ASiC Viewer to see the result (section 14).

5. The main window

The window shows only what the selected operation needs. The first list, Operation, chooses what the program does:

Menus

6. Digital certificates

A digital certificate is your electronic identity card, issued by a certification authority. To sign with ASiC Signer you need one. This section explains where certificates are kept and how to select the one you want to sign with.

6.1 Where the certificates are stored

A certificate that can sign files has two parts: a public key (the part other people see, inside the certificate) and a private key (the secret part, which only you have). The digital signature is created with the private key. The certificates are kept in two places:

• in the Windows Certificate Store. The certificates of a smart card or of a USB token are in this list too, when the token is connected;
• in a PFX (or P12) file.

The Windows Certificate Store

The Windows Certificate Store is the place where Windows keeps the certificates of the computer and of each user. In ASiC Signer it appears as Windows Certificate Store and Windows certificates (including the inserted tokens).

To see the certificates of your account:

1. Press Win + R, type certmgr.msc and press Enter.
2. Open Personal → Certificates.

To create digital signatures, the certificates of the Personal store are used. They must have a public and a private key. You can check this by opening a certificate: in the General tab Windows writes You have a private key that corresponds to this certificate.

The private key itself can be stored:

• on the file system of the computer (for example, an imported PFX file);
• on a cryptographic smart card or USB token (like Aladdin eToken or SafeNet) — see 6.2;
• on an HSM (Hardware Security Module), a device that keeps keys for a company.

The certificates you can use are listed per store location: Current User (your own certificates, the usual case) or Local Machine (certificates installed for all the users of the computer).

PFX and P12 files

Another way to keep a digital certificate is a PFX (or P12) file. The file contains the public and the private key of the certificate, and it is protected by a password, to keep the key pair safe.

6.2 Certificates stored on smart cards or USB tokens

If your certificate is stored on a smart card or on a USB token (like Aladdin eToken or SafeNet), the private key never leaves the device: it signs inside the device. This is the kind of device used for qualified certificates (QSCD, see section 7). For ASiC Signer to use it, the certificate must appear in the Windows Certificate Store (6.1).

Usually, the driver of the smart card or its middleware (the software delivered with the token) installs the certificate in the Windows store automatically when the token is connected. If the certificate does not appear in the list, ask your vendor how to add it to the store, and look at the options of the middleware, like below:

Once the certificate is in the store, select it in ASiC Signer as described in 6.3. When you sign, the token asks for its PIN. The window belongs to the middleware of the token. If the token is not connected, its certificate is not in the Windows store and ASiC Signer tells you so, with the name of the certificate: The digital certificate '...' was not found in the Windows certificate store. If it is on a token or smart card, insert it and try again.

6.3 Select the digital certificate for creating signatures

To sign, a digital certificate must be selected first. Click Select the Digital Certificate... (or Tools → Select the Digital Certificate...). The certificate can be stored in the Windows store or in a PFX file.

Option A: a certificate installed in Windows

Certificates installed on the computer, or stored on a USB token or smart card, appear in the Windows Certificate Store.

1. Select Windows Certificate Store.
2. In Certificate Store choose Current User (your own certificates, the usual case) or Local Machine (certificates installed for the whole computer).
3. Pick your certificate from the list. Each line shows the name of the owner and the expiry date; a certificate that declares itself qualified is marked (qualified certificate), and an expired one is marked EXPIRED. The issuer is written in Certificate Information, under the list. Details... displays the full certificate.
4. If your token was inserted after the window was opened, click Refresh: the list is read again from Windows and your selection is kept.
5. If the certificate is on a smart card and you want to avoid the PIN window, tick Save the PIN (no PIN prompt) and type the PIN (section 6.2).
6. Click OK.

The list shows only the certificates that can create signatures: they have a private key and are not meant only for encrypting or for web servers. The most suitable certificate is the first one of the list: a valid one, a qualified one, one with the non-repudiation usage of the signature certificates (a token often has also a certificate used to log in), the one that expires last. When no certificate was selected before, this one is selected for you. The expired certificates (and those that are not valid yet) are at the end of the list, so that you see why they cannot be used: when you select one, ASiC Signer warns you, and OK does not accept it.

Option B: a PFX file

Some certificates are delivered as a file with the extension .pfx (or .p12), protected by a password.

1. Select PFX digital certificate file.
2. Click ... and pick your .pfx file (or type its path).
3. Type the PFX file password. The Details... button next to it displays the details of the certificate so you can check you picked the right one.
4. Click OK.

Certificate Information

In the middle of the window, Certificate Information summarizes the selected certificate: to whom and by whom it was issued, until when it is valid, and where its private key is stored. The same summary is shown under the certificate button of the main window.

Both RSA and ECDSA (elliptic curve) certificates are supported.

A certificate that is not meant to sign documents

Some certificates are issued for another purpose, for example only for time stamping. They are still in the list, because they have a private key, but ASiC Signer adds a Warning line to Certificate Information and a short one under the certificate button of the main window. The warning appears when the usage of the certificate allows neither the digital signature nor the non-repudiation, or when its extended key usage lists only other purposes.

The warning does not stop the signing, but the programs that validate the signature, such as the European validator, can report it. For your real files use a certificate issued for signing documents. From the command line (section 13) the same warning is written in the command window.

Validation data of the long-term levels

At the bottom of the window, Revocation data of the XAdES-B-LT and XAdES-B-LTA signatures chooses what proof of validity is saved inside those signatures (see section 7.4):

• OCSP responses (CRL only when OCSP is not available) — the default and the best choice for most users.
• CRLs, CRLs and OCSP responses, or No revocation data (only the certificates).
• Maximum size of a CRL (default 1024 kilobytes) limits how large a revocation list may be to be included.

The button Create a self-signed Certificate... at the bottom left is explained in section 11.

7. eIDAS, ASiC-E and long-term preservation

ASiC Signer creates the containers and the signatures that the European Union uses for electronic signatures on files of any type: ASiC-E containers (ETSI EN 319 162-1) with XAdES signatures (ETSI EN 319 132-1). This section explains how they relate to the eIDAS Regulation (EU) No 910/2014 and to the eIDAS 2 Regulation, what you need to obtain a qualified electronic signature or a qualified electronic seal, how to keep the signatures verifiable for many years, and how to check the result with the tools of the European Union. The text is a simplified explanation, not legal advice.

7.1 eIDAS, eIDAS 2 and the signature levels

The eIDAS Regulation (Regulation (EU) No 910/2014 on electronic identification and trust services for electronic transactions in the internal market) defines three levels of electronic signatures:

The same rules apply to electronic seals. A seal is the signature of a legal entity (a company, an institution), created with a certificate for electronic seals. A qualified electronic seal enjoys the presumption of integrity of the data and of correctness of the origin of the data (Article 35). ASiC Signer signs with a seal certificate in the same way as with a signature certificate.

A qualified electronic time stamp, issued by a qualified time stamping service, enjoys the presumption of the accuracy of the date and the time it indicates and of the integrity of the data to which they are bound (Article 41). Section 7.7 explains how to use it.

7.2 What you need for a qualified signature or seal

The level of a signature is given by the certificate and by the device that holds its private key, not by the software. ASiC Signer creates the signature in the format that the validators expect, and it works with all the kinds of certificates:

When the selected certificate declares itself as a qualified certificate, ASiC Signer writes (qualified certificate) after its name, in the main window and in the certificate window. This mark is only an indication that is read from the certificate: the qualified status itself is given by the EU Trusted Lists (see section 7.6).

7.3 The ASiC-E container

ASiC (Associated Signature Containers, ETSI EN 319 162-1) is the European standard for a signed package: the signed files and the signatures are stored together in a ZIP file. There are two kinds of containers: ASiC-S (simple), for one signed file, and ASiC-E (extended), for any number of files. ASiC Signer creates ASiC-E containers, also when you sign one file. The ASiC container is one of the formats referred to by Commission Implementing Decision (EU) 2015/1506 on the formats of advanced electronic signatures and seals, together with XAdES, CAdES and PAdES, and it is used by public administration, e-procurement and e-justice systems in the European Union. Check the requirements of the system that receives your files.

Inside the container (section 17.8 shows a real one):

7.4 Signature levels

The level decides how much information is stored inside the signature, and for how long the signature can be verified. If you are not sure, keep the first one. The four levels are the XAdES baseline profiles of ETSI EN 319 132-1, the formats recognised for advanced and qualified signatures. They are all in the list Signature level of the main window:

The letters B, T, LT and LTA come from the standard: Basic, Time-stamp, Long Term and Long Term Archival.

7.5 Long-term preservation and archiving

A signature is created in a moment, but the file is often kept for ten, twenty or more years: contracts, accounting documents, minutes, tender files. After so many years, checking the signature is not simple any more:

• the certificate of the signer expired (or was revoked later), and the program that verifies the signature must know that it was valid at the moment of the signature;
• the servers of the certification authority (the OCSP and CRL services) may not exist any more, so the proof of validity cannot be asked again;
• the time stamp that proves the moment is signed itself with a certificate that expires, and with an algorithm that can become weak.

The solution is to store the evidence together with the file, at the moment of the signing, and to protect it, periodically, with new time stamps. This is what the levels of XAdES do:

The Regulation (EU) No 910/2014 provides for a qualified preservation service for qualified electronic signatures (Article 34), which extends the trustworthiness of a qualified signature beyond its technological validity period, and eIDAS 2 adds the qualified electronic archiving as a trust service. These are services of qualified trust service providers. ASiC Signer gives you the technical means to do the same on your own: the evidence stored in the signature and the renewable archive time stamps. Whether this is enough for a particular legal obligation depends on the law and on the requirements of the receiving authority, so check them for your documents.

7.6 The EU Trusted Lists and the validation of the container

The EU Trusted Lists are the lists published by the Member States with the qualified trust service providers and their services (browse them here). The programs that validate signatures read them to decide whether a certificate is qualified and whether its key was on a QSCD.

Validate the container with the European validator

The European Commission publishes an open validation tool, DSS (Digital Signature Service, part of the eSignature building block), that checks signatures according to the eIDAS rules. You can use it to confirm that a container signed with ASiC Signer carries a correct XAdES signature and to see its level:

1. Open the validation page. Go to ec.europa.eu/digital-building-blocks/DSS/webapp-demo/validation.
2. Select the container. Choose the .asice container.
3. Validate. Keep the default validation policy and start the validation. Read the Simple Report; the Detailed Report and the Diagnostic data explain every check.

The report shows, for each signature:

• the container type (ASiC-E) and the signature format, for example XAdES-BASELINE-B, -T, -LT or -LTA;
• the signer and the certificate chain;
• the signing time or the time of the time stamp;
• the indication of the validation (passed, failed or indeterminate);
• the qualification of the signature. The validator reads the EU Trusted Lists and tells you whether the certificate is qualified and whether its key was on a QSCD. A qualified signature is reported as a qualified electronic signature (QESig); a qualified seal as a qualified electronic seal (QESeal).

Do not upload files with private content to a public service. For confidential files use a validation tool installed on your own computer, or ASiC Viewer (section 14), which checks the signatures without sending anything anywhere.

7.7 Qualified time stamps: qtsa.eu

A time stamp proves that the files existed at a given moment and were not changed since. A qualified time stamp is issued by a qualified trust service provider that is listed in the EU Trusted Lists, and it enjoys, in all the Member States, the presumption of the accuracy of the date and the time (Article 41 of the eIDAS Regulation). Together with a qualified signature or seal it proves both who signed the files and when, with the legal effects described in section 7.1. For the long-term preservation, the qualified time stamp is also the best protection of the archive time stamps.

ASiC Signer can use any time stamp server that follows the RFC 3161 standard, so the product works with qualified time stamps. To add them to your signatures:

1. Get the access data. The provider of the qualified time stamps gives you the address of the server and, usually, a user name and a password.
2. Open the time stamp settings. Select a level that uses a time stamp (XAdES-B-T, -LT or -LTA) and click Time Stamp Settings... (section 8).
3. Type the address and the access data. Write the address in Time Stamp Server URL; tick Time Stamp Server requires authentication and type the user name and the password.
4. Sign. Click OK and sign as usual. Every signature gets a time stamp from the server you set, and the same server is used for the archive time stamps of the Extend operation.

8. Time stamp settings

A time stamp is issued by a Time Stamp Authority (TSA), an independent service. It proves that your signature existed at a given moment and cannot be back-dated. It is used by XAdES-B-T, -LT and -LTA, and by the Extend operation for the archive time stamps. Open the window with Time Stamp Settings... (also in the Tools menu).

9. Signature properties

These properties are added to the signature when a regulation or the receiver requires them. They are optional: by default nothing is added. Click Signature Properties... in the main window (or Tools → Signature Properties...).

The properties you set are summarized next to the Signature Properties... button of the main window.

10. The operations

All the operations are in the list Operation. The first three create new containers; the others work on containers that already exist.

Signing a folder

Choose Sign a folder to sign a folder with its subfolders in one container, for instance a tender with its annexes.

1. Under Source folder choose the folder with the files.
2. Under Destination container choose the container to create. It cannot be inside the signed folder (it would be signed too the next time), and it cannot be one of the signed files.
3. Click Sign. The message tells you how many files were signed.

One container for each file

Choose Sign each file of a folder to sign many files, each one in its own container.

A problem with one file does not stop the others: at the end the program lists the files that failed and why. If the PIN of your smart card is rejected, the operation stops at once, so the card is not locked by repeated wrong attempts.

Co-signing

A container can have several signatures: the two parties of a contract, a manager and an accountant. Each new signature covers all the files, and it does not change the existing ones. Choose Co-sign a container, select the container and your certificate, and click Co-sign.

Extending the archive time stamp

Choose Extend a XAdES-B-LTA container (or the folder version) and click Add Archive Time-Stamp. The certificate button is disabled, because the signing certificate is not used; the program uses the time stamp server of the settings.

11. Creating a test certificate

If you do not have a certificate yet and only want to try the program, ASiC Signer can create a self-signed one. Open Tools → Create a self-signed Digital Certificate... (or the button in the certificate window).

1. Choose where to save it: On Microsoft Certificate Store or On a password protected PKCS#12 PFX file (you will be asked for the file name and a password).
2. Type Issued to (your name, required) and, if you wish, the organization, title, organizational unit, e-mail address and country code.
3. Choose the Validity period (default 3 years), the RSA Key Algorithm length (default 2048 bits) and the Signature Algorithm (default SHA256WithRSA). The defaults are fine.
4. Keep Set as current digital certificate ticked to use it right away, then click OK.

12. Saving your settings

The program remembers your choices (certificate, signature level, hash algorithm, signature properties, time stamp server...) the next time you start it. You can also keep several sets of settings in files — for example one for contracts and one for the archive:

• File → Save Configuration saves the current settings now. They are also saved when you close the program.
• File → Save Configuration As... saves the current settings in a file you name.
• File → Load Configuration... loads them again.
• Tools → Restore Defaults returns everything to the original values (it asks you to confirm first).

The settings are kept in the file configuration.xml, in the folder %APPDATA%\Secure Soft\ASiC Signer\<version> of your Windows account. A saved configuration file is also what the command line uses to sign containers automatically.

13. Batch signatures (automatically made without user intervention)

ASiC Signer can also work without showing its window, for example from a scheduled task, from a script or from another program. Nobody has to click anything: the program reads the settings from a configuration file, does the operation, and closes.

By default, ASiC Signer is installed in the folder C:\Program Files (x86)\Secure Soft\ASiC Signer (on a 32-bit Windows: C:\Program Files\Secure Soft\ASiC Signer) and the program is ASiC Signer.exe.

Command line parameters

"ASiC Signer.exe" create <container> <file1> [<file2> ...]           one container with the files
"ASiC Signer.exe" create-folder <source folder> <container>        one container with all the files of the folder (subfolders kept)
"ASiC Signer.exe" create-each <source folder> <destination folder> one container for each file of the folder
"ASiC Signer.exe" cosign <container | folder> [<output>]            adds a signature to the container(s)
"ASiC Signer.exe" extend <container | folder> [<output>]            adds an archive time stamp to the XAdES-B-LTA container(s)
"ASiC Signer.exe" verify <container | folder>                       verifies the container(s)
"ASiC Signer.exe" <files | folder | container>                      opens the window with them selected
"ASiC Signer.exe" /?                                               shows the help

• /config:<configuration file>: a file saved with File → Save Configuration As.... Every command (except verify) accepts it. When it is not given, the current configuration of the window is used (certificate, signature level, signature properties, time stamp server).
• cosign and extend without <output> update the container(s) in place: a container is replaced only after the new version is verified. The containers of a folder are the *.asice and *.sce files, without the subfolders.
• The container must have the extension .asice or .sce.
• Do not end a path written between quotes with a backslash: write "C:\Folder", not "C:\Folder\". Windows would read the last backslash and quote as one character and the arguments would be mixed up.

Sign files

c:\Program Files (x86)\Secure Soft\ASiC Signer>"ASiC Signer.exe" create C:\Demo\Signed\contract-001.asice C:\Demo\Contracts\contract-001.pdf C:\Demo\Contracts\annex-1.pdf
Signing certificate: Elaine Smith (XAdES-B-B, SHA256)
The container was signed successfully (2 file(s)): C:\Demo\Signed\contract-001.asice

Sign a folder, or each file of a folder

"ASiC Signer.exe" create-folder C:\Demo\Contracts\Tender C:\Demo\Signed\tender.asice
"ASiC Signer.exe" create-each C:\Demo\Contracts C:\Demo\Signed

Co-sign and verify

"ASiC Signer.exe" cosign C:\Demo\Signed\contract-001.asice /config:C:\Demo\accountant.config
"ASiC Signer.exe" verify C:\Demo\Signed
VALID     C:\Demo\Signed\contract-001.asice (2 signature(s))
          signer 1: Michael Brown (issued by Michael Brown)
          signer 2: Anna Lee (issued by Anna Lee)

The long-term archive

Sign the files with a configuration that has the level XAdES-B-LTA and the time stamp server of your provider, and renew the archive time stamps of the whole folder from time to time:

"ASiC Signer.exe" create C:\Archive\contract-001.asice C:\Demo\Contracts\contract-001.pdf /config:C:\Demo\archive.config
"ASiC Signer.exe" extend C:\Archive /config:C:\Demo\archive.config
OK      contract-001.asice -> C:\Archive\contract-001.asice
SKIPPED receipt-2019.asice (no XAdES-B-LTA signature)

Processed: 1 of 2, skipped: 1

Advanced values of the configuration file

The configuration file is a text file (XML) that you can also read with a text editor. These values are written with technical names:

Result codes

ASiC Signer is a Windows application, so the command prompt does not wait for it. To wait and read the result code:

cmd:         start "" /wait "ASiC Signer.exe" extend C:\Archive /config:C:\Demo\archive.config
             echo %errorlevel%

PowerShell:  (Start-Process "ASiC Signer.exe" -ArgumentList 'extend "C:\Archive" /config:"C:\Demo\archive.config"' -Wait -PassThru).ExitCode

Log files

Every container created or changed from the command line is recorded in log.txt, and every error in errorlog.txt. Both are in your user profile, in the folder %APPDATA%\Secure Soft\ASiC Signer\<version> (the last part is a folder named after the version of the program). The error messages are also written in the command window.

14. ASiC Viewer

ASiC Viewer is the second program of the product. Use it to check a container you created or received, and to get the files back.

Opening a container

Start ASiC Viewer, click ... next to ASiC-E container and pick the container (it is opened whatever its extension is: .asice, .sce, or a renamed .zip). You can also open a container with Open with → ASiC Viewer, or from ASiC Signer with Tools → Open ASiC Viewer.

What you see

A container that was changed

If somebody changes a file of the container after it was signed, ASiC Viewer says so clearly, and tells which file was changed:

Buttons

• Show Certificate — opens the Windows certificate window for the selected signer, with all its details.
• Save Report... — saves a text report of the verification, to keep with the archive.
• About... and Quit.

15. The Signature Library behind ASiC Signer

ASiC Signer is an application built on the Signature Library (SignLib), a library for .NET that creates and verifies digital signatures: PDF (PAdES), CAdES / PKCS#7, XML (XAdES), ASiC containers, Office and more. Everything ASiC Signer does is available to your own programs and scripts through the library:

• Library page: https://www.signfiles.com/signature-library/
• Download (library, samples and PowerShell scripts): https://www.signfiles.com/sdk/SignatureLibrary.zip
• Code samples: https://www.signfiles.com/code-samples/

The library works with Windows PowerShell, C#, VB.NET and ASP.NET, on .NET Framework and on the recent .NET versions, and it supports certificates from PFX files, from the Windows store and from smart cards, USB tokens and HSMs.

From the window to the code

ASiC-E containers are created with the class SignLib.Asic.AsicSignature. The table shows what each setting of ASiC Signer is in the library.

The same methods exist for containers in memory (arrays of bytes), for web applications and services. They are shown in section 17.

16. Digitally sign files using Windows PowerShell

The main functions of ASiC Signer are available in the SignLib library, which you can download from this link: https://www.signfiles.com/sdk/SignatureLibrary.zip

To create ASiC-E containers using Windows PowerShell, simply download the library above and inspect the Signature Library\PowerShell Scripts folder. There you find ready-made scripts for the other kinds of signatures; the scripts below do the same for ASiC-E containers: the first one signs files, the second one prepares the long-term archive and renews it.

Sign files in a container

Save it as signAsic.ps1, in the same folder with SignLib.dll. It creates a test PFX certificate on the fly, signs the files in an ASiC-E container (XAdES-B-B, SHA256) and verifies the result.

#digitally sign files in an ASiC-E container (XAdES-B-B), using a PFX certificate created on the fly, and verify the result
#the script can be configured to use an existing PFX file or a certificate loaded from the Windows store (smart card certificate)

if ($args.Length -lt 2)
{
    echo "Usage: signAsic.ps1 <container.asice> <file 1> [<file 2> ...]"
}
else
{
    #SignLib.dll must be in the same folder as the script (or write its full path)
    $DllPath = Join-Path $PSScriptRoot 'SignLib.dll'
    [System.Reflection.Assembly]::LoadFrom($DllPath) | Out-Null

    #create a PFX digital certificate
    $generator = new-object -typeName SignLib.Certificates.X509CertificateGenerator("serial number")
    $pFXFilePassword = "tempP@ssword"
    $generator.Subject = "CN=Your Certificate, E=useremail@email.com, O=Organization"
    $generator.Extensions.AddKeyUsage([SignLib.Certificates.CertificateKeyUsage]::DigitalSignature)
    $generator.Extensions.AddEnhancedKeyUsage([SignLib.Certificates.CertificateEnhancedKeyUsage]::DocumentSigning)

    echo "Create the certificate..."
    $certificate = $generator.GenerateCertificate($pFXFilePassword)

    #create the ASiC-E container with the signed files (XAdES-B-B, SHA256)
    $sign = new-object -typeName SignLib.Asic.AsicSignature("serial number")
    $sign.DigitalSignatureCertificate = [SignLib.Certificates.DigitalCertificate]::LoadCertificate($certificate, $pFXFilePassword)

    echo "Create the container and perform the digital signature..."
    $sign.CreateContainer([string[]]$args[1..($args.Length - 1)], $args[0])

    #verify the container
    $verify = new-object -typeName SignLib.Asic.AsicSignature("serial number")
    echo ("Signatures: " + $verify.GetNumberOfSignatures($args[0]))
    echo ("Valid: " + $verify.VerifyDigitalSignature($args[0]))
    foreach ($name in $verify.GetDataFileNames($args[0])) { echo ("File: " + $name) }
}

How to run it

How to run the Windows PowerShell script from the command line:

powershell -executionPolicy bypass -file d:\signAsic.ps1 d:\contracts.asice d:\contract.pdf d:\annex.pdf

The result in the window:

Create the certificate...
Create the container and perform the digital signature...
Signatures: 1
Valid: True
File: contract.pdf
File: annex.pdf

The long-term archive: sign with XAdES-B-LTA and renew the archive time stamps

Save it as archiveAsic.ps1, in the same folder with SignLib.dll. The first part creates a XAdES-B-LTA container with a time stamp; the second part, that you run later (for example once a year, from the Windows Task Scheduler), adds a new archive time stamp to every container of the archive folder. The signing certificate is not needed for the renewal.

#sign files in an ASiC-E container for the long-term preservation (XAdES-B-LTA, with a time stamp and an archive time stamp)
#and renew the archive time stamp of all the containers of a folder

if ($args.Length -lt 2)
{
    echo "Usage: archiveAsic.ps1 <archive folder> <file to sign> [<file to sign> ...]"
}
else
{
    $DllPath = Join-Path $PSScriptRoot 'SignLib.dll'
    [System.Reflection.Assembly]::LoadFrom($DllPath) | Out-Null

    $timeStampServer = [Uri]"https://ca.signfiles.com/TSAServer.aspx"       #use the server of a qualified provider for qualified time stamps

    #1. sign: XAdES-B-LTA container
    $sign = new-object -typeName SignLib.Asic.AsicSignature("serial number")
    $sign.DigitalSignatureCertificate = [SignLib.Certificates.DigitalCertificate]::LoadCertificate("d:\certificate.pfx", "password")
    $sign.SignatureStandard = [SignLib.Xml.XadesSignatureStandard]::XadesLTA
    $sign.TimeStamping.ServerUrl = $timeStampServer
    $container = Join-Path $args[0] "archive-001.asice"
    $sign.CreateContainer([string[]]$args[1..($args.Length - 1)], $container)
    echo ("Created: " + $container)

    #2. later (for example every year, with the Windows Task Scheduler): renew the archive time stamp of all the containers
    #   the signing certificate is not needed
    $archive = new-object -typeName SignLib.Asic.AsicSignature("serial number")
    $archive.TimeStamping.ServerUrl = $timeStampServer
    foreach ($file in Get-ChildItem -Path $args[0] -Filter *.asice)
    {
        try
        {
            $archive.AddArchiveTimestamp($file.FullName, $file.FullName)
            echo ("Renewed: " + $file.Name)
        }
        catch
        {
            echo ("Error: " + $file.Name + ": " + $_.Exception.InnerException.Message)
        }
    }

    #3. check
    $verify = new-object -typeName SignLib.Asic.AsicSignature("serial number")
    echo ("Valid: " + $verify.VerifyDigitalSignature($container))
}

The result in the window:

Created: d:\archive\archive-001.asice
Renewed: archive-001.asice
Valid: True

17. Digitally sign files using C# or VB.NET

The main functions of ASiC Signer are available in the SignLib library (download). To create ASiC-E containers using C# or VB.NET, download the library, add a reference to SignLib.dll in your project, and inspect the sample projects of the package and the code samples page.

ASiC-E containers are created with the class AsicSignature (namespace SignLib.Asic). It creates containers with XAdES signatures at the four baseline levels B-B, B-T, B-LT and B-LTA (section 7.4), adds signatures (co-signing), renews the archive time stamps and verifies the containers.

All the examples below use these namespaces. Every example was run with the library to check the result.

using System;
using System.Collections.Generic;   // Dictionary<string, byte[]>
using System.IO;
using System.Security.Cryptography.X509Certificates;
using SignLib;                 // HashAlgorithm
using SignLib.Asic;            // AsicSignature
using SignLib.Certificates;    // DigitalCertificate
using SignLib.Timestamping;    // time stamp settings
using SignLib.Xml;             // XadesSignatureStandard, XadesLtvLevel, XadesCommitmentType...

17.1 Create a container and verify the signature

The smallest program: load a certificate from a PFX file, sign the files in a container, and verify it. The signature level is XAdES-B-B and the hash is SHA256, exactly like the defaults of ASiC Signer. The files are not changed; the container is a new file.

// "serial number" is the serial number of the library
AsicSignature asic = new AsicSignature("serial number");
asic.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate(@"C:\Demo\elaine.pfx", "123456");

// create the ASiC-E container with the signed files: the files are not changed
string container = @"C:\Demo\Signed\contract-001.asice";
asic.CreateContainer(new string[] { @"C:\Demo\Contracts\contract-001.pdf", @"C:\Demo\Contracts\annex-1.pdf" }, container);

// verify the container
AsicSignature verifier = new AsicSignature("serial number");
Console.WriteLine("Signatures: " + verifier.GetNumberOfSignatures(container));
Console.WriteLine("Valid: " + verifier.VerifyDigitalSignature(container));
Console.WriteLine("Signer: " + verifier.GetDigitalSignatureCertificate(container, 0).Subject);
foreach (string name in verifier.GetDataFileNames(container))
    Console.WriteLine("File: " + name + " (" + verifier.ExtractDataFile(container, name).Length + " bytes)");

The result:

Signatures: 1
Valid: True
Signer: CN=Elaine Smith, O=Demo Company, C=US
File: contract-001.pdf (245551 bytes)
File: annex-1.pdf (245551 bytes)

The verification is True only when the container has at least one signature, all its signatures are valid and every signature covers all the files: a file that is added to, or changed in, a signed container makes the verification fail. The same example in VB.NET:

Imports System
Imports System.IO
Imports SignLib
Imports SignLib.Asic
Imports SignLib.Certificates
Imports SignLib.Xml

Module Module1
    Sub Main()
        ' "serial number" is the serial number of the library
        Dim asic As New AsicSignature("serial number")
        asic.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate("C:\Demo\elaine.pfx", "123456")
        asic.SignatureStandard = XadesSignatureStandard.XadesB
        asic.HashAlgorithm = HashAlgorithm.SHA256

        'create the container and perform the digital signature
        Dim container As String = "C:\Demo\Signed\contract-001-vb.asice"
        asic.CreateContainer(New String() {"C:\Demo\Contracts\contract-001.pdf", "C:\Demo\Contracts\annex-1.pdf"}, container)

        Dim verifier As New AsicSignature("serial number")
        Console.WriteLine("Signatures: " & verifier.GetNumberOfSignatures(container))
        Console.WriteLine("Valid: " & verifier.VerifyDigitalSignature(container))
        For Each name As String In verifier.GetDataFileNames(container)
            Console.WriteLine("File: " & name)
        Next
    End Sub
End Module

17.2 Signature levels, time stamp and long-term preservation

The level of the signature is chosen with SignatureStandard. The levels that contain a time stamp (XadesT, XadesLT, XadesLTA) need the address of a time stamp server (section 8). For the long-term preservation (section 7.5) use XadesLTA:

AsicSignature asic = new AsicSignature("serial number");
asic.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate(@"C:\Demo\elaine.pfx", "123456");

asic.HashAlgorithm = HashAlgorithm.SHA384;                              // SHA256 (default), SHA384 or SHA512
asic.SignatureStandard = XadesSignatureStandard.XadesLTA;               // XadesB, XadesT, XadesLT or XadesLTA
asic.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");
asic.LtvLevel = XadesLtvLevel.IncludeOcspOnly;                          // the revocation data saved in the LT and LTA signatures

asic.CreateContainer(new string[] { @"C:\Demo\Contracts\contract-001.pdf", @"C:\Demo\Contracts\annex-1.pdf" }, @"C:\Demo\Archive\contract-001.asice");

The time stamp server can be the server of a qualified time stamp authority (section 7.7). If the time stamp server asks for authentication, or you want to set other options of the request, use the other properties of TimeStamping:

asic.TimeStamping.UserName = "user";                      // only if the server requires authentication
asic.TimeStamping.Password = "password";
asic.TimeStamping.UseNonce = true;                        // a random number that protects the request
asic.TimeStamping.HashAlgorithm = HashAlgorithm.SHA256;
asic.MaxCrlSize = 2 * 1024 * 1024;                        // the largest CRL that is included, in bytes (default: 1 MB)

Renewing the archive time stamp (XAdES-B-LTA)

A XAdES-B-LTA signature is made to be kept for many years. After some time, add a new archive time stamp, before the certificate of the time stamp server expires (or its algorithms become weak). The signing certificate is not needed for this, and the new time stamp protects the previous ones, with their validation data. The output can be the input container.

AsicSignature archive = new AsicSignature("serial number");
archive.TimeStamping.ServerUrl = new Uri("https://ca.signfiles.com/TSAServer.aspx");

// the signing certificate is not needed; the output can be the input container
archive.AddArchiveTimestamp(@"C:\Demo\Archive\contract-001.asice", @"C:\Demo\Archive\contract-001.asice");

AsicSignature verifier = new AsicSignature("serial number");
Console.WriteLine("Valid: " + verifier.VerifyDigitalSignature(@"C:\Demo\Archive\contract-001.asice"));

// renew all the containers of an archive folder: a container that fails does not stop the others
foreach (string file in Directory.GetFiles(@"C:\Demo\Archive", "*.asice"))
{
    try
    {
        archive.AddArchiveTimestamp(file, file);
        Console.WriteLine("Renewed: " + Path.GetFileName(file));
    }
    catch (Exception ex)
    {
        Console.WriteLine("Error: " + Path.GetFileName(file) + ": " + ex.Message);
    }
}

The result:

Valid: True
Renewed: contract-001.asice

Run this code from a scheduled task (for example once a year). A container that has no XAdES-B-LTA signature, or a signature that is not valid, is not changed and the error is reported: The container has no XAdES-LTA signature.

17.3 A certificate from the Windows store or a smart card

When the certificate is in the Windows store (for instance, a qualified certificate on a smart card, section 6.2), load it with a search criterion. No window is shown, so the code can run without a user.

AsicSignature asic = new AsicSignature("serial number");

// the first certificate of the current user whose common name (CN) is "Elaine Smith"
// true = only the valid certificates (issued by a trusted authority); false = any certificate, also a self-signed test one
asic.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate(false, DigitalCertificateSearchCriteria.CommonNameCN, "Elaine Smith");

// only for a certificate on a smart card or on a token: the PIN, to avoid the PIN window. It applies to the next
// signature, made on this thread (a software certificate, like this one, does not use a PIN)
// DigitalCertificate.SmartCardPin = "1234";

asic.CreateContainer(new string[] { @"C:\Demo\Contracts\contract-001.pdf" }, @"C:\Demo\Signed\contract-001-store.asice");
Console.WriteLine("Signed with the certificate: " + asic.DigitalSignatureCertificate.Subject);

The result:

Signed with the certificate: CN=Elaine Smith

Other search criteria are the other fields of the subject (OrganizationO, EmailE...), the thumbprint and the serial number of the certificate. To let the user choose the certificate in a Windows window, call DigitalCertificate.LoadCertificate() without parameters.

17.4 Sign a folder, or each file of a folder

The container is created from the names and the contents of the files. A name can contain folders (with /), so a whole folder can be signed in one container and its structure is kept. For a smart card, set the PIN before every signature.

AsicSignature asic = new AsicSignature("serial number");
asic.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate(@"C:\Demo\elaine.pfx", "123456");

// one container with all the files of a folder: the subfolders are kept (annexes/annex-1.pdf)
string folder = @"C:\Demo\Contracts\Tender";
Dictionary<string, byte[]> files = new Dictionary<string, byte[]>();
foreach (string file in Directory.GetFiles(folder, "*", SearchOption.AllDirectories))
    files[file.Substring(folder.Length + 1).Replace('\\', '/')] = File.ReadAllBytes(file);

File.WriteAllBytes(@"C:\Demo\Signed\tender.asice", asic.CreateContainer(files));

AsicSignature verifier = new AsicSignature("serial number");
foreach (string name in verifier.GetDataFileNames(@"C:\Demo\Signed\tender.asice"))
    Console.WriteLine("File: " + name);

// one container for each file of a folder
foreach (string file in Directory.GetFiles(@"C:\Demo\Contracts", "*.pdf"))
{
    try
    {
        // DigitalCertificate.SmartCardPin = "1234";      // for a smart card: before each signature
        asic.CreateContainer(new string[] { file }, Path.Combine(@"C:\Demo\Signed", Path.GetFileName(file) + ".asice"));
        Console.WriteLine("Signed: " + Path.GetFileName(file));
    }
    catch (Exception ex)
    {
        // an error on a file does not stop the other files
        Console.WriteLine("Error: " + file + ": " + ex.Message);
    }
}

The result:

File: tender.pdf
File: annexes/annex-1.pdf
File: annexes/annex-2.pdf
Signed: annex-1.pdf
Signed: contract-001.pdf

17.5 Several signatures in the same container

A container can have several signatures: a new signature covers all the files and it does not invalidate the existing ones. Sign the container again with AddSignature, then check each signature. The index of the signatures starts at 0.

string container = @"C:\Demo\Signed\agreement.asice";

AsicSignature first = new AsicSignature("serial number");
first.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate(@"C:\Demo\manager.pfx", "123456");
first.CreateContainer(new string[] { @"C:\Demo\Contracts\contract-001.pdf" }, container);

AsicSignature second = new AsicSignature("serial number");
second.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate(@"C:\Demo\accountant.pfx", "123456");
second.AddSignature(container, container);                  // the output can be the input container

AsicSignature verifier = new AsicSignature("serial number");
int count = verifier.GetNumberOfSignatures(container);
for (int i = 0; i < count; i++)
    Console.WriteLine("Signature " + (i + 1) + ": " + verifier.GetDigitalSignatureCertificate(container, i).GetNameInfo(X509NameType.SimpleName, false));
Console.WriteLine("All the signatures are valid: " + verifier.VerifyDigitalSignature(container));

// is there a valid signature of this person?
X509Certificate2 manager = DigitalCertificate.LoadCertificate(@"C:\Demo\manager.pfx", "123456");
Console.WriteLine("Signed by the manager: " + verifier.VerifyDigitalSignature(container, manager));

The result:

Signature 1: Michael Brown
Signature 2: Anna Lee
All the signatures are valid: True
Signed by the manager: True

(X509NameType and X509Certificate2 are in the namespace System.Security.Cryptography.X509Certificates.)

A changed container

If a file is modified after the signature, the verification returns False. The example replaces the content of a file in a copy of the container (a container is a ZIP file; it needs a reference to System.IO.Compression.FileSystem and the namespace System.IO.Compression):

string changed = @"C:\Demo\Signed\agreement-changed.asice";
File.Copy(container, changed, true);
using (ZipArchive zip = ZipFile.Open(changed, ZipArchiveMode.Update))
{
    ZipArchiveEntry entry = zip.GetEntry("contract-001.pdf");
    using (Stream stream = entry.Open())
    {
        stream.SetLength(0);
        byte[] other = Encoding.ASCII.GetBytes("changed content");
        stream.Write(other, 0, other.Length);
    }
}
Console.WriteLine("Valid: " + new AsicSignature("serial number").VerifyDigitalSignature(changed));
// Valid: False

17.6 Containers in memory

Web applications and services often have the files and the containers in memory, not on disk. All the methods have a version with arrays of bytes: CreateContainer (with a dictionary of names and contents), AddSignature, AddArchiveTimestamp, VerifyDigitalSignature, GetNumberOfSignatures, GetDataFileNames and ExtractDataFile.

AsicSignature asic = new AsicSignature("serial number");
asic.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate(@"C:\Demo\elaine.pfx", "123456");

// the files are in memory (for example, uploaded to a web application): name in the container and content
Dictionary<string, byte[]> files = new Dictionary<string, byte[]>();
files["report.txt"] = Encoding.UTF8.GetBytes("Quarterly report");
files["data/figures.csv"] = Encoding.UTF8.GetBytes("a;b\n1;2");

byte[] container = asic.CreateContainer(files);

// add a signature, check the container and extract a file, always in memory
AsicSignature second = new AsicSignature("serial number");
second.DigitalSignatureCertificate = DigitalCertificate.LoadCertificate(@"C:\Demo\manager.pfx", "123456");
container = second.AddSignature(container);

AsicSignature verifier = new AsicSignature("serial number");
Console.WriteLine("Signatures: " + verifier.GetNumberOfSignatures(container) + ", valid: " + verifier.VerifyDigitalSignature(container));
Console.WriteLine("report.txt: " + Encoding.UTF8.GetString(verifier.ExtractDataFile(container, "report.txt")));

(Encoding is in the namespace System.Text.) The result:

Signatures: 2, valid: True
report.txt: Quarterly report

17.7 More options of the signature

These options are the Signature Properties of the window (section 9). They add information to the signature when a regulation or the receiver requires it.

// the commitment declared by the signer: approval, origin, receipt...
asic.CommitmentType = XadesCommitmentType.ProofOfApproval;

// the place where the signature was created
asic.SignatureProductionPlace = new XadesProductionPlace { City = "Bucharest", CountryName = "Romania" };

// an explicit signature policy: identifier (OID or URI), digest of the policy document, the algorithm of the digest, the address of the policy
asic.SetSignaturePolicyInformation("2.16.724.1.3.1.1.2.1.9", policyHash, "SHA256", "https://example.com/policy.pdf");

17.8 How the container looks

A container is a ZIP file. The entries below are those of a container with two files and one XAdES-B-LTA signature (the sizes depend on the files). mimetype is the first entry and it contains the type of the container:

mimetype                  (31 bytes)     application/vnd.etsi.asic-e+zip
contract.pdf              (245551 bytes)
annex.pdf                 (245551 bytes)
META-INF/manifest.xml     (471 bytes)
META-INF/signatures.xml   (12286 bytes)

The manifest lists the files and their types:

<?xml version="1.0" encoding="utf-8"?>
<manifest:manifest manifest:version="1.2" xmlns:manifest="urn:oasis:names:tc:opendocument:xmlns:manifest:1.0">
  <manifest:file-entry manifest:full-path="/" manifest:media-type="application/vnd.etsi.asic-e+zip" />
  <manifest:file-entry manifest:full-path="contract.pdf" manifest:media-type="application/pdf" />
  <manifest:file-entry manifest:full-path="annex.pdf" manifest:media-type="application/pdf" />
</manifest:manifest>

The signature file contains the XAdES signature. This is its structure (the values are omitted). The signed properties (the signing time, the certificate of the signer, the type of every file) are protected by the signature; the time stamp, the certificates and the archive time stamps (two, after one renewal) are added to it as unsigned properties:

asic:XAdESSignatures
  Signature
    SignedInfo                         (a reference to every file and to the signed properties)
    SignatureValue, KeyInfo
    Object
      xades:QualifyingProperties
        xades:SignedProperties
          xades:SignedSignatureProperties
            xades:SigningTime
            xades:SigningCertificateV2
          xades:SignedDataObjectProperties
            xades:DataObjectFormat    (one for every file)
        xades:UnsignedProperties
          xades:UnsignedSignatureProperties
            xades:SignatureTimeStamp          (XAdES-B-T and above)
            xades:CertificateValues           (XAdES-B-LT and above)
            xades:RevocationValues            (when the certificate has OCSP or CRL)
            xades141:ArchiveTimeStamp         (XAdES-B-LTA: one more for every renewal)

17.9 Good to know

18. Problems and solutions

19. Glossary

20. Warning and disclaimer, trademarks

Every effort has been made to make this manual as complete and accurate as possible, but no warranty or fitness is implied. The information provided is on an “as is” basis. The author shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this manual. The information about the eIDAS Regulations and about the long-term preservation is a simplified explanation and it is not legal advice.

.NET, Windows, PowerShell, SmartScreen and Visual Studio are trademarks of Microsoft Corporation. All other trademarks are the property of their respective owners.