Skip to main content

Interface: WindowsHsmSigningConfig

Beta

HSM 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

Path to the certificate file containing the public certificate chain (.crt / .cer / .pfx). The private key is NOT read from this file — it is provided by the HSM via cryptoServiceProvider.

certificateSha1?​

readonly optional certificateSha1?: string | null

Beta

Alternative to certificateFile: locate the public certificate in the Windows certificate store by its SHA-1 thumbprint. The private key still comes from the HSM via cryptoServiceProvider / keyContainer; this only identifies which public certificate to sign with.

certificateSubjectName?​

readonly optional certificateSubjectName?: string | null

Beta

Alternative to certificateFile: locate the public certificate in the Windows certificate store by (a substring of) its subject name. The private key still comes from the HSM via cryptoServiceProvider / keyContainer; this only identifies which public certificate to sign with.

cryptoServiceProvider​

readonly cryptoServiceProvider: string

Beta

The name of the cryptographic service provider (CSP) that holds the private key. Maps to signtool's /csp flag. Examples:

  • Google Cloud KMS: "Google Cloud KMS Provider"
  • Smart card / FIPS token: "Microsoft Base Smart Card Crypto Provider"

Requires a modern winCodeSign toolset (the default; only the legacy "0.0.0" pin is unsupported). Windows-only — use type: "pkcs11" on macOS/Linux.

keyContainer​

readonly keyContainer: string

Beta

The key container name within the CSP. Maps to signtool's /kc flag.

Example for Google Cloud KMS: "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/1"

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: "hsm"

Beta

Discriminator selecting HSM / hardware-token signing via signtool's /csp and /kc flags.