PKI Proxy Getting Started

Requirements: PKI Proxy

Introduction
Sharing a Certificate
Client PKCS#11 Driver
Code Signing
- Jarsigner
- SignTool (Authenticode)
PDF Signing
- Adobe Reader

Introduction

PKI Proxy allows you to remotely sign code, documents and drivers using your own keys via a secure API. Utilizing our proprietary PCKS#11-compliant driver and self-hosted API, the private key remains securely on a single machine under your control while document or driver signing operations can occur nearly anywhere.

Both file-based certificates (PFX files) as well as hardware tokens are supported. All communication takes place via TLS and makes use of simple access controls.

Sharing a Certificate

PKI Proxy allows selecting PFX files, certificates installed to the Windows certificate store, and certificates stored on hardware tokens (PKCS#11). Access is controlled selecting which users can access the certificate.

To select the certificate to share, navigate to the Certificates tab and click the New button. Within this dialog the Select Certificate button will open a new dialog to pick the desired certificate.

PFX Files

For PFX files, simply select the PFX File tab and browse to the PFX location on disk, enter the password and choose appropriate certificate from the list.

Windows Certificate Store

PKI Proxy supports selecting certificates installed to either the System certificate store or the current user's certificate store. From either the System Store or User Store select the desired certificate from the list.

Hardware Tokens / PKCS#11

For hardware tokens, on the Security Key tab first browse to the PKCS#11 driver provided by your hardware token manufacturer. This driver may be installed with tools provided by your hardware token manufacturer or may be provided as a separate download. For instance the "SafeNet Authentication Client" software used by many certificate authorities will install a PKCS#11 library at C:\Windows\System32\eTPKCS11.dll. Yubikeys are supported via the libykcs11.dll which is included with the Yubico PIV Tool.

Configure Access

After selecting a certificate, click the Add button in the Allowed Users section to add an existing user, or create a new user.

If no users have been created select the Create New User ... option from the dropdown.

Follow the steps on the New User dialog to define a user and grant access to the certificate.

Finally, press OK to start sharing the certificate.

Client PKCS#11 Driver

The PKI Proxy PKCS#11 Driver provides a standardized client-side access mechanism to certificates shared using PKI Proxy. Any third-party application that knows how to work with PKCS#11 can be used with this driver to create signatures with such certificates. PKI Proxy includes two versions of the driver, applicable for x64 and x86 applications:

pkcs11/win32/pkiproxy_pkcs11.dll
pkcs11/win64/pkiproxy_pkcs11.dll

Generally, there are no requirements for PKCS#11 drivers to be installed to a specific location (such as a directory included in PATH), meaning you can use it from the directory where it was installed, or copy/rename it to any location you find convenient.

Configuring the Driver

Prior to using the driver, a configuration file (.conf) must be set up so the driver knows how to communicate with the server. You can find the .conf file next to the pkiproxy_pkcs11.dll. For instance: C:\Program Files\PKI Proxy\pkcs11\win64\pkiproxy_pkcs11.conf


# The online location of the shared certificate.
#
# Please check that the endpoint is reachable and/or
# allowed through the firewall if accessing 
# the certificate over the Internet.

Location = https://127.0.0.1:9266

# Access credentials: These credentials should match the credentials 
# configured in the PKI Proxy server application.

KeyId = User
KeySecret = User_Secret_Access_Key

# TrustedTLSCerts should match the fingerprint of the Transport Layer Security (TLS) certificate, 
# as configured in the PKI Proxy service. For instance:
#
#   TrustedTLSCerts = 68D2E3D6A0FE5FEA72E25AD56706270F9F8B182A

TrustedTLSCerts = TLS_Fingerprint_From_PKI_Proxy

# The optional PIN setting configures the driver to request a PIN
# from any application that uses the PKCS#11 driver. When set, a 
# connecting application must specify the PIN that matches the value
# set here. If not set (default), no PIN is required. 
# 
# Note: This PIN is exchanged only between the connecting application 
# and the PKCS#11 driver. It is not used to access the shared certificate.

#PIN = 12345

# Log file location uncomment to enable logging.
#
# Provide the required verbosity level. Possible values are as follows:
#  0 - None
#  1 - Error
#  2 - Warning
#  3 - Info (Default)
#  4 - Verbose
#  5 - Debug

#LogFile = C:\temp\pkiproxy.log
#LogDetail = 5

When editing the file, fill in the KeyId with one of the users that you granted access to the key and the KeySecret with their Secret Access Key. To get the fingerprint for the TrustedTLSCerts value, check the settings page of PKIProxy:

Code Signing

One of the primary use cases for PKI Proxy is code signing. When the certificate is present only on a single machine, PKI Proxy allows other machines to perform code signing without direct access to the certificates. The sections below detail the most common code signing scenarios.

Jarsigner

The Jarsigner utility supports using PKCS#11 natively. By configuring Jarsigner to use the PKI Proxy PKCS#11 Driver signing can be performed relatively simply. To configure Jarsigner to use the PKI Proxy PKCS#11 Driver a configuration file must be created with contents like in the example below. This file tells Jarsigner which PKCS#11 driver to use. Save this file in a convenient location. The name of this file is not important, and this article will use jarsigner.config.

jarsigner.config Example


name = PKIProxy
library = "C:\\Program Files\\PKIProxy\\pkcs11\\win64\\pkiproxy_pkcs11.dll" 
description = PKIProxy PKCS#11 Driver
slot = 0

Jarsigner Execution

In the command below MyAlias is the alias of the certificate defined in PKI Proxy when the certificate was initially selected. The alias/label should either be double quoted, or unquoted. Single quotes around this value are not supported by Jarsigner. For example:


jarsigner
  -verbose
  -tsa http://timestamp.digicert.com
  -keystore NONE
  -storetype PKCS#11
  -providerClass sun.security.pkcs11.SunPKCS11
  -providerArg C:\path\to\jarsigner.config
  -storepass anything 
  -sigalg SHA256withRSA 
  MyApp.jar 
  MyAlias

If signing succeeded you should see output from Jarsigner like below:


>>> Signer
    X.509, CN=/N SOFTWARE INC., O=/N SOFTWARE INC., ST=North Carolina, C=US
    [certificate is valid from 1/12/23 7:00 PM to 1/12/26 6:59 PM]
    X.509, CN=Sectigo Public Code Signing CA R36, O=Sectigo Limited, C=GB
    [certificate is valid from 3/21/21 8:00 PM to 3/21/36 7:59 PM]
    X.509, CN=Sectigo Public Code Signing Root R46, O=Sectigo Limited, C=GB
    [certificate is valid from 5/24/21 8:00 PM to 12/31/28 6:59 PM]
    X.509, CN=AAA Certificate Services, O=Comodo CA Limited, L=Salford, ST=Greater Manchester, C=GB
    [trusted certificate]
>>> TSA
    X.509, CN=DigiCert Timestamp 2022 - 2, O=DigiCert, C=US
    [certificate is valid from 9/20/22 8:00 PM to 11/21/33 6:59 PM]
    X.509, CN=DigiCert Trusted G4 RSA4096 SHA256 TimeStamping CA, O="DigiCert, Inc.", C=US
    [certificate is valid from 3/22/22 8:00 PM to 3/22/37 7:59 PM]
    X.509, CN=DigiCert Trusted Root G4, OU=www.digicert.com, O=DigiCert Inc, C=US
    [certificate is valid from 7/31/22 8:00 PM to 11/9/31 6:59 PM]

jar signed.

The signer certificate will expire on 2026-01-12.
The timestamp will expire on 2031-11-09.

SignTool (Authenticode)

Authenticode signatures can be used to sign Windows libraries and executables. The Windows Platform SDK includes a signtool.exe utility used to create these types of signatures, however it does not directly support the use of PKCS#11. PKI Proxy includes a similar tool called pkpsigntool.exe which natively supports creating Authenticode signatures and adds support for PKCS#11 drivers.

To sign a library or executable with pkpsigntool use the following syntax:


pkpsigntool 
  sign 
  /d "PKI Proxy Signature" 
  /fd sha256 
  /f "C:\Program Files\PKI Proxy\pkcs11\win64\pkiproxy_pkcs11.dll" 
  /tr http://timestamp.server.com
  /td sha256 
  /ac ca.pem
  /ac root.pem
  App.exe

The parameters are designed to be as similar to the Windows SDK's SignTool as possible. Supported parameters include:

Param	Description
`/d`	Specifies the short description string that is embedded into the signature.
`/fd`	Specifies the digest algorithm to use for signing, for instance `sha256`.
`/f`	Specifies the path to the 64-bit PKI Proxy PKCS#11 driver to use.
`/tr`	Specifies the RFC 3161 compatible timestamp server to use.
`/td`	Specifies the digest algorithm to use for timestamping, for instance `sha256`.
`/ac`	Specified a certificate file to be added to the signature block. This is typically used to include intermediate and root CA certificates.
`/p`	Specifies a PIN, if required. If the driver is configured to require a PIN from connecting applications, the PIN can be specified by setting this parameter.

If the sign command is successful you will see output like:


Opening PKCS#11 storage...
Storage opened, looking for a non-empty slot...
Token found in slot #0 (PKI Proxy Certificate Adapter 0)
Logged in, looking for the certificate
Signing using certificate: CN=\/N SOFTWARE INC. (expires: 9/27/2025 12:00:00 PM)
Requesting an RFC3161 timestamp from http://timestamp.digicert.com
Timestamp received and embedded into the signature
SUCCESS: App.exe
All files have been processed successfully

The signature of the library or executable can be verified by right clicking the file in Windows Explorer, selecting Properties, and inspecting the Digital Signatures tab.

PDF Signing

Another common use case for PKI Proxy is PDF signing. Once again, PKI Proxy allows you to share a certificate with other machines so they can perform PDF signing without direct access to the certificate.

Adobe

You can use PKI Proxy to sign PDFs with Adobe products by registering the PKI Proxy PKCS#11 DLL:

First, disable Protected Mode by navigating to Edit -> Preferences -> Security (Enhanced), and unchecking "Enable Protected Mode at startup", then restarting the application.
To add the driver, go to Edit -> Preferences -> Signatures, and click the "More..." button opposite the "Identities and Trusted Certificates" section. In the dialog window that appears, click on "PKCS#11 Modules and Tokens" in the tree on the left, then click the "Attach Module" button at the top. Select the win32 variant of the PKI Proxy driver (at "C:\Program Files\PKI Proxy\pkcs11\win32" by default) to match the architecture of the application. After this step, the virtual device should be added to the list under the "PKCS#11 Modules and Tokens" branch:

Click on the middle entry ("PKI Proxy Certificate Adapte-" in the example above), and then on the "Login" button at the top. If the driver configuration file (pkiproxy_pkcs11.conf) enables PIN protection for the driver, please provide the PIN when asked. If PIN protection is not enabled any value may be used.
Finally, select the last entry in the list ("PKI Proxy Certificate Adapter 0" in the example). In the right panel, click on the certificate entry, then click the "Usage Options" button at the top and check the "Use for Signing" option.

To sign a PDF document, navigate to the signing facility of your PDF application. In Adobe Reader you can access it by clicking the "More Tools" button on the panel on the right, then selecting the "Certificates" applet in the list.

On the "Certificates" panel, click on the "Digitally Sign" button and draw the area where you want to place the signature:
Select the shared certificate in the list that appears. It should have the "PKCS#11 device" marker in brackets to the left of its subject string. Click "Continue".
Click "Sign" and specify the location where you want to save the signed document.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.