Setting up your environment (Simple)
This recipe shows how to set up your Pass type in Apple's provisioning Portal and generate the required files for code signing.
Getting ready
To get started with creating your own Pass, you will need a paid iOS developer account. If you intend to present the Passes within an existing iOS app, you will need access to the iOS developer account that publishes this existing app. In addition, many of these steps require apps and utilities only available on OSX, Keychain Access for example, which is used in the certificate creation process. Therefore, these steps should be undertaken using a Mac, running OSX.
How to do it…
If you intend to present Passes within an iOS App, but have not yet created the app, you will need to create an App ID within the Identifiers section of the iOS Developer Center.
Log in to the iOS Developer Center and navigate to Certificates | Identifiers & Profiles | Identifiers, or follow this link:
https://developer.apple.com/account/ios/identifiers/bundle/bundleList.action
Click the + button at the top-right hand corner.
Enter an app name in the App ID Description field:
Under Application Services, ensure that Passbook is enabled.
Under App ID Prefix, use Team ID unless you have a reason to explicitly specify this.
An App ID Suffix is a string identifier that is unique to your app. The provisioning portal will not allow you to specify a Bundle Identifier being used in another app. The suggestion is to use a reverse domain name style string. For example, throughout this book I have used the domain name http://passkit.pro, therefore the Bundle Identifier I have chosen is
pro.passkit.exampleas this will be the app ID for the example app.If you have a pre-existing app ID, you will need to enable Passbook for this app ID. From the app ID section of the provisioning portal, select the app ID, and note down the prefix, as we need it when specifying the Team Identifier of your Pass. Having done this, choose Settings:
Check the checkbox next to Passbook and click on Done. A warning will be displayed, informing that all new provisioning profiles created for this app ID will be enabled for Passes. This is presented as a reminder that pre-existing provisioning profiles will not be enabled for Passbook, until they are re-created. Therefore, if you have a pre-existing App published to the App Store, you will need to re-generate the App's distribution provisioning profile, re-build the App with this new provisioning profile, and submit an update of the App to the App Store. Until you do this, your App will not be able to add Passes into Passbook. When Passes have been correctly enabled for an app ID the Passes' indicator will turn green and be labeled as Enabled in the app ID summary screen:
Regardless of whether you intend to present your Pass in an app, you will now need to create a Pass Type ID. Follow the link on the left menu for Pass Type IDs or visit:
https://developer.apple.com/account/ios/identifiers/passTypeId/passTypeIdList.action
Click on the + button to create a new Pass Type ID. You will need to create a Pass Type ID for each type of Pass you intend to create. The types of Passes currently available to create are Boarding Pass, Coupon, Event Ticket, Store Card, and Generic. The Pass types are presented differently and have different functionality, as we will see. In our examples we will focus on building a Generic Pass. If you intend to create a Store Card type Pass and a Coupon type Pass, you will need to create a Pass Type ID for each:
For the description, choose a name that defines the type of Pass you are creating. For the main example later in the book, a Generic type Pass will be created, therefore in the example Pass Type ID above, the description Generic is used.
The Identifier has to start with
pass., then a reverse domain name string is suggested, with the type of Pass placed on the end. In the example above, I use the full app ID created earlier, with Pass Type of generic, giving the full Pass Type Identifier as follows:pass.pro.passkit.example.generic
With the Pass Type ID created, we will generate an associated cryptographic key and certificate, which is needed for authentication of the Pass. Select the Pass Type ID and note down the Pass Type ID, as this will be needed later when creating the Pass:
Click on the Settings button and follow the instructions to create a Certificate Signing Request. I will repeat the instructions below, with some suggestions to help avoid confusion later.
Launch the Keychain Access utility.
From the menu, select Keychain Access | Certificate Assistant | Request a Certificate from a Certificate Authority. In the Certificate Information window, enter the following:
User Email Address: Enter the e-mail address associated with your iOS developer account.
Common Name: Choose a name that relates to the Pass Type ID. This will be displayed next to the key in Keychain Access, so a common name that isn't specific enough can cause confusion. See the following screenshot, which is how this will be presented in Keychain Access after step 18.
CA Email Address: Leave this field blank
Request is: Choose Saved to Disk
Click on Continue and save your Certificate Signing Request. Then, in Safari (other browsers may have problems or incompatibilities that prevent you from choosing a file), click on Choose File and select the Certificate Signing Request that has just been generated. Click on Generate and wait for the pass Type certificate to be generated:
Once generated, click on Done and download your certificate. Open your downloaded certificate, which will launch Keychain Access and attach the certificate to the associated private key, which was created during the generation of the Certificate Signing Request:
The certificate and key pair should now be visible in Keychain Access. These now need to be converted into a format that can be used to correctly sign the Passes you will create. Select the certificate in Keychain Access, and from the menu choose File | Export Items, and choose an export location. You will be asked to provide a password to protect the exported items, you may also be asked for the administrator password as you are performing a task that requires administrator privileges.
You will need to use a command-line tool called OpenSSL to use the exported file to generate the key and certificate files that will be needed. This command line tool can be run from a built-in OSXutility called Terminal. To open Terminal, go to your Applications folder in Finder. Terminal is located in the Utilities folder.
Use the following Terminal commands to generate a
certificate.pemfile and akey.pemfile.openssl pkcs12 -in <Path to exported .p12> -clcerts -nokeys -out certificate.pem openssl pkcs12 -in <Path to exported .p12> -nocerts -out key.pem
On generating the
key.pem, you will be prompted to enter an import passport, which is the password that was set when exporting from Keychain Access. You will then be prompted for a pass phrase; this can be the same as the import password, but note that this pass phrase will need to provided when signing your Passes and so may form part of an automated script.In addition to the
certificate.pemfile andkey.pemfile generated above, the Apple WWDR intermediate certificate is also required. This can be found by going to the provisioning portal, in the Certificates section, click on the + button, or visit the following. The certificate is labeled Worldwide Developer Relations Certificate Authority under Intermediate Certificates.https://developer.apple.com/account/ios/certificate/certificateCreate.action
Once this has been downloaded, it also needs to be converted into a
.pemfile. Double-click on the WWDR certificate file, to load it into Keychain Access, and select the certificate in Keychain Access:
Then, from the menu choose File | Export Items, change the file format to Privacy Enhanced Mail
(.pem) and save as itwwdr.pem.
How it works…
Apple's security model ensures that only registered iOS developers can create Passes and that Passes cannot be altered by a third party while being delivered to a user's device, without being detected, and rejected by Passbook.
The certificate creation process produces a Pass Type certificate that is tied to the Pass Type ID that it was created from, which in turn ties it to your developer account. This provides a method for verifying the contents of a Pass signed using this certificate, and therefore, a way of detecting any manipulation of the Pass by anyone other than the registered Pass creator.