Beginning Passbook in iOS 6: Part 1/2

Time to make it beautiful, baby!

They say an image is worth a thousand words – lucky for you, there’s no space for thousand words on the front side of the pass, so when in need you might as well use an image.

Go ahead and download the assets I’ve prepared for you: PassAssets.zip. Extract the files and inside the FreeHugCoupon folder you will find a bunch of PNG files. Copy them over into your pass work folder.

And that’s it – you’re done! Phew, that was easy.

Wait, what? You don’t have to add any code inside pass.json to tell Passbook which image files to load. That’s right!

Passbook will automatically load image files following standard naming conventions. This means images named icon.png; icon@2x.png; logo.png; logo@2x.png; strip.png and strip@2x.png will be displayed on the pass, if provided. No need to do anything but include these files in the pass bundle. (There’s also few more images that this chapter will cover later on.)

Note: There’s one nasty gotcha about the pass images, which took me a while to figure out – the image files need to be exported as PNG24 format. For some reason the much smaller-in-size PNG8 format just won’t show up in Passbook.

“Let’s give that pass a try! I want to see it already!”, for sure you are crying in despair.

Unfortunately, until the pass bundle is complete, signed and zipped you cannot preview the pass. Passbook won’t display any invalid (incomplete) passes. So muster a little more patience and keep going.

The pass manifest

The pass manifest is another JSON file you need to create, and it describes all the files included in the pass bundle and their SHA1 checksums.

You can make this yourself by generating the SHA1 checksums for each file yourself (as I’ll show you in a minute), but so that you can move faster with building your first pass I’ve included an already-generated manifest.json file in the PassAssets.zip file you already downloaded and extracted. Find manifest.json inside the folder where you extracted the zip file and copy it over to your pass work folder.

It’s contents are as follows:

{
 "strip.png":"25b4c9ff2bafe056f3e28379db0ef3fb460c718b",
 "strip@2x.png":"dee775ed6fb3c7278b84c65853401e760caabc92",
 "icon.png":"8eaa0896db93f2165fa417df3d002ce9c61fcd92",
 "icon@2x.png":"555ce7f70f2f44fb7ac9d9f46df5738ec6250f37",
 "logo.png":"e8c4edfbcae41d9d88fad7137d8ed30ae5f73e67",
 "logo@2x.png":"1f9b1cc4c75b380ade07e9f2b7f37f988d9d14c3",
 "pass.json":"<INSERT YOUR PASS SHA1 HERE>"
}

The SHA1 checksums for the images are already pre-filled, but the final checksum – the one for your pass.json file – is not. You are going to generate its SHA1 yourself. It’s quite easy – open up Terminal and navigate to your pass folder.

Note: If you aren’t familiar with navigating directories in the Terminal, do this: move your pass files into a folder on your Desktop and call it “FreeHugCoupon”, then launch Terminal and enter this command:

There you go.

cd ~/Desktop/FreeHugCoupon

cd ~/Desktop/FreeHugCoupon

Enter this command at the Terminal prompt:

openssl sha1 pass.json

The output of the command should look something like this (the actual checksum will be different for you):

SHA1(pass.json)= c24766ef5aa92197eace640fcc4fb584a505a733

Select the alphanumeric checksum value and in your manifest.json file replace “” with the checksum string. Save the file and you’re done! (Make sure you leave the quotes alone.)

NB! It’s important that you do not edit pass.json anymore until told to do so. If you add even one character to pass.json, the SHA1 checksum will change and your manifest.json will become invalid, since the checksum given there will no longer match the checksum of the modified pass.json file.

This is the last source file you need for your pass. Awesome!

Can I have your signature, please?

Now comes the most interesting part of creating a pass.

Remember the certificate you got from Apple for your pass type? You’ve imported it to your Keychain and you haven’t touched it since. Now you’re going to export the certificate and the key in PEM format, so that you can use them with OpenSSL.

Open up Keychain Access, select Certificates from the left menu (under Categories) and find the certificate called “Pass Type ID: pass.com.yourdomain.couponfreehug”. Make sure you’ve selected the item itself and not the private key underneath:

Next right-click on the certificate and choose from the popup menu Export “Pass Type ID: pass.com.yourdomain.couponfreehug”… Save the exported file as “Certificates.p12” inside your working pass folder. You’ll be presented with a dialog to choose a password:

To make the process a bit easier, just click OK – the certificate will be exported with no password protection.

Note: At this point you might be prompted to enter the password for the login keychain. If you are, then simply providing your user password should suffice.
The Certificates.p12 file now contains both the pass certificate and your private key. OpenSSL needs those in separate files, so now you have to extract them from the .p12 file.

Switch back to Terminal – it’s time for OpenSSL magic!

After making sure the current directory is the correct one (to double check, enter “ls –al” and hit Enter – you should see the file listing of the folder, and it should contain your Certificates.p12 file), enter the following command:

openssl pkcs12 -in Certificates.p12 -clcerts -nokeys -out passcertificate.pem -passin pass:

That’ll export only the pass certificate in PEM format and save it as “passcertificate.pem” inside the same folder. (OpenSSL will spit out the message “MAC verified OK” if the operation is successful.)

Next, export the key as a separate file with this command:

openssl pkcs12 -in Certificates.p12 -nocerts -out passkey.pem -passin pass: -passout pass:12345

Note that this time, you need to provide a password in order to export the key file. In this case, just use “12345” – obviously for production environments it’s advisable to use a strong password (doh!) – so, nothing of the “password1” or “passw00t” sort, please.

To sign your pass bundle you will need one more certificate – the WWDR Intermediate certificate, which authorizes the issuer of your own certificate – Apple. Chances are you already have it installed in your Keychain. Open up Keychain Access, select the “Certificates” category and look for a certificate called “Apple Worldwide Developer Relations Certification Authority” (yes, this is a quite long name indeed):

If by any chance you don’t have this certificate already imported, then open up in your browser this web page: http://www.apple.com/certificateauthority/. Here you can freely download the most important Apple certificates you might need. Scroll down, find the WWDR certificate, download the .cer file and import it in Keychain.

You’re ready to go on with exporting the certificate. Back in Keychain Access right click on the certificate name and choose the Export option in the popup menu:

In the “Save as…” dialogue find the File format drop box and choose Privacy Enhanced Mail (.pem) option:

In the text field at the top of the dialogue give the file the name “WWDR.pem”, select your working pass directory as destination, and hit the Save button to finish the export.

You’re ready to create the signature. Enter this command:

openssl smime -binary -sign -certfile WWDR.pem -signer passcertificate.pem -inkey passkey.pem -in manifest.json -out signature -outform DER -passin pass:12345

Read through the command line above once more – it’s quite easy to understand all the parameters. The signer parameter is your pass certificate’s file name; inkey is the key file used to sign manifest.json; in is the input file name; out is the output file name; outform is the output format (you need “DER” to create a detached signature); and finally, passin is the password for the key file.

Now you have your signature and the production of the pass is almost complete.

The last remaining step is to combine the various files for the pass into a .pkpass file. Enter this command in the Terminal:

zip -r freehugcoupon.pkpass manifest.json pass.json signature logo.png logo@2x.png icon.png icon@2x.png strip.png strip@2x.png

By using the shell command “zip” you create a ZIP file called freehugcoupon.pkpass and the archive will contain all the files in the list that follows.
Believe it or not… that’s it! High fives all around! You did it!