Security

General Security Notes

PKI Proxy enables remote code and document signing using centrally stored keys. Multiple layers of security protect your keys and data.

Secure at Rest

Your private keys never leave their storage location. Whether your private key resides in a file, the Windows certificate store, or on a USB token or in a hardware security module (HSM), the key is never exported from its original location. PKI Proxy communicates with HSMs directly, allowing it to perform security operations without exposing the signing key.

Any sensitive data used by PKI Proxy are encrypted using DPAPI and stored securely in the registry. Only the profile owner can decrypt this data. PKI Proxy settings are stored in the registry at HKEY_CURRENT_USER\SOFTWARE\nsoftware\PKIProxy. The Users key makes use of a Credential string value which holds the DPAPI encrypted user's password when the authentication type is set to Basic or Secret Key. This is not applicable to NTLM. The Certificates key makes use of a Credential string value which holds the DPAPI encrypted certificate password (for file-based certificates) or the PIN for HSM-based private keys. Additionally, the server's TLS certificate password is DPAPI encrypted and stored in the TLSCertPass string value.

Secure in Transit

All data exchanged between PKI Proxy and a connected client are encrypted using Transport Layer Security (TLS). Whether the client is the included PKCS#11 driver, the included KSP module, or a direct connection using the Web API, the communication is protected by TLS.

Access Control and Authentication

Users must authenticate to PKI Proxy in order to perform any operations with the shared certificates. Users are created within the PKI Proxy application and can be assigned any of the following authentication methods:

When a certificate is shared, only the users which have been allowed access to that specific certificate may perform operations with it. User access can be granted or modified from the PKI Proxy application on the Certificates tab.

The application also creates a detailed log of all operations, which can be configured on the Settings tab.

Running PKI Proxy

Getting Started

The PKI Proxy application controls which keys are shared, and which users have access to the shared keys. Run the PKI Proxy application by following the links in the start menu, or by running PKIProxy.exe from the installation directory. The Server Configuration page provides details about how to enable TLS, share a certificate, and manage users.

Clients can access PKI Proxy from local or remote locations using the included PKCS#11 driver, configuring the included Key Storage Provider (KSP), or by using the Web API directly.

In most cases, the KSP is the simplest mechanism to enable remote access, since certificates will be visible and usable from the Windows certificate store on the client machine. The Client Configuration (KSP) page provides additional details about KSP configuration.

The cross-platform PKCS#11 driver supports Windows, Linux, and macOS and provides an alternative access mechanism which only requires copying a few files to the client machine. The Client Configuration (PKCS#11) page provides additional details about PKCS#11 configuration.

Server Configuration

Configuring the Server

The PKI Proxy Service is responsible for making local signing keys available to applications residing outside the system. The Settings tab contains settings for the server itself. You can enable or disable TLS, generate or select a TLS certificate, and choose which port the server will use.

Managing Users

The list of users that may access PKI Proxy can be managed on the Users tab. Click 'New...' to create a new user. Users must authenticate to PKI Proxy in order to perform any operations with the shared certificates. Users are created within the PKI Proxy application and can be assigned any of the following authentication methods:

When a certificate is shared, only the users which have been allowed access to that specific certificate may perform operations with it. User access can be granted or modified from the PKI Proxy application on the Certificates tab.

Sharing a Certificate

PKI Proxy allows selecting PFX files, certificates installed to the Windows certificate store, and certificates stored on hardware tokens (PKCS#11). To share a certificate, navigate to the Certificates tab. Click the 'New...' button to select a certificate to share. This will open a dialog window where you can select the certificate.

PFX File

For PFX files, simply select the PFX File tab and browse to the PFX location on disk, enter the password and choose the 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. Navigate to either the System Store or User Store tab and 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.

Configure Access

Once you have selected the certificate to be shared and provided an optional alias (e.g., 'Driver signing'), click the Add... button to select users that will have access to the certificate, then click OK to complete the setup.

Configuring startup mode

PKI Proxy has 2 startup settings that you can combine to match your circumstances best. You can set PKI Proxy to "Run as a system service" and/or "Run on system startup". You will find the respective controls at the bottom of the Settings tab of the administration console.

By switching the 'Run as a system service' checkbox you can configure the PKI Proxy sharing server to work as a user-mode background process (the default mode) or a system service. The second option may be useful if you want to run PKI Proxy on an unmanned server.

By default, PKI Proxy registers the service to run under the Local System account. However, if you want to share certificates from a user's Personal system certificate store, you will need to change the service to run under that user's account (from the Windows Services app). A service that runs under the local system or a different account won't be able to see them.

Enabling "Run at system startup" will cause the sharing server and administration console to start automatically when you sign into the system. An entry will be added at "Computer\HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run" telling Windows to run PKI Proxy at startup, and if "Run as a system service" is also enabled, the service will be set to "Automatic".

Remember to restart the PKI Proxy service after making any changes to the startup mode, including the change of the user account in the Services applet.

Client Configuration (KSP)

General Information

The PKI Proxy Key Storage Provider (KSP) module is a Windows component that enables seamless integration of certificates from a remote PKI Proxy server with the local Windows environment. This provider allows PKI Proxy certificates to appear in the Windows certificate store, enabling third-party applications to access and utilize them as if they were locally stored. Any application that can work with certificates in the local Windows certificate store can transparently use PKI Proxy certificates.

The KSP module is installed during the setup process. After installation the PKIProxyKSP.dll library should be present in both C:\Windows\System32 and C:\Windows\SysWOW64.

Certificates shared by PKI Proxy are not exposed automatically by the KSP. Use the PKIProxyCertMgr.exe application present in the installation directory of PKI Proxy to add, remove, or view remote certificates currently mapped to the Windows certificate store.

Adding a Certificate

Click the Add button to add a PKI Proxy certificate to the Windows certificate store. The Add Certificate dialog provides options to configure the URL of the PKI Proxy application, as well as user credentials.

The following configuration options are available in this dialog.

When configuration is complete, use the Test Connection button to confirm successful communication between the client side and the PKI Proxy Server. After pressing OK, the certificate shared by PKI Proxy should be visible in the Current User's "Personal" certificate store in Windows.

Modifying Certificate Properties

Use the Edit button to update the certificate access properties, such as the access credentials, TLS certificate fingerprint, or logging options.

Removing the Certificate from the Windows Certificate Store

Click the Delete button to remove a PKI Proxy certificate from the Windows store. This does not delete the remote certificate. This operation only removes the certificate from the Windows store.

Disabling a Certificate

Use the Disable button to temporarily disable operations using the configured certificate. The certificate will continue to be visible in the Windows store but cannot be used for any cryptographic operations. Click the Enable button to re-enable the certificate.

Client Configuration (PKCS#11)

General Information

The PKI Proxy PKCS#11 driver provides a standardized client-side access mechanism to certificates shared using the PKI Proxy Web API. Any third-party application that knows how to work with PKCS#11 can be used with this driver to perform signing.

PKI Proxy includes four versions of the driver, which are applicable for 32- and 64-bit Windows applications, as well as for 64-bit Linux and macOS programs:

• pkcs11/win32/pkiproxy_pkcs11.dll
• pkcs11/win64/pkiproxy_pkcs11.dll
• pkcs11/linux64/pkiproxy_pkcs11.so
• pkcs11/mac64/pkiproxy_pkcs11.dylib

When referencing the driver, please use the driver version that matches the architecture of your application.

Installing the Driver

Generally, there are no requirements for PKCS#11 drivers to be installed to a specific location, so it can be used from the default installation directory. However, some applications may require that you copy the driver to one of the standard locations (such as C:\Windows\System32) or add the installation directory to the PATH environment variable.

Configuring the Driver

The driver can be configured by creating a configuration file and placing it in the same folder as the DLL, with the file name matching the name of the driver DLL and a '.conf' extension. For instance, pkcs11/win32/pkiproxy_pkcs11.conf.

The following is an example of the contents of the configuration file:

# This file contains settings for the PKI Proxy PKCS#11 driver. 
# Please adjust the below parameters to match the actual settings
# of the PKI Proxy sharing application. 

[driver]

# Location is the URL where PKI Proxy is running.
#
# Please check that the endpoint is reachable and/or
# allowed through on 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 for the certificate.
#
# The current version supports the following types of access credentials:
# Secret Key, HTTP Basic, and HTTP NTLM. The authentication type
# to use can be specified via the Auth configuration setting.
#
# 1. Secret Key
#
# In this mode you need to provide a pair of credentials via the User
# and SecretKey parameters. These parameters should match those set up
# for the certificate on the server side. For instance:
#
#   Auth = SecretKey
#   User = user
#   SecretKey = SecretAccessKey123
#
# 2. HTTP Basic
#
# This mode expects you to provide the username and password for the HTTP
# Basic authentication mechanism. These should match the credentials
# configured for the certificate in the PKI Proxy application. For instance:
#
#   Auth = Basic
#   User = user
#   Password = password
#
# 3. HTTP NTLM
#
# NTLM authentication lets you authenticate using the Windows-native
# authentication mechanism. Your local credentials are securely mapped
# to the credentials on the remote system. You do not need to provide
# any usernames or passwords for this to work; everything is done 
# by Windows behind the scenes.
#
#   Auth = NTLM
#
# NTLM authentication with a user other than the current user is also supported.
# To specify a different user, provide the Username and Password parameters as well.
# For instance
#
#   Auth = NTLM
#   User = OtherUser
#   Password = OtherUserPassword
#
#
# Note: you can encrypt secret values, such as KeySecret, using the pkpenc
# tool from the tools directory.

Auth = SecretKey
User = User
SecretKey = User_Secret_Access_Key


# TrustedTLSCerts should match the fingerprint of the 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 NOT the PIN that is used on the server side 
# to access the HSM (if configured). The PIN provided here is used to restrict
# access to the client-side PKI Proxy PKCS#11 driver. It is exchanged
# only between the connecting application (e.g. Adobe Reader) and the driver.

#PIN = 12345


# LogFile optionally specifies the path to a file on disk.
#
# Use LogMode to specify the required verbosity level. Possible values are:
#  0 - None
#  1 - Error
#  2 - Warning
#  3 - Info (Default)
#  4 - Verbose
#  5 - Debug

#LogFile = C:\temp\pkiproxy.log
#LogMode = 3

Signing Files

General Information

The PKI Proxy PKCS#11 driver is a standard PKCS#11 driver. Configuring a third-party application usually means providing a path to the PKI Proxy PKCS#11 driver DLL that matches the platform the application has been compiled for. Some applications may also require parameters such as the slot number or some form of certificate identifier.

The KSP module lets you add PKI Proxy certificates to the Windows certificate store. This allows third-party Windows applications to use them in a standardized manner. No special setup is needed apart from adding the certificate to the system store using the PKI Proxy Certificate Manager application: the applications that know how to use Windows certificates will pick them up right away.

Signing with Jarsigner

Before following these steps, ensure that PKI Proxy has already been configured to share a certificate and that the local PKI Proxy PKCS#11 driver has been configured to use it. See Client Configuration (PKCS#11) for details about configuring PKI Proxy and the PKCS#11 driver.

Using jarsigner with PKI Proxy is no different than using it with any other PKCS#11 driver. The syntax is as follows:

jarsigner
  -tsa http://timestamp.digicert.com
  -keystore NONE
  -storetype PKCS11
  -providerClass sun.security.pkcs11.SunPKCS11
  -providerArg jarsigner.config
  -storepass fakepass 
  -sigalg SHA256withRSA 
  MyApp.jar 
  "My Certificate"

The -tsa parameter tells jarsigner to use timestamp.digicert.com to timestamp the created signature. A timestamp provides a trusted third-party certification of the signature's creation time.

The -keystore, -storetype, and -providerClass parameters together tell jarsigner to use the PKCS#11 mechanism for signing.

The -providerArg parameter should point to a configuration file that provides the settings for the Sun PKCS#11 provider. Note that it is not the PKI Proxy driver configuration file; it is a separate file that must be created to direct jarsigner to the PKI Proxy PKCS#11 driver. See the following jarsigner.config example (on Windows, note that the paths must use double backslashes, as shown):

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

The -sigalg parameter specifies the signature algorithm to use

The library setting should point to the 64-bit PKI Proxy PKCS#11 driver. The slot should always be 0 for the current version of PKI Proxy.

MyApp.jar specifies the jar file to sign.

"My Certificate" is the label or alias of the certificate that needs to be used for signing. The exact format of the label and its contents is specific to a particular security device. In some cases, it matches the common name of the certificate subject; in others, it is a general tag such as "Default Signing ID". You can use the keytool utility included with the JRE to find the label of your signing certificate. Use the same configuration parameters that you pass to jarsigner:

keytool 
  -list 
  -keystore NONE 
  -storetype PKCS11 
  -providerClass sun.security.pkcs11.SunPKCS11 
  -providerArg jarsigner.config 
  -storepass fakepass

Provided that the PKI Proxy driver is configured properly and is referenced correctly in jarsigner.config, you should get the following output from the keytool call:

Keystore type: PKCS11
Keystore provider: SunPKCS11-PKIProxy

Your keystore contains 1 entry

Demo Certificate R3 | Demo Certificate R3, PrivateKeyEntry, 
Certificate fingerprint (SHA-256): AD:4E:D1:E0:39:C7:94:5E:48:A1:D3:60:17:A0:64:5F:E6:88:B5:E9:84:87:A5:98:25:DE:24:21:83:E9:53:A5

The Demo Certificate R3 | Demo Certificate R3 in the previous output is the label that you need to pass to jarsigner:

jarsigner
  -verbose
  -tsa http://timestamp.digicert.com
  -keystore NONE
  -storetype PKCS11
  -providerClass sun.security.pkcs11.SunPKCS11
  -providerArg jarsigner.config
  -storepass fakepass 
  -sigalg SHA256withRSA 
  MyApp.jar 
  'Demo Certificate R3 | Demo Certificate R3'

Adding the -verbose parameter will make the previous call output the following:

requesting a signature timestamp
TSA location: http://timestamp.digicert.com
 updating: META-INF/MYAPP.SF
 updating: META-INF/MYAPP.RSA
  signing: manifest.mf
  signing: myapp/MyAppFirstClass.class
  signing: myapp/MyAppSecondClass.class
  ...

>>> Signer
    X.509, CN=SecureBlackbox Demo Certificate R3, O="/n software, Inc.", EMAILADDRESS=sales@nsoftware.com, L=Chapel Hill, ST=NC, C=US
    [trusted certificate]
>>> TSA
    X.509, CN=DigiCert Timestamp 2022 - 2, O=DigiCert, C=US
    [certificate is valid from 21/09/2022, 01:00 to 21/11/2033, 23:59]
    X.509, CN=DigiCert Trusted G4 RSA4096 SHA256 TimeStamping CA, O="DigiCert, Inc.", C=US
    [certificate is valid from 23/03/2022, 00:00 to 22/03/2037, 23:59]
    X.509, CN=DigiCert Trusted Root G4, OU=www.digicert.com, O=DigiCert Inc, C=US
    [certificate is valid from 01/08/2022, 01:00 to 09/11/2031, 23:59]

jar signed.

Call jarsigner with the -verify parameter to check the integrity of the created signature, as follows:

jarsigner 
  -verify MyApp.jar 
  -verbose 

The output will be as follows:

s     1341616 Wed Dec 14 13:58:36 GMT 2022 META-INF/MANIFEST.MF
      1340173 Wed Dec 14 14:38:40 GMT 2022 META-INF/MYAPP.SF
        7629 Wed Dec 14 14:38:40 GMT 2022 META-INF/MYAPP.RSA
sm      5690 Thu Dec 01 12:51:34 GMT 2022 manifest.mf
sm      2249 Thu Dec 01 12:51:34 GMT 2022 myapp/MyAppFirstClass.class
...

  s = signature was verified 
  m = entry is listed in manifest
  k = at least one certificate was found in keystore

- Signed by "CN=Demo Certificate R3, O="/n software, Inc.", EMAILADDRESS=sales@nsoftware.com, L=Chapel Hill, ST=NC, C=US"
    Digest algorithm: SHA-256
    Signature algorithm: SHA256withRSA, 2048-bit key
  Timestamped by "CN=DigiCert Timestamp 2022 - 2, O=DigiCert, C=US" on Wed Dec 14 14:38:48 UTC 2022
    Timestamp digest algorithm: SHA-256
    Timestamp signature algorithm: SHA256withRSA, 4096-bit key

jar verified.

Signing with SignTool

Microsoft uses a proprietary Authenticode format for signing executable files. PKI Proxy supports the following methods for creating Authenticode signatures.

• Using Microsoft SignTool with the PKI Proxy KSP
• Using pkpsigntool as a drop-in replacement for Microsoft SignTool
• Using Microsoft SignTool with PKCS#11 (not recommended)

Using Microsoft SignTool (KSP)

Before following these steps, ensure that PKI Proxy has already been configured to share a certificate and that the certificate has been imported to the Windows certificate store using the Certificate Manager application. See Client Configuration (KSP) for details about configuring PKI Proxy and the Windows KSP module.

The easiest way to use signtool with PKI Proxy is by leveraging the PKI Proxy KSP module. In this case the use of signtool is no different to the way you would use it normally. The PKI Proxy client and server components will do their magic transparently and securely behind the scenes.

To sign an executable with a PKI Proxy certificate, use the following syntax:

signtool sign /fd SHA256 /sha1 2170a80c36fcafe9b0a2f5ce150ccdd496c7203d program.exe

In the command above, the 2170a80c36fcafe9b0a2f5ce150ccdd496c7203d string is the SHA1 fingerprint of the certificate to use. You can check it by opening the certificate from the Windows certificates MMC applet and consulting the Thumbprint property:

If the PKI Proxy sides have been configured correctly, and the service is online, signtool should output the result of the signing operation:

Done Adding Additional Store
Successfully signed: program.exe

Using pkpsigntool

Before following these steps, ensure that PKI Proxy has already been configured to share a certificate and that the local PKI Proxy PKCS#11 driver has been configured to use it. See Client Configuration (PKCS#11) for details about configuring PKI Proxy and the PKCS#11 driver. For ease of use, PKI Proxy includes a utility called pkpsigntool, which is capable of creating Authenticode signatures and also includes support for PKCS#11 drivers. The Microsoft SignTool utility does not include direct support for PKCS#11 drivers.

Use the following syntax with the included pkpsigntool utility to sign an executable with a certificate shared by PKI Proxy:

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 /d parameter specifies the short description string that is embedded into the signature.

The optional /du parameter may be used to provide a link to a web page providing a longer description.

The /fd parameter specifies the digest algorithm to use for signing. For instance sha256.

The /f parameter provides a path to the PKCS#11 driver to use for signing. Specify the path to the 64-bit PKI Proxy PKCS#11 driver here.

The /tr parameter specifies the timestamp server to use when timestamping the created signature. A timestamp provides a trusted third-party certification of the signature creation time. Authenticode supports two forms of timestamps. Use the /t flag to specify a so-called 'legacy' timestamping service, or /tr to specify an RFC 3161-compatible timestamping service. Because most modern environments use RFC 3161-compatible services, it is safe to assume the use of the /tr flag.

The /td parameter specifies the digest algorithm to use for timestamping (e.g., sha256).

The /ac parameter allows passing any additional certificates that may make sense in the signature. Typically, this flag is used to pass the certificates that make up the signing certificate chain.

The /n parameter allows selecting a certificate by its name. This is useful when multiple certificates are available. This may be set to the alias value as defined in PKI Proxy, or the common name of the certificate. For instance, if the subject includes CN=My Certificate, this may be set to the value My Certificate. This parameter is optional.

The /i parameter allows selecting a certificate by its issuer's name. This is useful when multiple certificates are available. This may be set to the common name of the certificate's issuer. For instance, if the issuer certificate's subject includes CN=DigiCert EV Code Signing CA, this may be set to the value DigiCert EV Code Signing CA. This parameter is optional.

The /sha1 parameter allows selecting a certificate by its SHA-1 hash value (as a hex-encoded string). This is useful when multiple certificates are available. This is commonly referred to as the thumbprint when viewing the certificate details within Windows, such as d81a01d4f47797faab50400e85817dc974f4b3f3. This parameter is optional.

The /u parameter optionally specifies the Enhanced Key Usage (EKU) OID that must be present in the signing certificate. The value must be an OID. For instance, the code-signing key usage OID is 1.3.6.1.5.5.7.3.3. This parameter is optional.

The /p parameter 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 (e.g., /p 12345).

Provided that the PKI Proxy driver is configured properly, you should get the following output from the above pkpsigntool call:

Opening PKCS#11 storage...
Storage opened, looking for a nonempty slot...
Token found in slot #0 (AKS ifdh 0)
Logged in, looking for the certificate
Requesting an RFC 3161 timestamp from http://timestamp.server.com
Timestamp received and embedded into the signature
SUCCESS: App.exe
All files have been processed successfully

You can verify that the signature was added successfully by right-clicking on the signed executable in Windows Explorer, selecting Properties from the pop-up menu, and checking the Digital Signatures tab on the dialog that appears.

Using Microsoft SignTool (PKCS#11)

Before following these steps, ensure that PKI Proxy has already been configured to share a certificate and that the local PKI Proxy PKCS#11 driver has been configured to use it. See Client Configuration (PKCS#11) for details about configuring PKI Proxy and the PKCS#11 driver.

It is recommended to use Microsoft SignTool with the PKI Proxy KSP, or use the included pkpsigntool utility to simplify the authenticode signing process whenever possible. The following steps using the Microsoft SignTool utility should be used only if there is a specific reason to do so. Please see the Signing with SignTool section for details on using pkpsigntool.

The Microsoft SignTool utility does not include direct support for PKCS#11 drivers. While signtool can be used with PKCS#11 drivers such as PKI Proxy, it requires several additional steps and requires the use of a separate PKCS#11 tool that is not part of PKI Proxy.

If pkpsigntool cannot be used and SignTool must be used, the first step is to generate the digest with signtool by using the /dg option. In the following example, the nsoftware.cer file is the public x509 certificate. The private key of the code signing certificate must correspond to this public certificate.

signtool.exe sign /dg c:\temp\sign /fd SHA256 /f c:\temp\sign\nsoftware.cer c:\temp\sign\test.exe

The output of the above command is a Base64-encoded digest. The digest must be formatted properly to be used. The value must first be Base64 decoded. For instance, using the Base64 utility from Cygwin:

Base64 -d c:\temp\sign\test.exe.dig > c:\temp\sign\test.exe.dig.bin

Next the decoded SHA-256 digest must be modified to include a prefix to indicate the hash algorithm that was used to calculate it. The prefixes are defined by PKCS#11. One way to accomplish this is to first prepare a "prefix" file that then can be concatenated with the digest file from the above command. To do this, create a file with the hex contents 3031300d060960864801650304020105000420.

Note: The file contents must be the bytes corresponding to the hex characters. Copying the hex string into a file will not result in the correct contents.

Once the SHA-256 prefix file has been created, it can be concatenated with the digest. For instance, using the cat cat command from Cygwin.

cat c:\temp\sign\sha256prefix.bin c:\temp\sign\test.exe.dig.bin > c:\temp\sign\test.exe.fmtdig.bin

The digest should now be properly prepared; however, a separate tool must be used to perform the signing. PKCS#11 tools may be obtained from the device manufacturer, or other tools like pkcs11-tool from OpenSC may be used. The PKCS#11 tool you choose must first be configured to use the PKI Proxy PKCS#11 driver. Consult the documentation for your tool provider for instructions on how to configure a PKCS#11 module (.dll).

Once the pkcs11 tool has been configured, it can be used to sign the digest. As an example, when using pkcs-tool from OpenSC the --list-objects operation may be used to determine the Id of the certificate that will be used. For instance:

pkcs11-tool --list-objects
Using slot 0 with a present token (0x0)
Public Key Object; RSA 2048 bits
  label:      SIGN pubkey
  ID:         02
  Usage:      encrypt, verify, wrap
  Access:     none
Certificate Object; type = X.509 cert
  label:      Certificate for Digital Signature
  subject:    DN: C=US/postalCode=27517, ST=NC, L=Chapel Hill/street=101 europa dr ste 110, O=/N SOFTWARE INC., CN=/N SOFTWARE INC.
  ID:         02

In this case, the Id is 02.

To then sign the digest with pkcs11-tool, the following command can be used. The RSA-PKCS mechanism should be used, not the SHA256-RSA-PKCS mechanism. The latter will also attempt to calculate a hash, which has been done in previous steps using the /dg option.

pkcs11-tool --sign --id 02 -l --pin 123456 --mechanism RSA-PKCS -i c:\temp\sign\test.exe.fmtdig.bin -o c:\temp\sign\test.exe.dig.bin.signed
Using slot 0 with a present token (0x0)
Using signature algorithm RSA-PKCS

The output of the previous command is a binary file and must be Base64 encoded for signtool to use it. The Base64 tool from Cygwin can be used to accomplish this. For instance:

Base64 c:\temp\sign\test.exe.dig.bin.signed > c:\temp\sign\test.exe.dig.signed

To import the signed digest and complete the signing process with signtool the following command may be used:

signtool.exe sign /di "C:\temp\sign" C:\temp\sign\test.exe

If successful, an output message such as Successfully signed: C:\temp\sign\test.exe should be visible.

If timestamping is desired, the /tr option of the signtool utility may be used.

Signing with Adobe

PKI Proxy can be used to sign PDFs from Adobe Acrobat or Reader. Please use the following steps to make the remote certificate available for signing in Adobe Acrobat or Reader.

Using the KSP module with Adobe

The easiest way to use PKI Proxy to sign documents in Adobe is by leveraging the PKI Proxy KSP module. You do not need to perform any extra steps for KSP-based signing with Adobe, as long as PKI Proxy has been configured to share a certificate and the certificate has been imported to the Windows certificate store using the Certificate Manager application.

See Client Configuration (KSP) for details about configuring PKI Proxy and the Windows KSP module.

Using the PKCS#11 driver with Adobe

Before following these steps, ensure that PKI Proxy has already been configured to share a certificate and that the local PKI Proxy PKCS#11 driver has been configured to use it. See Client Configuration (PKCS#11) for details about configuring PKI Proxy and the PKCS#11 driver.

Adobe products can use third-party PKCS#11 drivers only when working in nonprotected mode. To start the Adobe application in nonprotected mode, navigate to Edit -> Preferences -> Security (Enhanced), and uncheck the Enable Protected Mode at startup box at the top, and then restart the application.

After restarting the Adobe application, navigate to Edit -> Preferences -> Signatures, and click the More... button opposite the "Identities and Trusted Certificates" section. In the dialog that appears, click on the PKCS#11 Modules and Tokens item in the tree on the left, and click on the Attach Module button at the top. Navigate to the PKI Proxy driver location (normally C:\Program Files\PKI Proxy\pkcs11\win32). Make sure to select the win32 version of the driver to match the architecture of the Acrobat executable.

After selecting PKI Proxy's win32 PKCS#11 driver, the virtual device should be added to the list under the PKCS#11 Modules and Tokens branch. The titles of the elements may differ and depend on the type of the certificate being shared. For instance:

Click on the middle entry (PKI Proxy Certificate Adapter- in the previous example), 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. Your certificate is protected by the real credentials that you specify in the driver configuration file.

Next select the last entry in the list (PKI Proxy Certificate Adapter 0 in our example), after which you should see the certificate in the panel on the right. Click on the certificate entry, and then click the Usage Options button at the top and check the Use for Signing item (make sure a check appears next to the item).

Close all currently open dialogs to complete the setup process. Documents can now be signed.

PDF Signing

After the setup above, the signing process is the same regardless of whether you are using the KSP or the PKCS#11 driver. To sign a PDF document, open the document and navigate to the signing facility of your PDF application. In Adobe Reader, you can access this functionality by clicking the More Tools button on the panel on the right (at the very bottom), and then selecting the Certificates applet in the list. Doing so adds a Certificates panel at the top of the document view.

On the Certificates panel, click on the Digitally Sign button:

Draw the signature square with your mouse when asked. Select the shared certificate in the list that appears. It should have the PKCS#11 device (for certificates accessed via the driver) or Windows Digital ID (for certificates accessed via the KSP module) marker in brackets to the right of its subject string. Click Continue.

Click Sign. When asked, specify the location where to save the signed document.

Signing with JavaScript (In Browser)

Before following these steps, ensure that PKI Proxy has already been configured to share a certificate and that the local PKI Proxy PKCS#11 driver has been configured to use it. See Client Configuration (PKCS#11) for details about configuring PKI Proxy and the PKCS#11 driver.

PKI Proxy includes a Javascript module that can be used to access the Web API from Javascript code running within a web page. The module provides a collection of easy-to-use classes that encapsulate certificate browsing and signing functionality.

The Javascript module sends data to PKI Proxy for signing and returns the signature. PKI Proxy may run either locally on 127.0.0.1 or elsewhere on the Internet.

The following code snippet shows how to sign data in the browser with PKI Proxy:

  // Provide user credentials
  keystore.setUserId(userId);
  keystore.setUserKeySecret(userSecret);
          
  // Open the shared key store
  await keystore.open('https://sharedkeys.mycompany.com/', 'open', '');

  // Select the signing key
  await keystore.select('id=' + keyid, true, false, 0);

  // Prepare the input
  var buf = (new TextEncoder()).encode('Hello, world!');

  // Specify the signing key
  crypto.setCryptoKey(keystore.getKeys().item(0));

  // Specify the security mechanism to use
  crypto.setMechanism('sha256WithRSAEncryption');
          
  // Sign the data. 
  var res = await crypto.sign(buf, true); 

This snippet matches the following OpenSSL command, which uses a local private key:

$> openssl dgst -sign privkey.pem -keyform PEM -sha256 -out signature.bin data.txt

The signature produced by this code snippet can then be validated with the inverse OpenSSL command:

$> openssl dgst -verify pubkey.pem -keyform PEM -sha256 -signature signature.bin -binary data.txt 

Please refer to the Javascript demo application in the demos\js directory of the installation for more information.

Signing with SecureBlackbox

Before following these steps, ensure that PKI Proxy has already been configured to share a certificate and that the local PKI Proxy PKCS#11 driver has been configured to use it. See Client Configuration (PKCS#11) for details about configuring PKI Proxy and the PKCS#11 driver.

SecureBlackbox can use the PKI Proxy PKCS#11 driver to access remote certificates as if they were local. Just provide the path to the configured PKI Proxy driver where you would normally provide a path to a regular PKCS#11 driver.

The following code snippet illustrates the use of the PKI Proxy driver with SecureBlackbox:

  Certificatestorage storage = new Certificatestorage();

  // Opening the storage
  storage.Open("pkcs11://user:password@localhost/C:/Program%20Files/PKI%20Proxy/pkcs11/win32/pkiproxy_pkcs11.dll?readonly=true");

  // Listing the certificates
  Certificate cert = null;
  for (int i = 0; i < storage.Certificates.Count; i++)
  {
      Console.WriteLine("Certificate " + (i + 1).ToString() + ": " + storage.Certificates[i].SubjectRDN);

      // Using the first certificate with a private key to do the signing
      if ((cert == null) && (storage.Certificates[i].PrivateKeyExists))
      {
          cert = storage.Certificates[i];
          Console.WriteLine("(using the above certificate for signing)");
      }
  }

  // Signing an XML document
  if (cert != null)
  {
      Xadessigner signer = new Xadessigner();

      signer.SigningCertificate = cert;
      signer.InputFile = "unsigned.xml";
      signer.OutputFile = "signed.xml";
      signer.IgnoreChainValidationErrors = true;
      signer.Sign();

      Console.WriteLine("Signing succeeded\r\n");

      signer.Dispose();
  }
  else
  {
      Console.WriteLine("No suitable signing certificates found");
  }

  // Closing the storage
  storage.Close(false);
  storage.Dispose();

Advanced

PKI Proxy can be accessed by any tool or library that supports PKCS#11 operations. The included PKI Proxy PKCS#11 driver can be used like any other PKCS#11 driver.

The PKI Proxy PKCS#11 driver communicates with a REST API to discover certificates and make signing requests. In addition, the REST API can be used directly to perform common operations, such as signing without the need for PKCS#11 support. For details on on the API, go to REST API

Scripting and Automation

PKI Proxy includes a pkptool utility that provides a console interface to client-side PKI Proxy functions. You can use this tool to make PKI Proxy calls from scripts and non-interactive applications. The tool can also be useful in investigating PKI Proxy connectivity issues and managing its configuration files.

The pkptool utility is available for Windows, Linux, and macOS, and it can be found in the "tools" folder in the installation directory. It provides the following functions:

• Obtaining PKI Proxy web service information
• Listing and exporting public objects from a live PKI Proxy web service
• Making signing, encryption, and decryption requests to the service
• Managing certificates available via the KSP module
• Editing configuration files for the PKI Proxy PKCS#11 driver

You can access the usage information for a particular command by calling it with the -help parameter:

pkptool sign -help

General

This is the help output for "pkptool -help". It lists the available commands and general-use options.

Usage: pkptool [command] [options]

Commands:

  info               Get PKI Proxy service information
  config             Show, create, or change configuration file
  list               Lists objects in a PKI Proxy key store
  export             Export certificate or public key
  sign               Sign a file or text
  encrypt            Encrypt a file or text
  decrypt            Decrypt a file or text
  enc                Encrypt or decrypt a sensitive string using system encryption (DPAPI)
  ksp                Performs Windows KSP operations

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

PKI Proxy service options:

  -config|-c         Path to the configuration file
  -location|-l       Service location/URL
  -authtype|-a       Authentication type. Possible values are: SecretKey, Basic, NTLM
  -user|-u           Username for authentication
  -secretkey|-s      SecretKey value for SecretKey authentication type
  -password|-p       Password for Basic and NTLM authentication types
  -trustedtlscerts   Fingerprint(s) of trusted TLS certificates
  -logfile|-lf       Path to the log file
  -logmode|-lm       The required log verbosity level. Possible values are:
      0 - None
      1 - Error
      2 - Warning
      3 - Info (Default)
      4 - Verbose
      5 - Debug
  -pin               PKCS11 driver access PIN
  -notifications|-n  Tray notifications setting: 0 - None, 1 - Confirm, 2 - Notify

Use "pkptool command_name -help" for usage of command_name

Config

The "config" command can be used to edit a config file for the PKI Proxy PKCS#11 driver.

Usage: pkptool config [options]

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

Config command options:

  -new               Create new configuration file
  -input|-in         Path to configuration file to show/change
  -output|-out       Path to new configuration file
  -print             Print the contents of the configuration file in user-friendly form
  -location|-l       New PKI Proxy service location
  -authtype|-a       New authentication type. Possible values are: SecretKey, Basic, NTLM
  -user|-u           New username for authentication
  -secretkey|-s      New secret key value for SecretKey authentication type
  -password|-p       New password for Basic and NTLM authentication types
  -trustedtlscerts   New fingerprints of trusted TLS certificates
  -logfile|-lf       New path to the log file
  -logmode|-lm       New log mode. Possible values are:
      0 - None
      1 - Error
      2 - Warning
      3 - Info (Default)
      4 - Verbose
      5 - Debug
  -pin               New PKCS11 driver access PIN
  -notifications|-n  New tray notification level: 0 - None, 1 - Confirm, 2 - Notify
  

Decrypt

The "decrypt" command can be used to decrypt an encrypted file.

Usage: pkptool decrypt [options]

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

PKI Proxy service options:

  -config|-c         Path to the configuration file
  -location|-l       Service location/URL
  -authtype|-a       Authentication type. Possible values are: SecretKey, Basic, NTLM
  -user|-u           Username for authentication
  -secretkey|-s      SecretKey value for SecretKey authentication type
  -password|-p       Password for Basic and NTLM authentication types
  -trustedtlscerts   Fingerprint(s) of trusted TLS certificates
  -logfile|-lf       Path to the log file
  -logmode|-lm       The required log verbosity level. Possible values are:
      0 - None
      1 - Error
      2 - Warning
      3 - Info (Default)
      4 - Verbose
      5 - Debug
  -pin               PKCS11 driver access PIN
  -notifications|-n  Tray notifications setting: 0 - None, 1 - Confirm, 2 - Notify

Decrypt command options:

  -id                The id of the private key to use
  -label             The label of the private key to use
  -handle            The handle of the private key to use
  -k                 The KSP key identifier
  -input|-in         Path to file to be decrypted.
  -output|-out       Where to save the decrypted file
  

Enc

The "enc" command can be used to encrypt or decrypt input with the system's encryption API

Usage: pkptool enc [options]

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

Encrypt command options:

  -encrypt|-e        Encrypt the input
  -decrypt|-d        Decrypt the input
  -input|-in         Path to file to be encrypted.
  -output|-out       Where to save the encrypted file
  -nonotify          Use non-interactive encryption
  -quiet             Print only encrypted/decrypted data
  

Encrypt

The "encrypt" command can be used to encrypt a file.

Usage: pkptool encrypt [options]

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

PKI Proxy service options:

  -config|-c         Path to the configuration file
  -location|-l       Service location/URL
  -authtype|-a       Authentication type. Possible values are: SecretKey, Basic, NTLM
  -user|-u           Username for authentication
  -secretkey|-s      SecretKey value for SecretKey authentication type
  -password|-p       Password for Basic and NTLM authentication types
  -trustedtlscerts   Fingerprint(s) of trusted TLS certificates
  -logfile|-lf       Path to the log file
  -logmode|-lm       The required log verbosity level. Possible values are:
      0 - None
      1 - Error
      2 - Warning
      3 - Info (Default)
      4 - Verbose
      5 - Debug
  -pin               PKCS11 driver access PIN
  -notifications|-n  Tray notifications setting: 0 - None, 1 - Confirm, 2 - Notify

Encrypt command options:

  -id                The id of the public key to use
  -label             The label of the public key to use
  -handle            The handle of the public key to use
  -k                 The KSP key identifier
  -input|-in         Path to file to be encrypted.
  -output|-out       Where to save the encrypted file
  

Export

The "export" command can be used to export a public certificate or key from PKI Proxy.

Usage: pkptool export [options]

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

PKI Proxy service options:

  -config|-c         Path to the configuration file
  -location|-l       Service location/URL
  -authtype|-a       Authentication type. Possible values are: SecretKey, Basic, NTLM
  -user|-u           Username for authentication
  -secretkey|-s      SecretKey value for SecretKey authentication type
  -password|-p       Password for Basic and NTLM authentication types
  -trustedtlscerts   Fingerprint(s) of trusted TLS certificates
  -logfile|-lf       Path to the log file
  -logmode|-lm       The required log verbosity level. Possible values are:
      0 - None
      1 - Error
      2 - Warning
      3 - Info (Default)
      4 - Verbose
      5 - Debug
  -pin               PKCS11 driver access PIN
  -notifications|-n  Tray notifications setting: 0 - None, 1 - Confirm, 2 - Notify

Export command options:

  -id                  Extract object by id
  -label               Extract object by label
  -handle              Extract object by handle
  -output|-out         Where to save the object
  -type                Extract object(s) by type: publickey, certificate
  -exportpassword|-ep  Password to file with extraction object
  

Info

The "info" command can be used to return information on the PKI Proxy service.

Usage: pkptool info [options]

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

PKI Proxy service options:

  -config|-c         Path to the configuration file
  -location|-l       Service location/URL
  -authtype|-a       Authentication type. Possible values are: SecretKey, Basic, NTLM
  -user|-u           Username for authentication
  -secretkey|-s      SecretKey value for SecretKey authentication type
  -password|-p       Password for Basic and NTLM authentication types
  -trustedtlscerts   Fingerprint(s) of trusted TLS certificates
  -logfile|-lf       Path to the log file
  -logmode|-lm       The required log verbosity level. Possible values are:
      0 - None
      1 - Error
      2 - Warning
      3 - Info (Default)
      4 - Verbose
      5 - Debug
  -pin               PKCS11 driver access PIN
  -notifications|-n  Tray notifications setting: 0 - None, 1 - Confirm, 2 - Notify
  

KSP

The "ksp" command can be used to configure the PKI Proxy KSP from the command line.

Usage: pkptool ksp [options]

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

KSP command options:

  -o                 The KSP operation. Possible values are:
      install   - Register a PKI Proxy KSP in the system
      uninstall - Unregister a PKI Proxy KSP from the system
      enumprovs - Return a list of KSPs registered on the system
      import    - Install a PKI Proxy certificate to the system MY store
      remove    - Remove a PKI Proxy certificate from the system MY store
      list      - Return a list of PKI Proxy certificates installed in the system's MY store
      update    - Update an installed certificate's configuration record
      export    - Export an installed certificate's configuration record
      enable    - Enable an installed PKI Proxy certificate
      disable   - Disable an installed PKI Proxy certificate
  

List

The "list" command can be used to list the certificates available from the PKI Proxy web API

Usage: pkptool list [options]

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

PKI Proxy service options:

  -config|-c         Path to the configuration file
  -location|-l       Service location/URL
  -authtype|-a       Authentication type. Possible values are: SecretKey, Basic, NTLM
  -user|-u           Username for authentication
  -secretkey|-s      SecretKey value for SecretKey authentication type
  -password|-p       Password for Basic and NTLM authentication types
  -trustedtlscerts   Fingerprint(s) of trusted TLS certificates
  -logfile|-lf       Path to the log file
  -logmode|-lm       The required log verbosity level. Possible values are:
      0 - None
      1 - Error
      2 - Warning
      3 - Info (Default)
      4 - Verbose
      5 - Debug
  -pin               PKCS11 driver access PIN
  -notifications|-n  Tray notifications setting: 0 - None, 1 - Confirm, 2 - Notify

List command options:

  -format|-f           List format: raw, default, group
  

Sign

The "sign" command can be used to sign a file.

Usage: pkptool sign [options]

Common options:

  -verbose|-v        Verbose output when executing the command
  -help              Show help information

PKI Proxy service options:

  -config|-c         Path to the configuration file
  -location|-l       Service location/URL
  -authtype|-a       Authentication type. Possible values are: SecretKey, Basic, NTLM
  -user|-u           Username for authentication
  -secretkey|-s      SecretKey value for SecretKey authentication type
  -password|-p       Password for Basic and NTLM authentication types
  -trustedtlscerts   Fingerprint(s) of trusted TLS certificates
  -logfile|-lf       Path to the log file
  -logmode|-lm       The required log verbosity level. Possible values are:
      0 - None
      1 - Error
      2 - Warning
      3 - Info (Default)
      4 - Verbose
      5 - Debug
  -pin               PKCS11 driver access PIN
  -notifications|-n  Tray notifications setting: 0 - None, 1 - Confirm, 2 - Notify

Sign command options:

  -id                The id of the private key to use
  -label             The label of the private key to use
  -handle            The handle of the private key to use
  -k                 The KSP key identifier
  -input|-in         Path to file to be signed.
  -output|-out       Where to save the signed file
  -hashed            Indicates that input file contains the hash to be signed (no need to hash it)
  -hash|-d           The hash algorithm to use
  

Additional Settings

All settings for PKI Proxy are stored in the Windows registry in HKEY_CURRENT_USER\SOFTWARE\nsoftware\PKIProxy\24. This registry key holds settings that are available for the product. This include typical settings that are managed through the UI, as well as additional settings which can only be set by modifying the registry key directly.

The following keys hold configuration information:

The following values can be configured within the root HKEY_CURRENT_USER\SOFTWARE\nsoftware\PKIProxy\24 registry key:

Registry Keys

The following values can be configured for the service:

Certificates

Certificate Settings

The following values can be configured for each shared certificate:

Users

User Settings

The following values can be configured for each users: