Omnis Technical Note TNMA0001Dec 2023

macOS code signing

for Omnis Studio 11 or above
By Andrei Augustin, Omnis Software Engineer

Code Signing is a macOS security technology that you use to certify that an app was created by you. Once an app is signed, the system can detect any change to the app – whether the change is introduced accidentally or by malicious code (source: developer.apple.com).

Requirements

Code signing certificate

In order to sign your application, you will need a code signing certificate which can be obtained from your Apple Developer account.

Here's a step-by-step guide on obtaining a valid code signing certificate:

• Create an Apple Developer Account

  • If you don't already have one, you will need to create an Apple Developer account. Visit the Apple Developer website and sign up. Note that to access certain resources, a paid membership may be required.

• Access the Apple Developer Portal

  • Once your account is set up, log in to the Apple Developer portal.

• Generate a Certificate Signing Request (CSR)

  • On your Mac, open the Keychain Access application.
  • From the menu bar, select Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority.
  • Enter your email address and name. Choose 'Saved to disk' and continue. This action generates a CSR file.

• Request a Signing Certificate

  • In the Apple Developer portal, navigate to the 'Certificates, Identifiers & Profiles' section.
  • Select 'Certificates' and click the '+' to add a new certificate.
  • Choose the Apple Developer ID certificate type (used for signing macOS apps to prepare them for distribution outside the Mac App Store and for notarization) and continue.
  • When prompted, upload the CSR file you generated earlier and complete the certificate request.

• Download and Install Your Certificate

  • Once your certificate request is approved, you can download it from the Apple Developer portal.
  • Double-click the downloaded certificate to install it in your Keychain Access.

• Verify Certificate Installation

  • In Keychain Access, under the 'My Certificates' category, verify that your new certificate is listed and valid.

Xcode command-line tools

Xcode 13.2 is the minimum required for the notary tool, used during code signing.

• Check for Existing Installation:

  • Open Terminal and type xcode-select -p to see if the command-line tools are already installed.

• Install Xcode Command-Line Tools

  • If not installed, type xcode-select --install in the Terminal.
  • A software update popup will appear, prompting you to install the tools. Click 'Install' to proceed.

• Alternative Installation via Xcode

  • If you prefer, you can install Xcode through the Mac App Store. Once Xcode is installed, open it.
  • Go to Preferences > Locations.
  • In the 'Command Line Tools' dropdown, select the latest version of the Xcode command-line tools.

• Verify Installation

  • After installation, rerun xcode-select -p in the Terminal. It should now display the path to the installed command-line tools.

• Accepting the License Agreement

  • To ensure all command-line tools are usable, you may need to accept the Xcode license. Type sudo xcodebuild -license in the Terminal and follow the prompts to accept the license.

Code signing

Omnis Studio has an intricate application bundle structure primarily due to the extensive range of features and their dependencies.

Furthermore, as new features are added or older features are improved, the bundle structure is likely to change. This fluidity poses a challenge to users that code sign their Omnis Studio applications themselves.

To rememdiate this problem, we think it's best to standardise the code signing process of an application built with Omnis Studio, and the best way to achieve that is to share the code signing script we use ourselves.

The benefits of using our script to code sign are:

• Up-to-date Process

  • The script is continually maintained and updated by our development team. This ensures that it always aligns with the latest structure and requirements of Omnis Studio's application bundle.

• Code signing consistency

  • By using the same script for both internal and external code signing processes, we ensure a consistent approach. This uniformity is crucial for maintaining the integrity and reliability of the application.

• Ease of use

  • The script is designed to be straightforward and user-friendly. It abstracts the complexity of the code signing process, making it accessible even for those who may not be deeply familiar with the intricacies of macOS code signing.

• Extensibility

  • You can simply call the sign function at the bottom of the script in order to code sign specific components you added.

You can download the code signing script here and its dependency script for generating application entitlements here.

How to use the code signing script

Xcode 13.2 is the minimum required for the notary tool, used during code signing.

Once you have downloaded the codesign_omnis.sh and its generate_entitlements.sh dependency, place them both in the same folder.

In order to start the code signing process, launch the Terminal and execute:

Replace the identity with the name of your code signing certificate as it is in Keychain and the path to your application bundle.

You can run /path/to/codesign_omnis.sh --help for further details.

Adding further components to code sign

If you have further components to code sign, you can call the sign function in the codesign_omnis.sh script.

We advise you do this at the end of the script, before the last call to sign which is meant to re-seal everything:

For most applications, you may not need to add any extra components to sign.

The safest approach would be to attempt notarization once your application has been code signed and if any components fail to pass, only then you should consider adding them to the signing script, and only if code signing was the issue they failed.

A notarization failure due to bad code signature might contain errors such as "The signature does not include a secure timestamp" or "The binary is not signed with a valid Developer ID certificate".