diff --git a/docs/tutorial/code-signing.md b/docs/tutorial/code-signing.md
index 0516d32e9a8b..369a801e3013 100644
--- a/docs/tutorial/code-signing.md
+++ b/docs/tutorial/code-signing.md
@@ -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
+
+
+
+
+ com.apple.security.cs.allow-jit
+
+ com.apple.security.cs.allow-unsigned-executable-memory
+
+ com.apple.security.cs.debugger
+
+
+
+```
+
+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
+
+
+
+
+ com.apple.security.cs.allow-jit
+
+ com.apple.security.cs.allow-unsigned-executable-memory
+
+ com.apple.security.cs.debugger
+
+
+
+```
## 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