Handle common problems reported in the notarization log file, or that arise during ticket stapling.
If the Apple notary service encounters any problems while notarizing your app, it reports those errors in the log files, as described in Check the Status of Your Request. Fix any problems reported by the service and notarize your app again.
Ensure a Valid Code Signature
Before you can notarize an app, you must first code sign it. If you don’t, or if you make a modification to the bundle after signing, notarization fails with the following message:
To debug signing issues for anything besides an installer package, use the
codesign utility to test the signature:
vvv option to perform a verification with elevated verbosity. You use the
deep option to ensure the utility checks nested code content. The
strict option increases the restrictiveness of the validation to match that required by notarization. See the
codesign man page for more information about these options and how to interpret the output.
To debug signing issues with installer packages, use the
pkgutil utility instead:
The utility’s output includes the strings “Signed with a trusted timestamp” and “1. Developer ID Installer:” for a properly signed installer. If the signature test fails, make sure you’re using a Developer ID Installer certificate, and that you use either the
productbuild utility during package creation, or the
productsign command to sign an existing installer. All of these command line utilities take the
sign option, which includes a secure timestamp by default. See the man pages of the various utilities for more information about using each.
Use a Valid Developer ID Certificate
You can only notarize apps that you sign with a Developer ID certificate. If you use any other certificate — like a Mac App Distribution certificate, or a self-signed certificate — notarization fails with the following message:
Be sure to use the correct Developer ID certificate for the given target. When code signing items like Mach-O files, disk images, bundles, apps, command line tools, photos, and so on, sign with a Developer ID Application certificate. Sign installer packages with a Developer ID Installer certificate. Although distributing kernel extensions (kexts) is discouraged, you can use a Developer ID Application certificate that has the kext capability to do so.
To learn about managing your signing certificates in Xcode, see Manage Signing Certificates.
Additionally, you can use the
spctl utility to determine if the software to be notarized will run with the system policies currently in effect:
raw option to generate a more detailed output in the form of a property list.
Include a Secure Timestamp
By default, Xcode doesn’t include a secure timestamp as part of the app’s code signature during the build process. Instead, it adds a secure timestamp only during the archive (as of Xcode 10.2) and export workflows. If you use a custom export process, notarization might fail with the following message:
In this case, be sure to add a secure timestamp by adding the
timestamp option to your
OTHER build setting, or by using the option directly with the
codesign utility if you sign manually, as described in the previous section.
You can check if a binary has a secure timestamp with the following command:
dvv option tells codesign to display information about the code at the given path with elevated verbosity. For a binary with a secure timestamp, the output of this command includes a
Timestamp value with a corresponding date. Alternatively, the presence of
Signed Time in the output indicates the binary doesn’t have a secure timestamp.
Avoid the Get-Task-Allow Entitlement
When you create a new macOS project, Xcode automatically sets the target’s
CODE build setting to
YES. This setting tells Xcode to add the
com entitlement to your app at build time. This entitlement facilitates debugging on a system that uses System Integrity Protection (SIP) by circumventing certain security checks.
However, this poses a security risk for a shipping app, because it can allow an attacker to inject code at runtime. As a result, Xcode automatically strips the entitlement from your app when you export and sign it using the standard workflow. If you use a custom workflow and fail to remove the
com entitlement, notarization fails with the following message:
To avoid receiving this error message, archive (as of Xcode 10.2) or export your app directly from Xcode, or set the
CODE build setting to
NO before building your app for distribution. But only change the build setting when you’re done debugging and ready to distribute, because doing so makes it impossible to debug the binary on a system that uses System Integrity Protection.
Use the macOS 10.9 SDK or Later
Because of significant differences in the way code signing works prior to macOS 10.9 (see Code Signing Changes in OS X Mavericks 10.9), notarization only works for binaries linked against macOS 10.9 or later. If you use an older SDK, notarization fails and reports an issue with the following message:
Using a newer SDK doesn’t affect your binary’s compatibility with earlier versions of macOS. Instead, version compatibility depends on the app’s deployment target, as described in Edit deployment info settings.
Enable the Hardened Runtime
Enable the hardened runtime capability as described in Enable hardened runtime (macOS). This adds security restrictions to your app by default while allowing you to ask for specific exceptions as needed. If you don’t enable the hardened runtime, notarization fails and reports an issue with the following message:
Hardened runtime is available in the Capabilities pane of Xcode 10 or later, but you can enable the feature manually using earlier versions of Xcode, as long as you’re on macOS 10.13.6 or later. To do this, add the following option to the
OTHER build setting:
If you need exceptions, manually add the entitlements to your app’s entitlements file. If you enable hardened runtime manually using an earlier version of macOS, make sure that you also test your app running on macOS 10.14 or later.
Handle Stapler Issues
You can resolve a few common stapler issues by upgrading your tools. In particular, if you see
error -68 on macOS 10.13.x, you can resolve the issue by upgrading to macOS 10.14 or later. Alternatively, run the following command once to clear the Valid cache:
If you see
error -73 while using Xcode 10, you can resolve this issue by upgrading to Xcode 10.1 or later. Also, in this case, check to ensure that the disk image or flat installer package you’re notarizing is writable so you can attach the ticket to the package with the
stapler man page for a discussion of other exit codes.
Ensure Properly Formatted Entitlements
Command line tools and apps use entitlements to gain access to system resources and capabilities. The file that declares an app’s entitlements must be ASCII-encoded and must not include Unicode Byte Order Marks (BOMs). When using Xcode to code sign, Xcode ensures that the entitlements file is a well-formed XML property list with no extra characters. It also automatically converts entitlement files stored as binary property lists (
bplist) into properly-formed XML properly lists.
When using a custom workflow, use the
plutil utility to ensure proper formatting of your entitlements file. This is especially true if you manually edit the file. Validate the formatting before passing your entitlements file as an argument to the
codesign utility. The
convert option converts the entitlements to an XML property list, and the
lint option verifies proper formatting:
After code signing — but before notarizing — you can verify your app or command line tool has a properly formed XML entitlement property list:
If the output of this command contains the text
bplist00, the executable has a binary property list, which the notary service will reject with an error message like:
Furthermore, starting in macOS 10.15.4, processes with malformed embedded entitlements no longer run and instead abort with a code signature validation error message: