How to sign your Mac OS X App for Gatekeeper

If a prospective customer downloads your software onto Mac OS X 10.8 and it hasn’t been signed, they will see a scary warning:

Not good. To run unsigned software they need to go into Mac OS X Preferences>Security & Privacy>General and change Allow applications downloaded from Mac App store and identified developers to Anywhere:

Or they need to right/Ctrl click and see another scary warning. Double plus not good. This is the new Mac Gatekeeper system in action. Apple being Apple, Gatekeeper defaults to only allowing users to run software they have downloaded off the Internet if it has been signed. This could have a big effect on your conversion rate on Mac. So if you are shipping software for the Mac, you really need to sign it.

Apple fanboys will tell this is a sensible way for Apple to control software quality. A valid certificate shows that your software hasn’t been tampered with and, if it turns out to be malware, Apple can revoke your certificate. The more cynical might see it as a way for Apple to exert even greater control over Mac developers than it already does, while simultaneously extorting $99 per year from each and every one of them. Make your own mind up on that one.

I have now managed to sign my table planner software, ready for its next release. I should have done it months ago. But I expected the process to be so tedious that it has taken me this long to get around to it. And it was every bit as mind-numbingly tedious as I expected trying to find a few useful nuggets amongst the acres of Apple documentation. I found some useful stuff in blogs, but it was quite fragmented. So I have thrown together these notes in the hope that it saves someone else a few hours going round in circles. Note that I am not currently submitting my software to the Mac App Store, so I don’t cover that here. Also my software is developed in C++/Qt using Qt Creator, rather than Objective-C/Cocoa using XCode, and my approach reflects that.

1. Sign up for Apple Developer Connection ($99 per year). Doesn’t matter if you already paid through the nose for a Windows authenticode certificate. Gatekeeper only accepts Apple certificates, so you have no choice. On the plus side, you do get other benefits, including downloading new OS upgrades for free.

2. You need Mac OS X 10.8 so you can test that your signing works. If you have an Apple Developer Connection subscription, you can download 10.8 for free (get a code from the ADC downloads area and using it in the Mac App Store). I found the upgrade from 10.6 to 10.8 was surprisingly painless (Microsoft eat your heart out).

3. Request your Apple certificates and install them into your Keychain. You can do this from Xcode (instructions here). You may need to upgrade Xcode to a recent version.

4. Use the codesign command line tool to sign:

Every framework in your .app bundle
Every plugin in your .app bundle
Your .app file

I believe you can do this as part of your Xcode build. But I prefer a shell script. For example:

echo --sign frameworks -- codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Frameworks/QtCore.framework/Versions/4/QtCore codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Frameworks/QtGui.framework/Versions/4/QtGui codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Frameworks/QtNetwork.framework/Versions/4/QtNetwork codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Frameworks/QtSql.framework/Versions/4/QtSql codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Frameworks/QtXml.framework/Versions/4/QtXml codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Frameworks/Qt3Support.framework/Versions/4/Qt3Support

echo --sign plugins-- codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/accessible/libqtaccessiblecompatwidgets.dylib codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/accessible/libqtaccessiblewidgets.dylib codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/bearer/libqcorewlanbearer.dylib codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/bearer/libqgenericbearer.dylib codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/codecs/libqcncodecs.dylib codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/codecs/libqjpcodecs.dylib codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/codecs/libqkrcodecs.dylib codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/codecs/libqtwcodecs.dylib codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/graphicssystems/libqtracegraphicssystem.dylib codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app/Contents/Plugins/imageformats/libqjpeg.dylib

echo --sign app-- codesign --force --verify --verbose --sign "Developer ID Application: <yourID>" <yourApp>.app

I do this in a build shell script that automates the whole process of creating a .dmg for download. I’m not sure if the order you sign the components in is important.

Note that:

<yourID> is the ID on your certificate (in my case “Oryx Digital Ltd”).
For frameworks you sign the folder, not the file.
Any changes to the .app bundle after signing may invalidate the signature (that is kind of the point).

5. Verify the signing of the .app file. For example:

codesign -vvv -d <yourApp>.app

6. Package your .app into a .dmg, .zip, .pkg or whatever other format you use to install it (I believe .pkg files might require additional signing with a different certificate).

7. Make sure your Mac OS X 10.8 machine is set to the default Gatekeeper setting.

8. Download your software onto Mac OS X 10.8 and check if the scary warning has gone away.

9. Pray that Apple doesn’t decide to revoke your certificate at some point for an infraction, real or imagined.

Until you have released a signed version you can put up a warning with some simple Javascript, for example:

13 thoughts on “How to sign your Mac OS X App for Gatekeeper”

Luke Deniston (@lukedeniston) 30 August 2012 at 11:00 pm

The javascript there at the end is getting parsed on the page. :/
1. Andy Brice Post author31 August 2012 at 9:49 am
  
  So it is. I’ve change it to an image to stop it getting mangled. Is there a better way?
  1. Jon Matthews 31 August 2012 at 1:17 pm
    
    Should *hopefully* work if you put it in tags.
    1. Jon Matthews 31 August 2012 at 1:18 pm
      
      Dang… needed to escape those ;) I meant <code></code> tags.
    2. Andy Brice Post author31 August 2012 at 2:03 pm
      
      It had code tags.
Torben Gundtofte-Bruun 31 August 2012 at 6:52 am

You need to add Google+ to your sharing options. I shared it manually instead.
1. Andy Brice Post author31 August 2012 at 9:57 am
  
  Thanks. I’ve added Google+ under ‘Share this’>’More’.
Ryan Newell 14 September 2012 at 12:46 am

Great article! I’ve signed my app and packaged it inside a .DMG. It runs fine on 10.8 when I copy the DMG from a USB thumb drive, but when I download it from a webserver 10.8 continues to throw up the “Unidentified Developer” error. The DMG files are exactly the same, the only difference is how the DMG got to the machine. Any ideas?
1. Andy Brice Post author14 September 2012 at 1:41 pm
  
  I am guessing OS X doesn’t check the signing when you load from a thumb drive. Have you tried running codesign to verify it?
  
  codesign –verify –verbose yourapp.app
  
  NB:
  -Make sure you sign all the frameworks and plugins.
  -Make sure you don’t change anything in the .app after signing.
  1. Jonathan Matthews 21 September 2012 at 8:59 am
    
    > I am guessing OS X doesn’t check the signing when you load from a thumb drive.
    
    No, it doesn’t, or when it comes through (S)FTP, or DropBox etc. This tripped me up too. I’d highly recommend verifying using Andy’s suggested method (codesign command). I’d also download the file through a browser then run it again once you’re finished for a final check.
2. Ryan Newell 15 October 2012 at 11:26 pm
  
  In case it helps anyone else: Apple support confirmed that I needed to sign the app on a 10.7.3 (minimum) with Xcode 4.3. Once I did that, I was able to sign it and get all the “requirements satisfied”. Signing on a 10.6.8 machine did NOT work properly.
  
  Also, it was not necessary to sign all of the internal bundles, etc. Signing the root .app file was sufficient enough.
  
  This guide helped me a lot, thank you very much!
Jason Cliff 10 October 2012 at 4:19 am

Thanks for this guide Andy. There is a similar situation faced with Windows developers and drivers with a lack of clear information on the subject. Normal Windows applications also need to be signed if they want to be shown in the best light. ie When a UAC prompt appears asking for more privileges it will show the publisher as unknown unless it is signed.

Seems Microsoft and Apple are both going down this path unfortunately.
Chris Bruno 16 October 2012 at 6:43 am

Thanks for this. I can testify to what Ryan said, old versions of codesign do not work. I learned this the hard way after seeing sales drop off as Mountain Lion usage increased, had to re-release with the binary signed with a newer version of codesign.