Article

Notarizing Your App Before Distribution

Give users even more confidence in your software by submitting it to Apple for notarization.

Overview

Notarization gives users more confidence that the Developer ID-signed software you distribute has been checked by Apple for malicious components. Notarization is not App Review. The Apple notary service is an automated system that scans your software for malicious content, checks for code-signing issues, and returns the results to you quickly. If there are no issues, the notary service generates a ticket for you to staple to your software; the notary service also publishes that ticket online where Gatekeeper can find it.

When the user first installs or runs your software, the presence of a ticket (either online or attached to the executable) tells Gatekeeper that Apple notarized the software. Gatekeeper then places descriptive information in the initial launch dialog to help the user make an informed choice about whether to launch the app.

Gatekeeper lets the user know that Apple notarized the app being launched.

You can notarize several different types of software deliverables, including:

  • macOS apps

  • Non-app bundles, such as kernel extensions

  • Disk images (UDIF format)

  • Flat installer packages

Notarization also protects your users if your Developer ID signing key is exposed. The notary service maintains an audit trail of the software distributed using your signing key. If you discover unauthorized versions of your software, you can work with Apple to revoke the tickets associated with those versions.

Prepare Your Software for Notarization

Notarization requires Xcode 10 or later. Building a new app for notarization requires macOS 10.13.6 or later. Uploading and stapling an app requires macOS 10.12 or later.

Apple's notary service requires you to adopt several protections for your software. Specifically, you must:

  • Enable code-signing for all of the executables you distribute.

  • Enable the Hardened Runtime capability for your executable targets, as described in Enable hardened runtime.

  • Use a Developer ID application or installer certificate for your code-signing signature. (Don't use a Mac Distribution or local development certificate.) For more information, see Managing signing certificates.

  • Include a secure timestamp with your code-signing signature. (The Xcode distribution workflow includes a secure timestamp by default. For custom workflows, include the --timestamp option when running the codesign tool.)

  • Not include the com.apple.security.get-task-allow entitlement with the value set to any variation of true.

Apple recommends that you notarize all of the software that you distributed before WWDC 2018, even if it doesn't meet all of these requirements. For more information, see Notarize Your Pre-Existing Software.

Notarize Your App Automatically as Part of the Distribution Process

Before distributing your app directly to customers, your team agent must sign the app with your Developer ID. Xcode’s Organizer window includes a workflow for generating a distributable version of your app. In Xcode 10 and later, this workflow includes an option to notarize your app automatically. To notarize your app using this workflow, do the following:

  1. Open your Xcode project.

  2. Create an archive of your app.

  3. Open Xcode's Organizer window.

  4. In the Archives tab, select the archive you created.

  5. Click Distribute App to view the distribution options.

  6. Choose Developer ID for your method of distribution.

  7. Click Next.

  8. Choose Upload to send your archive to the Apple notary service.

  9. Click Next.

When distributing an app, choosing the upload option sends the app to Apple to be notarized.

When you click Next, Xcode uploads your archive to the notary service. When the upload is complete, the notary service begins the scanning process, which usually takes less than an hour. While the notary service scans your software, you can continue to prepare your archive for distribution. For example, you can export the archive and perform any final testing that you require prior to making your software available to customers.

When the notarization process finishes, Xcode downloads the ticket and staples it to your archive. At that point, export your archive again to receive a distributable version of your software that includes the notary ticket.

For more information about how to use the Xcode UI to upload your software, see Upload a macOS app to be notarized.

Notarize Your Pre-Existing Software

Notarizing your pre-existing software lets Gatekeeper warn users when they try to run it. It also helps the notary service distinguish your legitimate software from variants that have been tampered with. You can notarize an existing disk image, installer package, or ZIP archive containing your app.

To notarize your pre-existing software, do the following:

  1. Make Xcode 10 your active Xcode installation. (If you're not sure whether Xcode 10 is the active installation, use the xcode-select command-line to make it active. For information about how to use this tool, see the man page for it.)

  2. Upload your software to the Apple notary service, as described in Upload Your App to the Notarization Service.

  3. Staple the returned ticket to your existing software, as described in Staple the Ticket to Your Distribution.

For tips on how to resolve issues that can occur during notarization, see Resolving Common Notarization Issues.

Add a Notarization Step to Your Build Scripts

If you use an automated build system, you can integrate the notarization process into your existing build scripts. The altool and stapler command-line tools (included with Xcode) allow you to upload your software to the Apple notary service, and to staple the resulting ticket to your executable.

For information about how to incorporate notarization into your custom build scripts, see Customizing the Notarization Workflow.

Topics

Notarization

Customizing the Notarization Workflow

Notarize your app from the command line to handle special distribution cases.

Resolving Common Notarization Issues

Handle common problems reported in the notarization log file, or that arise during ticket stapling.

See Also

Secure Code

Code Signing Services

Examine and validate signed code running on the system.

Preparing Your App to Work with Pointer Authentication

Test your app against the arm64e architecture to ensure that it works seamlessly with enhanced security features.