Notarization
Apple notarization is a required step for distributing macOS applications outside the Mac App Store. KestrelSign handles the entire process -- submission, progress tracking, and ticket stapling.
What is Notarization?
Notarization is Apple's automated security check for software distributed outside the App Store. You submit your signed application to Apple's notary service, which scans it for malicious content and verifies the code signature. If it passes, Apple issues a "ticket" that Gatekeeper recognizes, allowing the application to run without warnings.
Prerequisites
- Your application must be signed with a Developer ID certificate and hardened runtime
- An App Store Connect API key, or your Apple ID with an app-specific password
- Apple's
notarytool(included with Xcode Command Line Tools)
Configuring Credentials
KestrelSign supports two methods for authenticating with Apple's notary service:
App Store Connect API Key (recommended)
This is the preferred method. You create an API key in App Store Connect and provide KestrelSign with the Key ID, Issuer ID, and the private key file (.p8). This method does not require two-factor authentication and is more reliable for automated workflows.
Apple ID
You can also use your Apple ID email and an app-specific password.
Generate the app-specific password at
appleid.apple.com under Security. This method works
but is being phased out by Apple in favor of API keys.
The setup wizard walks you through configuring either method and stores your credentials in a notarization profile on your Mac.
The Notarization Process
1. Archive Creation
KestrelSign creates a zip archive of your signed application using
Apple's ditto tool. This preserves symlinks, extended
attributes, and resource forks that are critical for valid code signatures.
Standard zip tools can corrupt these attributes, so KestrelSign always
uses the native tool.
Important: KestrelSign uses ditto rather than
Python's built-in zipfile module specifically because standard zip tools
strip symlinks and extended attributes, which invalidates the code signature.
2. Submission
The archive is uploaded to Apple's notary service using notarytool submit.
KestrelSign shows real-time upload progress and provides the submission ID
for tracking.
3. Progress Tracking
After submission, Apple processes your application. This typically takes between 2 and 15 minutes, though it can occasionally take longer. KestrelSign polls the notary service and displays the current status in the project dashboard.
4. Results
When processing completes, you will see one of three results:
- Accepted -- your app passed. KestrelSign proceeds to stapling.
- Invalid -- something failed the check. KestrelSign retrieves the notarization log with details about what went wrong.
- Rejected -- the app was rejected (rare, usually indicates malware detection).
5. Stapling
Once accepted, KestrelSign automatically staples the notarization ticket
to your application using xcrun stapler staple. Stapling
embeds the ticket directly in your app bundle, so Gatekeeper can verify
it even when the user is offline.
Notarization Log
If notarization fails, KestrelSign retrieves the detailed log from Apple and displays it in the project dashboard. The log identifies specific files or issues that caused the failure, such as unsigned binaries, missing hardened runtime, or invalid entitlements.
Common Issues
Upload fails or times out
Large applications can take time to upload. If you have a slow connection, be patient. If the upload repeatedly fails, check your network connection and verify your credentials are correct.
Rejected: contains unsigned binaries
Every executable in your app bundle must be signed. This includes helper apps, frameworks, plugins, and dynamic libraries. Use KestrelSign's inside-out signing to ensure everything is covered.
Rejected: hardened runtime not enabled
Apple requires the hardened runtime for notarization. Make sure the hardened runtime entitlement is enabled in your project settings. KestrelSign enables this by default.