Skip to main content

Interface: WindowsPkcs11SigningConfig

Beta

Sign with a PKCS#11 hardware token (smart card, USB HSM, cloud KMS exposed via a PKCS#11 provider) using osslsigncode. Unlike hsm, this mode does not require Windows or a Windows VM, so it can sign Windows binaries directly from macOS/Linux CI. The token PIN is read from the WIN_CSC_KEY_PASSWORD (or CSC_KEY_PASSWORD) environment variable.

PKCS#11 signing is available in v27 as a beta feature. The interface is stable but real-hardware test coverage is limited.

Extends​

  • WindowsSigningSharedOptions

Properties​

additionalCertificateFile?​

readonly optional additionalCertificateFile?: string | null

Beta

Path to an additional certificate file (typically an intermediate / cross-signing CA certificate) whose contents are added to the signature block via signtool's /ac flag. Use this when the signing certificate's full chain is not already present on target machines and you want it embedded in the signature so the chain can be validated.

Inherited from​

WindowsSigningSharedOptions.additionalCertificateFile

certificateFile?​

readonly optional certificateFile?: string | null

Beta

Optional path to a certificate chain file to accompany the PKCS#11 key. If omitted the certificate embedded in the token is used.

pkcs11KeyUri​

readonly pkcs11KeyUri: string

Beta

RFC 7512 PKCS#11 URI identifying the private key within the module. Maps to osslsigncode's -key parameter.

Example: "pkcs11:token=MyToken;object=MyKey;type=private"

Must be paired with pkcs11Module.

pkcs11Module​

readonly pkcs11Module: string

Beta

Path to the PKCS#11 shared library (.so on Linux, .dylib on macOS). The library must be installed separately — electron-builder does not bundle it.

Example: "/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so"

Must be paired with pkcs11KeyUri.

publisherName?​

readonly optional publisherName?: string | string[] | null

Beta

The publisher name(s) to associate with the signature, written exactly as the subject appears in your code signing certificate. May be a single string or an array — an array is useful when rotating certificates, so updates signed by either the old or the new certificate still verify.

This value is not a signtool argument; it is consumed in two places:

  • Update verification — when verifyUpdateCodeSignature is enabled, it is written into app-update.yml and electron-updater checks it against the certificate that signed each downloaded update.
  • AppX / MSIX identity — the package Publisher attribute must equal the certificate subject, so electron-builder derives it from this value (or the certificate) to keep them in sync; a mismatch makes packaging fail with ERROR_BAD_FORMAT.

Defaults to the Common Name (CN) extracted from your code signing certificate. Set to null to opt out.

See​

https://github.com/electron-userland/electron-builder/issues/1187#issuecomment-278972073

Inherited from​

WindowsSigningSharedOptions.publisherName

rfc3161TimeStampServer?​

readonly optional rfc3161TimeStampServer?: string | null

Beta

The URL of the RFC 3161 timestamp server, used for SHA-256 and nested/appended signatures (signtool's /tr flag). Timestamping records when the file was signed so the signature stays valid after the signing certificate expires. Ignored when the build runs with ELECTRON_BUILDER_OFFLINE=true.

Default​

http://timestamp.digicert.com

Inherited from​

WindowsSigningSharedOptions.rfc3161TimeStampServer

sign?​

readonly optional sign?: string | CustomWindowsSign | null

Beta

A custom signing hook that replaces electron-builder's built-in signtool / osslsigncode invocation. Provide a function, or the path / module id of a file that exports a sign function (resolved relative to the project, then as a module).

The hook is invoked once per signing pass (i.e. once per entry in signingHashAlgorithms) and receives a configuration object describing the file to sign (path), the resolved certificate info (cscInfo), the current hash, and whether this pass is a nested signature (isNest), plus a computeSignToolArgs(isWin) helper that returns the default arguments electron-builder would otherwise have used. Use this to integrate an external or cloud signing service. See Code Signing.

Inherited from​

WindowsSigningSharedOptions.sign

signingHashAlgorithms?​

readonly optional signingHashAlgorithms?: ("sha256" | "sha1")[] | null

Beta

The digest (hash) algorithms to sign with, applied via signtool's /fd flag (or osslsigncode's -h). One signing pass runs per entry, in order; listing more than one dual-signs the file, with each additional signature appended as a nested signature (signtool /as). Signing with both sha1 and sha256 lets a single binary validate on legacy (pre-SHA-2) Windows as well as modern Windows.

Some targets override this: .msi cannot be dual-signed (a single hash is used) and AppX/MSIX is always sha256 only.

Default​

['sha1', 'sha256']

Inherited from​

WindowsSigningSharedOptions.signingHashAlgorithms

timeStampServer?​

readonly optional timeStampServer?: string | null

Beta

The URL of the legacy Authenticode timestamp server, used for SHA-1 signatures (signtool's /t flag). This is also the timestamp server used by osslsigncode (-t) when signing on macOS/Linux. See rfc3161TimeStampServer for SHA-256 / nested signatures. Ignored when the build runs with ELECTRON_BUILDER_OFFLINE=true.

Default​

http://timestamp.digicert.com

Inherited from​

WindowsSigningSharedOptions.timeStampServer

type​

readonly type: "pkcs11"

Beta

Discriminator selecting cross-platform PKCS#11 token signing via osslsigncode.