SPB Git

Repository Public

notarization.md 7.9 KB

# Notarization

This page describes how ORIX DJ is notarized by Apple and how the ticket is stapled, as implemented by Scripts/notarize.sh. Notarization is done twice per release: once for the application and once for the disk image. No submission has been made yet for version 1.0.0; submission identifiers and tool output will be recorded here after the release run.

Related pages: signing, distribution, release checklist.

# Prerequisites

Requirement Detail
A signed application dist/ORIX DJ.app, produced by Scripts/sign.sh: Developer ID signature, Hardened Runtime, secure timestamp, no get-task-allow (all checked by that script, see signing)
A notarytool keychain profile The script uses an existing profile. Its name is taken from the environment variable NOTARY_PROFILE and defaults to MacLustr-Notarize. A notarytool profile exists on the build machine
Network access to Apple's notary service notarytool submit --wait blocks until Apple answers

The script never creates, prints or modifies credentials. Creating the profile (xcrun notarytool store-credentials) is a one-time manual operation that is not part of this repository, and .gitignore excludes notary*.json, *.p8, AuthKey_* and asc.env.

# Usage

sh
Scripts/notarize.sh [target] [name]
Argument Default Meaning
target dist/ORIX DJ.app the bundle or file to notarize
name app short name used for the files written under build/notary/

Scripts/release.sh calls it twice:

sh
Scripts/notarize.sh "dist/ORIX DJ.app" app
Scripts/notarize.sh "dist/ORIX-DJ-$VERSION.dmg" dmg

# What the script does

It runs from the repository root with set -euo pipefail.

Step Action Outcome on failure
1 Check that the target exists exit 1: "not found. Run Scripts/sign.sh first."
2 Create build/notary/
3 If the target is a directory (the .app), compress it to build/notary/<name>.zip with ditto -c -k --keepParent. A file target (the .dmg) is submitted as is
4 xcrun notarytool submit <file> --keychain-profile "$PROFILE" --wait --output-format json, standard output to build/notary/<name>.json, standard error to build/notary/<name>.json.err exit 2: "Notary service refused the submission" followed by the first 8 lines of the error file
5 Read status and id from the JSON with /usr/bin/python3 and print submission <id>: <status>
6 Fetch the notary log: xcrun notarytool log <id> --keychain-profile "$PROFILE" build/notary/<name>-log.json (errors ignored)
7 Require status to be exactly Accepted exit 3: "RESULT: NOT notarized. See build/notary/-log.json"
8 xcrun stapler staple <target> non-zero status stops the script
9 xcrun stapler validate <target> non-zero status stops the script
10 Print RESULT: <target> is notarized by Apple (submission <id>) and stapled.

Two properties of this sequence matter:

  • The success message is printed only after Apple answered Accepted and both stapler commands succeeded. Any other status (Invalid, Rejected, a timeout) ends with a non-zero exit code, which stops Scripts/release.sh.
  • The log is downloaded before the status is tested, so a rejected submission leaves build/notary/<name>-log.json on disk with Apple's list of issues.

# Why two submissions

Submission Submitted file Stapled object Purpose
app build/notary/app.zip (a ZIP of the app made only for upload) dist/ORIX DJ.app The ticket is attached to the bundle itself, so the app passes Gatekeeper offline wherever it is copied, including when extracted from the release ZIP
dmg dist/ORIX-DJ-<version>.dmg the disk image The signed disk image carries its own ticket, so mounting it does not depend on an online check

The order is fixed by the scripts: Scripts/package.sh refuses to run unless xcrun stapler validate "dist/ORIX DJ.app" succeeds, so the disk image and the ZIP always contain an already stapled application. The release ZIP (dist/ORIX-DJ-<version>.zip) is not submitted separately: a ZIP cannot be stapled, and it contains the stapled app. Scripts/finalize.sh extracts it and validates the app inside (see distribution).

# Files written

File Content
build/notary/app.zip upload archive of the application
build/notary/app.json, build/notary/dmg.json notarytool JSON answer (id, status, ...)
build/notary/app.json.err, build/notary/dmg.json.err standard error of notarytool
build/notary/app-log.json, build/notary/dmg-log.json Apple's notary log for the submission

build/ is ignored by git. Scripts/finalize.sh later reads the two JSON answers to copy the submission identifiers and statuses into dist/release.json.

# Results of the release run

Nothing below has been produced yet.

# Application

Field Value
Profile used MacLustr-Notarize unless NOTARY_PROFILE was set
Submission ID eafc4e24-d278-4460-8cef-0d7827e2481e
Status Accepted ("Ready for distribution")
Issues in build/notary/app-log.json none (issues: null)
text
xcrun stapler staple / validate "dist/ORIX DJ.app"
text
Processing: dist/ORIX DJ.app
The validate action worked!

# Disk image

Field Value
Submission ID 4c301728-4b75-4c88-b3b2-831d986bcbaa (an earlier submission of a plain fallback image was superseded when the designed image was rebuilt)
Status Accepted ("Ready for distribution")
Issues in build/notary/dmg-log.json none (issues: null)
text
xcrun stapler staple / validate "dist/ORIX-DJ-1.0.0.dmg"
text
Processing: dist/ORIX-DJ-1.0.0.dmg
The validate action worked!

# Checking a notarized artifact by hand

sh
xcrun stapler validate "dist/ORIX DJ.app"
xcrun stapler validate dist/ORIX-DJ-1.0.0.dmg
spctl --assess --type execute --verbose=2 "dist/ORIX DJ.app"
spctl --assess --type open --context context:primary-signature --verbose=2 dist/ORIX-DJ-1.0.0.dmg
xcrun notarytool log <submission-id> --keychain-profile MacLustr-Notarize

These are the commands Scripts/finalize.sh runs (except the last). For a notarized Developer ID build the two spctl assessments are expected to answer accepted with source=Notarized Developer ID; the actual answers will be recorded in distribution after the run.

# If a submission is refused

The script gives three distinct exit codes, which map to three situations:

Exit code Situation Where to look
1 nothing to submit run Scripts/sign.sh (or Scripts/package.sh for the disk image) first
2 notarytool itself failed: unknown profile, expired credentials, no network, agreement not accepted build/notary/<name>.json.err (first lines are printed)
3 Apple processed the submission and did not accept it build/notary/<name>-log.json

The usual causes of an Invalid status are exactly what Scripts/sign.sh checks beforehand: a binary without Hardened Runtime, a signature without secure timestamp, a get-task-allow entitlement, or unsigned nested code. Since the app has no nested frameworks and no entitlements (see signing), none is expected, but this has not been confirmed by a real submission.

After fixing the cause, the application must be rebuilt and re-signed with Scripts/sign.sh (which erases dist/), and the whole sequence repeated: a stapled ticket belongs to one exact build.

# What notarization does not establish

Notarization is an automated malware and signing check by Apple. It does not test the application's behaviour. That the notarized build starts on a Mac other than the build machine, plays audio, and behaves correctly under the Hardened Runtime are separate gates in the release checklist, none of which has been passed yet.

Files main
Menu

Theme