Handle common problems reported in the notarization log file, or that arise during ticket stapling.
Framework
- Security
Overview
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.
Note
Xcode automatically resolves many issues when you use the standard app distribution UI. For information about how to use this UI, see Notarize Your App Automatically as Part of the Distribution Process.
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:
The signature of the binary is invalid.
To debug signing issues, use the codesign
utility to test the signature:
$ codesign -vvv --deep --strict /path/to/binary/or/bundle
Use the 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:
The binary is not signed with a valid Developer ID certificate.
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:
$ spctl -vvv --assess --type exec /path/to/application
Add the --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:
The signature does not include a secure timestamp.
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.
Note
Generating a secure timestamp requires Internet access.
You can check if a binary has a secure timestamp with the following command:
$ codesign -dvv /path/to/binary/or/bundle
The 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-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:
The executable requests the com.apple.security.get-task-allow entitlement.
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.
Note
To enable debugging a plug-in in the context of a host executable, the host can include the com
entitlement if it also includes the Disable Library Validation Entitlement
. Don’t disable library validation for executables that don’t host plug-ins because library validation protects them from loading untrusted code.
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:
The binary uses an SDK older than the 10.9 SDK.
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:
The executable does not have the hardened runtime enabled.
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:
--options=runtime
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.
Important
You can notarize an app that you build with earlier versions of Xcode, but you must use Xcode 10 or later to actually perform the notarization. This is because the altool
utility, which you use to perform notarization, only supports notarization starting in Xcode 10. See Customizing the Notarization Workflow.
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:
$ sudo killall -9 trustd; sudo rm /Library/Keychains/crls/valid.sqlite3
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
utility.
See the stapler
man page for a discussion of other exit codes.