docs: Explain notarization, improve code-signing docs (#21373)

* docs: Explain notarization

* Update docs/tutorial/code-signing.md

Co-Authored-By: Zeke Sikelianos <zeke@github.com>
pull/21485/head^2
Felix Rieseberg 2019-12-13 11:16:20 -05:00 committed by Samuel Attard
parent cf833a7650
commit 7932e28aa2
2 changed files with 26 additions and 9 deletions

BIN
docs/images/gatekeeper.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 190 KiB

View File

@ -3,7 +3,7 @@
Code signing is a security technology that you use to certify that an app was
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.
On Windows the system assigns a trust level to your code signing certificate which
@ -11,15 +11,18 @@ 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.
For example, here's what macOS users see when attempting to start an unsigned app:
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.
![unsigned app warning on macOS](https://user-images.githubusercontent.com/2289/39488937-bdc854ba-4d38-11e8-88f8-7b3c125baefc.png)
![macOS Catalina Gatekeeper warning: The app cannot be opened because the developer cannot be verified](../images/gatekeeper.png)
> App can't be opened because it is from an unidentified developer
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
it should be code-signed. The Mac and Windows app stores do not allow unsigned
apps.
# Signing macOS builds
@ -39,7 +42,20 @@ pass the `--osx-sign=true` flag to sign your build.
in your forge config.
- [`electron-builder`] has built-in code-signing capabilities. See [electron.build/code-signing](https://www.electron.build/code-signing)
For more info, see the [Mac App Store Submission Guide].
## Notarization
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.
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.
## Mac App Store
See the [Mac App Store Guide].
# Signing Windows builds
@ -70,8 +86,9 @@ See the [Windows Store Guide].
[`electron-forge`]: https://github.com/electron-userland/electron-forge
[`electron-osx-sign`]: https://github.com/electron-userland/electron-osx-sign
[`electron-packager`]: https://github.com/electron/electron-packager
[`electron-notarize`]: https://github.com/electron/electron-notarize
[`electron-winstaller`]: https://github.com/electron/windows-installer
[Xcode]: https://developer.apple.com/xcode
[signing certificates]: https://github.com/electron-userland/electron-osx-sign/wiki/1.-Getting-Started#certificates
[Mac App Store Submission Guide]: mac-app-store-submission-guide.md
[signing certificates]: https://github.com/electron/electron-osx-sign/wiki/1.-Getting-Started#certificates
[Mac App Store Guide]: mac-app-store-submission-guide.md
[Windows Store Guide]: windows-store-guide.md