You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/code-signing.md
+24-5
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,9 @@ Windows is dual code-signed (SHA1 & SHA256 hashing algorithms).
4
4
5
5
On a macOS development machine, a valid and appropriate identity from your keychain will be automatically used.
6
6
7
-
!!! tip
7
+
!!! tip
8
8
See article [Notarizing your Electron application](https://kilianvalkhof.com/2019/electron/notarizing-your-electron-application/).
9
-
9
+
10
10
11
11
| Env Name | Description
12
12
| -------------- | -----------
@@ -29,7 +29,7 @@ To sign an app on Windows, there are two types of certificates:
29
29
* EV Code Signing Certificate
30
30
* Code Signing Certificate
31
31
32
-
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.
32
+
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.
33
33
34
34
If you are using an EV Certificate, you need to provide [win.certificateSubjectName](configuration/win.md#WindowsConfiguration-certificateSubjectName) in your electron-builder configuration.
35
35
@@ -52,7 +52,7 @@ To sign app on build server you need to set `CSC_LINK`, `CSC_KEY_PASSWORD`:
52
52
In case of AppVeyor, don't forget to click on lock icon to “Toggle variable encryption”.
53
53
54
54
Keep in mind that Windows is not able to handle enviroment variable values longer than 8192 characters, thus if the base64 representation of your certificate exceeds that limit, try re-exporting the certificate without including all the certificates in the certification path (they are not necessary, but the Certificate Manager export wizard ticks the option by default), otherwise the encoded value will be truncated.
55
-
55
+
56
56
[1]`printf "%q\n" "<url>"`
57
57
58
58
## Where to Buy Code Signing Certificate
@@ -75,10 +75,29 @@ Please note — Gatekeeper only recognises [Apple digital certificates](http://s
75
75
76
76
## How to Disable Code Signing During the Build Process on macOS
77
77
78
-
To disable Code Signing when building for macOS leave all the above vars unset except for `CSC_IDENTITY_AUTO_DISCOVERY` which needs to be set to `false`. This can be done by running `export CSC_IDENTITY_AUTO_DISCOVERY=false`.
78
+
To disable Code Signing when building for macOS leave all the above vars unset except for `CSC_IDENTITY_AUTO_DISCOVERY` which needs to be set to `false`. This can be done by running `export CSC_IDENTITY_AUTO_DISCOVERY=false`.
79
79
80
80
Another way — set `mac.identity` to `null`. You can pass aditional configuration using CLI as well: `-c.mac.identity=null`.
81
81
82
+
## Using with Azure Trusted Signing (beta)
83
+
84
+
To sign using Azure Tenant account, you'll need the following env variables set that are read directly by `Invoke-TrustedSigning` module; they are not parsed or resolved by electron-builder.
85
+
86
+
!!! tip
87
+
Descriptions of each field can be found here: [Azure.Identity class - EnvironmentCredential Class](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.environmentcredential?view=azure-dotnet#definition)
88
+
89
+
| Env Name | Description
90
+
| -------------- | -----------
91
+
| `AZURE_TENANT_ID` | See the Tip mentioned above.
92
+
|`AZURE_CLIENT_ID`|
93
+
|`AZURE_CLIENT_SECRET`|
94
+
|`AZURE_CLIENT_CERTIFICATE_PATH`|
95
+
|`AZURE_CLIENT_SEND_CERTIFICATE_CHAIN`|
96
+
|`AZURE_USERNAME`|
97
+
|`AZURE_PASSWORD`|
98
+
99
+
`win.azureOptions` needs to be configured per [Microsoft's instructions](https://learn.microsoft.com/en-us/azure/trusted-signing/how-to-signing-integrations#create-a-json-file) directly in electron-builder's configuration. Additional fields can be provided that are passed directly to `Invoke-TrustedSigning` powershell command.
100
+
82
101
## Alternative methods of codesigning
83
102
84
103
Codesigning via Electron Builder's configuration (via package.json) is not the only way to sign an application. Some people find it easier to codesign using a GUI tool. A couple of examples include:
Copy file name to clipboardexpand all lines: docs/configuration/win.md
+44-10
Original file line number
Diff line number
Diff line change
@@ -15,25 +15,59 @@ The top-level [win](configuration.md#Configuration-win) key contains set of opti
15
15
</ul>
16
16
<hr>
17
17
<ul>
18
-
<li><codeid="WindowsConfiguration-signingHashAlgorithms">signingHashAlgorithms</code> = <code>['sha1', 'sha256']</code> Array<“sha256” | “sha1”> | “undefined” - Array of signing algorithms used. For AppX <code>sha256</code> is always used.</li>
19
-
<li><codeid="WindowsConfiguration-sign">sign</code> String | (configuration: CustomWindowsSignTaskConfiguration) => Promise - The custom function (or path to file or module id) to sign Windows executable.</li>
20
-
<li><codeid="WindowsConfiguration-certificateFile">certificateFile</code> String | “undefined” - The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable <code>CSC_LINK</code> (<code>WIN_CSC_LINK</code>) for some reason. Please see <ahref="/code-signing">Code Signing</a>.</li>
21
-
<li><codeid="WindowsConfiguration-certificatePassword">certificatePassword</code> String | “undefined” - The password to the certificate provided in <code>certificateFile</code>. Please use it only if you cannot use env variable <code>CSC_KEY_PASSWORD</code> (<code>WIN_CSC_KEY_PASSWORD</code>) for some reason. Please see <ahref="/code-signing">Code Signing</a>.</li>
22
-
<li><codeid="WindowsConfiguration-certificateSubjectName">certificateSubjectName</code> String | “undefined” - The name of the subject of the signing certificate, which is often labeled with the field name <code>issued to</code>. Required only for EV Code Signing and works only on Windows (or on macOS if <ahref="https://www.parallels.com/products/desktop/">Parallels Desktop</a> Windows 10 virtual machines exits).</li>
23
-
<li><codeid="WindowsConfiguration-certificateSha1">certificateSha1</code> String | “undefined” - 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 <ahref="https://www.parallels.com/products/desktop/">Parallels Desktop</a> Windows 10 virtual machines exits).</li>
24
-
<li><codeid="WindowsConfiguration-additionalCertificateFile">additionalCertificateFile</code> String | “undefined” - The path to an additional certificate file you want to add to the signature block.</li>
25
-
<li><codeid="WindowsConfiguration-rfc3161TimeStampServer">rfc3161TimeStampServer</code> = <code>http://timestamp.digicert.com</code> String | “undefined” - The URL of the RFC 3161 time stamp server.</li>
26
-
<li><codeid="WindowsConfiguration-timeStampServer">timeStampServer</code> = <code>http://timestamp.digicert.com</code> String | “undefined” - The URL of the time stamp server.</li>
18
+
<litag.description=""><codeid="WindowsConfiguration-signingHashAlgorithms">signingHashAlgorithms</code> Array<“sha256” | “sha1”> | “undefined” - Array of signing algorithms used. For AppX <code>sha256</code> is always used. Deprecated:</li>
19
+
<litag.description=""><codeid="WindowsConfiguration-sign">sign</code> String | (configuration: CustomWindowsSignTaskConfiguration) => Promise - The custom function (or path to file or module id) to sign Windows executables Deprecated:</li>
20
+
<litag.description=""><codeid="WindowsConfiguration-certificateFile">certificateFile</code> String | “undefined” - The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable <code>CSC_LINK</code> (<code>WIN_CSC_LINK</code>) for some reason. Please see <ahref="/code-signing">Code Signing</a>. Deprecated:</li>
21
+
<litag.description=""><codeid="WindowsConfiguration-certificatePassword">certificatePassword</code> String | “undefined” - The password to the certificate provided in <code>certificateFile</code>. Please use it only if you cannot use env variable <code>CSC_KEY_PASSWORD</code> (<code>WIN_CSC_KEY_PASSWORD</code>) for some reason. Please see <ahref="/code-signing">Code Signing</a>. Deprecated:</li>
22
+
<litag.description=""><codeid="WindowsConfiguration-certificateSubjectName">certificateSubjectName</code> String | “undefined” - The name of the subject of the signing certificate, which is often labeled with the field name <code>issued to</code>. Required only for EV Code Signing and works only on Windows (or on macOS if <ahref="https://www.parallels.com/products/desktop/">Parallels Desktop</a> Windows 10 virtual machines exits). Deprecated:</li>
23
+
<litag.description=""><codeid="WindowsConfiguration-certificateSha1">certificateSha1</code> String | “undefined” - 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 <ahref="https://www.parallels.com/products/desktop/">Parallels Desktop</a> Windows 10 virtual machines exits). Deprecated:</li>
24
+
<litag.description=""><codeid="WindowsConfiguration-additionalCertificateFile">additionalCertificateFile</code> String | “undefined” - The path to an additional certificate file you want to add to the signature block. Deprecated:</li>
25
+
<litag.description=""><codeid="WindowsConfiguration-rfc3161TimeStampServer">rfc3161TimeStampServer</code> = <code>http://timestamp.digicert.com</code> String | “undefined” - The URL of the RFC 3161 time stamp server. Deprecated:</li>
26
+
<litag.description=""><codeid="WindowsConfiguration-timeStampServer">timeStampServer</code> = <code>http://timestamp.digicert.com</code> String | “undefined” - The URL of the time stamp server. Deprecated:</li>
27
27
</ul>
28
28
<hr>
29
29
<ul>
30
-
<li><codeid="WindowsConfiguration-publisherName">publisherName</code> String | Array<String> | “undefined” - <ahref="https://github.com/electron-userland/electron-builder/issues/1187#issuecomment-278972073">The publisher name</a>, exactly as in your code signed certificate. Several names can be provided. Defaults to common name from your code signing certificate.</li>
30
+
<litag.description=""><codeid="WindowsConfiguration-publisherName">publisherName</code> String | Array<String> | “undefined” - <ahref="https://github.com/electron-userland/electron-builder/issues/1187#issuecomment-278972073">The publisher name</a>, exactly as in your code signed certificate. Several names can be provided. Defaults to common name from your code signing certificate. Deprecated:</li>
31
+
<li><codeid="WindowsConfiguration-signtoolOptions">signtoolOptions</code> <ahref="#WindowsSigntoolConfiguration">WindowsSigntoolConfiguration</a> | “undefined” - Options for usage with signtool.exe</li>
32
+
<li><codeid="WindowsConfiguration-azureSignOptions">azureSignOptions</code> <ahref="#WindowsAzureSigningConfiguration">WindowsAzureSigningConfiguration</a> | “undefined” - Options for usage of Azure Trusted Signing (beta)</li>
31
33
<li><codeid="WindowsConfiguration-verifyUpdateCodeSignature">verifyUpdateCodeSignature</code> = <code>true</code> Boolean - Whether to verify the signature of an available update before installation. The <ahref="#publisherName">publisher name</a> will be used for the signature verification.</li>
32
34
<li><codeid="WindowsConfiguration-requestedExecutionLevel">requestedExecutionLevel</code> = <code>asInvoker</code> “asInvoker” | “highestAvailable” | “requireAdministrator” | “undefined” - The <ahref="https://msdn.microsoft.com/en-us/library/6ad1fshk.aspx#Anchor_9">security level</a> at which the application requests to be executed. Cannot be specified per target, allowed only in the <code>win</code>.</li>
33
35
<li><codeid="WindowsConfiguration-signAndEditExecutable">signAndEditExecutable</code> = <code>true</code> Boolean - Whether to sign and add metadata to executable. Advanced option.</li>
<p><strong><codeid="WindowsAzureSigningConfiguration-endpoint">endpoint</code></strong> 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.</p>
44
+
<p>Translates to field: Endpoint</p>
45
+
<p>Requires one of environment variable configurations for authenticating to Microsoft Entra ID per <ahref="https://learn.microsoft.com/en-us/dotnet/api/azure.identity.environmentcredential?view=azure-dotnet#definition">Microsoft’s documentation</a></p>
46
+
</li>
47
+
<li>
48
+
<p><strong><codeid="WindowsAzureSigningConfiguration-certificateProfileName">certificateProfileName</code></strong> String - The Certificate Profile name. Translates to field: CertificateProfileName</p>
<li><codeid="WindowsSigntoolConfiguration-sign">sign</code> module:app-builder-lib/out/codeSign/windowsSignToolManager.__type | String | “undefined” - The custom function (or path to file or module id) to sign Windows executables</li>
55
+
</ul>
56
+
<hr>
57
+
<ul>
58
+
<li><codeid="WindowsSigntoolConfiguration-signingHashAlgorithms">signingHashAlgorithms</code> = <code>['sha1', 'sha256']</code> Array<“sha256” | “sha1”> | “undefined” - Array of signing algorithms used. For AppX <code>sha256</code> is always used.</li>
59
+
<li><codeid="WindowsSigntoolConfiguration-certificateFile">certificateFile</code> String | “undefined” - The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable <code>CSC_LINK</code> (<code>WIN_CSC_LINK</code>) for some reason. Please see <ahref="/code-signing">Code Signing</a>.</li>
60
+
<li><codeid="WindowsSigntoolConfiguration-certificatePassword">certificatePassword</code> String | “undefined” - The password to the certificate provided in <code>certificateFile</code>. Please use it only if you cannot use env variable <code>CSC_KEY_PASSWORD</code> (<code>WIN_CSC_KEY_PASSWORD</code>) for some reason. Please see <ahref="/code-signing">Code Signing</a>.</li>
61
+
<li><codeid="WindowsSigntoolConfiguration-certificateSubjectName">certificateSubjectName</code> String | “undefined” - The name of the subject of the signing certificate, which is often labeled with the field name <code>issued to</code>. Required only for EV Code Signing and works only on Windows (or on macOS if <ahref="https://www.parallels.com/products/desktop/">Parallels Desktop</a> Windows 10 virtual machines exits).</li>
62
+
<li><codeid="WindowsSigntoolConfiguration-certificateSha1">certificateSha1</code> String | “undefined” - 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 <ahref="https://www.parallels.com/products/desktop/">Parallels Desktop</a> Windows 10 virtual machines exits).</li>
63
+
<li><codeid="WindowsSigntoolConfiguration-additionalCertificateFile">additionalCertificateFile</code> String | “undefined” - The path to an additional certificate file you want to add to the signature block.</li>
64
+
<li><codeid="WindowsSigntoolConfiguration-rfc3161TimeStampServer">rfc3161TimeStampServer</code> = <code>http://timestamp.digicert.com</code> String | “undefined” - The URL of the RFC 3161 time stamp server.</li>
65
+
<li><codeid="WindowsSigntoolConfiguration-timeStampServer">timeStampServer</code> = <code>http://timestamp.digicert.com</code> String | “undefined” - The URL of the time stamp server.</li>
66
+
</ul>
67
+
<hr>
68
+
<ul>
69
+
<li><codeid="WindowsSigntoolConfiguration-publisherName">publisherName</code> String | Array<String> | “undefined” - <ahref="https://github.com/electron-userland/electron-builder/issues/1187#issuecomment-278972073">The publisher name</a>, exactly as in your code signed certificate. Several names can be provided. Defaults to common name from your code signing certificate.</li>
0 commit comments