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, use the
codesign utility to test the signature:
vvv flag to perform a verification with elevated verbosity. You use the
deep flag to ensure the utility checks nested code content. The
strict flag increases the restrictiveness of the validation to match that required by notarization. See the
codesign man page for more information about these flags and how to interpret the output.
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:
To learn about managing your signing certificates in Xcode, see Manage Signing Certificates. Alternatively, you can use the
codesign utility with the
s flag to manually sign your app:
deep flag to recursively sign nested code—like helpers, frameworks, and plug-ins—and the
force flag to ensure that
codesign replaces any existing signatures with new ones as it traverses the hierarchy. The
preserve-metadata flag tells
codesign to reuse the given information from a previous signature when creating a new one. Include the
timestamp flag because notarization requires a secure timestamp, as described in Include a Secure Timestamp. The optional
vv flag increases the verbosity of the console output.
Include a Secure Timestamp
By default, Xcode doesn’t include a secure timestamp as part of the app’s code signature during the build or archive process. Instead, it adds a secure timestamp only during the export workflow. 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 flag to your
OTHER build setting, or by using the flag 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 flag 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-Tasks-Allow Entitlement
When you create a new macOS project, Xcode automatically sets the target’s
INJECT 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, either export your app directly from Xcode, or set the
INJECT build setting to
NO before building your app for distribution. But only do this when you’re done debugging and ready to distribute, because changing this build setting 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 flag 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.