HOWTO macOS notarization (plugins, app, pkg installers)

[george]

Requirements:

• Apple Developer ID ($99/year).
• Xcode 14 or later (Xcode 16 recommended for latest SDK support). If you're using command line tools only, ensure you have the latest version.
• Internet access.
• Create an app-specific password for your Apple ID.

Notarization is required for all plugins, apps, and installers distributed outside the Mac App Store. If you are distributing through a PKG or DMG (which contains a PKG), you can notarize the PKG or DMG, and everything inside will be notarized automatically.

If you distribute your plugins using a simple ZIP file, you need to notarize the contents. You can't staple a ZIP file directly, but you can staple the individual components after they have been notarized.

PLUGIN FILES

Signing via terminal requires your Team Name (your name and surname) followed by your Team ID number (like 87UBP9ZN95) in parentheses:

Code: Select all

codesign --timestamp -s "Developer ID Application: Team Name (Team ID)" "/path/plugin.component"
codesign --timestamp -s "Developer ID Application: Team Name (Team ID)" "/path/plugin.vst"
codesign --timestamp -s "Developer ID Application: Team Name (Team ID)" "/path/plugin.vst3"

AAX Signing:

For AAX plugins, use the PACE wraptool instead of codesign:

Code: Select all

/Applications/PACEAntiPiracy/Eden/Fusion/Current/bin/wraptool sign --account xxxx --wcguid xxxx --in "plugin.aaxplugin" --out "plugin.aaxplugin" --password xxx --signid xxx

Verify the AAX signature:

Code: Select all

/Applications/PACEAntiPiracy/Eden/Fusion/Current/bin/wraptool verify --verbose --in "plugin.aaxplugin"

Notarizing standalone plugins:

If you are distributing a .vst / .component / .vst3 without an installer:

1. Create a ZIP file containing the signed plugin(s).
2. Submit for notarization:

Code: Select all

xcrun notarytool submit "plugin.zip" --apple-id "your@apple-id.com" --password "your-app-specific-password" --team-id "TEAM_ID" --wait

3. After it's accepted, staple the individual plugin files (not the ZIP):

Code: Select all

xcrun stapler staple "/path/to/plugin.component"
xcrun stapler staple "/path/to/plugin.vst3"

APP NOTARIZATION

The notary service generates tickets for the top-level file and each nested file. For example, if you submit a disk image containing a signed installer package with an app bundle inside, the notarization service generates tickets for the disk image, installer package, and app bundle.

• Code sign your app:

  Code: Select all

  codesign --deep --force --timestamp --sign "Developer ID Application: Your Name (TEAM_ID)" "Application.app"

• Create a ZIP file of your app:

  Code: Select all

  ditto -c -k --keepParent "MyApp.app" "MyApp.zip"

• Submit for notarization:

  Code: Select all

  xcrun notarytool submit "MyApp.zip" --apple-id "your@apple-id.com" --password "your-app-specific-password" --team-id "TEAM_ID" --wait

• After acceptance, staple the app:

  Code: Select all

  xcrun stapler staple "MyApp.app"

• Verify notarization:

  Code: Select all

  spctl --assess --verbose "MyApp.app"

  You should see:

  Code: Select all

  MyApp.app: accepted
  source=Notarized Developer ID

• The app is ready for distribution.

PKG INSTALLER NOTARIZATION

You can use WhiteBox Packages to create and sign installers. Make sure you set the Developer ID Installer certificate in your PKG settings:

• Submit the signed PKG to Apple:

  Code: Select all

  xcrun notarytool submit "Install.pkg" --apple-id "your@apple-id.com" --password "your-app-specific-password" --team-id "TEAM_ID" --wait

  After a few minutes you should receive a notification via terminal.
• Staple the PKG:

  Code: Select all

  xcrun stapler staple "Install.pkg"

• Verify:

  Code: Select all

  spctl -a -vvv -t install "Install.pkg"

  You should see:

  Code: Select all

  Install.pkg: accepted
  source=Notarized Developer ID
  origin=Developer ID Installer: Your Name (TEAM_ID)

• Ready to distribute!

Alternative Authentication Methods:

Instead of using --apple-id and --password flags each time, you can:

1. Store credentials in Keychain:

Code: Select all

xcrun notarytool store-credentials "ProfileName" --apple-id "your@apple-id.com" --team-id "TEAM_ID"

Then use:

Code: Select all

xcrun notarytool submit "file.pkg" --keychain-profile "ProfileName" --wait

2. Use API Key authentication (for CI/CD workflows):

Code: Select all

xcrun notarytool submit "file.pkg" --key "/path/to/AuthKey_XXXX.p8" --key-id "KEY_ID" --issuer "ISSUER_ID" --wait

Checking Notarization Status:

If you need to check the status of a submission:

Code: Select all

xcrun notarytool info SUBMISSION_ID --apple-id "your@apple-id.com" --team-id "TEAM_ID" --password "your-app-specific-password"

To view the notarization log for debugging:

Code: Select all

xcrun notarytool log SUBMISSION_ID --apple-id "your@apple-id.com" --team-id "TEAM_ID" --password "your-app-specific-password"

[xhunaudio]

A very big thank you for your contribution, George.

Talking just for the PLUGINS, the signing process doesn't involve Xcode, so Xcode10 is not a requirement, right?

I ask this because I'm on Xcode7 and I don't want to update / change anything (once it works... )

[george]

You’re welcome. I think so Bruno, but for notarizing DMG/PKG/app then XCode 10 command line tools or the built in tools should be used.

By the way it’s very easy to sign plugins in XCode 10 and it has a new compilation system, so I’d recommend giving at least a try

[xhunaudio]

My fear with Xcode10 is that WDL-OL doesn't like it...

...or maybe it should be better to wait until IPlug2 will be out (and production-ready). By the way thank you again !

[audiothing]

I use the app Packages to distribute the plugins and it works great. However right now the digitally signed build from it are NOT compatible with Apple notarization.

What version are you using? The latest one (v1.2.6) works perfectly fine with the notarization here.

[george]

What version are you using? The latest one (v1.2.6) works perfectly fine with the notarization here.

Current Packages version 1.2.6 doesn't build a signed secure timestamp PKG. I was in talk with the developer these days. Version 1.2.7 of Packages which is going to be released before the end of September should be able to do so.

At least for me, checking the stapled PKG code signed with Packages 1.2.6 resulted in a rejected file. Right now the only way to add a secure timestamp is using product sign command line tool as described on the howto.

Cheers,
George.

[audiothing]

Current Packages version 1.2.6 doesn't build a signed secure timestamp PKG. I was in talk with the developer these days. Version 1.2.7 of Packages which is going to be released before the end of September should be able to do so.

At least for me, checking the stapled PKG code signed with Packages 1.2.6 resulted in a rejected file. Right now the only way to add a secure timestamp is using product sign command line tool as described on the howto.

I've just retested and I can notarize and staple my PKGs without issues using Packages v1.2.6 in our build script using packagesbuild.
I've verified the PKG signature before submitting it for notarization with:

Code: Select all

pkgutil --check-signature installer.pkg
Status: signed by a certificate trusted by Mac OS X
   Certificate Chain:
    1. Developer ID Installer: XXXXX 

Then notarized/stapled and verified with:

Code: Select all

spctl -a -vvv -t install installer.pkg
installer.pkg: accepted
source=Notarized Developer ID
origin=Developer ID Installer: XXXXX

If the current version of Packages doesn't add the timestamp I guess it would be a huge mess

[george]

I'm referring to Whitebox Packages and it looks like you're pointing to packagesdev/packages which BTW added timestamp embedded in the CMS signature around 1 month ago.

I contacted the WhiteBox Packages developer and he answered 1.2.6 doesn't set a secure timestamp and will be added on 1.2.7 this September. After using productsign on the PKG I was able to notarize without issues.

OP has been clarified to avoid any confusions. Thanks for the feedback!

[audiothing]

I'm referring to Whitebox Packages and it looks like you're pointing to packagesdev/packages which BTW added timestamp embedded in the CMS signature around 1 month ago.

I'm really confused. According to the Whitebox Packages page, that repo is the source code of Packages. I'm just using the command line to build the PKGs, and the command is packagesbuild.

From http://s.sudre.free.fr/Software/Packages/about.html

Integrating Packages into an automated production workflow is easy with the packagesbuild command line tool. Once you have created your Packages project, the packagesbuild tool will let you build it from the Terminal, a shell script or an Xcode Run Script Build phase.

So, I've tested again, removing and adding the certificate (Project > Set certificate), building from the GUI this time (no command line, no build script, everything manually), notarized and stapled with no issues. I hope I'm not doing anything wrong...

[george]

It doesn't work here when building from GUI and CMS signature not supported by app is confirmed by the dev himself, so no idea what's going on From what I understand the command line tool correctly CMS signs the PKG.

[daniel_noiseash]

Hi Thank you so much for this nice tutorial!

• What will happen for updates? If we notarized an installer with a Bundle Identifier and a altool password; when we want to update it, do we have to upload and notarize the new version again? With the same Bundle Identifier and specific altool password?

• Does this specific altool password has to be individual for different software installers?

• I use Whitebox Packages 1.2.6 too. When I Staple the PKG, there is nothing happening. But when I check it, it seems to ok.

Best Regards...

[george]

Hi Thank you so much for this nice tutorial!

• What will happen for updates? If we notarized an installer with a Bundle Identifier and a altool password; when we want to update it, do we have to upload and notarize the new version again? With the same Bundle Identifier and specific altool password?

I think any files should be notarized.

• Does this specific altool password has to be individual for different software installers?

Nope.

• I use Whitebox Packages 1.2.6 too. When I Staple the PKG, there is nothing happening. But when I check it, it seems to ok.

Yeah, it happened the same here and after deeper investigation notarization wasn't OK. What I did is detailed on the OP. 1.2.7 will add CMS timestap which is not supported right now (not the command line tool from what it was reported thought).

[daniel_noiseash]

Ok thanks! I should better wait for the 1.2.7 release.

[daniel_noiseash]

Today I rebuilt Packages installer. Signed, Notarized and retried timestamp. This time I saw successful message in Terminal after timestamp attempt (yesterday there was no message after timestamp attempt).

I think this issue can be Apple's notarization system. Yesterday it didn't but today it is ok. I am using Packages 1.2.6

Weird!

[BlueprintInc]

So I may need to upload a multiple gigabyte big app everytime to notarize it? That's really hilarious