A Quick Rundown on Notarization

I get periodically asked about Apple’s notarization requirements, so I thought I’d amass my knowledge in one place and link people to when they have questions. This is not an extensive overview, but I’ve tried to strike a balance between technical and understandable. Hopefully you’ll find it useful, especially if I’ve just sent you this link.

What is notarization?

Starting with macOS Catalina (10.15), applications that are not distributed through the Mac App Store must be notarized by Apple. In short, after building an application, you need to upload the build to Apple, have them sign it with their certificate, and then download a receipt from them which gets stapled to the application to show that it is notarized. During this process, Apple verifies the application does not contain malware.

Importantly, you can only staple notarization receipts to packaged applications, which are basically fancy folders containing the application’s files. It is not currently possible to staple a receipt to a standalone executable since there is nowhere to store it. The only workaround is to convert the executable into a packaged application.

When most applications are run (see below for exceptions), Apple will verify the stapled receipt. If a receipt wasn’t stapled to the application, macOS will check with Apple’s servers to see if the application is notarized. If a receipt exists, or the server responds positively, then the application will run normally. If both checks fail, macOS will display an error and refuse to run the application.

Screenshot of the alert that appears when an application isn't notarized

How does notarization work?

Notarization is built on top of a technology called Gatekeeper, which is built on top of extended file attributes. Starting with OS X 10.5, files downloaded via certain methods, such as a web browser, receive a quarantine flag. When users launch an application, Gatekeeper checks for the quarantine flag. In macOS 10.15, if the quarantine flag is present, Gatekeeper will verify the application is notarized and prevent it from running if it is not. Previous versions of macOS would only display a warning.

The current implementation introduces a loophole: the quarantine flag is not set for all downloaded files. For example, games downloaded by Steam do not currently have a quarantine flag, so the notarization check is not run for those games. This loophole extends to basically all applications downloaded or updated by custom mechanisms.

What will notarization look like in the future?

In a session from WWDC 2019, an Apple employee recommended that all software be notarized (emphasis mine):

First, sign and notarize all the software that you distribute, even if it doesn’t get quarantined today.

We don’t know if the loophole for Steam and other downloads is intentional and will remain forever, but their wording leaves the possibility of an expanded quarantine in the future, and Apple is the type of company that chooses their words carefully.

We should hopefully receive more information during WWDC20, but it’s probably a safe bet that we’ll see more changes to notarization in the next version of macOS.