How-To: Sign JAR Files Using jarsigner and PKCS#11¶
Sign Java JAR files with the standard jarsigner tool through the Keyserver PKCS#11 module. jarsigner ships in the bin/ directory of every JDK, not in a JRE-only install. The private key stays in the Keyserver, and jarsigner uses it as if it were on a local token.
Internal Authserver for Testing Only
On the trial environment the internal Authserver may be used for testing. Production JAR signing must authenticate through an external OAuth2/OIDC provider, such as Azure Entra ID or GitLab OIDC. See the Authentication Model.
How it works¶
sequenceDiagram
participant J as jarsigner (SunPKCS11)
participant M as libpkcs11ks.so
participant K as Keyserver
J->>M: PKCS11 sign request (JAR digest)
M->>K: Sign order (Bearer KSC_ID_TOKEN,<br/>operation KSC_OPERATION_ID)
K-->>M: Signature
M-->>J: SignatureDiagram: jarsigner (SunPKCS11); libpkcs11ks.so; Keyserver; PKCS11 sign request (JAR digest); Sign order (Bearer KSC_ID_TOKEN, operation KSC_OPERATION_ID); Signature
jarsigner loads the Keyserver module through Java's SunPKCS11 provider. The module turns each signing call into a Keyserver sign order, as described in the PKCS#11 Library Reference. PKCS#11 signing therefore needs the same access token and approved operation as REST signing. The private key never reaches this machine: jarsigner sends only the hash, and the Keyserver returns the signature. This holds for KEYSTORE keys too: such a key leaves the Keyserver only through an explicit export.
Background: what Java requires¶
Trust chain. A JAR signature is verified against the signer's certificate chain, which the verifier must trust: the JVM's cacerts, an application-specific truststore, or an OSGi container's configuration. If you control the verifying runtimes, import your Keyserver ROOT certificate into their truststore. For third-party JVMs you need a publicly trusted code-signing certificate, imported into the Keyserver as in Import an Existing Key.
Timestamping. Pass an RFC 3161 timestamp authority with -tsa, in pipelines too. The timestamp countersignature proves when the JAR was signed, so the signature stays valid after the signing certificate expires. Without it, jarsigner warns at signing time, and the signature becomes invalid when the certificate expires.
Prerequisites¶
- The Keyserver PKCS#11 module
libpkcs11ks.so. See Getting the library. - A JDK 8 or later, for
jarsigner. Examples use OpenJDK 25. curl,jq,openssl,pkcs11-tool(packageopensc)- An OAuth2 client whose subject has a role built from the fwsigner nature scoped to the signing key. See Manage Roles in the Keyserver.
- An RSA FW key, the safest choice across Java runtimes. The worked example is
fw-rsa(RSA-2048, SHA256). The trial environment ships only an EC key (fw-quickstart), so create the RSA key first. See Create and Manage Keys in the Keyserver or Admin Configuration.
Install the tools (Ubuntu example):
Set the base URLs:
export KSC_API_SERVER="https://keyserver.<UNIQUE-ID>.cryptera-security.io"
export AUTHSERVER="https://authserver.<UNIQUE-ID>.cryptera-security.io/oauth2/token"
Step 1: Authenticate and Obtain an OAuth2 Token¶
Trial environment
Use a pre-registered client such as fw-client; its credentials are listed in Trial Environment. fw-client is wired only to fw-quickstart, so before Step 2 create a role from the fwsigner nature scoped to fw-rsa and attach it to fw-client. See Manage Roles in the Keyserver. Without it, creating the operation returns 403. In production, replace this step with your identity provider's flow. See Choosing a flow.
Request a token. KSC_ID_TOKEN holds the OAuth2 access token:
export AUTH_CREDS=$(printf '%s' "<CLIENT_ID>:<CLIENT_SECRET>" | base64 | tr -d '\n')
export KSC_ID_TOKEN=$(
curl -sS --tlsv1.3 \
-X POST \
-H "Authorization: Basic $AUTH_CREDS" \
-d "grant_type=client_credentials" \
"$AUTHSERVER" | jq -r .access_token
)
[ -n "$KSC_ID_TOKEN" ] && [ "$KSC_ID_TOKEN" != null ] && echo "token OK (${#KSC_ID_TOKEN} chars)"
Expected output: token OK ( followed by the token length. If it prints nothing, the credentials or the AUTHSERVER URL are wrong. The check never prints the token itself.
Step 2: Create a Signing Operation¶
export KSC_OPERATION_ID=$(
curl -sS --tlsv1.3 \
-X POST "$KSC_API_SERVER/api/operations" \
-H "Authorization: Bearer $KSC_ID_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"validms": 600000,
"description": "JAR signing of myapp.jar",
"new-keyusagerestrictions": [
{ "keyid": "fw-rsa", "maxusagecount": 1 }
]
}' | jq -r .id
)
echo "$KSC_OPERATION_ID"
Expected output: an operation UUID. Replace fw-rsa with your JAR-signing key. If it prints null, the request failed: a 404 means the keyid is unknown or the key has been revoked. The 10-minute window (validms: 600000) allows for a manual approval; CI pipelines usually use much shorter windows.
Step 3: Approve the Operation (If Required)¶
If the key requires approvers:
- Open
https://keyclient.<UNIQUE-ID>.cryptera-security.io/approvaladmin - Log in as an approver and approve the operation
Confirm before continuing:
curl -sS --tlsv1.3 -H "Authorization: Bearer $KSC_ID_TOKEN" \
"$KSC_API_SERVER/api/operations/$KSC_OPERATION_ID" | jq .approved
Expected output: true. Keys with 0 required approvers are approved immediately.
Step 4: Configure the PKCS#11 Environment¶
KSC_API_SERVER, KSC_ID_TOKEN and KSC_OPERATION_ID are already set. Add the description recorded in the audit log:
These variables must be set in the environment that runs jarsigner. The module reads them once, when it loads. Full variable reference: PKCS#11 Library Reference.
Step 5: Create the Java PKCS#11 Provider Configuration¶
jarsigner loads the module through SunPKCS11 with this configuration, the same one JSign uses in the Authenticode guide:
cat > ks-pkcs11.cfg << 'EOF'
name = CrypteraKS
library = /path/to/libpkcs11ks.so
slotListIndex = 0
EOF
Set library to the path of your libpkcs11ks.so.
Step 6: Verify the Setup and Identify the Key Label¶
List the keys the module can see:
Expected output includes:
The label is the Keyserver key ID. Java addresses the key by this label.
Before running jarsigner, verify:
| Check | Must be | If it is not |
|---|---|---|
env \| grep KSC_ | KSC_API_SERVER, KSC_ID_TOKEN, KSC_OPERATION_ID all set in the shell that runs jarsigner | The key label is not found, or signing fails with an authorization error |
jq .approved on the operation (Step 3) | true | Signing fails with 409 "Need more approvers" |
pkcs11-tool --list-objects | Shows your key's label as a Private Key Object | Wrong --module path, wrong KSC_API_SERVER/KSC_ID_TOKEN, or the subject's role cannot see the key |
library in ks-pkcs11.cfg | Absolute path of your libpkcs11ks.so | jarsigner cannot load the provider |
Step 7: Sign the JAR¶
Assuming myapp.jar and key label fw-rsa (RSA/SHA256):
jarsigner \
-providerClass sun.security.pkcs11.SunPKCS11 \
-providerArg ks-pkcs11.cfg \
-keystore NONE \
-storetype PKCS11 \
-storepass none \
-sigalg SHA256withRSA \
-digestalg SHA-256 \
-tsa http://timestamp.digicert.com \
myapp.jar \
fw-rsa
What the options do:
-providerClass/-providerArg: load the SunPKCS11 provider withks-pkcs11.cfg. On JDK 9+,-addprovider SunPKCS11is the preferred equivalent.-keystore NONE -storetype PKCS11: no local keystore; keys come from the PKCS#11 token-storepass none: required byjarsigner, ignored by the module, which authenticates withKSC_ID_TOKEN. Any placeholder works.-sigalg/-digestalg: must match the key's hash algorithm (fw-rsauses SHA256). The Keyserver does not check the digest length: with an RSA key a different digest gives a signature that does not verify, and with an ECDSA key the signature verifies only against the digest you used.-tsa: the timestamp authority. See Background: what Java requires.fw-rsa: the key label from Step 6
Expected output:
On the trial environment a warning follows: "The signer's certificate chain is invalid ... unable to find valid certification path". This is expected, because the key chains to a Keyserver ROOT that is not in your JVM's truststore. See Background: what Java requires.
Step 8: Verify the JAR¶
Expected output shows the signer and the timestamp, and ends with the verdict:
- Signed by "C=DK, ..., CN=fw-rsa"
Digest algorithm: SHA-256
Signature algorithm: SHA256withRSA, 2048-bit key
Timestamped by "CN=DigiCert SHA256 RSA4096 Timestamp Responder ..." on ...
jar verified.
On the trial environment the certificate-chain warning from Step 7 appears here too.
-certs prints the signer's certificate chain. Confirm it is your Keyserver key's certificate. To export that certificate for a truststore:
pkcs11-tool --module /path/to/libpkcs11ks.so \
--read-object --type cert --label fw-rsa --output-file fw-rsa.der
openssl x509 -inform DER -in fw-rsa.der -out fw-rsa.pem
Running it in CI¶
Practices that apply to every CI signing job, such as token handling and operation budgets, are in CI practices. Specific to JAR signing:
- Verify before publishing. Run Step 8 in the pipeline and fail the build if the verdict is not
jar verified.. This catches wrong-key and wrong-algorithm mistakes at build time instead of at deployment.
If something fails¶
| Symptom | Cause and fix |
|---|---|
| Token check in Step 1 prints nothing | Wrong credentials or AUTHSERVER URL |
401 "The user/client is not valid" | The client ID does not match a registered subject |
403 "Access forbidden" | The subject's role lacks the fwsigner permissions for the key |
jarsigner cannot load the provider | Wrong library path in ks-pkcs11.cfg, or the config file path passed to -providerArg is wrong |
| "Enter Passphrase for keystore" / "you must enter key password" | Missing -storepass none (any placeholder value works) |
| Key label not found | KSC_API_SERVER/KSC_ID_TOKEN not exported in jarsigner's environment, or the subject cannot see the key |
Signing fails with 409 "Need more approvers" | Operation not approved (Step 3) |
Signing fails with 410 "Operation has expired" | validms elapsed. Create a new operation |
Signing fails with 410 "Operation is cancelled" | An approver revoked the operation, or its creator cancelled it. Create a new operation |
Creating the operation fails with 404 | The keyid is unknown, or the key has been revoked (the response does not say which) |
Signing fails with 410 "Signing key has been revoked" | A key named in the operation has been revoked, so the operation can no longer be used. Create a new operation with another key |
Step 8 does not print jar verified. after signing succeeded | -sigalg/-digestalg does not match the key's configured hash algorithm, or the JAR changed after signing |
jarsigner warns "no timestamp" | -tsa omitted (see Background) |
Full status-code reference: Error Codes. PKCS#11-specific issues: PKCS#11 Library Reference.
Related pages¶
- Tutorial Part 2: Sign Code Using the Trial Environment: the REST flow behind this guide