0 Replies
      Latest reply on Apr 17, 2020 3:27 AM by eskimo
      eskimo Apple Staff Apple Staff (13,895 points)

        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:

        1. 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].

        2. Download your product in a way that quarantines it (for example, using Safari).

        3. Disconnect the machine from the network.

        4. 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 why Gatekeeper is unhappy [2], fix that, and then retest.

        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).  You can 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.

        [1] macOS 10.15.4 fixes a bug that made Gatekeeper unnecessarily strict (r. 57278824).

        [2] Unfortunately it’s not always easy to work out what Gatekeeper is unhappy about.  I’ve posted some hints on this thread.


        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 spctl as follows:

          % spctl -a -t exec -vvv WaffleVarnish.app

          .

        • Disk image — Run spctl as follows:

          % spctl -a -t open -vvv --context context:primary-signature WaffleVarnish.dmg

          .

        • Installer package — Run spctl as follows:

          % spctl -a -t install -vvv WaffleVarnish.pkg

          .

        • Other code — Run codesign as follows:

          % codesign -vvvv -R="notarized" --check-notarization WaffleVarnish.bundle

          Note This requires macOS 10.15 or later.

        Share and Enjoy

        Quinn “The Eskimo!”
        Apple Developer Relations, Developer Technical Support, Core OS/Hardware
        let myEmail = "eskimo" + "1" + "@apple.com"

        Change history:

        • 25 Mar 2020 — First version.

        • 17 Apr 2020 — Added the section discussing spctl.