To ship a product outside of the Mac App Store, you must notarise it. The notary service issues a notarised ticket, and the ultimate consumer of that ticket is Gatekeeper. However, Gatekeeper does not just check the ticket; it also applies a variety of other checks, and it’s possible for those checks to fail even if your notarised ticket is just fine. To avoid such problems showing up in the field, test your product’s compatibility with Gatekeeper before shipping it.
To do this:
Set up a fresh machine, one that’s never seen your product before. If your product supports macOS 10.15.x, x < 4, the best OS version to test with is 10.15.3 [1].
Download your product in a way that quarantines it (for example, using Safari).
Disconnect the machine from the network. It might make sense to skip this step. See the discussion below.
Install and use your product as your users would.
If the product is signed, notarised, and stapled correctly, everything should work. If not, you’ll need to investigate what’s making Gatekeeper unhappy, fix that, and then retest. For detailed advice on that topic, see Resolving Trusted Execution Problems.
Run this test on a fresh machine each time. This is necessary because Gatekeeper caches information about your product and it’s not easy to reset that cache. Your best option is to do this testing on a virtual machine (VM). Take a snapshot of the VM before the first test, and then restore to that snapshot when you want to retest.
Also, by using a VM you can disable networking in step 3 without disrupting other work on your machine.
The reason why you should disable networking in step 3 is to test that you’ve correctly stapled the notarised ticket on to your product. If, for some reason, you’re unable to do that stapling, it’s fine to skip step 3. However, be aware that this may cause problems for a user if they try to deploy your product to a Mac that does not have access to the wider Internet. For more background on this, see The Pros and Cons of Stapling.
[1] macOS 10.15.4 fixes a bug that made Gatekeeper unnecessarily strict (r. 57278824), so by testing on 10.15.3 you’re exercising the worst case.
The process described above is by far the best way to test your Gatekeeper compatibility because it accurately tests how your users run your product. However, you can also run a quick, albeit less accurate test, using various command-line tools. The exact process depends on the type of product you’re trying to check:
App — Run syspolicy_check like this:
% syspolicy_check distribution WaffleVarnish.app
This tool was introduced in macOS 14. On older systems, use the older spctl tool. Run it like this:
% spctl -a -t exec -vvv WaffleVarnish.app
Be aware, however, that this check is much less accurate.
Disk image — Run spctl like this:
% spctl -a -t open -vvv --context context:primary-signature WaffleVarnish.dmg
Installer package — Run spctl like this:
% spctl -a -t install -vvv WaffleVarnish.pkg
Other code — Run codesign like this:
% codesign -vvvv -R="notarized" --check-notarization WaffleVarnish.bundle
This command requires macOS 10.15 or later.
Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"
Revision history:
2024-12-05 Added instructions for using syspolicy_check. Made other minor editorial changes.
2023-10-20 Added links to Resolving Trusted Execution Problems and The Pros and Cons of Stapling. Made other minor editorial changes.
2021-02-26 Fixed the formatting.
2020-04-17 Added the section discussing spctl.
2020-03-25 First version.
