These new options are available in the Inspector Panel when selecting the Sign step available under Build Settings > macOS.

Requirements

In order to apply Sandboxing, Hardened Runtime and go through the Notarization process for your macOS app, you will need to make sure that the following is installed on your Mac:

• macOS 11.3 or later.
• Xcode 13 or later – Run it at least one time and make sure that all its required components and SDKs are installed.
• Apple Developer ID – This needs to be a paid Apple Developer membership. Also, make sure you have your Developer certificates installed in the Mac.
• A working Internet connection.

Sandboxing

With the Sandboxing switch enabled, you can access the associated editor in order to enable the appropriate entitlements for the purposes of the app.

The Sandboxing settings will be applied even when the app is run from the IDE (debug mode). That means that Sandboxing can be applied both using an Ad-Hoc Certificate or the user Developer ID Application Certificate.

Hardened Runtime

When the Hardened Runtime switch is enabled, you will be able to access the associated editor in order to set the appropriate hardening entitlements for the purposes of the app.

Note: The Hardened Runtime will not be applied when the project is run from the IDE.

When building the app, if Hardened Runtime is enabled and no Developer ID Application value is entered in the Developer ID field (that is, signed as ad-hoc), then the following dialog will be shown and the build process will stop.

Notarization

When the Notarization switch is enabled, it will automatically enable the Hardened Runtime Switch if it is not already enabled (because the Notarization process requires Hardened Runtime!).

With the Notarization switch enabled, you will be able to access the Setup dialog in order to setup the app-specific password required by this process to properly work. Creating this password only needs to be done one time, because it will be saved to the computer keychain and even synced via iCloud to others Macs from the same user (that is, iCloud account).

Note: As with the Hardened Runtime feature, the Notarization process will not take place if the project is run from the IDE.

When building the app, if Notarization is enabled and no Apple Development value is entered in the Developer ID field, then the following dialog will be shown and the build process will stop.

The Notarization process does require an active network connection to the Internet because it needs to talk with the Apple Service responsible of checking the app bundle contents. This means that the required time to complete the process will vary depending of your Internet connection speed and the load or availability of the Apple Notarization service itself.

Custom User Entitlements

Besides the entitlements you may have selected in the Sandboxing and Hardened Runtime editors, you may need to add other ones not available in these editors. This is something you can do through the User Entitlements field (.Plist file format). Such custom entitlements will be merged with the ones selected in the editors. If the custom entitlements entries collide with the ones selected in the editors, then the ones from the editors will be applied, discarding the duplicated ones found in the provided file.

Building macOS apps… from Windows

When the macOS app is built from Windows, and Sandboxing, Hardened Runtime or Notarization is applied (and optionally custom entitlements), then the final compressed archive will include all the required supporting files including the shell script required to run from a macOS computer to complete the signing process using the provided Apple Developer certificate (except the option to create an App-specific password for the Notarization step, because that can’t be done from Windows).

Summary

As you can see, Xojo 2024r4 streamlines the ability to apply Sandboxing, Hardened Runtime and Notarization to your macOS apps, and even run them as sandboxed from the IDE, so you can get better feedback during the debugging process to everything related with the access to files, network user, camera access, etc. That is, the same behaviour your users will have once they run the app downloaded from the Mac App Store or from your website.

See detailed steps in the Xojo Documentation. If you need to know about what Sandboxing, Hardened Runtime or Notarization means, please take a look to the “macOS Apps: From Sandboxing to Notarization, The Basics” blog post.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

More in this series on distributing Mac apps:

• Sandboxing, Hardened Runtime and Notarization arrives to the Xojo IDE
• macOS Apps: From Sandboxing to Notarization, The Basics
• Uploading macOS Builds to App Store Connect
• Provisioning Profiles for macOS Apps

What’s New in Xojo 2024r4

Xojo 2024r4 brings a range of exciting updates that enhance cross-platform development, improve security, and provide more tools for creating dynamic and interactive applications. Here are some of the standout features:

Web Framework
Enjoy smoother and more efficient web applications with updates to Xojo’s Web Framework. Improved memory usage and numerous bug fixes ensure that your web apps run reliably and perform optimally, providing a better experience for your users.

Discover Web Framework Improvements

These updates and enhancements are designed to make your development process more efficient, productive, and enjoyable. Whether you’re building new applications or enhancing existing ones, Xojo 2024r4 provides the tools and capabilities you need to succeed.

Get Started

To learn more about Xojo 2024 Release 4 and begin your development journey, please visit the Xojo 2024r4 Release Notes. The update is available for download now from the Xojo downloads page.

What’s Next?

We’re continuously working on new features, updates, and enhancements to our platform. If you have any suggestions or ideas, please add them to the Xojo tracker. We’re always looking to improve and expand Xojo to better serve our community.

Thank you for being part of the Xojo community. We’re excited to see what you create with Xojo 2024r4!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

In fact, Apple recommends to Notarize the software even if you are going to distribute it from your own website, outside of the Mac App Store. But, don’t be scared! Currently there are good third parties options available that ease the path, like App Wrapper from Ohanaware, or some OpenSource options as for example Xojo2DMG; and through this article you will see how to enable Sandboxing, runtime hardening and even Notarizing on a simple example app. Of course, this will touch only the basics and it is up to you to read the related Apple Documentation to add the entries, both the Entitlements and additional keys/values in the app Info.plist file, required by the purposes of your particular app, for example file access, camera or mic access, network access, etc.

A Bit of Common Ground

At this point, your head may be spinning if you are unfamiliar with these app security terms; so, what do Sandbox, hardened runtime and Notarizing mean when they are applied to macOS apps?

Sandboxing

When a macOS app is sandboxed, that means that macOS will create an exclusive container for everything related to the app the first time it is launched. This is what happens when installing an iOS app, too! Such a container will have its own structure to access things like documents, pictures, downloads, etc. Think about it as the own private execution space for the app:

Of course, there are entitlements waiting for you so your sandboxed app can access the files created by other apps (including the Desktop, Downloads, Movies, Music and Picture folders), among other things.

Hardened Runtime

When enabled for your macOS app, hardened runtime adds an extra layer of protection to the running code itself. For example, it prevents certain classes of exploits, like code injection, dynamically linked library (DLL) hijacking, and process memory space tampering. This kind of protection is also enhanced by the System Integrity Protection (SIP).

Notarization

In brief, this is a third layer of confidence for the potential users of your macOS app. When the app is notarized, that ensures to the user that the Developer ID-signed software you distribute has been checked by Apple for malicious components. This is not related with the Apple Review process of your app when it is submitted to the Mac App Store, it’s related to the macOS Gatekeeper technology. So, when a Notarized app is downloaded from Internet, for example, Gatekeeper will use the notarization ticket attached to your app/DMG file to provide more meaningful information about the origin of the app, including if it is safe for the user to open it.

Preparation

In order to follow this article, you will need:

• Xojo. Download it for macOS if you have not done yet.
• macOS 11.3 or later.
• Xcode 13 or later. Run it at least one time and make sure that all its required components and SDKs are installed.
• Apple Developer ID. This needs to be a paid Apple Developer membership. Also, make sure you have your Developer certificates installed in the Mac.
• A working Internet connection.

With all of this in place, open Xojo to create a macOS Desktop project and do some basic layout in the by default window. It is not required to add any functionality to keep the focus in the task at hand. Then, use Build Settings > macOS > Mac App Name to give an appropriate name to the built application (for this example I named it “SandboxedApp”).

Lastly, save the project (for example into the Documents folder) and click the Build button to build the app! It is not required at this point to assign the Developer ID in the Build Settings > macOS > Sign section, because we are going to sign it (again) in the next steps.

Creating the Entitlements File

The entitlements file is pretty similar to the Info.plist file you probably already know that is in charge of storing the required keys and values for the app to properly work. Both of these are in XML format, and the only difference is that while the Info.plist file is created for you by Xojo, the Entitlements file needs to be, currently, manually created for you.

So, open your text editor of choice (there a lot of there out there, both free and paid ones; personally I tend to use BBEdit from BareBones Software). Add the following lines to the text document and save it with the name “Entitlements.plist” (if you keep it next to the saved built macOS app, the better). This is the file where you will probably want to add more entitlement entries as your app requires them:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
  <key>com.apple.security.app-sandbox</key>
  <true/>
</dict>
</plist>

Sandbox Your App

With the compiled app and the entitlements file in place, open the Terminal app and type the following command and press the return key:

> codesign --force --deep --timestamp --entitlements <path-to-your-entitlements.plist-file> -s "Developer ID Application: <your-full-developer-name (including-the-team-id)>" <path-to-the-bundle-of-your-app>

Once executed, run the “SandboxedApp”, open the Activity Monitor app and make sure that the Sandbox option is enabled under the View > Columns options. Then, use the search box of the main window to filter the displayed processes so it only displays your app. Take a look to the value under the Sandbox column and you will see that the app is now Sandboxed, and the Container for it has been created under the Library/Containers path. Quit the app when you are done.

Hardened Runtime

With our app already sandboxed, let’s look how to add the hardened option to it. Once again, type the following command in the Terminal prompt:

> codesign --force --deep --options runtime --timestamp --entitlements <path-to-your-entitlements.plist-file> -s "Developer ID Application: <your-full-developer-name (including-the-team-id)>" <path-to-the-bundle-of-your-app>

As you can see, it doesn’t vary much from the previous command. All it adds is the “–options runtime” text in charge of enabling the runtime hardening. Also, as you might guess, using this command will enable the Sandboxing of the app and also the runtime hardening, at all once.

Do you want to check if it worked? Well, type the following command at the Terminal prompt:

> codesign --display --verbose <path-to-the-bundle-of-your-app>

It will produce an output similar to this one:

Executable=<path-to-the-executable>
Identifier=com.xojo.sandboxedapp
Format=app bundle with Mach-O universal (x86_64 arm64)
CodeDirectory v=20500 size=43297 flags=0x10000(runtime) hashes=1342+7 location=embedded
Signature size=9100
Timestamp=13 Aug 2024 at 12:51:28 PM
Info.plist entries=15
TeamIdentifier=************
Runtime Version=11.1.0
Sealed Resources version=2 rules=13 files=4
Internal requirements count=1 size=184

It is the “flags=0x1000(runtime)” which shows that, in fact, the app runtime is hardened. Congrats!

Notarizing the App

This is the final step, but is going to require an extra step from your side. Because the notarytool command line tool, used for notarizing the app, is going to require the ID and password from your Apple ID account, plus the fact that it uses 2FA authentication, it is very convenient to create an app specific password for it.

Creating an App-Specific Password

In order to create the password used by the notarytool process, follow this steps:

1. Sign in to appleid.apple.com
2. In the Sign-in and Security section, select the App-Specific Passwords option:

3. The previous action will bring a new dialog displaying all the app-specific passwords already created. Click the “+” button to add a new one:

4. Type a meaningful name for as the “Title” or description for your new password in the presented dialog (notarytool could be a good one):

5. Once you click the Create button it is possible that you will be asked to authenticate again using your Apple ID. Once done, a new dialog will present the generated password to you. Copy it and write it down (or paste it) into a safe place, because we are going to need it in the next step.

Adding the notarytool specific password to the Keychain

Because this app-specific password is going to be used by the notarytool command line tool, it would be very convenient to have it stored in the macOS Keychain. To do so, type the following command at the Terminal prompt, and press the Return key:

> xcrun notarytool store-credentials "notarytool-password" --apple-id "<your-apple-ID>" --team-id <your-developer-team-id> --password <the-password-copied-from-the-previous-step>

Once executed, you will be able to see the password added to the Keychain app under the name of “notarytool-password”:

Creating a Zip file for your app

The notarization process is handled by the Apple notary service running in the Internet, what means that notarytool needs to send (upload) the bundle of your app in an appropriate format. There are two options: as a DMG file (that needs to be signed before submitting), or as a zipped file, what is even faster and easier (Trivia: Did you know how easy it is to create Zip files in Xojo code?)

So, in order to upload our app for notarization, we need to create a Zip file first. Once again, it is time to type a new command at the Terminal prompt:

> /usr/bin/ditto -c -k --keepParent <path-to-app-bundle> <path-to-generated-zip-file/file-name.zip>

Uploading the app for Notarization

With our Zip file in place, we now have all the pieces to send it to the notarization process. The time spent by that process may (and will) vary depending of several factors.

In order to send the file, type the following command at the Terminal prompt:

> xcrun notarytool submit <path-to-zip-file/file-name.zip> --keychain-profile "notarytool-password" --wait 

After pressing the Return key, the process will start and the Terminal will output information about the progress; something similar to this:

Conducting pre-submission checks for <name-of-your-zip-file> and initiating connection to the Apple notary service...
Submission ID received
  id: <some-id-number-goes-here>
Upload progress: 100.00% (8.65 MB of 8.65 MB)   
Successfully uploaded file
  id: <some-id-number-goes-here>
  path: <path-of-the-zip-file>
Waiting for processing to complete.
Current status: Accepted........
Processing complete
  id: <keep-this-id-in-a-safe-place-you-will-need-it-later>
  status: Accepted

Have you seen the last line? The “status: Accepted” means that everything worked OK, and the notarization process has been successful, but it’s better if we check! Type the following command at the Terminal prompt. This one will ask the notarytool command to download the log file in JSON format to be saved at the desired path. It is a good habit to do it, because such a log file will include some eventual error and explanation about possible errors during the notarization process, including those related to the app itself:

> xcrun notarytool log <put-here-the-value-you-saved-in-a-secure-place-from-the-id-field-in-the-previous-output> --keychain-profile "notarytool-password" <path-to-save-the-log.json>

Staple the Ticket!

Assuming that everything worked OK, it is time to staple the notarization ticket to the app itself. It is not required, but is convenient to avoid online checks when the user runs the app, or Gatekeeper inspects it.

Yeah, that means using a new command from Terminal on the already signed, sandboxed and runtime hardened app bundle (not the Zip file you created for submitting using notarytool):

> xcrun stapler staple "<path-to-the-signed-sandboxed-and-hardened-app-bundle>"

After that, you can check that everything went OK using the following command:

> spctl -a -vvv -t install <path-to-the-signed-sandboxed-and-hardened-app-bundle>

And you should get something similar to this as the output:

source=Notarized Developer ID
origin=<your-full-developer-ID-Application>

App Distribution

That’s fine, but you will probably want to distribute your app from the Internet using a DMG container. In that case, follow these steps:

1. Create a DMG container (file).
2. Copy your already notarized app bundle into it.
3. Notarize the DMG file.
4. Staple the ticket to the DMG file.

That way the DMG container will be Notarized along with the app bundle inside it.

In Summary

As we did see, all the process of sandboxing, runtime hardening and Notarization involves a bunch of commands from the terminal, including the creation of the Zip file. But the good news is that all the process could be automated using Xojo itself! (take a look to the Shell class and the Zip method from the FolderItem class if you are not familiar with them).

As I said before, this article only on touches the basics and doesn’t dig into Provisioning Profile creation (associated with Capabilities required by the app), the Entitlements your app may need to properly work, among other topics; so you may find these Apple Developer Documentation of interest:

– Provisioning profiles.
– macOS Entitlements.
– macOS Sandbox.
– macOS Hardened Runtime.
– macOS Notarization.

Happy Xojo Coding!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

More in this series on distributing Mac apps:

• Sandboxing, Hardened Runtime and Notarization arrives to the Xojo IDE
• macOS Apps: From Sandboxing to Notarization, The Basics
• Uploading macOS Builds to App Store Connect
• Provisioning Profiles for macOS Apps