# MacOS Codesigning Scripts Well, here we are. The Apple notarization procedure is complex enough that I need an actual pile of scripts and writeup to be able to remember how to do it. The basic procedure is as follows: - Build code - Build docs - Sign binary with Developer Application ID - Upload binary to notarization service to get notarized - Use code + docs to generate a component package - Use component package to generate a distribution package - Sign distribution package with Developer Installer ID - Upload distribution package to notarization service to get notarized Et. voila, you have a notarized distribution package which can be installed. I fully anticipate that this procedure will break in the future, so here is the (scant) documentation that I have been able to scrape together on these procedures, along with some commentary on things that I've found and requirements for these scripts. You will need XCode installed. ## Short-form Command Line Invocation If you have the prerequisites set up (including the environment variables as described below, built docs, and built release binary), you can generate the package file with the following command: ``` ./install/macos_packages/build_and_notarize.sh target/release/starship docs x64 ``` or `arm64` if building on Apple silicon. ## Setting Up Credentials ### Apple Developer Account In order to get the signing keys, you need to have a developer account. You can buy one at https://developer.apple.com/programs/ for $100 a year (at time of writing). There is no other way to acquire an account, which is needed to obtain non-self-signed keys and to be able to notarize files. ### Signing Keys To generate the signing keys, I went through the [XcodeGUI](https://help.apple.com/xcode/mac/current/#/dev154b28f09), though there are several other methods to do this. You will need at least one Application signing key and one Installer signing key. To check what signing keys are available, you can use the following command: ``` security find-identity -p basic -v ``` ### Notarization Credentials To be able to notarize objects, you will need an app-specific password. You will need to set it up using the instructions [on this page](https://support.apple.com/en-us/HT204397). You will also need your team ID, which can be found at https://developer.apple.com/account/#/membership (if it goes to the home page, click on "Membership" on the left panel), and your Apple ID (usually an email address). If you want to enter everything manually, most commands that require these values accept the `--apple-id`, `--team-id`, and `--password` flags. However, I find it simpler to store the credentials in the keychain. You can do so with the following command: ``` xcrun notarytool store-credentials "" --apple-id "" --password "" --team-id "" ``` where `` is a name you will use later to refer to the credentials, and the other three items are the Apple ID, the Team ID, and the app-specific password, respectively. For the rest of this document, I will assume that its value is `AC_PASSWORD` for compatibility with Apple's website, though you may choose whatever you like. ### Script Assumptions The scripts in this directory assume that the signing keys and the notarization credentials are unlocked and available within a specific keychain file, stored in a file at `$RUNNER_TEMP/$KEYCHAIN_FILENAME`. Additionally, it assumes that the `AUTH_ITEM_NAME` used to refer to the notarization credentials is found in the environment under the variable `KEYCHAIN_ENTRY`. The CI environment ensures that the keychain file exists at the appropriate locations and is destroyed after use. If you are running these scripts locally, the values that correspond to what Apple uses in their tutorials are: ``` KEYCHAIN_ENTRY=AC_PASSWORD # Or whatever you picked for above RUNNER_TEMP=~/Library/Keychains KEYCHAIN_FILENAME=login.keychain ``` Note to developers: because the keychain file may be a user's personal keychain, you MUST NEVER WRITE TO THE KEYCHAIN FILE in these scripts. On the CI, CI actions will ensure that the keychain file is shredded after use. ## Codesigning a Binary This is actually fairly simple. Run ``` codesign --timestamp --sign "" --verbose -f -o runtime ``` to sign the binary file. `--timestamp` is not required for signing, but will be required for notarization. `` can be one of two things: the name of the signing key (on the right of `security find-identity -p basic -v`), or the key hash (the hex string on the left of the command). Usually you can use name of the key, but if you have multiple keys like me, you may need to use the hex string to specify. ## Notarizing a Binary Once the binary has been signed, you need to package it into a .zip file in order to be able to send it to Apple for notarization. The simplest way to do this is to run `zip `. Then, run `xcrun notarytool submit --keychain-profile "AC_PASSWORD" --wait` to submit the binary for notarization. The `--wait` flag will cause the tool to block until the notarialization is complete. If you want to be able to leave and check the results later, omit `--wait` (though starship notarization usually takes no more than 60s). Finally, you should check the submission logs. To get a record of all notarization attempts, run ``` xcrun notarytool history --keychain-profile "AC_PASSWORD" ``` Find the `id` of the attempt you wish to view, then run one of these commands: ``` xcrun notarytool info --keychain-profile "AC_PASSWORD" xcrun notarytool log --keychain-profile "AC_PASSWORD" ``` The `log` command downloads a JSON log of the notarization attempt, and can reveal warnings that should be fixed before the next submission. Additional details on the notarization process can be found at https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow. Note that while Apple has a lot of requirements on their pages, including stuff like Hardened Runtime requirements and listing entitlements, as far as I can tell, starship does not require any of these even though we do things like send notifications and access the network via an HTTP client. Nonetheless, I'm linking the [entitlements page](https://developer.apple.com/documentation/bundleresources/entitlements) here in case it becomes important later. ## Creating a Component Package Since I'm only dealing with one binary, we will make one Component package and one Distribution package. Surprisingly, the flat package (.pkg) format is not documented by Apple. [This guide](https://matthew-brett.github.io/docosx/flat_packages.html) and many of the links within it are the best documentation available on the subject. To build a component package, we first need to create a temporary directory and create a pseudo-filesystem within it (similar to makepkg on Arch). For example, if we place the directory at `$TEMP_DIR/usr/local/bin/starship`, the binary will be installed at `/usr/local/bin/starship` once the installer runs. An aside on docs: We would also like to include documentation in the pkg. Unfortunately, Vuepress currently cannot build with relative paths, and any attempt at hacking this in seems to create even more problems. Instead, the scripts do the dumbest thing imaginable: build the documentation, serve it with a simple HTTP server, and then use `wget` to make a local copy which can be viewed offline. Once everything is placed in the correct locations, we can run the following command to generate the component package: ``` pkgbuild --identifier com.starshipprompt.starship --version "" --root output.pkg ``` ## Notarizing the Component Package (and why we don't need to) Fortunately for us, Apple has confirmed that we only need to notarize the [outermost installer mechanism](https://developer.apple.com/forums/thread/122045). Therefore, if we are sending the component package on its own, we should notarize it now. However, for starship, we will bundle this into a distribution package, so we don't need to notarize this pkg file. ## Creating a Distribution Package To create a distribution, we do the following steps: - Use `productbuild` to generate a skeleton distribution file. - Insert custom welcome/license/conclusion and icon files into the installer. - Build the installer with `productbuild`. I have elected not to make a fat binary due to concerns over startup cost, so there are two .plist files that can be used to specify the architecture required. ## Signing the Distribution package This is also fairly simple, and analogous to signing the binary. ``` productsign --timestamp --sign "" ``` ## Notarizing the Distribution Package Also analogous to notarizing the binary. We run ``` xcrun notarytool submit --keychain-profile "AC_PASSWORD" --wait ``` and also check the submission logs. Note: you may need to enter your password a ridiculous number of times (like 4+) in order to successfully notarize this. ## Stapling the Result Finally, we staple the notarization ticket to the package, ensuring that anyone who downloads the file can see that the installer was notarized: ``` xcrun stapler staple ``` Note that `.dmg`, `.app`, and `.pkg` files can be stapled, but `.zip` and binary files cannot. Distributing the latter files alone will require that the installing computer can access the internet to verify notarization of the app. ## Putting It All Together If you don't want to run these commands, a full workflow is available in `build_and_notarize` script. Check the documentation at the top of the script for environment variables and arguments that need to be set--it is a fairly complicated script, but this is a fairly complicated procedure. # Testing Notarization To test if a particular item is notarized, run one of the following commands: ``` codesign --test-requirement="=notarized" --verify --verbose spctl -a -vvv -t install ``` # External Links https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow https://github.com/akeru-inc/xcnotary https://www.reddit.com/r/rust/comments/q8r90b/notarization_of_rust_binary_for_distribution_on/