Code Signing for Windows
Windows code signing is supported. If the configuration values are provided correctly in your package.json, then signing should be automatically executed.
Windows is dual code-signed (SHA1 & SHA256 hashing algorithms).
To sign an app on Windows, there are two types of certificates:
- EV Code Signing Certificate
- Code Signing Certificate
Both certificates work with auto-update. The regular (and often cheaper) Code Signing Certificate shows a warning during installation that goes away once enough users installed your application and you've built up trust. The EV Certificate has more trust and thus works immediately without any warnings. However, it is not possible to export the EV Certificate as it is bound to a physical USB dongle. Thus, you can't export the certificate for signing code on a CI, such as AppVeyor.
If you are using an EV Certificate, you need to provide certificateSubjectName in your win configuration.
If you use Windows 7, please ensure that PowerShell is updated to version 3.0.
If you are on Linux or Mac and you want sign a Windows app using EV Code Signing Certificate, please use the guide for Unix systems.
Using Azure Trusted Signing
Microsoft itself offers a code signing service called Azure Trusted Signing which you can use to code-sign your applications.
If you do not already have an Azure setup and only want to use their code signing service, set up an Azure "Trusted Signing Account" using this quickstart guide. Then, set up an "App registration" in Azure, follow the steps to create a "Secret" for it, and assign the role "Trusted Signing Certificate Profile Signer" to the App registration (note, the App registration is considered a "service principal" and you will need to type its name into the search bar to find it in the web panel).
To sign using your certificate, you'll need to adapt electron-builder's configuration and set the environment variables used for authentication. The environment variables are read directly by the Invoke-TrustedSigning module; they are not parsed or resolved by electron-builder.
First, to direct electron-builder to utilize Azure Trusted Signing, you'll need to set the property win.azureSignOptions in your electron-builder configuration. Configure it per Microsoft's instructions.
| Property | Description |
|---|---|
publisherName | This must match exactly the CommonName (CN) property of the certificate you wish to use. |
endpoint | This corresponds to the endpoint you selected when creating your certificate. |
certificateProfileName | The name of the certificate profile within your Trusted Signing Account. |
codeSigningAccountName | This is the name of the Trusted Signing Account (note that it is not the account name for the app registration. |
Additional fields can be provided under win.azureSignOptions that are passed directly to the Invoke-TrustedSigning powershell module.
Second, provide the appropriate environment variables to the build action. Descriptions of each variable can be found in Azure.Identity class - EnvironmentCredential Class. You only need to provide the environment variables that are listed in the table corresponding to which authentication method you choose to use.
If you use the minimal setup using an "App registration" that is described above, the section "Service principal with secret" applies to you. In this case, you only need the Tenant ID, Client ID, and Client Secret.
| Env Name | Description |
|---|---|
AZURE_TENANT_ID | Your Azure AD Tenant ID; can be found in the Entra ID portal. |
AZURE_CLIENT_ID | The Application (Client) ID of your "App registration." Note that this is not the "object" ID. |
AZURE_CLIENT_SECRET | The value of the "Secret" you created for your App registration. Note that this is not the secret's ID. |
AZURE_CLIENT_CERTIFICATE_PATH | Required if you bring your own certificate. |
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN | Required if you bring your own certificate. |
AZURE_USERNAME | The username for your Microsoft Entra account. |
AZURE_PASSWORD | The password for your Microsoft Entra account. |
Azure Signing Configuration
The top-level win.azureSignOptions key contains set of options for Azure Trusted Signing.
Interface: WindowsAzureSigningConfiguration
Indexable
[
k:string]:string|Nullish
Allow other CLI parameters (verbatim case-sensitive) to Invoke-TrustedSigning
Note: Key-Value pairs with undefined/null value are filtered out of the command.
Properties
certificateProfileName
readonlycertificateProfileName:string
The Certificate Profile name. Translates to field: CertificateProfileName
codeSigningAccountName
readonlycodeSigningAccountName:string
The Code Signing Signing Account name. Translates to field: CodeSigningAccountName
endpoint
readonlyendpoint:string
The Trusted Signing Account endpoint. The URI value must have a URI that aligns to the region your Trusted Signing Account and Certificate Profile you are specifying were created in during the setup of these resources.
Translates to field: Endpoint
Requires one of environment variable configurations for authenticating to Microsoft Entra ID per Microsoft's documentation
fileDigest?
readonlyoptionalfileDigest?:string
The File Digest for signing each file. Translates to field: FileDigest
Default
SHA256
publisherName
readonlypublisherName:string
The publisher name, exactly as in your code signed certificate. Several names can be provided.
timestampDigest?
readonlyoptionaltimestampDigest?:string
The Timestamp Digest. Translates to field: TimestampDigest
Default
SHA256
timestampRfc3161?
readonlyoptionaltimestampRfc3161?:string
The Timestamp rfc3161 server. Translates to field: TimestampRfc3161
Default
http://timestamp.acs.microsoft.com
Signtool Configuration
The top-level win.signtoolOptions key contains options for classic signtool.exe-based code signing.
Interface: WindowsSigntoolConfiguration
Properties
additionalCertificateFile?
readonlyoptionaladditionalCertificateFile?:string|null
The path to an additional certificate file you want to add to the signature block.
certificateFile?
readonlyoptionalcertificateFile?:string|null
The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable CSC_LINK (WIN_CSC_LINK) for some reason.
Please see Code Signing.
certificatePassword?
readonlyoptionalcertificatePassword?:string|null
The password to the certificate provided in certificateFile. Please use it only if you cannot use env variable CSC_KEY_PASSWORD (WIN_CSC_KEY_PASSWORD) for some reason.
Please see Code Signing.
certificateSha1?
readonlyoptionalcertificateSha1?:string|null
The SHA1 hash of the signing certificate. The SHA1 hash is commonly specified when multiple certificates satisfy the criteria specified by the remaining switches. Works only on Windows (or on macOS if Parallels Desktop Windows 10 virtual machines exits).
certificateSubjectName?
readonlyoptionalcertificateSubjectName?:string|null
The name of the subject of the signing certificate, which is often labeled with the field name issued to. Required only for EV Code Signing and works only on Windows (or on macOS if Parallels Desktop Windows 10 virtual machines exits).
publisherName?
readonlyoptionalpublisherName?:string|string[] |null
The publisher name, exactly as in your code signed certificate. Several names can be provided. Defaults to common name from your code signing certificate.
rfc3161TimeStampServer?
readonlyoptionalrfc3161TimeStampServer?:string|null
The URL of the RFC 3161 time stamp server.
Default
http://timestamp.digicert.com
sign?
readonlyoptionalsign?:string|CustomWindowsSign|null
The custom function (or path to file or module id) to sign Windows executables
signingHashAlgorithms?
readonlyoptionalsigningHashAlgorithms?: ("sha1"|"sha256")[] |null
Array of signing algorithms used. For AppX sha256 is always used.
Default
['sha1', 'sha256']
timeStampServer?
readonlyoptionaltimeStampServer?:string|null
The URL of the time stamp server.
Default
http://timestamp.digicert.com