Packaging Adobe AIR applications for the desktop

Additional required other products

• Firefox 3.6 or later

Note: This is an updated and expanded version of an article originally written by Todd Prekaski.

When you're ready to ship an Adobe AIR application, you'll be required to digitally sign it 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, you instill confidence in your customers because they can validate the source of the application. Adobe offers a few different ways to build your AIR applications using Adobe Flash Builder 4.5, Adobe Flash Professional CS5.5, or Adobe Dreamweaver CS5.5. In this tutorial I will show you how to sign your AIR applications using these tools when targeting the desktop.

For information on how to package AIR applications for devices refer to the following tutorials:

• Packaging Adobe AIR applications for Google Android
• Packaging Adobe AIR applications for BlackBerry Tablet OS
• Packaging Adobe AIR applications for Apple iOS devices

When users install your application, they're trusting you, as the developer, to not create an application that behaves maliciously, for example, by accessing financial data files, deleting local images, or sending e-mails to all your contacts. 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 may 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 modifying the application, injecting some malicious code, and then redistributing it. Users should be aware that software they install from the web could have been tampered with or created by an unreliable malware vendor.

The best 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 virtually all commercial software development, whether you're dealing with a mobile app, device drivers for a major operating system, desktop applications from big publishers, or the AIR applications that you create. When users install software, they want to know who really built it, where the code came from, and whether it was modified since its release.

Digital signing also allows customers to verify the organizational affiliation of the software's publisher. For example, I can't sign an application with another company's certificate. This eliminates the possibility of building fake applications. Otherwise spyware makers could easily create an application, name it Photoshop.exe to make it look like it is from Adobe, and have it perform unauthorized, unwanted actions on users' systems.

In summary, code signing builds 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.

A developer can use any class-3, high-assurance certificate provided by any CA to sign an Adobe AIR application. However, only ChosenSecurity, GlobalSign, Thawte, and VeriSign come preinstalled on most end user's machines (including Mac OS X or Windows).

Note: For a list of CAs and certificate formats, see 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 administrator charged with managing a computer on an enterprise network, manually install a root certificate for that certificate authority.

A developer may also 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 an UNKOWN publisher warning (see Figure 1)–unless, of course, your user has installed your self-signed certificate on his or her machine.

ChosenSecurity, GlobalSign, Thawte, and VeriSign sell official Adobe AIR Developer Certificates on their websites. In the example below, you're going to purchase a certificate from Thawte using the Firefox browser.

Note: If you are familiar with 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 article. 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.

Obtaining an official Adobe AIR Developer Certificate from Thawte is one way to get your code signed. ChosenSecurity, GlobalSign, Thawte, and VeriSign have similar processes.

Note: The GlobalSign Free Code Signing Tool provides a simple front end to the command-line tools for signing Adobe AIR applications. Using the tool is simple and intuitive: select your application type, your certificate, and optionally add a timestamp. GlobalSign's Code Signing Tool prompts to download the correct SDK and tools depending on your chosen application, and shows the executable command line helping expedite the process of digitally signing applications with ease. For more information refer to the GlobalSign website.

For this example, I'll show you how to get a certificate from Thawte using the Firefox web browser. When you use Firefox, the purchased certificate is installed into the Firefox certificate manager where it can 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 Adobe AIR, specify the duration of your certificate and then click the red Buy button (see Figure 2).

2. Follow the instructions on screen to provide your organizational information, website, and a password for managing your account.
   When you complete the process Thawte will authenticate your organization and then request documentation from you. Be prepared to fax them information such as articles of incorporation, VAT certificates, partnership papers, fictitious name certificates, and so on. During this process they verify your identity and business association.
   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.
3. Open the link that you received from Thawte in the Firefox web browser and log into the Thawte website using the password you created when ordering the certificate.
4. Click Fetch certificate. Thawte will automatically install the certificate you purchased from them into your Firefox certificate manager.
   Now that Thawte has installed your certificate into Firefox, it's time to export it for use in Adobe tools.
5. In Firefox, choose Tools > Options, click Advanced, and then click the Encryption tab (see Figure 3).

6. Click View Certificates (see Figure 4).

7. Locate and select the certificate you purchased from Thawte, and then click Export. 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 4.5 SDK, Flash Builder 4.5, Dreamweaver CS5.5, or Flash CS5.5.

   Note: You may be required to change the file name extension to .pfx, depending on the toolset you're signing with.

8. Specify the directory and name for the  file. Use a name that you'll remember later. I put mine in c:\mydev\certificates\air_cert.p12.
9. You'll be prompted to create a password for your certificate and private key (see Figure 5); type it twice.

10. Click OK. After Firefox exports your certificate, you are ready to start signing your Adobe AIR applications.

Flash Builder makes it easy to sign your AIR applications.

1. Right-click the project in the Package Explorer and choose Export > Flash Builder > Release Build.
2. In the Export Release Build wizard, specify the file name of the AIR file that will be created and the path for that file (if you leave the path empty, the AIR file will be created in the root folder of your project).
3. Select Signed AIR Package (see Figure 5) and click Next.

4. Next, you'll need to provide the path to your certificate.
5. If you don't have a certificate and you want to use a self-signed certificate, then click Create. In the Create Self-Signed Digital Certificate dialog box, type the Publisher name and password, fill out any other information you want to include, and click OK (see Figure 7). 

6. Assuming you have a certificate from Thawte or another CA, type the path to the certificate file (or browse to it) and type its password (see Figure 8).

Note: To check what will be included in the release build, click Package Contents. This is a good opportunity to make sure that everything your application needs (for example, the images used for icons) is included.

7. Click Finish.

Flash Builder will generate your AIR file.

You can also create signed AIR applications using Flash Professional CS5.5. When you are ready to sign your application, follow these steps:

1. Choose File > Publish.
2. In the AIR Settings dialog box, select the Signature tab (see Figure 9).
3. Type the path to your certificate (or navigate to it) and type the password.

Note: If you don't have a certificate and you want to use a self-signed certificate click New Then fill in all the fields, choose a name and a location for the certificate (see Figure 10), and click OK. You should see a confirmation window saying the certificate was created.

The AIR Settings dialog box also includes General, Icons, and Advanced tabs. You can use the General tab to review the included files and assets. The Icons tab, as the name suggests, lets you set the application icons. The Advanced tab is helpful when you want to set the default width and height, the default x and y position of your window, the installation folder, and so on.

4. When you are ready to publish, click Publish.

The next time you choose File > Publish, the settings you selected previously will be used as the default values. If you want to change them, then click the tool icon next to the Player option (see Figure 11) in the Publish settings. This opens the AIR Settings dialog box. Click OK to save any changes you make.

If you created your AIR app using HTML, CSS, and JavaScript then most likely you've been using Dreamweaver.

Note: To enable support for AIR applications in Dreamweaver you have to download and install the Adobe AIR extension for Dreamweaver.

Follow these steps to create a signed AIR application in Dreamweaver:

1.  Choose Site > AIR Application Settings (see Figure 12).

2. In the AIR Application and Installer Settings dialog box, fill in the required information, including File Name, ID, and Initial Content.
3. Click the Set button next to Digital Signature: AIR Package Will Be Signed With (see Figure 13).

4. In the Digital Signature dialog box, specify the location of your certificate and type the password.

Note: If you do not have a certificate from a CA and you want to create a self-signed certificate, click Create (see Figure 14). Then type the publisher name and password (at a minimum), and click OK (see Figure 15) to create a self-signed certificate.

5. When you are ready to create the signed application, click Create AIR File from the AIR Application and Installer Settings dialog box. If you've previously specified settings for your certificate, you can choose Site > Create AIR File directly. After a few seconds you should see a confirmation (see Figure 16).

If you prefer working with command line tools, then you can use the ADT command line tool from the AIR SDK to generate the certificate and sign your application.

If you don't have a certificate from a CA and you want to use a self-signed certificate, you can create one using ADT. Here is an example, which you can execute at the command line in a Console or Terminal window:

For the –cn parameter you should set your name or company name. Don't forget the password you set (in this example, it is certificate_password). You will need it later. After executing this command you should have a certificate named certificate_name.p12 in the directory in which you executed the command. (You can specify an absolute path together with the certificate name if you want to create the file in a different folder.)

When you are ready to package and sign your application, you can use the following command:

Note that in the command above that you have to specify at least:

• the name of the AIR file that will be created
• the name of the application descriptor file
• the name of the SWF file

In this example, the command is meant to be run inside the folder that contains these three resources are. If you want to add additional resources to the package, such as icon images, just add the file names at the end of the command.

Note: To compile your application and obtain the SWF file you can use the mxmlc application from the command line.

As you can see, Adobe offers many options for developing and signing AIR applications. Likewise there are many options for purchasing your certificates (for more information refer to the Adobe AIR documentation for ActionScript and HTML/JavaScript developers). I strongly suggest getting your certificate from Thawte as illustrated in this article, because it's so easy to manage with Firefox. However, any class-3, high-assurance certificate should suffice. Remember that ChosenSecurity, GlobalSign, VeriSign, and Thawte root certificates are installed on all Windows and Mac OS systems by default, though, which makes them more convenient for most users.