Skip to main content
Version: 1.3

GlobalSign cryptographic provider

The GlobalSignDss cryptographic provider enables access to the GlobalSign Digital Signing Service (GlobalSign DSS). The service can then be used to perform cryptographic functions such as sign a document. This provider requires a GlobalSign DSS account. Accounts with static and dynamic identities are supported.

Quick start

Download the full sample now in C# and Java.

Interested in C or other language samples? Let us know on the contact page and we'll add it to our samples backlog.

The GlobalSign DSS provides signing certificates and basic cryptographic (PKCS#1) signatures. Additional certificates such as issuer certificates are stored in the Certificates directory. These certificates are required when adding validation information to signatures that do not have the full trust chain embedded. The certificates directory may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form.

In this example, the GlobalSignDss cryptographic provider is used to apply a document approval signature to a PDF document. The signing certificate is loaded from the GlobalSign DSS. An account that supports dynamic identities is used. The signing certificate is identified by passing the common name of the certificate. Information required for long-term signature validation (LTV) is embedded in the output PDF.

Steps to sign a document:

  1. Configure the HTTP client handler.
  2. Connect to GlobalSign DSS.
  3. Create the document signature.
  4. (Optional) Add long-term validation information.
  5. Open and sign the document.
Before you begin

You need to initialize the library.

Configuring the HTTP client handler​

When using the GlobalSignDss cryptographic provider, you need to configure the HttpClientHandler with the SSL client certificate, private key, and password from your GlobalSign DSS account.

// Configure the SSL client certificate to connect to the GlobalSign DSS service
var httpClientHandler = new HttpClientHandler();
using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.cer"))
    using (var sslClientKey = File.OpenRead(@"C:\path\to\privateKey.key"))
    httpClientHandler.SetClientCertificateAndKey(sslClientCert, sslClientKey, password);

Connecting to GlobalSign DSS​

The next step is to open a Session to the GlobalSign DSS by logging in with the API key and secret from your GlobalSign DSS account. The Session object provides access to the certificates and private keys stored by GlobalSign. In this example, the default URI for the GlobalSign DSS is used.

Advice on using the service​

Whenever you create a new GlobalSign Session, a login is performed. In this session, signatures can be created using different identities, i.e. signing certificates, which are created as they are needed. Both signing sessions and signing certificates expire after 10 minutes.

There are rate limits for both creating new identities and for signing operations. If multiple documents must be signed at once, you should re-use the same session (and hence its signing certificates) for signing.

Due to the short-­lived nature of the signing certificates, it is important to embed revocation information immediately. For example, by using AddValidationInformation or EmbedRevocationInfo. Furthermore, it is highly recommended to embed a timestamp to prove that the signature was created during the certificate’s validity period.

// Connect to the GlobalSign Digital Signing Service
using var session = new GlobalSignDss.Session(new Uri("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler);

Creating the document signature​

In this step, the Session object is used to create a signature configuration for a GlobalSign DSS account that supports dynamic identities. The signing certificate is identified by passing the common name of the certificate. The signature configuration may be used to sign one or more documents.

tip

If multiple documents must be signed at once, you should re-use the same session (and hence its signing certificates) for signing.

// Create a signing certificate for an account with a dynamic identity
// This can be re-used to sign multiple documents
var identity = JsonSerializer.Serialize(new { subject_dn = new { common_name = commonName } });
var signature = session.CreateSignatureForDynamicIdentity(identity);

Adding long-term validation information​

As an optional step, long-term validation information can be added to the output document. It embeds revocation information such as online certificate status response and certificate revocation lists. Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing.

// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;

Opening and signing the document​

After opening the Session and creating the signature configuration, you are ready to apply the digital signature to a document.

The input and output PDF documents are created as streams (in this example, as file streams). The Signer object is used to apply the digital document signature.

Non-critical processing errors raise a Warning event. It is recommended to listen for these events, and review the WarningCategory to determine if further action is needed.

// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);

// Create a stream for the output file
using var outStr = File.Create(outPath);

// Create the Signer object
Signer signer = new Signer();

// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);

// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);

Full example​

// Configure the SSL client certificate to connect to the GlobalSign DSS service
var httpClientHandler = new HttpClientHandler();
using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.cer"))
    using (var sslClientKey = File.OpenRead(@"C:\path\to\privateKey.key"))
    httpClientHandler.SetClientCertificateAndKey(sslClientCert, sslClientKey, password);

// Connect to the GlobalSign Digital Signing Service
using var session = new GlobalSignDss.Session(new Uri("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler);

// Create a signing certificate for an account with a dynamic identity
var identity = JsonSerializer.Serialize(new { subject_dn = new { common_name = commonName } });
var signature = session.CreateSignatureForDynamicIdentity(identity);

// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;

// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);

// Create a stream for the output file
using var outStr = File.Create(outPath);

// Create the Signer object
Signer signer = new Signer();

// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);

// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);