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
|
||||
introduced accidentally or by malicious code.
|
||||
|
||||
On Windows the system assigns a trust level to your code signing certificate which
|
||||
if you don't have, or if your trust level is low will cause security dialogs to
|
||||
appear when users start using your application. Trust level builds over time
|
||||
so it's better to start code signing as early as possible.
|
||||
On Windows, the system assigns a trust level to your code signing certificate
|
||||
which if you don't have, or if your trust level is low, will cause security
|
||||
dialogs to appear when users start using your application. Trust level builds
|
||||
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
|
||||
Windows and macOS will, by default, prevent either the download or the
|
||||
execution of unsigned applications. Starting with macOS Catalina (version 10.15),
|
||||
users have to go through multiple manual steps to open unsigned applications.
|
||||
Windows and macOS will, by default, prevent either the download or the execution
|
||||
of unsigned applications. Starting with macOS Catalina (version 10.15), users
|
||||
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
|
||||
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,
|
||||
it should be code-signed. The Mac and Windows app stores do not allow unsigned
|
||||
apps.
|
||||
it should be code-signed.
|
||||
|
||||
# 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)
|
||||
2. Download and install [Xcode]
|
||||
2. Download and install [Xcode] - this requires a computer running macOS
|
||||
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-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)
|
||||
## `electron-forge`
|
||||
|
||||
## 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.
|
||||
"Notarization" as defined by Apple means that you upload your previously signed
|
||||
application to Apple for additional verification _before_ distributing the app
|
||||
to your users.
|
||||
Let's take a look at an example configuration with all required fields. Not all
|
||||
of them are required: the tools will be clever enough to automatically find a
|
||||
suitable `identity`, for instance, but we recommend that you are explicit.
|
||||
|
||||
To automate this process, you can use the [`electron-notarize`] module. You
|
||||
do not necessarily need to complete this step for every build you make – just
|
||||
the builds you intend to ship to users.
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
|
|
@ -62,19 +163,24 @@ See the [Mac App Store Guide].
|
|||
Before signing Windows builds, you must do the following:
|
||||
|
||||
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)
|
||||
* [Comodo](https://www.comodo.com/landing/ssl-certificate/authenticode-signature/)
|
||||
* [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:
|
||||
|
||||
- [`electron-winstaller`] will generate an installer for windows and sign it for you
|
||||
- [`electron-forge`] can sign installers it generates through the Squirrel.Windows or MSI targets.
|
||||
- [`electron-winstaller`] will generate an installer for windows and sign it for
|
||||
you
|
||||
- [`electron-forge`] can sign installers it generates through the
|
||||
Squirrel.Windows or MSI targets.
|
||||
- [`electron-builder`] can sign some of its windows targets
|
||||
|
||||
## Windows Store
|
||||
|
|
|
|||
Loading…
Reference in a new issue