Signing Mozilla apps for Mac OS X

Mac OS X's Gatekeeper functionality prevents users from launching applications that haven't been code-signed, in order to help keep their computers secure. Firefox and Thunderbird releases are both signed before shipping; this article describes the process.

Signing Mozilla apps without the signing server

Firefox and Thunderbird are built using Mozilla's Release Automation infrastructure. On Mac OS X, part of this infrastructure is automatic signing of the ".app" folder using Apple's codesign tool. For projects that don't use Mozilla's Release Automation and would like to be signed for secure launching on OS 10.8 Mountain Lion and later, this guide should provide some insight into how to make sure applications are signed correctly using Apple's codesign tool. Apple's Code Signing Guide is also a good resource on the subject.

Getting a signing certificate

In order to code-sign an application, you need a signing certificate.

While testing and debugging

For test and debug purposes, the easiest way to get a signing certificate is to use Apple's Keychain feature to create one. There are good instructions available under "To use the Certificate Assistant to Create a self-signed signing identity".

For release

Creating a Developer ID requires a paid Apple Developer Account. Once you have that you can do the following to create your ID:

Open the Developer Certificate Utility.
Click "Certificates" from the left hand menu.
Click "Create a Certificate" at the top right corner
Select the "Developer ID" radio button and uncheck the "Developer ID Installer Certificate" box.
Click "Create" and follow the instructions in the wizard. It will guide you through creating a private key, certificate signing request, and importing your new Developer ID into the Keychain Access application on your Mac. If the "Developer ID" radio button is greyed out you probably have a group account. These types of accounts only allow for the "Agent" role to create Developer IDs. Contact the person who created your group Apple Developer Account if you get stuck here.

The codesign tool

Apple provides a tool called codesign; this command-line application is used to add a signature to an application bundle. The man page for codesign is available online, or you can simply type "man codesign" in a Terminal window. The main options of note are:

-s your-signing-identity: Lets you specify the signing certificate you want to sign the application with your-signing-identity is the name of your certificate.
--keychain /path/to/keychain: Lets you specify which keychain contains the signing certificate specified by your-signing-identity, rather than allowing the codesign to search the keychain list. The path specified must be a full path; it's usually something similar to /Users/username/Library/Keychains/keychain-name.keychain.
--resource-rules /path/to/coderesources: Specifies a file to use when generating the rules to be applied to the code signing. When you're signing Mozilla applications with v1 signatures, you'll need to specify a custom CodeResources file here.
-f: Forces codesign to overwrite an existing signature on the application.
-v: Increases the verbosity of the codesign tool's output.
--deep: For v2 signing, sign all nested executables with the same settings. Note that you cannot specify an identifier requirement if you do this, or otherwise you need to sign the outer application again with the identifier requirement.
--requirement 'designated requirement': Adds additional requirements for verifying the signature and application metadata. At a minimum you'll need to provide:

identifier: This must be the same as the value of the CFBundleIdentifier specified in your application's info.plist file.
leaf[subject.OU]: This needs to be the subject OU of your Developer ID. You can find it by running this command in the terminal:

openssl x509 -text -noout -inform DER -in devloperID_application.cer | grep Subject

Putting it all together, you'll wind up using a command similar to the one below to sign your app. You'll of course need to change the signing ID, keychain, bundle path, and requirements.

codesign -s Mac-Testing -fv \
         --keychain /Users/user/Library/Keychains/MyKeychain.keychain \
         --resource-rules ./Application.app/Contents/_CodeSignature/CodeResources \
         --requirements '=designated => identifier "org.you.yourapp" and ( (anchor apple generic and certificate leaf[field.1.2.840.113635.100.6.1.9] ) or (anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] and certificate leaf[field.1.2.840.113635.100.6.1.13] and certificate leaf[subject.OU] = "43AQ936H96"))' \
         Application.app

Or if you're using v2 signing, the command might look like this:

codesign -s Mac-Testing -fv --deep \
         --keychain /Users/user/Library/Keychains/MyKeychain.keychain \
         --requirements '=designated => ( (anchor apple generic and certificate leaf[field.1.2.840.113635.100.6.1.9] ) or (anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] and certificate leaf[field.1.2.840.113635.100.6.1.13] and certificate leaf[subject.OU] = "43AQ936H96"))' \
         Application.app

Depending on your keychain preferences, the codesign command may display a popup asking for the password for the specified keychain. Once the application has been signed, the signature of an application bundle can be validated by calling:

codesign -vvvv Application.app

Where Application.app is the application bundle you wish to validate. The folder will fail to validate if any of these cases occur (there may be other cases not listed here):

If any files that were included in the signature have been removed or modified
If any files have been added to a folder that should have all files signed

The CodeResources file

This file is located in your application's bundle at Contents/_CodeSignature/CodeResources. If you don't provide one, codesign will automatically generate it. However, to modify Apple's automatic signing process (for example, to exclude a file or folder), you'll need to provide this file.. Once the application bundle is signed, this file will contain the hashes/checksums of all files that are included in the signature. If any file is subsequently changed, the folder will no longer validate.

The CodeResources file used to sign official Firefox and Thunderbird builds is available in mozilla-central. For more details on using the CodeResources file, refer to the Code Resources section on Erick Dransch's blog post about code signing.