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:
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.
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.
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:
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.
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:
.cer
.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.
When you have your application identifier, you can register it with Apple. To do this:
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:
.entitlements
file extension. For example, if your application is called Sample, create a file called Sample.entitlements
.<?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.
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."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.
After you code sign your application, you must upload it to Apple for notarization. To fulfill the upload requirements, the following items are necessary:
Apple requires that you compress your application before you upload it for notarization. To do this:
Open Terminal and navigate to the directory the application is in.
"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.
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
.
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:
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
For Apple to notarize your application, you need to upload it to their notarization servers. To do this:
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:
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:
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.
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,
"ApplicationName.app"
is the name of your application: xcrun stapler staple "ApplicationName.app"
.Unity Cloud Build can notarize and staple your macOS application during the build process. To do this, Unity requires the following:
.p12
file.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:
After you complete these steps:
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:
.p12
) format. For information on how to do this, refer to Import and export keychain items using Keychain Access on Mac.After you meet the requirements, fill out and submit the Unity Cloud Build notarization form.
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:
After you meet the requirements, fill out and submit the Unity Cloud Build notarization form.
A .p12
file bundles both your Developer ID certificate and a private key. To create one from your Developer ID certificate:
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.
.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
mykey.key
is the file name of the private key to output.openssl genrsa -out mykey.key 2048
.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
After you meet the requirements outlined in Notarization using Unity Cloud Build, follow these steps to setup Unity Cloud Build notarization:
.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..p12
file.codesign
command with the following flags: --deep --force --verify --verbose --timestamp --options runtime
. It’s not currently possible to specify custom flags.FASTLANE_NOTARIZE_VERBOSE=true
in your build target Environment Variables.