#Signing and notarization
krate native sign and notarize - macOS codesign and notarytool, Windows signtool or osslsigncode, Linux gpg signatures, and where secrets come from.
Experimental. Part of Krate Native, which is under construction.
krate native package --sign [--notarize] # sign while packaging
krate native sign [dir] [--target <os/arch>] # sign what is already packaged
krate native notarize [dir] # macOS: notarize and staplesign works on dist-native/packages/<os>-<arch>/, signs the files inside,
then rebuilds the zip, dmg and installers from the signed files and refreshes
the update signature, so every archive carries signed code. The signing tools
are platform tools; each is found in PATH and a missing one is KR7224 with a
hint. Secrets come from environment variables or files. They are never printed:
a password argument shows as **** in the command echo.
#macOS
Runs only on macOS (codesign is part of macOS). The identity is
--identity "Developer ID Application: Acme Inc (ABCDE12345)" or
KRATE_MACOS_IDENTITY. With no identity the app is signed ad hoc
(--sign -), which runs locally but is not trusted by Gatekeeper.
Signing goes inside out: every nested Mach-O file, framework and helper bundle
first (the Go host binary, bundled runtimes), then the .app, each with
codesign --force --options runtime --timestamp --entitlements <file> --sign <id>, then codesign --verify --deep --strict. An ad hoc signature uses
--timestamp=none.
Entitlements are generated next to the package as entitlements.plist, or
pass --entitlements <file>. A WKWebView app needs none: the page's JavaScript
and its JIT run in Apple's WebContent process, and the embedded QuickJS host
and the Go runtime do not JIT. If native.host.runtime is node, bun or
deno the file gets com.apple.security.cs.allow-jit and
allow-unsigned-executable-memory, which their JIT needs under the hardened
runtime. The app is not sandboxed by default, so the network client
entitlement is not added.
#Mac App Store
A Mac App Store build is signed differently (sandbox entitlements, no hardened
runtime, an "Apple Distribution" or "3rd Party Mac Developer Application"
identity, a signed .pkg) and is signed while it is packaged:
krate native package --target mas. krate native sign refuses a store build.
See Stores and universal apps.
#Notarization
krate native notarize (or package --sign --notarize) zips the app with
ditto, runs xcrun notarytool submit --wait, then xcrun stapler staple and
validate, and rebuilds the archives so the ticket is inside them. Credentials,
first match wins:
| Source | Variables or flag |
|---|---|
| Keychain profile (best) | --keychain-profile <name> or KRATE_NOTARY_PROFILE; create it once with xcrun notarytool store-credentials |
| App Store Connect API key | KRATE_NOTARY_KEY (path of the .p8), KRATE_NOTARY_KEY_ID, KRATE_NOTARY_ISSUER |
| Apple ID | KRATE_NOTARY_APPLE_ID, KRATE_NOTARY_TEAM_ID, KRATE_NOTARY_PASSWORD (app-specific password) |
Missing credentials are KR7226. A password given to notarytool is a process
argument that other users on the machine can see; prefer a profile or key. A
rejected submission prints Apple's status and the id for xcrun notarytool log
(KR7225).
#Windows
Authenticode with signtool on Windows, or osslsigncode anywhere. Without
either, KR7224. A pure Go signer is out of scope.
| Variable or flag | Meaning |
|---|---|
KRATE_WINDOWS_PFX or --pfx |
certificate file |
KRATE_WINDOWS_PFX_PASSWORD |
its password (environment only) |
KRATE_WINDOWS_CERT_SHA1 or --thumbprint |
certificate in the Windows store (signtool only) |
KRATE_WINDOWS_TIMESTAMP_URL or --timestamp-url |
RFC 3161 server, default http://timestamp.digicert.com |
It runs signtool sign /fd SHA256 /tr <ts> /td SHA256 /f <pfx> /p <password>
(or /sha1 <thumbprint>) on the .exe and .dll files of the install tree
before the zip, the NSIS installer and the MSIX are built, then on the NSIS
installer and the MSIX. An MSIX installs only if its signature's subject
equals bundle.windows.publisher.
#Linux
With --gpg-key <id> (or KRATE_GPG_KEY) every .deb, .rpm, .tar.gz and
.AppImage gets a detached, armored signature <file>.asc from gpg. The key
passphrase is handled by gpg-agent.
#What CI checks
The CI native job signs with throwaway keys made inside the job, so the code
paths run against the real tools, not stand-ins:
| OS | Signing | Verified with |
|---|---|---|
| Linux | krate native sign --gpg-key with a key from gpg --gen-key |
gpg --verify on every .deb, .rpm, .tar.gz and AppImage, and a tampered copy must fail |
| macOS | ad hoc (--sign), and --identity <hash> of a self-signed code-signing certificate in a temporary keychain |
codesign --verify --deep --strict, codesign -dvv (the identity is named, or Signature=adhoc), and a tampered bundle must fail |
| Windows | signtool with a certificate from New-SelfSignedCertificate, trusted in the job |
signtool verify /pa, Get-AuthenticodeSignature, and the signed MSIX installs |
A self-signed signature is real but trusted by nobody else: Gatekeeper and
SmartScreen still warn, and the MSIX installs only because the job trusts its
certificate. Notarization stays manual. It needs an Apple Developer account
and credentials that CI does not have, and so do Developer ID signing and an
Authenticode certificate from a public authority; run krate native notarize
yourself for a release and check it with spctl -a -vv and xcrun stapler validate. An RPM gets a detached .asc like the other Linux packages, not an
embedded RPM signature, so rpm -K reports digests only.
#Update signatures are separate
Update files are signed with the updater key, not with a platform certificate; see Updates. Do both for a release: the platform signature makes the OS trust the app, the updater signature makes the app trust the update.
Last updated: 2026-11-17
Contributors: Noinkin