Code sign and notarize your macOS application

This page details the process of code signing and notarization for macOS applications.

Code signing is the process of creating a code signature for an application. This signature guarantees the integrity of applications and safeguards from any tampering. Apple devices use an application’s code signature to detect changes made after the code signature was created. If an application doesn’t have a code signature, the device warns the end user before they open it. Unity automatically code signs any application it builds for macOS.

Notarization is when Apple verifies your application to ensure it has a Developer ID code signature and doesn’t contain malicious content. For more information about notarization, refer to Apple’s documentation on macOS Code Signing in Depth and Notarizing macOS Software Before Distribution.

If you develop on an Apple device, you can use Xcode, Xcode command-line tools, or Unity Cloud Build to notarize your application. If you don’t have an Apple device, use Unity Cloud Build.

This page has information on the following notarization methods:

• Notarization using Xcode
• Notarization using Xcode command-line tools
• Notarization using Unity Cloud Build

Note: Notarization isn’t required to distribute your application through the Mac App Store. The Mac App Store’s upload process includes similar content validation to notarization. Refer to Delivering to the Mac App Store for more information.

Use Xcode to notarize your application

Unity can create an Xcode project that represents your Unity project during the build process. You can use this Xcode project to notarize your application. Follow the macOS application build steps to create an Xcode project from your Unity project. For information on notarizing the Xcode project, see Apple’s documentation on Notarizing macOS Software Before Distribution.

Use Xcode command-line tools to notarize your application

If you can’t notarize your application in the Xcode environment or want to control notarization manually, you can use Xcode’s command-line tools. To do this, you need the following:

• An Apple ID.
• An Apple device that runs macOS 10.15 Catalina or later.
• Xcode 11 or later. This installs the required command-line tools.
• An Apple Developer Program membership. If you don’t have an Apple Developer membership, sign up at Apple Developer.

Code sign your application

To notarize your application with the Xcode command-line tools, you must first code sign the application. This section explains how to code sign your application using Xcode’s command-line tools.

Signing identity

Unity adds a code signature to every macOS build it produces. This simple code signature doesn’t identify you as the developer. To notarize an application, Apple requires the code signature to include a cryptographic signature that identifies the developer. This is called a signing identity. Usually, you use a Developer ID certificate.

To create a new Developer ID certificate, go to Create a New Certificate:

1. Follow the prompts to create a private key and upload a Certificate Signing Request.
2. Download your Developer ID certificate. The file format for this certificate is .cer.
3. Click on the certificate to add it to your Keychain. Within the Keychain, it appears with a name formatted like: Developer ID Application : XXX (YYY).

Application identifier

To notarize your application, Apple needs to identify it. There are two ways to get the application identifier: in Unity, or in the built application’s information property list file.

• In Unity:
  1. Go to Edit > Project Settings > Player.
  2. Expand the Other Settings section and go to Mac App Store Options.
  3. See the value of Bundle Identifier.
• In the information property list file:
  1. In the Finder, go to your built application.
  2. Right-click on the application and select Show Package Contents.
  3. Go to Contents and open Info.plist.
  4. The key that represents the application identifier is CFBundleIdentifier.

When you have your application identifier, you can register it with Apple. To do this:

1. Go to Apple Developer and log in.
2. Select Certificates, IDs & Profiles.
3. Select Identifiers
4. Add your bundle ID.

Entitlements

Entitlements are permissions or restrictions your code signature includes that allow or prevent your application from taking specific actions.

To set entitlements for your application:

1. In the same directory as your built application, create a file with the same name as your application with the .entitlements file extension. For example, if your application is called Sample, create a file called Sample.entitlements.
2. Open the file with a text editor and copy in the following content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
       <key>com.apple.security.cs.disable-library-validation</key>
       <true/>
       <key>com.apple.security.cs.disable-executable-page-protection</key>
       <true/>
    </dict>
</plist>

These entitlements are the minimum entitlements a macOS application requires to have a Hardened Runtime. If your application requires any more entitlements, add them to this list.

Code sign an application

The code signing process uses the command line. To start, open Terminal and navigate to the directory that the application is in. To ensure that you have the necessary read permissions to process code signing, run the following command where "application_name.app" is the name of your application:

chmod -R a+xr "application_name.app"

A code signature uses a particular signing identity. Usually, this is your Developer ID Application signing identity. However, some digital distribution services, such as the Mac App Store require a different signing identity.

To code sign your application, run the following command where:

• "application_name.app" is your built application.
• `“application_name.entitlements” is the name of the entitlements file.
• "Developer ID Application : XXX (YYY)" is your signing identity.

codesign --deep --force --verify --verbose --timestamp --options runtime --entitlements "application_name.entitlements" --sign "Developer ID Application : XXX (YYY)" "application_name.app"

This command recursively navigates through the application bundle folder, signs all files, adds a secure timestamp, and embeds the entitlements you’ve set into the signature.

Warning: Using the --deep option might cause issues with your code signature. This is because:

• It applies the same code signing options and entitlements to all the code that it signs.

• It only signs code files that it finds. If there are code files in a place where the system expects to find data, using --deep doesn’t sign these code files.

For more information about the --deep option and how to resolve issues with it, refer to Sign your code.

Upload an application for notarization

After you code sign your application, you must upload it to Apple for notarization. To fulfill the upload requirements, the following items are necessary:

• An Apple ID.
• A compressed application.
• An application password.
• A provider short name.

Compress the application

Apple requires that you compress your application before you upload it for notarization. To do this:

1. Open Terminal and navigate to the directory the application is in.

2. Run the following command where:
   • "application_name.app" is your built application.
   • "application_name.zip" is the name of the compressed file to generate.

ditto -c -k --sequesterRsrc --keepParent "application_name.app" "application_name.zip" 

This compresses your application and outputs the compressed file to the same directory as your application.

Generate an application password

To notarize an application, Apple requires a unique password in a particular format. To generate an application password, you need to have an Apple ID. If you don’t have one, go to Manage your Apple ID and create one.

For information on how to generate an application password, refer to How to generate an app-specific password. The password you generate uses the following format: xxxx-xxxx-xxxx-xxxx.

Retrieve your provider short name

A provider short name is a single-word label that identifies an individual or a company. Apple uses a provider short name to determine which organization to notarize for when your Apple ID is associated with more than one organization. To get your provider short name:

1. Open Terminal.
2. Run the following Xcode command where:
   • apple_id is your Apple ID.
   • xxxx-xxxx-xxxx-xxxx is your application password.

xcrun iTMSTransporter -m provider -u apple_id -p xxxx-xxxx-xxxx-xxxx

Start the upload process

For Apple to notarize your application, you need to upload it to their notarization servers. To do this:

1. Open Terminal and navigate to the directory the compressed application is in.
2. Run the following command where:
   • apple_id is your Apple ID.
   • xxxx-xxxx-xxxx-xxxx is your application password.
   • provider_short_name is your provider short name.
   • application_bundle_id is the application’s application identifier.
   • application_name.zip is the compressed application.

xcrun altool --notarize-app --username apple_id --password xxxx-xxxx-xxxx-xxxx --asc-provider provider_short_name --primary-bundle-id application_bundle_id --file application_name.zip

If the upload is successful, Apple displays a response in Terminal that contains a request ID. You can use this request ID to check on the status of your request. This is useful because the notarization process might take multiple hours depending on the traffic to the service. To do this:

1. Open Terminal and navigate to the directory the compressed application is in.
2. Run the following command where:
   • request_id is the request ID that Apple returns from the previous command.
   • apple_id is your Apple ID.
   • xxxx-xxxx-xxxx-xxxx is your application password.
   • provider_short_name is your provider short name.

xcrun altool --notarization-info request_id --username apple_id --password xxxx-xxxx-xxxx-xxxx --asc-provider provider_short_name

When the notarization process is complete, Apple sends you a confirmation email at the address associated with your Apple ID. You can then verify that notarization was successful. To do this:

1. Open Terminal and navigate to the directory the application is in.
2. Run the following command where:
   • application_name.app is the name of your application:

spctl -a -v application_name.app

If notarization was successful, this returns a message that indicates that Apple accepted the application and includes your Developer ID.

Staple the application

After notarizing your application, any device that runs it can verify that it has a code signature and contains no malicious content. However, the device can only perform this verification online. To verify your application on a device without an internet connection, you must staple the application. For information about stapling, refer to Staple the Ticket to Your Distribution.

To staple your application,

1. Open Terminal and navigate to the directory the application is in.
2. Run the following command where "ApplicationName.app" is the name of your application: xcrun stapler staple "ApplicationName.app".

Notarization using Unity Cloud Build

Unity Cloud Build can notarize and staple your macOS application during the build process. To do this, Unity requires the following:

• An Apple ID.
• An application-specific password.
• An Apple Developer Program membership.
• An entitlements file.
• A Developer ID certificate exported in the PKCS #12 Personal Information Exchange (.p12) file format.
• The password you used to create the .p12 file.
• Your provider short name.

Depending on the platform you are developing on, the process for some of these requirements differs. If you develop on an Apple device, you can use Xcode command-line tools to get the information and create the relevant files. If you develop on Windows or Linux, you won’t have access to Apple-specific Xcode command-line tools.

Regardless of which platform you use, the process to get the Apple ID, password, and entitlements files are platform-agnostic:

1. If you don’t have an Apple ID, go to Manage your Apple ID and create one.
2. Create an application password. For information on how to do this, refer to Generating an application Password.
3. If you don’t have an Apple Developer membership, sign up at Apple Developer.
4. Create an entitlements file for your application. For information on how to do this, refer to Entitlements.

After you complete these steps:

• If you are developing on macOS, see Unity Cloud Build notarization for Apple devices.
• If you are developing on Windows or Linux, see Unity Cloud Build notarization for Windows and Linux devices.

Unity Cloud Build notarization for Apple devices

If you develop on an Apple device, you can use Xcode command-line tools to meet the requirements listed in Notarization using Unity Cloud Build. You can then set up Unity Cloud Build to notarize and staple your application as part of the build process. To meet the requirements:

1. Follow the platform-agnostic steps in Notarization using Unity Cloud Build.
2. Create a Developer ID certificate and add it to your Keychain. For information on how to do this, refer to Signing identity.
3. Export the Developer ID certificate from the Keychain as a file in Personal Information Exchange (.p12) format. For information on how to do this, refer to Import and export keychain items using Keychain Access on Mac.
4. Get your provider short name. For information on how to do this, refer to Getting your provider short name.

After you meet the requirements, fill out and submit the Unity Cloud Build notarization form.

Unity Cloud Build notarization for Windows and Linux devices

If you develop on Windows or Linux and want to build, notarize, and staple your application for macOS, you can’t use Xcode command-line tools. To meet the requirements listed in Notarization using Unity Cloud Build to set up Unity Cloud Build to notarize and staple your application as part of the build process:

1. Follow the platform-agnostic steps in Notarization using Unity Cloud Build.
2. Create a Developer ID certificate and download it. For information on how to do this, refer to Signing identity. Note: The last step in Signing identity is only relevant for macOS users.
3. Convert the Developer ID certificate to the PKCS #12 Personal Information Exchange (.p12) file format. For information on how to do this, refer to Converting a Developer ID certificate to a .p12 file on Windows and Linux.
4. Get your provider short name through your Apple Developer account. To do this, go to Membership Details and find your Team ID. You can use the Team ID as a provider short name.

After you meet the requirements, fill out and submit the Unity Cloud Build notarization form.

Convert a Developer ID certificate to a .p12 file on Windows and Linux

A .p12 file bundles both your Developer ID certificate and a private key. To create one from your Developer ID certificate:

1. Open a command-line interface and go to the directory that contains your Developer ID certificate file. If you didn’t download your Developer ID certificate, refer to Signing identity.

2. Developer ID certificates use the .cer file format. Convert this file to the .pem file format. To do this, run the following command where:
   • developer_identity.cer is the Developer ID certificate file to convert.
   • developer_identity.pem is the file name and file type to output.

   openssl x509 -in developer_identity.cer -inform DER -out developer_identity.pem -outform PEM

3. Generate a new private key. To do this, run the following command where:
   • mykey.key is the file name of the private key to output.

   openssl genrsa -out mykey.key 2048

4. Generate the .p12 file. To do this, run the following command where:
   • mykey.key is the private key file you generated in step 3.
   • developer_identity.pem is the .pem file you generated in step 2.

   openssl pkcs12 -export -inkey mykey.key -in developer_identity.pem -out iphone_dev.p12

Submit the Unity Cloud Build notarization form

After you meet the requirements outlined in Notarization using Unity Cloud Build, follow these steps to setup Unity Cloud Build notarization:

1. Set up your project to use Unity Cloud Build. For information on how to do this, refer to Unity Cloud Build.
2. Create a new Mac Desktop build target in Cloud Build.
3. Return to the Config page. This page now includes the Notarization section. Open this section and click EDIT NOTARIZATION.
   
4. Enable the Notarization flag. If you have previously supplied a set of notarization credentials to Unity Cloud Build for the same Organization, you can select those from Credentials. Otherwise, select Add new provisioning credentials.
   
5. Provide the following:
   • Name: the name for your credentials set. You can use these credentials for any additional projects you set up in the same organization.
   • p12 File: The .p12 file you created in either Unity Cloud Build notarization for Apple devices or Unity Cloud Build notarization for Windows and Linux devices, depending on your platform.
   • Entitlements File (optional): The entitlements file you created in Notarization using Unity Cloud Build. If you do not provide an entitlements file, Unity Cloud Build uses the minimum entitlements a macOS application requires to have a Hardened Runtime. For information on what these minimum entitlements are, refer to Entitlements.
   • p12 Password: The password you supplied when you created the .p12 file.
   • Provider Short Name (optional): The provider short name you acquired in either Unity Cloud Build notarization for Apple devices or Unity Cloud Build notarization for Windows and Linux devices, depending on your platform. If your Apple ID is associated with more than one organization and you don’t provide this, notarization fails.
   • Apple ID Username: Your Apple ID username.
   • Apple ID Password: The application password you created in Notarization using Unity Cloud Build. Unity Cloud Build does not verify Apple credentials until it attempts to notarize your build, so make sure to enter the correct username and password.
   • Confirm your Apple ID Password: A repeat of the Apple ID Password.
     
6. Save your credentials.
7. Return to the Build History page and start a build for your Mac target.
8. If the build succeeds, Unity Cloud Build attempts to notarize and stable the result.
   • Cloud Build runs the codesign command with the following flags: --deep --force --verify --verbose --timestamp --options runtime. It’s not currently possible to specify custom flags.
   • Additional log outputs from notarization are available using the environment variable FASTLANE_NOTARIZE_VERBOSE=true in your build target Environment Variables.
9. After Unity Cloud Build builds, notarizes, and staples your project, you can download a compressed file that contains the build.