Notarizing GMAT on macOS

GMAT must be notarized before distributing it on macOS. Notarization is a process by which Apple scans all files in an application (executables and data) to ensure they are safe for public use. The GMAT development team notarizes and releases GMAT under NASA’s Apple organizational identity.

These instructions detail the requirements and process of notarizing GMAT on macOS prior to any type of distribution, including public (e.g. a GMAT release) or NASA-internal (e.g. release or testing versions). They apply to active members of NASA’s GMAT development team.

The notarization process requires NASA’s Apple developer certificates. To obtain these:

1. Create an Apple Account at https://account.apple.com

   1. NASA best practice is to use your NASA email address for your Apple Account.

   2. You do not need to add a credit card.

   3. You do not need to enroll in the Apple Developer Program, that will automatically happen when your Apple ID is added to NASA’s developer account in a later step.

2. Create an App-Specific Password for the notarization process

   1. Securely store the 16-character password before closing the generation window. It will no longer be retrievable after generation.

   2. Any name is acceptable, e.g. “Notarize” or “Notarize on GMAT Mac”.

   3. Note: All App-Specific Passwords are deleted and must be regenerated when the account password is changed

      Open

      

3. Contact the admin of NASA’s Apple Account, and give them a heads-up that you are a NASA GMAT developer who needs NASA developer certificates to notarize GMAT. You will be asked to submit a NAMS request for this.

   1. The NASA GMAT project lead can provide the name of NASA’s Apple Account admin.

4. Create a NAMS request for “Agency Apple Developer”.

   1. Sponsor: GMAT project lead

   2. Role: Developer

   3. Justification: “The NASA GMAT (General Mission Analysis Tool) software project needs to notarize GMAT for release on macOS.”

   4. Apple ID: Your Apple Account email

5. Once your NAMS request is approved, you will be sent two developer certificates (P12 files) and associated passwords by email. One for Application signing and one for Installer signing. Save them both to your computer.

6. Download Apple’s master Developer ID certificate, which will authenticate the NASA certificates

   1. Go to https://www.apple.com/certificateauthority/

   2. Download the Apple Intermediate Certificate: Developer ID - G2

7. Install the Developer ID certificate and both NASA certificates to your login keychain by double-clicking each one. They will be installed in the Keychain Access application. Note: As of macOS 14 Sonoma, there is a new Passwords application that handles most passwords, however Keychain Access still handles certificates.

8. Confirm that the certificates are installed by launching the Keychain Access application and searching for the following certificates:

   1. Developer ID Application: NASA

   2. Developer ID Installer: NASA

   3. Developer ID Certification Authority: The correct one will have Organizational Unit: G2 if you right-click and select “Get Info”.

   4. Both should show the message “ This certificate is valid”

9. Add the App-Specific Password to the local Keychain. This allows the password to only be entered once during the notarization process, and is required on any machine that will perform automated GMAT builds. This only needs to be done once for a given macOS account.

   1. Open a Terminal and run the following command at the prompt
      % xcrun notarytool store-credentials --apple-id "myappleid@organization.com" --team-id "82A95CK2HC"

   2. This will interactively prompt for the following inputs:

      1. Desired Profile Name: recommend using the Apple ID

      2. App-Specific Password: 16-character password created in the Apple Account

   3. A success message indicates this step was successful

Once the App-Specific Password has been created and all certificates loaded, the GMAT application can be notarized.

1. Follow the instructions at Compiling GMAT (CMake Build System) to create a macOS build of GMAT. By default this will be called GMAT-<versionName>-Darwin-x64 where versionName is the current release, e.g. R2026a. It will be in the root GMAT/ source folder.

2. Open a Terminal and navigate to the GMAT/build/install folder

3. Run the following command to notarize GMAT
   % mac_notarizeGMAT.sh -v <versionName> -u <notaryProfile> [-p <packageDirPath>]
versionName: GMAT version, e.g. R2026a
   notaryProfile: notarytool profile name stored in keychain, in quotes if it has spaces. e.g. -u myappleid@organization.com
packageDir: (Optional) Absolute path to GMAT folder to be distributed. If absent, assumes GMAT folder is GMAT-<versionName>-Darwin-x64 and is located in the root of the GMAT repository (CMake default).

Notarization can take several minutes, and performs the following steps:

1. Copies the GMAT folder to an adjacent GMAT <versionName> folder. This will be the final distributed folder.

2. Uses the NASA developer certificate to sign all executables, files, and folders inside GMAT <versionName>.

3. Bundles the folder into a signed disk image GMAT-<versionName>-Darwin-x64-signed.dmg

4. Uploads the signed disk image to Apple’s notary service. This step can take several minutes based on upload speeds and the current workload of Apple’s notarization servers.

   1. If successful, Apple’s notary service will respond with status: Accepted.

5. Attaches (in Apple’s terms, “staples”) the successful notarization ticket to the signed disk image.

   1. If successful, the stapler will respond with The staple and validate action worked!

If successful, this concludes the GMAT macOS notarization process! The signed disk image can be distributed per the rules of the signing authority.

If errors happen while running the mac_notarizeGMAT.sh script, they will be either signing errors or notarization errors.

Signing errors are either caused by improper certificate loading or issues with the GMAT folder being signed.

• Certificate issues should be handled by ensuring that both NASA developer certificates indicate that they are trusted in the Keychain Access application.

• GMAT folder issues should be addressed with the GMAT development team.

Apple’s notarization service is cloud-based, so errors must be diagnosed by retrieving the log file.

1. Find the notary submission id, which is shown during the notarization process. For example:

   Submitting to notarization service - this may take a while ... Conducting pre-submission checks for GMAT-R2026a-Darwin-x64-signed.dmg and initiating connection to the Apple notary service... Submission ID received id: de28f82c-5200-4c66-9aae-1a6aba44b921

2. Retrieve the notarization log file using the Submission ID and notary profile used during submission:
   % xcrun notarytool log de28f82c-5200-4c66-9aae-1a6aba44b921 --keychain-profile myappleid@organization.com

3. This will show a log of all errors, which should be addressed with the GMAT development team.