SPB Git

Repository Public

notarization.md 7.9 KB 145 lines markdown

1# Notarization23This 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.45Related pages: [signing](signing.md), [distribution](distribution.md), [release checklist](checklist.md).67## Prerequisites89| Requirement | Detail |10|---|---|11| 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](signing.md)) |12| 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 |13| Network access to Apple's notary service | `notarytool submit --wait` blocks until Apple answers |1415The 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`.1617## Usage1819```sh20Scripts/notarize.sh [target] [name]21```2223| Argument | Default | Meaning |24|---|---|---|25| `target` | `dist/ORIX DJ.app` | the bundle or file to notarize |26| `name` | `app` | short name used for the files written under `build/notary/` |2728`Scripts/release.sh` calls it twice:2930```sh31Scripts/notarize.sh "dist/ORIX DJ.app" app32Scripts/notarize.sh "dist/ORIX-DJ-$VERSION.dmg" dmg33```3435## What the script does3637It runs from the repository root with `set -euo pipefail`.3839| Step | Action | Outcome on failure |40|---|---|---|41| 1 | Check that the target exists | exit 1: "not found. Run Scripts/sign.sh first." |42| 2 | Create `build/notary/` | |43| 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 | |44| 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 |45| 5 | Read `status` and `id` from the JSON with `/usr/bin/python3` and print `submission <id>: <status>` | |46| 6 | Fetch the notary log: `xcrun notarytool log <id> --keychain-profile "$PROFILE" build/notary/<name>-log.json` (errors ignored) | |47| 7 | Require `status` to be exactly `Accepted` | exit 3: "RESULT: NOT notarized. See build/notary/<name>-log.json" |48| 8 | `xcrun stapler staple <target>` | non-zero status stops the script |49| 9 | `xcrun stapler validate <target>` | non-zero status stops the script |50| 10 | Print `RESULT: <target> is notarized by Apple (submission <id>) and stapled.` | |5152Two properties of this sequence matter:5354- 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`.55- 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.5657## Why two submissions5859| Submission | Submitted file | Stapled object | Purpose |60|---|---|---|---|61| `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 |62| `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 |6364The 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](distribution.md)).6566## Files written6768| File | Content |69|---|---|70| `build/notary/app.zip` | upload archive of the application |71| `build/notary/app.json`, `build/notary/dmg.json` | notarytool JSON answer (`id`, `status`, ...) |72| `build/notary/app.json.err`, `build/notary/dmg.json.err` | standard error of notarytool |73| `build/notary/app-log.json`, `build/notary/dmg-log.json` | Apple's notary log for the submission |7475`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`.7677## Results of the release run7879Nothing below has been produced yet.8081### Application8283| Field | Value |84|---|---|85| Profile used | `MacLustr-Notarize` unless `NOTARY_PROFILE` was set |86| Submission ID | `eafc4e24-d278-4460-8cef-0d7827e2481e` |87| Status | Accepted ("Ready for distribution") |88| Issues in `build/notary/app-log.json` | none (`issues: null`) |8990```text91xcrun stapler staple / validate "dist/ORIX DJ.app"92```9394```text95Processing: dist/ORIX DJ.app96The validate action worked!97```9899### Disk image100101| Field | Value |102|---|---|103| Submission ID | `4c301728-4b75-4c88-b3b2-831d986bcbaa` (an earlier submission of a plain fallback image was superseded when the designed image was rebuilt) |104| Status | Accepted ("Ready for distribution") |105| Issues in `build/notary/dmg-log.json` | none (`issues: null`) |106107```text108xcrun stapler staple / validate "dist/ORIX-DJ-1.0.0.dmg"109```110111```text112Processing: dist/ORIX-DJ-1.0.0.dmg113The validate action worked!114```115116## Checking a notarized artifact by hand117118```sh119xcrun stapler validate "dist/ORIX DJ.app"120xcrun stapler validate dist/ORIX-DJ-1.0.0.dmg121spctl --assess --type execute --verbose=2 "dist/ORIX DJ.app"122spctl --assess --type open --context context:primary-signature --verbose=2 dist/ORIX-DJ-1.0.0.dmg123xcrun notarytool log <submission-id> --keychain-profile MacLustr-Notarize124```125126These 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](distribution.md) after the run.127128## If a submission is refused129130The script gives three distinct exit codes, which map to three situations:131132| Exit code | Situation | Where to look |133|---|---|---|134| 1 | nothing to submit | run `Scripts/sign.sh` (or `Scripts/package.sh` for the disk image) first |135| 2 | notarytool itself failed: unknown profile, expired credentials, no network, agreement not accepted | `build/notary/<name>.json.err` (first lines are printed) |136| 3 | Apple processed the submission and did not accept it | `build/notary/<name>-log.json` |137138The 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](signing.md)), none is expected, but this has not been confirmed by a real submission.139140After 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.141142## What notarization does not establish143144Notarization 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](checklist.md), none of which has been passed yet.145
Files main
Menu

Theme