When you’re ready to ship an Adobe AIR application, you’ll be required to digitally sign it in order for the Adobe AIR installer to install it to the user’s system. The Adobe AIR runtime runs with the same user privileges as native applications, allowing local file system access, network operations, bitmap manipulations, local data access, and so on. By requiring your application to be signed, Adobe instills confidence in your customers by validating the source of the application, while giving developers writing these applications known access to the user’s system to enable rich Internet applications on the desktop.

Adobe offers a few different ways to build your AIR applications whether you use Flex Builder 3, Flash CS3 Professional, or Dreamweaver CS3. In this article, I’ll show you how to sign your Adobe AIR applications for distribution with a digitally signed certificate from an authorized certificate authority (CA). And if you’re just getting started with Adobe AIR and don’t want to shell out money, you can always sign your application with an untrusted certificate to allow the AIR runtime to install your application as UNVERIFIED publisher to get you through your testing cycle.

Requirements
In order to make the most of this article, you need the Firefox 2.0 (or later) web browser and one of the following:

  • Flex Builder 3 –
  • Flex 3 SDK and the ADT Application –
  • Flash CS3 Professional –
  • Adobe AIR update for Flash CS3 Professional –
  • Dreamweaver CS3 – 
  • Adobe AIR extension for Dreamweaver CS3 –
  • Firefox 2.0 web browser available free from Mozilla –


Prerequisite knowledge

You should be familiar with building Adobe AIR applications with the development methods of your choice: Flash, Flex, or HMTL and Ajax.

Why sign an application?
When users install your application, they’re trusting you that you’re not going to do sucky things, like sniff their files for financial data to upload to some server in a third-world country, or to delete all your local images, or to send e-mails on behalf of all your friends. Users want to feel confident that the software they’re installing comes from a reliable vendor (publisher), and that what they’re installing hasn’t been modified since that vendor released it. As a developer, you build a great application and release it to the world. After it’s released, though, you don’t really have any control over other people taking my application, modifying it, injecting some evil bits, and then distributing it on your behalf. Users should be aware that anything they install from the web could be tampered with or come from an unreliable malware vendor.

The only way to instill confidence in the end user is by requiring developers to digitally sign their applications with a security certificate from a trusted third-party vendor, such as ChosenSecurity, GlobalSign, Thawte, or VeriSign, called a certificate authority (CA). All AIR applications must be digitally signed in order for the AIR runtime to install them on the user’s machine. Digital signing has found its way into all commercial software development, whether you’re dealing with a mobile app executing on a PDA, device drivers for a major operating system, desktop applications from a big publishers, or the AIR applications that you create. How many times have you risked the stability of your system by knowingly installing some random software, even though you didn’t know who really built it, where the code came from, or whether it was modified since its release? Wouldn’t you feel much better knowing that you could verify the source and authenticity of the bits?

Digital signing also allows customers to verify their organizational affiliation. For example, I can’t sign an application with Adobe Software’s certificate. This eliminates the possibility of building fake applications. Otherwise spyware makers could easily create a Photoshop.exe app, pretending it is by Adobe, and have it use your bank account number from your tax software to create fake checks.

Code signing takes care of these scenarios by building customer confidence that what they’re installing was created by the named publisher, and that the code hasn’t been changed since that publisher signed it.

Pre-planning saves pain
Don’t wait until the night before you’re expecting to release your application to start the code signing process. There’s some administrative overhead involved in acquiring a certificate from a CA which will take time to resolve. There’s some learning and experimenting needed once you acquire a certificate. And then you don’t want to be releasing different versions of your application to users that are signed with different certificates.

When you sign an AIR application with a certificate, whether it’s a developer self-signed test certificate, or the official certificate of your company, that version of your AIR application can only ever be updated with another version of your application published with the same certificate. Let me clarify, you cannot create and release an application into the wild with a developer test certificate and then at a later date sign it with a production certificate and re-release it. It will have to be a new application. Any automatic updating of the old application will fail, and it’ll only install as a separate application.

Note: Within a large organization, individual developers are not allowed to keep the company’s credentials. As such, depending on the organization, you may need to provide an AIR Intermediate (AIRI) package or .airi file, which can then be signed by someone within the organization who has the proper credentials. If someone else purchases the cert, then that person would need to convert the AIRI file into a .p12/pfx for the developer to use. Check with your organization’s PKI team, if you’re working within a larger corporation. Preparing an AIRI file basically follows the same steps as choosing a digital signature for an AIR application (outlined in this tutorial), with the proviso that instead of choosing a certificate you specify that you want to create an AIRI file.

Let’s get started procuring a certificate.

How to get a certificate
A developer can use any class-3, high-assurance certificate provided by any CA to sign an Adobe AIR application. However, only ChosenSecurity, GlobalSign, Thwarte, and VeriSign come pre-installed on most end user’s machines (Mac OS X or Windows) and are trusted by the operating systems.

Note: For a list of CAs and certificate formats, see also the Adobe AIR documentation for Flash, Flex, and HTML developers.

The Adobe AIR runtime uses the operating system’s keystore of trusted certificates when installing applications. Whatever the OS trusts, AIR will trust. Most likely your users will have a ChosenSecurity, GlobalSign, Thawte, or VeriSign root certificate on their systems, which means your users will be able to see the valid publisher when Adobe AIR attempts to install your app. In this article, I’ll assume that you’re getting a certificate from Thawte as it simplifies the process for the developer. Using certificate authorities other than ChosenSecurity, GlobalSign, Thawte, or VeriSign is going to require that the end user (not the developer of the software), or a system admin charged with managing a computer on an enterprise network, manually install a root certificate for that certificate authority.

Note: There’s also a way for a developer to self-sign an Adobe AIR application so they can test it, but when the AIR runtime tries installing the application, it presents the user with a big old UNKOWN publisher warning, see Figure 1. (Unless, of course, your user has installed your self-signed certificate on his or her machine.)

Figure 1. A user sees this dialog box when installing an application with a developer certificate. Note the UNKNOWN publisher identity.

ChosenSecurity, GlobalSign, Thawte, and VeriSign sell an official Adobe AIR Developer Certificate on their websites. In the example below, you’re going to purchase a certificate from Thawte using the Firefox browser, which is required for the process you’re following here, because it’s the easiest. Thawte offers certificates starting at $300 for one year.

Note: For those of you familiar with the security protocols, Java tools, and the command line, there are other ways to get your Java certificate into the proper format for signing an Adobe AIR application. You’ll need the Java sign tools to get the certificate and private key into the right format. Your goal is to end up with a P12 file. Using the Java command line tools is beyond the scope of this document. Using the Firefox method and Thawte is the simplest way to procure a certificate. And you only have to do this once for the lifetime of your certificate.

Procuring a certificate from Thawte
Obtaining an official Adobe AIR Developer Certificate from Thawte is the easiest way to get your code signed. For this example, I’m going to get a certificate from Thawte using the Firefox web browser. It’s really important that you use Firefox because the purchased certificate is going to be installed into the Firefox certificate manager where it’ll be exported in a specific format required by all of the Adobe tools for signing your Adobe AIR application.

1.Go to the Thawte website, select an Adobe AIR Developer Certificate, and then press the red Submit button (see Figure 2).


Figure 2. Start the procurement process at Thawte’s website for a certificate to sign your Adobe AIR application.

The next step is the first of three at the Thawte website titled “Configure your Enrollment.”

2.Choose the duration for your certificate (1 year or 2 years), fill out your organizational information, website, and then provide a password for managing your account.
3.Continue through the steps “Confirm your Enrollment” and “Complete your enrollment.” Thawte will authenticate your organization (PDF, 112K) and then request more information from you. Be prepared to fax them information like Articles of Incorporation, VAT certificates, Partnership papers, fictitious name certificates, and so on. During this process they verify your identity and business association.
4.After organization verification is complete, Thawte will e-mail you instructions on how to retrieve the certificate. Again, be sure that you retrieve the certificate using Firefox since you’re going to export the certificate from Firefox in a format needed by all the Adobe code signing tools.
5.Open the link that you received from Thawte in the Firefox web browser and log in to the Thawte website using the password you created in Step 2 above.
6.Click Fetch certificate. Thawte will automatically install the certificate you purchased from them into your Firefox certificate manager.
7.Now that Thawte has installed your certificate into Firefox, it’s time to export it for use from all of Adobe’s tools. Navigate to Tools/Options/Advanced and you’ll see the dialog box in Figure 3.

Figure 3. The Firefox 2.0 Options dialog box

8.Click the View Certificates button to view Figure 4.

Figure 4. The Firefox certificate manager. Note the certificate you just purchased from Thawte (in this example: eBay).

9.Select the certificate you want to export, and then click the Backup button. Firefox will save your certificate and private key in a P12 file (PKCS12 format), which will be required for signing from either the ADT command line tool in the Flex 3 SDK and the Flex Builder 3 Export Wizard, as well as Dreamweaver CS3 or Flash CS3 with Adobe AIR support.
Note: You may be required to change the file name extension to .pfx, depending on the toolset you’re signing with.

10.Enter the location you want to save the file and give it a name that you’ll remember later. I put mine in c:\mydev\certificates\air_cert.p12.
11.You’ll be prompted to create a password for your certificate and private key (see Figure 5); enter it twice.


Figure 5. Create a password to protect your certificate and private key.

12.Click OK and voilà, your certificate is ready to start signing your Adobe AIR applications.
After you’ve acquired your certificate, you’re ready to start signing your Adobe AIR applications. Skip to the appropriate section below to learn how to use the certificate you just acquired from Thawte with your favorite tool:

Signing an Adobe AIR application with Flex Builder 3
Signing an Adobe AIR application with the Flex 3 SDK
Signing an Adobe AIR application with Flash CS3 Professional
Signing an Adobe AIR application with Dreamweaver CS3

Signing an AIR application with Flex Builder 3
Signing your AIR applications with Flex Builder is a simple process. After you’ve acquired your certificate from the CA, store it in a known directory. In this example, my certificate is stored in c:\mydev\certificates\. Don’t forget the password that you used to export your certificate from Firefox—you’ll need it to sign your application.

Whenever you export your Adobe AIR application from Flex Builder 3, code signing will be an integrated step. You can’t export your application without signing it. The export wizard provides the option of creating a self-signed certificate for testing purposes, or using the certificate you acquired above from Thawte (or any registered certificate authority).

To sign your AIR application in Flex Builder 3:

1.Select Project > Export Release build. This opens the Export Release build dialog box shown in Figure 6.


Figure 6. The AIR project export release wizard.

2.Select the Application entry point which is the main MXML file that will start when a user starts your application. Name the Adobe AIR package that you want to export. In this example, I used AirProject.air. This will be the name of the file that people download from your website, so be sure to choose a meaningful name for your product.
3.Click Next to open the Export Release Build dialog box (see Figure 7). Here you can either browse for an exiting digital certificate like the one you acquired from Thawte above, or you can create a self-signed developer certificate by pressing the Create button to the far right.


Figure 7. The Digital Signature signing step of the Export AIR application wizard.

4.If you don’t have a certificate, click the Create button to generate a self-signed developer certificate. You’ll be shown a new dialog box where you actually create a self-signed developer certificate. This window collects much of the same information that either VeriSign or Thawte will ask for when purchasing your certificate. In Figure 8, I’m filling out the publisher name (the name of your company), country, type, and password that I use to protect your certificate. Click OK to create the certificate and continue the Adobe AIR application export process. Don’t forget the password, as you’ll need this in the next step.


Figure 8. Creating a self-signed (developer) certificate for testing purposes.

5.Enter the password of the developer certificate you either created in Step 4 above or when you exported the certificate from Firefox in the previous section.
6.Click Finish.
7.You should now have a signed .air file sitting in your project directory.
Now it’s time to install the application to your machine just like a user would if they downloaded your AIR file from your website. If you’re not interested in reading about the signing process in any of the other tools, skip ahead to Testing the AIR installation.

Signing an AIR application with the Flex 3 SDK
Geeky developers may shun all rich development tools for creating their AIR applications, in which case, they’ve opted to use the Flex 3 SDK with their favorite text editor (Emacs, VI, TextMate, and so on) and the Flex SDK command line compiler (mxmlc.exe) to make applications happen. Or, maybe you have a build server that manages your code, compilation, and deployments and need it to automatically sign your AIR application before posting to a network share. When using the Flex SDK or having your build server manage builds, you’ll need to use the ADT application to package and sign your AIR application. Being a command line guru, I’ll assume you’ve already read Creating your first AIR application with the Flex SDK in Adobe LiveDocs, which should get you up to speed on creating your first AIR application that will need to be signed with the raw SDK.

To sign an AIR application written with the Flex SDK, you’ll need to acquire a certificate from a CA as documented above. However, for testing purposes, you can create a self-signed certificate from the command-line by using the ADT application which can be found in the Flex 3 SDK/bin directory. Make sure the Flex SDK/bin directory is in your system path so the applications there can be found when you execute them from other locations, like where your source code is for your application.

Let’s create a self-signed certificate from the command line:

1.Open a command window (Windows) or an Application shell (OS X) and type in:

adt -certificate -cn AnythingHere 1024-RSA test_cert.pfx passwordSubstitute your own common name for AnythingHere, your own name for the certificate file test_cert.pfx (making sure to keep the file name with a PFX extension), and a password of your choice. Don’t forget the password.

A certificate was created in the directory where you ran the ADT application with a name of test_cert.pfx. Remember the path to this file.

2.Now that you have a certificate, whether self-signed or acquired from Thawte according to the directions above, you’re ready to sign your AIR application.
3.From a command line, type:

adt -package -storetype pkcs12 -keystore test_cert.pfx -storepass
password TestApp.air TestApp-app.xml TestApp.swfWhere test_cert.pfx is your certificate that you either created above or exported from Firefox. TestApp-app.xml is the descriptor file that describes your application to the AIR runtime, and TestApp.swf is the application file that you created when you used the mxmlc application from the command line to compile your SWF. TestApp.air is the name of the AIR package that you’re creating which will be distributed to your end users. The value you pass into the storepass is the password that you used when you either exported your certificate from Firefox, or the self-signed certificate that you created above.

4.Press Enter to begin the packaging and signing process.
5.If all goes well, an AIR package titled TestApp.air will have been created and is ready to distribute to your users.
That’s it. You’ve packaged and signed an AIR application from the command line. Skip ahead and read Testing the AIR installation.

Signing an AIR application with Flash CS3 Professional
Flash developers can generate AIR files using the Adobe AIR update for Flash CS3 Professional. You should have already read Creating your first AIR application using Flash CS3 from Adobe LiveDocs, and installed Flash CS3 AIR Update, and created your Flash based AIR application. Along with the ability to package your Flash application for the desktop is the ability to sign your AIR applications.

You need to first acquire your certificate from a Certificate Authority as explained above (you’ll also have the opportunity to create your own self-signed developer test certificate, just like in Flex Builder CS3, from within Flash CS3 AIR Update).

To sign your Adobe AIR application in Flash CS3 Professional:

1.Change the extension of the .p12 file you exported from Firefox to .pfx; this is a necessary step.
2.From the main Flash toolbar, select the Command > AIR – Application and Installer to display the dialog box shown in Figure 9.


Figure 9. The main AIR Application & Installation Settings window.

This dialog box should look familiar to you—you’ve used it to configure your AIR runtime parameters, including default chrome, version, id and AIR package name. Halfway down there’s a section called Installer Settings with an item called Digital Signature. There’s a label there that describes the status of the certificate you’re using, or in the case of the first time you configure the application, it’ll say select a certificate to sign an AIR file. Since all AIR files must be signed, whether you use a self-signed certificate for testing or a fully qualified Thawte certificate for production, you can’t create an AIR file without choosing a certificate.

3.Press the Set button to open the Digital Certificate window (see Figure 10). From this window, you can either choose the PFX file you exported from Firefox earlier (which you renamed in Step 1), or choose to create a self-signed developer certificate.


Figure 10. Browse for your existing certificate or create a developer self-signed certificate.

4.If you want to create your own, self-signed certificate, click the Create button to open the Create Self-Signed Digital Certificate window and fill out the form (see Figure 11). It doesn’t matter what you fill out in the form because it’s going to show to the registered user as UNVERIFIED. Remember the password, as you’ll need that when packaging the application.


Figure 11. Create a self-signed certificate.

5.Click OK to create the certificate and return to the Digital Signature configuration screen.
6.Click the Browse button to choose either the digital signature that you exported from Firefox above when you purchased it from Thawte, or the self-signed certificate created in step 4.
7.Enter the password. (It’s the password you created when you exported the certificate from Firefox, or the password from when you created the self-signed certificate.)
8.Select the Remember password for this session check box so you don’t have to keep entering the password every time you build the AIR package.
9.Press the OK button to finalize your settings and return to the main AIR Settings & Installation window.
10.Now you’re ready to publish your signed AIR application. Press the Publish AIR File and an AIR file will be generated for you, ready to install to a user’s machine.
That’s it, you’re done. Test the installation by double-clicking the AIR file and watch the Adobe AIR installer do it’s magic. Reward yourself with a coffee break, then continue reading Testing the AIR installation.

Signing an AIR application with Dreamweaver
Web developers and designers can also use the Adobe AIR extension for Dreamweaver CS3 to easily create an AIR file of their HTML-based web app. You should have already read Create your first HTML-based AIR application with Dreamweaver from Adobe LiveDocs, installed the Adobe AIR extension for Dreamweaver CS3, and created your AIR application.

You need to first acquire your certificate from a certificate authority as explained above (you’ll also have the opportunity to create your own self-signed developer test certificate, just like in Flash and Flex, from within Dreamweaver).

To sign your HTML-based AIR app in Dreamweaver CS:

1.Change the extension of the .P12 file you exported from Firefox to .pfx.
2.Select Site > AIR Application Settings to open the AIR Application and Installer Settings dialog box (see Figure 12).


Figure 12. Click Set to choose a certificate to sign an AIR application.

This dialog box should look familiar to you—you’ve used it to configure your AIR runtime parameters, including window chrome and size, and which HTML file to use at startup. Now, click the Set button located next to the *Digital Signature required label.

3.With the Digital Signature window open (see Figure 13), you can see where you either choose an already created signature file, like you would have if you procured one from a certificate authority with Firefox as explained above, or you can create your own test certificate.


Figure 13. The Digital Signature box with the option of creating a test certificate or choosing one procured from a valid certificate authority.

4.Choose the PFX (formerly P12) file you exported from Firefox.
5.Enter your password.
6.Click OK to close the Digital Signature window and return to the AIR Settings and Installation window.
7.If all went well in the digital signature window, the status next to *Digital Signature should read AIR Package will be signed. This means every time you build the AIR file, the Dreamweaver AIR extension will automatically sign your application with the certificate you provided during the current development session
8.Fill in the name of the AIR package you want to create and press the Create AIR File button to build the AIR installation file.
That’s it, you’re done. Test your AIR installation.

Testing the AIR installation
Double-click the AirProject.air file and the AIR installation process will begin (make sure you have the Adobe AIR runtime installed). The first step of the installation process is the Adobe AIR installer displaying the information about the publisher of the code. If you’ve signed with a self-signed developer license, and since the operating system doesn’t trust certificates signed by you, the user will be shown a dialog box announcing that the publisher is UNVERIFIED (see Figure 14). This should cause them all sorts of discomfort and cause them to immediately stop installing your application. However, for testing purposes, this is just fine for you to test your installation. And users living on the edge can still select Install to load your untrusted application.


Figure 14. The verification of an UNKOWN Publisher about to install an application.

However, if you’ve signed your AIR application with a valid certificate, the user will be presented with an Adobe AIR installation dialog box with a valid publisher identity that should make your users all warm and fuzzy (see Figure 15).


Figure 15. An installation dialog box with a known publisher identity.

That’s all there is to signing and installing your Adobe AIR application.

Where to go from here
Adobe offers many options for developing and signing AIR applications. And there’s just as many options as to where and how you purchase your certificates (for more information refer to the Adobe AIR documentation for Flash, Flex, and HTML developers). We strongly suggest getting your certificate from Thawte as was done in this article because it’s really easy to manage with Firefox, but any class-3, high-assurance certificate should suffice. Remember that VeriSign and Thawte root certificates are installed on all PCs and Macs by default, though.

The process for signing your AIR applications will be the same whether you’re using the ADT command line tool, Flex Builder 3, or Dreamweaver CS3 and Flash CS3 with built-in AIR support. First, acquire the certificate from a CA. Then make it available in the proper file format (P12 or PFX), depending on the tool you use. Finally, sign your application from within your Adobe development tool.

Don’t wait until the night before you expect to release your product to start worrying about your certificate and signing. Get started right away on procuring your certificate from the CA, and then allow half a day for understanding and getting everything set up within your build process for signing your Adobe AIR application.

Creative Commons License
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License

This article was written by -Todd Prekaski – www.simplifiedchaos.com.