25 April 2011
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, Adobe instills 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 article I will show you how to sign your AIR applications using these tools when targeting the desktop as well as Android, BlackBerry Tablet OS, and iOS mobile 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).
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, which is recommended for the process you're following here because it's the easiest. Thawte offers certificates starting at about $300 for one year.
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 the easiest way to get your code signed. 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.
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.
Flash Builder makes it easy to sign your AIR applications.
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.
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:
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.
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.
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:
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.
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:
adt -certificate -cn YourNameOrCompanyOrAnythingYouWant 1024-RSA certificate_name.p12 certificate_password
–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:
adt -package -storetype pkcs12 -keystore PATH_TO_YOUR_CERTIFICATE/certificate_name.p12 -storepass certificate_password YOUR_APPLICATION_NAME.air YOUR_APPLICATION_NAME-app.xml YOUR_APPLICATION_NAME.swf
Note that in the command above that you have to specify at least:
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.
Starting with AIR 2 you can create native installers for your AIR application: EXE files for Windows, DMG files for Mac OS, and DEB or RPM for Linux. This is required if you want to communicate with other processes using the NativeProcess class. The first thing you should know is that the signing process must take place on the same platform as the native installer you are creating. For example, if you want to create an EXE AIR application, then you have to do it on a Windows machine. Likewise, if you want a DMG file, you have to package the application on a Mac.
You can create native installers using the command line tool (ADT), Flash Builder 4.5, or Flash Professional CS5.5.
In this section I won't explain the whole process for each method; see the preceding sections for a more detailed description of the necessary steps. Instead I will point out the differences when signing a native installer application.
This is the key difference between the signing process for an AIR file and for a native installer.
To create a native installer using Flash Professional CS5.5, start by opening the AIR Settings dialog box—click the tool icon to right left of the Player option in the Publish settings (see Figure 18).
Finally, if you want to use the command line tool, ADT, then all you have to do is insert an additional parameter (
-target native) in the command described in Signing an AIR application with the AIR SDK.
So the command will look like this on a Mac:
adt -package -storetype pkcs12 -keystore PATH_TO_YOUR_CERTIFICATE/certificate_name.p12 -storepass certificate_password –target native YOUR_APPLICATION_NAME.dmg YOUR_APPLICATION_NAME-app.xml YOUR_APPLICATION_NAME.swf
For Windows it will look like this:
adt -package -storetype pkcs12 -keystore PATH_TO_YOUR_CERTIFICATE/certificate_name.p12 -storepass certificate_password –target native YOUR_APPLICATION_NAME.exe YOUR_APPLICATION_NAME-app.xml YOUR_APPLICATION_NAME.swf
For Linux it will look like this:
adt -package -storetype pkcs12 -keystore PATH_TO_YOUR_CERTIFICATE/certificate_name.p12 -storepass certificate_password –target native YOUR_APPLICATION_NAME.rpm YOUR_APPLICATION_NAME-app.xml YOUR_APPLICATION_NAME.swf
If you plan to distribute your AIR application to Android Marketplace you are required to digitally sign your application using a self-generated code signing certificate. Here are some points you should keep in mind when signing AIR apps for Android:
You can use Flash Builder or Flash Professional CS5.5 to generate a self-signed certificate that will meet these requirements or you can generate one using ADT.
If you want to use the ADT command line tool, you can use a command in the following format (no new lines in between; everything on a single line):
adt -certificate -cn name [-ou org_unit][-o org_name] [-c country] [-validityPeriod number_of_years] key_type pfx_file password
Here is an example for running this command on Mac OS (note that for the –cn I escaped the space between Mihai and Corlan using a backslash):
adt -certificate -cn Mihai\ Corlan -ou corlan.org -validityPeriod 25 2048-RSA ~/androidselfcert.p12 somepass
This command will generate a file named androidselfcert.p12 in your home directory.
To sign your application using the command line, you also use ADT. Here is an example of the command:
./adt -package -target apk -storetype pkcs12 -keystore PATH_TO_YOUR_CERTIFICATE -storepass YOUR_CERTIFICATE_PASSWORD YOUR_APPLICATION_NAME.apk YOUR_APP_XML_FILE-app.xml YOUR_SWF_FILE.swf
The command above can be used when you've already created a release build of your application to generate the APK file.
Follow these steps to sign an Android app using Flash Builder:
Next, you need to create a self-signed certificate:
The APK file is typically created inside the root of your project. You can upload this file to the Android Market.
Each time you want to release an update for your application, first increase the versionNumber in your application descriptor file and then use the same workflow. For updates, instead of creating a new certificate you will select the one you created for the initial release.
Follow these steps to use Flash Professional CS5.5 to create AIR for Android apps:
On the Icons tab you can specify the icons used by your application. On the Permissions tab you can specify the permissions required in your application, including Internet access, SD card access, and so on (see Figure 24).
Before you can submit your application to Android Market, you'll need to register at the Android Market portal. There is a one-time registration fee of $25.
It is a good idea to prepare relevant screenshots of your application and a description in advance because you'll need them when filling out the online form for submitting your application.
The process is smooth and fast; you can publish your first application in Android Market in fewer than 15 minutes, and that includes creating your Android Market account and completing the forms.
There are two main steps you have to complete in order to sign AIR apps for BlackBerry Tablet OS:
The signing process for creating a BAR file that you can submit to BlackBerry App World requires signing your application twice. First, you'll use a code signing certificate as for any AIR app (you can use a self-generated certificate or one acquired from a CA). Second, you'll sign the application with a RIM certificate.
The first step is to make a request for signing PlayBook apps.
Pay special attention to these three sections:
The credit card is required only for verification purposes.
Once you finish this registration you should receive a confirmation email and within 24 hours you should receive five email messages, each one having either a CSI file or a CSJ file.
If for some reason you forget your PIN you can submit another request. You'll also need to submit another request if you want to sign applications from another computer.
You are now ready to use Flash Builder 4.5 to sign mobile ActionScript and Flex apps for the BlackBerry PlayBook.
The values you set for publisher and password must match the ones you provided when requesting permission to sign PlayBook apps.
To add this certificate, click Select Certificate.
Next, you have to register and configure the RIM certificate.
Flash Builder will communicate with the RIM servers (so be sure your computer has Internet access) and register your RIM certificate.
After you've registered your certificates with the BlackBerry Signing Authority you should receive an email that confirms your registration; for example:
A registration request completed successfully for client '56240569'. The client has 2147483647 code signing request(s) left.
The client was sent back the following message:
Client '56240569' successfully registered with signing server ID RDK, and now has 2147483647 code signing attempts remaining.
This transmission (including any attachments) may contain confidential information, privileged material (including material protected by the solicitor-client or other applicable privileges), or constitute non-public information. Any use of this information by anyone other than the intended recipient is prohibited. If you have received this transmission in error, please immediately reply to the sender and delete this information from your system. Use, dissemination, distribution, or reproduction of this transmission by unintended recipients is not authorized and may be unlawful.
<versionNumber>. Each time you export a release build you'll have to increase this number.
By default the BAR file will be created in the root folder of the project you are exporting. If you want to use a different path, use the Export To Folder option to set one.
Flash Builder will generate your BAR file. If you get errors, see Application Signing Errors on the BlackBerry website.
You can submit your application (the BAR file) to the BlackBerry App World portal, after you register as a vendor.
Currently, it doesn't cost you anything to become a vendor. However you should start the process before you are ready to submit your application because it takes a day or two. After you submit your request to become a vendor, you may receive an email asking for additional information. Once you send the requested information you should receive the confirmation in the next 24 hours.
Follow these steps to submit your app:
Flash Builder 4.5 includes support for packaging Flex and ActionScript applications for Google Android, as well support for packaging ActionScript applications for Apple iOS. An update to Flash Builder, scheduled for June 2011, will provide additional options to package Flex applications for Apple iOS and will include built-in support for packaging both Flex and ActionScript applications for BlackBerry Tablet OS.
When it comes to packaging your application for specific platforms, the process for acquiring signing certificates and provisioning files can vary. For Google Android and BlackBerry Tablet OS the process is relatively straightforward, whereas for Apple iOS there are a number of steps that must be completed before an application can be deployed to a device, even for testing and debugging purposes.
This section is for ActionScript and Flex developers, who are unfamiliar with Apple's process and need to complete the necessary steps so that applications built in Flash Builder can be deployed to iOS devices during the development and testing phases of the project.
To package applications for testing/debugging on iOS devices or for deployment to the Apple App Store you will need to enroll in the Apple Developer Program (fees apply). For more information on the Apple Developer Program and to create an account, visit Apple Developer Program Enrollment.
Once registered, you will need to login to the iOS Provisioning Portal to complete the following tasks:
You will also use the iOS Provisioning Portal to distribute your application via the App Store; that part of the process is not covered in this article, instead you should refer to Apple's documentation.
The development certificate (in P12 format) and the provisioning profile are required before you can package your application for iOS in Flash Builder.
Follow the guide on the iOS Provisioning Portal to generate your development certificate. The guide assumes you are using Mac OS, but it is possible to generate the certificate using Windows; for details see the iOS Certificates section of Signing AIR applications in the Adobe AIR documentation.
Before you can use the certificate with Flash Builder, you must convert it to P12 format. See Converting a developer certificate into a P12 keystore file.
Store the P12 file on your computer, as you will need to use it with Flash Builder later.
Devices that you wish to run/debug the application on must be specified in the provisioning profile used to package the application; as such, you must register the devices on the iOS Provisioning Portal.
To register a device you need the device's Unique Device Identifier (UDID). To get this, follow these steps:
More information on locating the UDID and registering a device can be found in the guide on the Apple website.
Each application that you intend to deploy must have an App ID, which comprises a Bundle Seed ID (also called the App ID Prefix) and a Bundle Identifier (also called the App ID Suffix).
Follow the guide on the iOS Provisioning Portal to create your App ID: http://developer.apple.com/ios/manage/bundles/howto.action
The Bundle Identifier must be the same as the value of the <id> attribute in your application's app.xml descriptor file in Flash Builder. For example, if you create a Bundle Identifier as com.adobe.myApp, then your app.xml file must contain the following:
<!-- A universally unique application identifier. Must be unique across all AIR applications. Using a reverse DNS-style name as the id is recommended. Required. --> <id>com.adobe.myApp</id>
You can use a wildcard in the Bundle Identifier to create a provisioning profile that is valid for a number of applications, for example a provisioning profile with a Bundle Identifier specified as com.adobe.* can be used with applications with an id of com.adobe.myApp and com.adobe.myOtherApp.
Note: Once created, you cannot remove an App ID from the iOS Provisioning Portal.
The final step you need to complete using the iOS Provisioning Portal is to create an iOS Development Provisioning Profile. You will define a profile name, specify the certificate you created, select an App ID, and choose the device or devices the application can be deployed to. More information on creating a Provisioning Profile can be found in the guide on the Apple website:
Download the provisioning file to your computer, as you will need to use it with Flash Builder later.
Before you are ready to deploy an application to an Apple iOS device you need to specify the information required to package the application as an IPA file.
To create an IPA file, right-click the project name in the Package Explorer and select Export > Flash Builder > Release build. Follow the steps in the Export Release Build wizard to generate your IPA file.
With the build packaging information defined you are ready to deploy or debug the application on an iOS device. Unlike with other platforms, it is not possible for Flash Builder to automatically deploy the application to a device – you will need to use Apple iTunes to complete this task.
Follow the steps in the documentation depending upon whether you are deploying or debugging your application on your device or exporting a package for wider deployment:
Once you have the provisioning file you can also use Flash Professional CS5.5 (instead of using Flash Builder 4.5) to sign and package your AIR app as an IPA file.