Signing, Notarization & OS Trust

Gatekeeper checks software that came from outside the App Store the first time it is opened. By default, downloaded software must be signed by a registered developer and notarized by Apple, and Gatekeeper asks for user approval before downloaded software opens for the first time. Apple’s platform security guide says Gatekeeper "tracks the provenance of files written by downloaded software": a quarantine-aware application such as a browser marks what it downloads with the com.apple.quarantine extended attribute, and that mark is what makes the first-launch check apply. A person who is sure of the source can override a block in System Settings, Privacy & Security, with the Open Anyway button.

Source: Apple Platform Security — Gatekeeper and runtime protection and Apple Support — Safely open apps on your Mac.

Two consequences matter for a command-line tool. First, the check is attached to the way a file arrived, not to its type: a binary fetched with curl is not quarantined, because curl does not set the attribute. The attribute is just an extended attribute, and the example below shows it by setting it by hand.

The file written by curl carries no com.apple.quarantine attribute (it shows only com.apple.provenance, an attribute that Apple’s public documentation does not describe); the attribute appears on shelf only because the example sets it by hand to the kind of value a browser would write. Do not mark files this way as a test of the real flow: download a build with Safari or Chrome on a clean Mac, as described under Verifying what a user sees. The Apple documentation describes the quarantine mechanism only in general terms and does not document how Gatekeeper treats a bare command-line tool that a user starts from a shell. Second, whatever the details, Apple’s rules for Developer ID software apply to command-line tools too: the notarization requirements below name "app and command line targets".

Source: Apple — Notarizing macOS software before distribution.

On Apple silicon, the linker signs what it produces. Compiling the shelf example produced a valid, ad hoc, linker-signed binary with no certificate behind it.

That signature lets the kernel run the file, and it detects changes, but TeamIdentifier=not set shows no identity vouches for it. Gatekeeper’s policy assessment agrees:

An ad hoc build is correct for development and for swift build output that you run yourself. It is not something to ship to other people. man codesign and man spctl are the reference; Apple’s public documentation pages read for this page do not describe the linker signature.

Notarization imposes a short list of requirements on the software you submit. For a command-line tool they are: a valid code signature on every executable, a Developer ID Application certificate (not a Mac Distribution, ad hoc, Apple Development or local certificate), the hardened runtime enabled for "app and command line targets", a secure timestamp in the signature, no com.apple.security.get-task-allow entitlement set to true, and linking against the macOS 10.9 or later SDK.

Source: Apple — Notarizing macOS software before distribution and Apple — Customizing the notarization workflow. This command needs a Developer ID certificate in the keychain and was not run while the page was written.

The same command with --sign - (ad hoc) was run, to show what each option changes. Without --identifier, codesign derives an identifier from the file name and a hash (shelf-55554944ed39c0e65496385ea1dadb0b279bf190); with it, the identifier is stable across builds, which is what a requirement or an entitlement lookup should rely on.

The runtime in flags confirms that the hardened runtime is on. On a universal binary, sign after lipo has produced the final file (see Command-Line Tools in Swift for a universal build), because any later change invalidates the signature.

The options table summarizes the flags used on this page; man codesign lists the others.

The hardened runtime, together with System Integrity Protection, protects the runtime integrity of a process against code injection, library hijacking and memory tampering. It does not affect most tools. The few things it disallows can be re-enabled one at a time with entitlements, which apply to executables; shared libraries and in-process plug-ins inherit the entitlements of their host. Apple’s advice is to use only the entitlements that are absolutely necessary.

A plain shelf needs none of them. A tool built on a runtime that generates code (the JVM, Node.js, a Python with a JIT) needs at least allow-jit, and the entitlements file is passed with --entitlements.

Source: Apple — Hardened Runtime.

Hardened-runtime protections also change how a tool behaves under a debugger and with injection tools, and com.apple.security.get-task-allow must not be set to true in a notarized build. The Apple notarization page names it as a reason for rejection.

The notary service accepts disk images (UDIF), signed flat installer packages and ZIP archives. It does not accept a bare executable file, so a standalone tool is archived first. ditto is the archiver the Apple examples use for bundles; for a single file it produces a ZIP that notarytool accepts.

Source: Apple — Customizing the notarization workflow. These commands need a paid Apple Developer Program membership and network access to Apple’s notary service and were not run while the page was written. The page above also describes app-specific passwords and the store-credentials keychain item; the API-key form shown here is the one that CI uses, and the credential options are explained on Distributing Mac Apps with Developer ID and Notarization. The installed notarytool was version 1.1.3 (42).

The service generates a ticket for the top-level file and for each nested file. Apple says to check the log even when notarization succeeds, because it can contain warnings to fix before the next submission. Notarization completes for most software within minutes. An Invalid result is resolved from the log; Apple’s Resolving common notarization issues page lists the usual causes (missing hardened runtime, missing secure timestamp, an unsigned nested binary, a debug entitlement).

Stapling attaches the notarization ticket to a file, so Gatekeeper can find it with no network connection and future copies carry it. Apple’s documentation states the limit directly: you can staple a ticket to an app, bundle, disk image or flat installer package; "while you can notarize a ZIP archive, you can’t staple to it directly"; and "although tickets are created for standalone binaries, it’s not currently possible to staple tickets to them."

The run below used an unnotarized shelf, so the failure shown is the "record not found" one; it is not a demonstration of the stapling limit, which comes from the documentation and not from this output.

Source: Apple — Customizing the notarization workflow.

There are three honest options, in order of how well they behave offline.

The reasoning behind the table is in Apple’s own text, which says that Gatekeeper finds the ticket online for any notarized software, and that you "should also attach the ticket" with stapler so that "Gatekeeper can find the ticket even when a network connection isn’t available". For a bare binary only the first half is possible.

Whichever container you ship, sign the tool inside it with Developer ID Application and the hardened runtime before you build the container. Apple’s guidance for a custom third-party installer is two rounds: notarize and staple the payload, then package it and notarize the installer.

pkgbuild builds a flat component package from a directory that mirrors the install location. The commands below (except productsign and notarytool) were run with an ad hoc signed tool, and the package was verified as unsigned.

Source: Apple — Customizing the notarization workflow. pkgbuild and pkgutil ran locally with the output shown; the Developer ID signing, productsign, notarization and stapling steps need certificates and an account and were not run. A disk image is built the same way (the hdiutil create command with -volname shelf, -srcfolder root/usr/local/bin and -format UDZO ran), then signed with codesign and a Developer ID Application identity, and submitted and stapled like the package. Which certificate signs which container (Application for apps and images, Installer for packages) is described on the Apple distribution page linked at the top.

Three commands check a release before you publish it, and a final manual test confirms it.

The spctl --assess command assesses the policy; for a notarized, correctly signed file it reports an accepted source, and for the ad hoc shelf it reported rejected, as shown earlier. The only real test is the user’s path: upload the container, download it with a browser onto a Mac that has never seen the file, and open it.

How a file reaches the disk decides whether Gatekeeper applies. A browser download is quarantined; a file written by curl, tar or a package manager is not, and an installer script that downloads with curl leaves a tool that is not subject to the first-launch check. That is not a reason to skip signing: the signature still identifies the build and can be verified by codesign, and the same file is the one that passes Gatekeeper when someone later downloads it with a browser. The packaging channels and their signing requirements are compared on Native Packages & Installers.

Windows code signing is called Authenticode. signtool.exe is installed with the Windows SDK in the Bin folder of the SDK path (for example C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64\signtool.exe). It has four commands (catdb, sign, timestamp, verify) plus remove, and returns exit code 0 for success, 1 for failure and 2 for completion with warnings. Newer SDK builds require the digest algorithm explicitly: SignTool’s sign command needs /fd (the file digest) and, when timestamping with /tr, /td (the timestamp digest). Microsoft recommends SHA256.

Source: Microsoft — SignTool. These commands need a code-signing certificate and a Windows machine and were not run while the page was written. The timestamp URL is the one used in the Microsoft examples; use your certificate authority’s server.

For verification, signtool verify /pa uses the Default Authentication Verification Policy; without /pa it uses the Windows Driver Verification Policy, which is the wrong one for an ordinary program. /tw warns when a signature has no timestamp, and /all checks every signature of a file that has more than one. signtool remove /s strips a signature.

Without a timestamp, a signature is valid only while the signing certificate is. A timestamp from an RFC 3161 server proves that the signature existed while the certificate was valid, so the file keeps verifying after the certificate expires. SignTool does not timestamp unless /tr or /t is given, and if the timestamp request fails it produces only a warning, so a CI job must check the result with signtool verify /pa /tw. The timestamp rules are the same for installers; see Timestamping in the MSIX page.

Microsoft Defender SmartScreen checks downloaded files against a list of reported malicious programs and against a list of files that are well known and downloaded frequently; if the file is not on that list, it shows a warning that advises caution. It also checks the digital signature used to sign a file. The page states the rule that matters for a new tool: if a URL, file, app or certificate has an established reputation, users do not see warnings; if there is no reputation, the item is treated as higher risk and the user sees one. SmartScreen protects against malicious files from the internet, not against files on network shares addressed with UNC paths.

What this means for shelf.exe:

Source: Microsoft — Microsoft Defender SmartScreen overview.

Microsoft’s Artifact Signing (formerly called Trusted Signing) is a managed signing service. It provides certificate lifecycle management inside FIPS 140-3 level 3 certified HSMs, integrates with developer toolsets, supports external timestamping services and public-trust signing, and signs a digest so that your file never leaves your machine. An account contains an identity validation and a certificate profile, and comes as a Basic or a Premium SKU. For signtool it is used through the /dlib option. The GitHub Actions workflow, the prices and the regions in which it is available are covered on the Azure Artifact Signing section of the MSIX page; this page does not repeat them. Other vendors' cloud-HSM and token-based services work through /dlib or through their own tools; the SignTool documentation lists the mechanism and not the vendors.

Source: Microsoft — What is Artifact Signing?.

Sign the executable, then sign the container: an MSI or EXE installer with signtool, an MSIX with signtool and a certificate whose subject matches the manifest publisher (see the MSIX page), and a ZIP of loose files cannot carry a signature of its own, so the files inside must be signed. A winget manifest records the installer’s SHA-256 (InstallerSha256), so sign first and hash afterwards; the policy on whether signing is required is on Distribution Channels. Cross-compiling a Windows tool from Linux or macOS is covered on Native Binaries & Cross-Compilation; signtool itself runs only on Windows, and the SignTool documentation describes no other signer.

A downloaded ELF file starts when its execute bit is set, with no signature check. The kernel does not know about publishers. Linux distributions put trust in two places instead: the package manager checks signed repository metadata and package signatures when installing, and the user (or an install script) checks a signature or checksum that the project publishes. Everything on this page for Linux is therefore a convention a user must apply, not an enforcement that happens automatically, which is why the way you publish matters: the more of the chain a package manager checks, the fewer users skip it.

Publish a SHA256SUMS file with every release and sign it, not the archives one by one, so that a user verifies one signature and one file.

A checksum proves the download is intact; it proves who built it only when the checksum file is itself signed or served over a trusted path. The same file feeds package manager manifests, such as the Homebrew sha256 and the winget InstallerSha256. The tool sha256sum is from GNU coreutils and was not run on this macOS host; macOS ships shasum -a 256 for the same job.

GPG remains what distribution repositories use. A detached, ASCII-armored signature sits next to the file.

Source: Debian Wiki — SecureApt (the gpg -abs form for signing a Release file). The gpg commands were not run while the page was written. The project key’s fingerprint must be published on a channel separate from the download (the project site, a signed commit or tag), otherwise a verified signature only shows that the file matches a key that came from the same place.

Sigstore’s cosign sign-blob signs a file. The documentation recommends keyless signing, in which an ephemeral key is tied to an OpenID Connect identity, and recommends a bundle (--bundle), which carries the verification metadata and must be stored for verification. --yes bypasses confirmation prompts for unattended runs.

Source: Sigstore — Signing blobs and Sigstore — Verifying signatures. These commands were not run while the page was written. The identity and issuer values in the verify command are an example for a GitHub Actions workflow and must be replaced; the cosign pages document the identity and issuer flags in general terms, and the GitHub-specific values come from the workflow’s own identity, as on the Security page.

Keyless verification is only as strong as the identity you ask for. Accepting any identity that Sigstore will certify is the same as accepting no publisher at all, so scripts must pin both the identity and the issuer.

The SLSA 1.0 specification describes provenance as a record of what entity built an artifact, the process it used and its inputs. Its build track has levels: L0 (none), L1 (provenance exists, but is easy to bypass or forge), L2 (a hosted build platform generates and signs the provenance) and L3 (a hardened platform isolates builds and protects the signing secrets). GitHub artifact attestations, which gh attestation verify checks, are the practical way to publish provenance for a GitHub release; the attestation links an artifact to its source and build and is not a certificate that the artifact is safe. The commands are on Packaging & Distribution.

Source: SLSA — Security levels.

For a .deb, apt checks a chain: the signed Release file lists the checksums of the Packages files, and those list the checksum of every package. The Release file is signed with an OpenPGP key, and apt aborts when a check fails. Trusted keys are kept as files in /etc/apt/trusted.gpg.d/ (the debian-archive-keyring package manages Debian’s) and apt-key has been removed in Debian 13. For a third-party repository, the key is converted to binary with gpg --dearmor and stored, for example under /usr/share/keyrings/; verifying that key is left to the administrator. A publisher builds the metadata with apt-ftparchive and signs it:

Source: Debian Wiki — SecureApt. The page is partly dated: it does not describe the inline-signed InRelease file or the signed-by option for source entries, so check the current apt-secure(8) and sources.list(5) manual pages before publishing a repository. The commands were not run while the page was written.

For RPM repositories, DNF has separate switches, all defaulting to False:

Source: DNF Configuration Reference. A published repository that ships gpgcheck=0 or omits the key gives users no verification, so the repository file that your documentation tells users to install should set the checks on explicitly. Building .deb and .rpm files with nfpm, hosting repositories and the Snap, AppImage and Nix channels are on Native Packages & Installers.