Signing PDFs using GlobalSign® Atlas™ * and ABCpdf .NET

 

Wednesday, February 1, 2023

Signing PDFs using GlobalSign Atlas in C# under .NET. This is a secure process and the setup can be quite involved if you are not familiar with it. To help you, we have produced this guide to accompany the ABCpdf .NET GlobalSign example project. Just follow the simple instructions and you will be producing cloud signed documents in no time flat!

 

GlobalSign is one of the largest and most trusted certificate authorities in the world. Find out more on their web site.

ABCpdf comes with a GlobalSign example project showing how to sign PDF documents using a GlobalSign Atlas account.

You will need a GlobalSign account to use the ABCpdf GlobalSign example project. You can get an account and request a trial pack of GlobalSign digital signatures.

You will need to download and install ABCpdf .NET. You will find the GlobalSign example project in the Examples folder under the ABCpdf Windows Start Menu item.





Download Free Trial

You can ask GlobalSign to provide you with a trial signature pack which will allow you to sign documents using untrusted certificates.

Using a trial pack your certificates will be valid, but not trusted. So you would need to explicitly trust the demo account certificate to see a more representative test result.

If you are using a demo account the issuer of the certificates will typically be GlobalSign Non-Public HVCA Demo.

Once you are happy that the trial signature pack is working as you would expect, you can upgrade to a live account.

Roughly What Do I Need?

 

Once you have your trial pack or live account, you will need to set up a secure channel to GlobalSign. For access to the GlobalSign REST interfaces you need an mTLS custom certificate trusted by GlobalSign.

The creation of this certificate takes a bit of time but is not difficult as long as you follow the instructions carefully.

During the production of this certificate you will also be creating an API name and password to access your account.

There will be four outputs from this process:

  • A .PFX certificate file used for secure REST communication
  • A password for the .PFX
  • An API key used to identify your usage
  • An API secret - a password for the API key

The ABCpdf .NET GlobalSign project needs to be adjusted to include your values for these four outputs.

So How Do I Do This?

 

To create this you will need OpenSSL. There are various pre-built downloads available such as those from Shining Light Productions.

If you are unsure about the provenance of your download, a simple way to ensure security is to run it in the Windows Sandbox.

OpenSSL implementations do vary a bit, so if you are using a different build or a very different version you may get slightly different behavior.

GlobalSign provide their own instructions for this process. Here we present a more procedural approach specific to the ABCpdf GlobalSign example project.

Here we are going to generate a key called wsg. You may wish to change this name to something more appropriate to your organization.

Open a command line prompt and run the following.

"C:\Program Files\OpenSSL-Win64\bin\openssl" req -out wsg.csr -new -newkey rsa:2048 -keyout wsg.key

OpenSSL will ask you for various pieces of organization information.

Many pieces of information are optional and can be left blank. Some you may wish to provide.

It will also ask for a PEM pass phrase (password) which you should keep safe.

The wsg.key file is your private key and should be kept by you. The password relates to this file.

The wsg.csr file is a Certificate Signing Request which you need to present to GlobalSign Atlas so that it can generate a certificate for you.

GlobalSign Atlas Portal

You will now need to sign into the GlobalSign Atlas portal.

API Credentials

Go to the "API Credentials" section and create a new API credential linked to your account.

This will provide you with two things:

  • An API key sixteen characters long
  • An API secret forty characters long

These are the first and second of the four items you will need.

mTLS Certificates

Go to the "mTLS Certificates" section.

Generate a new mTLS certificate selecting the "Directly via the API" option.

Select your API Credential.

At this point GlobalSign Atlas will ask for your CSR. Open your wsg.csr file in notepad and copy the contents into the site.

You will get two products returned.

The first is an mTLS certificate which is presented as text. Copy this text and paste it into a file called "wsg.crt".

The second is the Intermediate Certificate Authority, a file with a rather random name which we will rename as a "globalsign_ica.crt"

Back to OpenSSL

Open your command prompt again and run the following,

"C:\Program Files\OpenSSL-Win64\bin\openssl" pkcs12 -export -out wsg.pfx -inkey wsg.key -in wsg.crt -certfile globalsign_ica.crt

The result is the "wsg.pfx" file which you can use for communication over the REST interfaces.

The PFX and the password you created for it are the third and fourth of the four items you need.

Where Do These Bits Go?

 

The PFX file need to be added to the top level folder of the ABCpdf GlobalSign project - the folder in which the file GlobalSign.csproj is located.

The Program.cs file needs to be altered to add in the PFX password, the API key and the API secret.

After you have altered the Program.cs file, it will look something like this.

static Rest rest = new Rest("jl6ago81tuvbhbgv", "cr7xjbkng0xsabkm2wmbvxrtpbia6zpubraihsu8", "wsg.pfx", "password");

static void Main(string[] args) {
if (rest.Dir == null) {
Console.WriteLine($"Unable to find pfx file. See Notes.rtf for what to do.");
...

At this point you can run the code to produce a signed PDF.

Finally adapt the code to your needs and integrate into your solution.

* GlobalSign, GlobalSign Atlas and associated logos are trademarks, registered trademarks or service marks of GlobalSign or its group company.