Documentation | CodeSign Secure

Overview

The wrapper is a PKCS#11 library. Tools such as apksigner, jarsigner, JSign, OpenSSL, XML signing tools, and GnuPG load it like any PKCS#11 token. The wrapper authenticates to CodeSign Secure, sends the hash for signing over PKCS#11 api calls, and returns the signature to the tool.

Download it from Signing Tools for your operating system.
It is configured with ec_pkcs11client.ini, whose path you set in the EC_INI_FILE_PATH environment variable.
Also requires the pkcs11properties.cfg file that points to the wrapper library.

ec_pkcs11client.ini reference

[logconfig_file]
name = <Path to EC_PKCS11_CLIENT-LogConfig.xml>    ; ships in the wrapper download

[server_url]
url = https://codesign.example.com

[pfxfile_path]
path = <Path to client auth certificate>           ; client authentication certificate

[pfxfile_passwd]
passwd = <PFX password>

[login_token]
username = <CodeSign Secure Registered username>
passcode = <CodeSign Secure passcode>

; Optional: the key to sign with (v3.02.01 and later)
;[key_filter]
;label = EC-Cert-020

Section	Key	Required	Description
[logconfig_file]	name	Yes	Absolute path to EC_PKCS11_CLIENT-LogConfig.xml, which ships in the wrapper download and controls logging
[server_url]	url	Yes	Your CodeSign Secure address, for example https://codesign.example.com
[pfxfile_path]	path	Yes	Absolute path to the client authentication certificate (PFX) generated in System Setup > User
[pfxfile_passwd]	passwd	Yes	The PFX Certificate password
[login_token]	username	Yes	CodeSign Secure Registered username
[login_token]	passcode	Yes	CodeSign Secure passcode
[key_filter]	label	No	The key label to sign with, for example EC-Cert-020. Available from 3.02.01.

Important: This file holds passwords. Never commit it to source control. See Client Authentication.

pkcs11properties.cfg reference

name = signingmanager

#ships in the wrapper download
library = <Path to ec_pkcs11client PKCS#11 library (.dll, .so, and .dylib)>

#only required for Thales Luna HSM
#slot=0

attributes = compatibility

attributes(*, *, *) = {
CKA_TOKEN=true
}

Key	Required	Description
library	Yes	Absolute path to ec_pkcs11client library (.dll, .so, and .dylib), which ships in the wrapper download and controls PKCS#11 api calls
slot	No	Only required for Thales Luna HSM

Environment variables

Variable	Required	Values	Default
EC_INI_FILE_PATH	Yes	Absolute path to ec_pkcs11client.ini	Not set
EC_PKCS11_KEY_LABEL	No	The key label to sign with	Not set
EC_PKCS11_NO_AUTO_KEY_LABEL	No	1 turns off automatic key label detection	Not set: detection on
EC_PKCS11_DISABLE_CACHE	No	1 turns off key caching	Not set: cache on

# Linux and macOS (current shell)
export EC_INI_FILE_PATH=/opt/ec/ec_pkcs11client.ini

# Windows PowerShell (current session)
$env:EC_INI_FILE_PATH = "C:\PKCS11_Wrapper-Windows\ec_pkcs11client.ini"

# Windows (persistent; open a new console afterwards)
setx EC_INI_FILE_PATH "C:\PKCS11_Wrapper-Windows\ec_pkcs11client.ini"

Key label and caching (3.02.01)

The wrapper caches the signing key, so repeated signing is faster. It needs to know which key to use, and you can tell it in one of three ways:

Method	How
Automatic detection (default)	The wrapper reads the key label from the signing tool’s command line, for example, the alias passed to jarsigner
Environment variable	EC_PKCS11_KEY_LABEL=EC-Cert-020
INI file	[key_filter] section with label = EC-Cert-020

Use one method at a time so it is always clear which key is used.
Set EC_PKCS11_NO_AUTO_KEY_LABEL=1 to stop automatic detection, for example when the label is always set explicitly.
Set EC_PKCS11_DISABLE_CACHE=1 to test without the cache when a certificate has changed and the wrong key seems to be used.

Signing guides

For errors, see Troubleshooting.