Remember to backup your keychain

I cannot believe another year has gone by and I need to renew my iOS development certificate again. Luckily I left myself a reminder last year on how to do it. Even though I should know by now it still caught me by surprise when I saw the messages warning me that I did not have a valid signing certificate.

Unfortunately in the process of deleting the old, expired development key from my keychain I had a problem with fat fingers and managed to delete something I should not have done. Luckily I have several different mechanisms to backup my keychain. In addition to an hourly backup by Time Machine I also have Super Duper making a full bootable clone of my OS X disk and a separate backup copying key data up to the cloud.

Restoring the Keychain

The keychain files are stored under the users home directory at ~/Library/Keychains. To restore the login keychain I just needed to restore the login.keychain file from the previous backup and I was back in business. The moral of the story is of course to check that you are backing up your Mac. In my experience user failure is at least as common as hard drive failure and it is good to know that you can recover quickly when the inevitable happens.

One other quick tip on the keychain whilst I am on the topic. You should from time to time check the health of the keychain. You can do this by running the Keychain Access utility and using the Keychain First Aid option in the Keychain Access menu. After you enter your password you can verify the state of the keychain and repair any errors.

Creating iPhone Ad Hoc Distribution builds

Each time I need to create a build for a beta tester I find myself hunting around for my notes on how to create and distribute an Ad Hoc build. So here, once and for all, are my notes on what to do to create an Ad Hoc distribution of an iPhone App.

Adding Beta Tester Devices

Apple allows an Ad Hoc build to be distributed to up to 100 devices which they enforce by making you add the devices to the distribution provisioning certificate. This means that you need to retrieve the UDID for all of the test devices, add them to the provisioning profile using the iOS Provisioning Portal and then download and install the profile.

Finding the UDID

To get started you need to ask your beta testers to supply the Unique Device ID (UDID) for their devices. Now unless the user is also an iOS developer they are unlikely to know what that means. You can try to explain to them how they need to connect the device to iTunes, select the device in the Devices section, find the Summary page, click on the Serial Number to reveal the “hidden” UDID and then command-c (Mac) or ctrl-c (Windows) to copy it into an email. However I find the easiest thing to do is to point them towards this article by Apple which explains the steps. The article is for the iPad but the steps are the same for all devices.

Registering the Device

Once you have the UDID you need to add it to your account in the iOS Provisioning Portal in the same way you would for a development device. You do this in the Devices section of the portal and can either use the ‘Add Device’ button to manually add a single device or use the Upload Devices button to bulk upload multiple UDIDs from a text file.

Note if you want to bulk upload multiple devices the format of the text file needs to be as follows with the two columns separated with tabs:

Device ID                                Device Name
1234567890123456789012345678901234567890 Test iPad

The contents of the first line are not important but you need to put something as the first line is ignored when you upload.

Also be aware that you can only register up to 100 devices each year. You can delete devices any time you want but once added they still count towards your annual allocation. (So if you add 100 devices and then delete 50 of them you still have to wait until the next year before you can add any more). This has never been an issue for me as I am nowhere near to having 100 beta testers or development devices.

Creating the Distribution Provisioning Profile

Assuming you already have a distribution certificate the process to create an Ad Hoc provisioning profile is quick and easy. In the Distribution tab of the Provisioning section use the New Profile button.

The only difference between an Ad Hoc profile and a normal App Store profile is the Distribution Method

Ensure you select the Ad Hoc method and then enter a profile name, the App ID and finally ensure you select all of the devices you want the Ad Hoc build to run on. Once you have finished submitting the profile you should download it and save it somewhere safe as you will need to send it to each of the beta testers. The file should have an extension of .mobileprovision. You should also drag the file onto your Xcode icon to install it, you can use the Xcode organiser to verify that it installed ok. You should see the profile in the Provisioning Profiles section.

Building for Ad Hoc Distribution

With the provisioning profiles configured correctly the next step is to prepare the project in Xcode for an Ad Hoc build. I have found it useful to create a configuration just for Ad Hoc builds so that I do not have to worry about the details each time. The easiest way to do that is to copy an existing configuration, if you already have a Distribution configuration that is probably a good starting point otherwise you can start from the default “Release” configuration.

With the project open in Xcode, right-click on the target and select “Get Info” to bring up the Info dialog window and select the Build tab and then in the Configuration drop down menu select “Edit Configurations…”

Select an existing configuration (e.g. Release or Distribution) and then at the bottom of the window use the Duplicate button to create a copy of the configuration and name it “AdHoc”.

In the Target Info window ensure this new AdHoc configuration is selected and then adjust the following settings in the Build tab. In the Code Signing section, look for the  “Any iOS” setting under Code Signing Identity and make sure it is set to iPhone Distribution and matches the Ad Hoc provisioning profile we installed previously.

Entitlements

There is one additional step if your project includes an Entitlements.plist file (perhaps because you needed to enable keychain data sharing). For an Ad Hoc distribution you need to ensure that the get-task-allow flag is not set in the plist file. The way I handle this is to add a second file (Entitlements-adhoc.plist) just for the Ad Hoc build which is identical apart from the get-task-allow flag:

To ensure this new Entitlements file is used you need to modify the Code Signing Entitlements setting in the AdHoc configuration to reference the new file.

Build and Archive

With the AdHoc build settings active use the Build and Archive command to create the distribution build. Assuming the build was successful you should find it in the Xcode Organizer in the Archived Applications section. You can add a name and comment to the organizer for future reference at this point.

Sharing the Application

I find the easiest way to send the application files to a beta tester is to use the Xcode organizer to create an ipa file. To do that select the AdHoc build in the Archived Applications section and use the Share button and then select Save to Disk. Xcode will create a signed application file and save it to disk with a name of your choosing. Name the file something useful like appName-x.y.z.ipa where x.y.z is the version number.

You can then send this .ipa file together with the .mobileprovision file to your beta tester with instructions to drag onto their iTunes library to install it on the test device.

Xcode 3.2.3 Instant Setup

I recently picked up a third generation iPod Touch with the intention of also using it as a test device for iOS 4. Now that Xcode 3.2.3 is out I thought I would test the “instant setup” feature as an alternative to manually entering device details and downloading profiles from the provisioning portal.

Team Provisioning Profiles

The whole process is driven from the Xocde organizer window which now has an additional option on the provisioning profiles page for Automatic Device Provisioning:

This option was already enabled in my case so I guess that is the default when you install Xcode 3.2.3. When you plug in a new device it shows up under the list of devices in the organizer with a Use for Development button which after providing your iPhone developer account details automatically adds the device to the portal for you.

As well as adding the device it also creates a new provisioning profile named “Team Provisioning Profile” which has a wild card App ID and assigns the new device (and it seems any existing devices registered in the portal) to the profile. The profile shows up in the provisioning portal along with your other development provisioning profiles but unlike the other profiles you cannot edit it directly as it is “Managed by Xcode”:

Specialized Development

Unfortunately the team provisioning profile is not going to be enough if you are engaging in what Apple refers to as “specialized” development. Since it is using a wildcard App ID you cannot use it if you require push notifications, in-app purchase or the upcoming game center integration. These features require a specific App ID so you cannot provision them with the generic team profile.

What this means is that you still have to go to the provisioning profile and manually add the device to the specific provisioning profile you created for the app. Once you have done that you will probably need to refresh the Provisioning Profiles page in organizer to get it to show up. One thing I noticed is that this seems to actually create a new profile so I ended up with two profiles with the same name in the organizer. I deleted the old one and dragged the new one onto the icon for the device. At that point it showed up on the physical device (General -> Profiles in the Settings app).

So, in summary, it is not a totally seamless process, especially if you need to use specific App ID’s but it is still a big step forward and relieves some of the pain inflicted on us by the provisioning portal.

Requesting a new development certificate

In addition to renewing your development provisioning profiles every three months, once a year you need to request a new development certificate. Without a valid development certificate installation to a test device does not work, though applications already installed continue to function. Since mine expired this week I thought I may as well post some comments on the renewal process.

Checking your development certificate

To check the status of your development certificate, use the keychain access utility to check the login keychain for the certificate named “iPhone Developer: <Your Name>”. The expiry date is listed on the right hand side. Alternatively open the organiser in Xcode and check the Provisioning Profiles. If you see the following your development certificate has expired:

Requesting a certificate.

To get a new certificate you need to logon to the iPhone Provisioning Portal and select Certificates.

In the Development tab, which should show that you do not currently have a valid certificate, use the Request Certificate button to get the process underway. Note that you do not renew a development certificate, once it expires you need to request a new one.

The first step is to submit your Certificate Signing Request (CSR) which if you are well organised you should still have saved away in your keys directory (look for something named CertificateSigningRequest.certSigningRequest). If you cannot find it then you will have to create a new one following the procedure on the provisioning portal page. Since I still have mine I submitted it which gets you a certificate with status “Pending Issuance”.

If you are an individual developer you will get an email indicating that a certificate request requires your approval. If you are a business the notification will go to the team admin who will need to approve the request. An individual developer can just refresh the web page and the status will change to Issued and you can download the certificate.

By default the downloaded file is named developer_identity.cer. To avoid confusion it is worth deleting the old file (if you still have it) before saving the new one to your keys directory.

Installing a development certificate

To install the new certificate you should just be able to double click the developer_identity.cer file to install it into the keychain. I got an import error the first time I did this (Error: 100013). I found that deleting my old expired certificate from the keychain and exiting the keychain utility and Xcode fixed the problem (not sure which of those steps did the trick).

If the import is successful you should see the certificate in the keychain with an expiry date one year ahead.

Recreate the Provisioning Profiles

Now for the bad news…

A development provisioning profile requires three things: an iPhone developer certificate, device identifiers for your test devices and an App ID. This unfortunately means that it is now necessary to update each profile with the new certificate to get things working again. Before starting to do this I find it easiest to delete each of the profiles from the Xcode organiser and any test devices and archive the existing keys that I have saved in my repository.

Updating the profiles is simple, from the Development Provisioning Profiles page of the portal, edit each profile, select the new certificate and submit the new request. After refreshing the page the new profile should show as Active and can be downloaded. To install drag the downloaded file onto the Organizer window.

Renewing provisioning profiles

One of the joys of developing for the iPhone is the need to renew the various certificates from time to time. This starts out easy enough but can soon get complicated when you need to manage developer certificates, provisioning profiles and maybe Apple Push Notification certificates for development, distribution and ad hoc distribution builds. Since these certificates all expire at different times you quickly become a frequent visitor to the Apple iPhone Provisioning Portal.

Renewing Development Provisioning Profiles

The development provisioning profiles expire every 3 months so even if you never submit an application to the App Store you have to deal with renewing this certificate. There is normally plenty of warning that it will expire since your test device will pop up warning messages for several weeks before the expiration. Once the profile has expired the application will no longer launch on the device and if you attempt to build and install the app from Xcode you will get the following build error:

Code Sign error: Provisioning profile 'App-name' has expired

A good place to see in advance when the profiles will expire on a device is within the Settings application. Under General > Profiles you should see a list of all profiles installed on the device. Selecting an individual profile will show when it was installed and when it will expire. You can also remove the profile from this screen. You can see similar detail from the Xcode organizer window when the device is attached.

To renew the profile you need to visit the iPhone Provisioning Portal. From the iPhone Provisioning Profiles page you should see the profile with a status of Expired and a Renew button under Actions as follows:

Clicking Renew changes the status to Pending and with a refresh of the page it should already have changed to Active. You can now download it and save it. I keep a directory called keys under my project directory where I store all of that projects keys so that they also get checked into the source code repository. Within the keys directory I create three separate sub-directories for Development, Distribution and Ad Hoc keys to store the provisioning profile and any push certificates for each build.

With the new provisioning profile downloaded it needs to be installed. Open the Xcode Organizer window (^⌘O) and drag the new profile onto the Provisioning Profiles page. You should also delete the old, expired profile which should be showing up with a red cross next to it in the list of profiles.

At this point the project should build without error and install on the test device. If it doesn’t check the code signing section of the target Build settings and make sure the correct profile is being used. One other error that I have seen when installing a new provisioning profile is a security policy error when Xcode attempts to install the application on the device:

Error launching remote program: security policy error.

This can happen when the device has two provisioning profiles for the same application installed. If you get this error check the profiles installed on the devices with the Settings application (General > Profiles). If you still see the old, expired profile select it and remove it. The application should now install correctly.

If you are still getting problems at this point it is always worth doing a complete clean and rebuild (Build -> Clean All Targets) or finally quitting Xcode and with the Finder delete the build directory for your application. Both of these have resolved strange provisioning errors for me in the past.