docs: Improve the codesigning docs (#22838)
* docs: Improve the codesigning docs * docs: Clarify builder notarization * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> * Update docs/tutorial/code-signing.md Co-Authored-By: Mark Lee <malept@users.noreply.github.com> Co-authored-by: Mark Lee <malept@users.noreply.github.com>
This commit is contained in:
Felix Rieseberg
GitHub
parent
37e92b7650
commit
7d9e4a74c4
1 changed files with 139 additions and 33 deletions
|
|
@ -6,52 +6,153 @@ created by you.
|
||||||
On macOS the system can detect any change to the app, whether the change is
|
On macOS the system can detect any change to the app, whether the change is
|
||||||
introduced accidentally or by malicious code.
|
introduced accidentally or by malicious code.
|
||||||
|
|
||||||
On Windows the system assigns a trust level to your code signing certificate which
|
On Windows, the system assigns a trust level to your code signing certificate
|
||||||
if you don't have, or if your trust level is low will cause security dialogs to
|
which if you don't have, or if your trust level is low, will cause security
|
||||||
appear when users start using your application. Trust level builds over time
|
dialogs to appear when users start using your application. Trust level builds
|
||||||
so it's better to start code signing as early as possible.
|
over time so it's better to start code signing as early as possible.
|
||||||
|
|
||||||
While it is possible to distribute unsigned apps, it is not recommended. Both
|
While it is possible to distribute unsigned apps, it is not recommended. Both
|
||||||
Windows and macOS will, by default, prevent either the download or the
|
Windows and macOS will, by default, prevent either the download or the execution
|
||||||
execution of unsigned applications. Starting with macOS Catalina (version 10.15),
|
of unsigned applications. Starting with macOS Catalina (version 10.15), users
|
||||||
users have to go through multiple manual steps to open unsigned applications.
|
have to go through multiple manual steps to open unsigned applications.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
As you can see, users get two options: Move the app straight to the trash or
|
As you can see, users get two options: Move the app straight to the trash or
|
||||||
cancel running it. You don't want your users to see that dialog.
|
cancel running it. You don't want your users to see that dialog.
|
||||||
|
|
||||||
If you are building an Electron app that you intend to package and distribute,
|
If you are building an Electron app that you intend to package and distribute,
|
||||||
it should be code-signed. The Mac and Windows app stores do not allow unsigned
|
it should be code-signed.
|
||||||
apps.
|
|
||||||
|
|
||||||
# Signing macOS builds
|
# Signing & notarizing macOS builds
|
||||||
|
|
||||||
Before signing macOS builds, you must do the following:
|
Properly preparing macOS applications for release requires two steps: First, the
|
||||||
|
app needs to be code-signed. Then, the app needs to be uploaded to Apple for a
|
||||||
|
process called "notarization", where automated systems will further verify that
|
||||||
|
your app isn't doing anything to endanger its users.
|
||||||
|
|
||||||
|
To start the process, ensure that you fulfill the requirements for signing and
|
||||||
|
notarizing your app:
|
||||||
|
|
||||||
1. Enroll in the [Apple Developer Program] (requires an annual fee)
|
1. Enroll in the [Apple Developer Program] (requires an annual fee)
|
||||||
2. Download and install [Xcode]
|
2. Download and install [Xcode] - this requires a computer running macOS
|
||||||
3. Generate, download, and install [signing certificates]
|
3. Generate, download, and install [signing certificates]
|
||||||
|
|
||||||
There are a number of tools for signing your packaged app:
|
Electron's ecosystem favors configuration and freedom, so there are multiple
|
||||||
|
ways to get your application signed and notarized.
|
||||||
|
|
||||||
- [`electron-osx-sign`] is a standalone tool for signing macOS packages.
|
## `electron-forge`
|
||||||
- [`electron-packager`] bundles `electron-osx-sign`. If you're using `electron-packager`,
|
|
||||||
pass the `--osx-sign=true` flag to sign your build.
|
|
||||||
- [`electron-forge`] uses `electron-packager` internally, you can set the `osxSign` option
|
|
||||||
in your forge config.
|
|
||||||
- [`electron-builder`] has built-in code-signing capabilities. See [electron.build/code-signing](https://www.electron.build/code-signing)
|
|
||||||
|
|
||||||
## Notarization
|
If you're using Electron's favorite build tool, getting your application signed
|
||||||
|
and notarized requires a few additions to your configuration. [Forge](https://electronforge.io) is a
|
||||||
|
collection of the official Electron tools, using [`electron-packager`],
|
||||||
|
[`electron-osx-sign`], and [`electron-notarize`] under the hood.
|
||||||
|
|
||||||
Starting with macOS Catalina, Apple requires applications to be notarized.
|
Let's take a look at an example configuration with all required fields. Not all
|
||||||
"Notarization" as defined by Apple means that you upload your previously signed
|
of them are required: the tools will be clever enough to automatically find a
|
||||||
application to Apple for additional verification _before_ distributing the app
|
suitable `identity`, for instance, but we recommend that you are explicit.
|
||||||
to your users.
|
|
||||||
|
|
||||||
To automate this process, you can use the [`electron-notarize`] module. You
|
```json
|
||||||
do not necessarily need to complete this step for every build you make – just
|
{
|
||||||
the builds you intend to ship to users.
|
"name": "my-app",
|
||||||
|
"version": "0.0.1",
|
||||||
|
"config": {
|
||||||
|
"forge": {
|
||||||
|
"packagerConfig": {
|
||||||
|
"osxSign": {
|
||||||
|
"identity": "Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)",
|
||||||
|
"hardened-runtime": true,
|
||||||
|
"entitlements": "entitlements.plist",
|
||||||
|
"entitlements-inherit": "entitlements.plist",
|
||||||
|
"signature-flags": "library"
|
||||||
|
},
|
||||||
|
"osxNotarize": {
|
||||||
|
"appleId": "felix@felix.fun",
|
||||||
|
"appleIdPassword": "my-apple-id-password",
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `plist` file referenced here needs the following macOS-specific entitlements
|
||||||
|
to assure the Apple security mechanisms that your app is doing these things
|
||||||
|
without meaning any harm:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||||
|
<plist version="1.0">
|
||||||
|
<dict>
|
||||||
|
<key>com.apple.security.cs.allow-jit</key>
|
||||||
|
<true/>
|
||||||
|
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
|
||||||
|
<true/>
|
||||||
|
<key>com.apple.security.cs.debugger</key>
|
||||||
|
<true/>
|
||||||
|
</dict>
|
||||||
|
</plist>
|
||||||
|
```
|
||||||
|
|
||||||
|
To see all of this in action, check out Electron Fiddle's source code,
|
||||||
|
[especially its `electron-forge` configuration
|
||||||
|
file](https://github.com/electron/fiddle/blob/master/forge.config.js).
|
||||||
|
|
||||||
|
|
||||||
|
## `electron-builder`
|
||||||
|
|
||||||
|
Electron Builder comes with a custom solution for signing your application. You
|
||||||
|
can find [its documentation here](https://www.electron.build/code-signing).
|
||||||
|
|
||||||
|
## `electron-packager`
|
||||||
|
|
||||||
|
If you're not using an integrated build pipeline like Forge or Builder, you
|
||||||
|
are likely using [`electron-packager`], which includes [`electron-osx-sign`] and
|
||||||
|
[`electron-notarize`].
|
||||||
|
|
||||||
|
If you're using Packager's API, you can pass [in configuration that both signs
|
||||||
|
and notarizes your
|
||||||
|
application](https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html).
|
||||||
|
|
||||||
|
```js
|
||||||
|
const packager = require('electron-packager')
|
||||||
|
|
||||||
|
packager({
|
||||||
|
dir: '/path/to/my/app',
|
||||||
|
osxSign: {
|
||||||
|
identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',
|
||||||
|
'hardened-runtime': true,
|
||||||
|
entitlements: 'entitlements.plist',
|
||||||
|
'entitlements-inherit': 'entitlements.plist',
|
||||||
|
'signature-flags': 'library'
|
||||||
|
},
|
||||||
|
osxNotarize: {
|
||||||
|
appleId: 'felix@felix.fun',
|
||||||
|
appleIdPassword: 'my-apple-id-password'
|
||||||
|
}
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
The `plist` file referenced here needs the following macOS-specific entitlements
|
||||||
|
to assure the Apple security mechanisms that your app is doing these things
|
||||||
|
without meaning any harm:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||||
|
<plist version="1.0">
|
||||||
|
<dict>
|
||||||
|
<key>com.apple.security.cs.allow-jit</key>
|
||||||
|
<true/>
|
||||||
|
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
|
||||||
|
<true/>
|
||||||
|
<key>com.apple.security.cs.debugger</key>
|
||||||
|
<true/>
|
||||||
|
</dict>
|
||||||
|
</plist>
|
||||||
|
```
|
||||||
|
|
||||||
## Mac App Store
|
## Mac App Store
|
||||||
|
|
||||||
|
|
@ -62,19 +163,24 @@ See the [Mac App Store Guide].
|
||||||
Before signing Windows builds, you must do the following:
|
Before signing Windows builds, you must do the following:
|
||||||
|
|
||||||
1. Get a Windows Authenticode code signing certificate (requires an annual fee)
|
1. Get a Windows Authenticode code signing certificate (requires an annual fee)
|
||||||
2. Install Visual Studio 2015/2017 (to get the signing utility)
|
2. Install Visual Studio to get the signing utility (the free [Community
|
||||||
|
Edition](https://visualstudio.microsoft.com/vs/community/) is enough)
|
||||||
|
|
||||||
You can get a code signing certificate from a lot of resellers. Prices vary, so it may be worth your time to shop around. Popular resellers include:
|
You can get a code signing certificate from a lot of resellers. Prices vary, so
|
||||||
|
it may be worth your time to shop around. Popular resellers include:
|
||||||
|
|
||||||
* [digicert](https://www.digicert.com/code-signing/microsoft-authenticode.htm)
|
* [digicert](https://www.digicert.com/code-signing/microsoft-authenticode.htm)
|
||||||
* [Comodo](https://www.comodo.com/landing/ssl-certificate/authenticode-signature/)
|
* [Comodo](https://www.comodo.com/landing/ssl-certificate/authenticode-signature/)
|
||||||
* [GoDaddy](https://au.godaddy.com/web-security/code-signing-certificate)
|
* [GoDaddy](https://au.godaddy.com/web-security/code-signing-certificate)
|
||||||
* Amongst others, please shop around to find one that suits your needs, Google is your friend :)
|
* Amongst others, please shop around to find one that suits your needs, Google
|
||||||
|
is your friend 😄
|
||||||
|
|
||||||
There are a number of tools for signing your packaged app:
|
There are a number of tools for signing your packaged app:
|
||||||
|
|
||||||
- [`electron-winstaller`] will generate an installer for windows and sign it for you
|
- [`electron-winstaller`] will generate an installer for windows and sign it for
|
||||||
- [`electron-forge`] can sign installers it generates through the Squirrel.Windows or MSI targets.
|
you
|
||||||
|
- [`electron-forge`] can sign installers it generates through the
|
||||||
|
Squirrel.Windows or MSI targets.
|
||||||
- [`electron-builder`] can sign some of its windows targets
|
- [`electron-builder`] can sign some of its windows targets
|
||||||
|
|
||||||
## Windows Store
|
## Windows Store
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue