Migrating security certificates in AIR

Having acquired a new Thawte digital security certificate, I now need to ensure that the app will update smoothly from the old one. The thing to do is to migrate the certificate, using Adobe’s ADT.

A week ago, I took the first step in acquiring the Thawte security certificate I had received from Adobe, by filling in the form on the Thawte site. Just three hours after submitting that form, I got a call from a Thawte rep who was checking out my telephone number and name. They had already found my company in the national KvK registry, and I was quite impressed.

Yesterday I got their confirmation e-mail, saying “We have successfully completed the necessary background checks and issued the certificate to BLAGOWORKS.” Weee — I’m a trusted source! So today I took the second step: retrieving the certificate and update the app with it.

The goal: a Code Yellow during install – with a digital certificate, the publisher’s identity is now verified

Retrieving the certificate

Using Adobe’s help-page and Firefox, it was a pretty straightforward process to get it. First you use Firefox to “fetch” the certificate, meaning that it is stored in Firefox’s keystore, and then you make a local backup copy of the p12 file, using Firefox’s “Manage certificates” dialog (see Adobe’s help for details).
This file, and the password I attached to it when I made the local copy, is used by the publishing tool (Flash) to digitally sign the AIR app.

Using this new certificate means that my app’s publisher identity – its pubid – will change, of course. When the pubid changes, the update feature doesn’t work anymore, as it does not recognize the new file as an updated version of the old one. But, as I mentioned in my previous post, Adobe offers a migrating option for AIR. Only thing is, you have to use the command-line Adobe Development Tool (ADT) for that, and I was not very happy with that – I’m using Flash CS4, not the SDK or a text editor, to build and publish…

Changing certificates: migrate from self-signed to commercial certificate

This Adobe help page explains how to migrate from self-signed to commercial certificate.
Basically, it’s three steps:

• create your update
• publish it with the new certificate in the usual way
• publish it again – using the ADT, running it with a -migrate flag attached on the command line

Didn’t seem too hard to do. But I’m sorry to say, it took me a while to figure out how to make the ADT work. Here’s how I finally managed to get the migration done.

Using the Adobe Developer Tool to migrate

1. get the tools:
You need the Flex SDK for this, a 122 Mb download. Unzip the SDK. The ADT.bat – a 1k file – is in the bin folder. Make a note of its location, for example in Notepad; it’ll be something like this:
D:\Downloads\Flash\Flex_SDK\bin

ADT is a Java program that you can run from the command line, so you need Java as well: get Java, or check if you have it already

2. configure system path:
One way to make ADT run from the command promt is to set a custom System path variable. For Windows XP (not sure about Vista), open System Properties by clicking System in your Control Panel. Click the Advanced tab, and there, click the Environment Variables button.
In the System variables list, select the “Path” entry and then click the Edit button. Add the path to the bin directory to the end of the variables line, separating it from previous values with a semicolon:
systempathvariables; D:\Downloads\Flash\Flex_SDK\bin

Click OK to close the panels.

3. check if ADT will run:
Select Start > Run, type “cmd” (command), click OK. Now you should have the familiar black cmd.exe window open. Type “adt” after the promt and hit enter. You should get “No arguments were found” plus a list of arguments you could use under “usage”.

4. construct the command line:
Preferably in Notepad, construct the string you’ll be typing after the command prompt to make ADT do what you want. The migrate argument has the following syntax:
adt -migrate OLD-STORE-TYPE OLD-CERTIFICATE-FILE NEWLY-SIGNED-AIR-FILE MIGRATING-AIR-FILE

The NEWLY-SIGNED-AIR-FILE is the air file with the new certificate that you’ve published in the normal way. The MIGRATING-AIR-FILE will be the one published with the old certificate added as backup: migrating your app from old to new.
In its most basic form, this would look like:
adt –migrate -storetype pkcs12 -keystore cert.p12 myApp.air myApp.air

You should put in the full paths to the files, separated by a space; I’m sure this can be done easier but for now, this is working (on one line):
adt –migrate -storetype pkcs12 -keystore F:\_BlagoWorks\mycert.p12
F:\_BlagoWorks\RSSreader_2009\air\install_blagoTelexer_2.air
F:\_BlagoWorks\RSSreader_2009\air\install_blagoTelexer_210.air

5. type
Now type the string in one long go after the command prompt. Hit enter, and the ADT will ask for a password. This is the password to the outgoing keystore, the old one. Type it in (it will not be showing as text) and hit enter again. And if all went well, after a few seconds you’ll have a migrated AIR file with a new certificate, that will update normally for your users!