Packaging an AIR installation file using the AIR Developer Tool (ADT)

Contents [Hide]

Packaging an AIR installation file
ADT command line signing options
Creating an unsigned AIR intermediate file with ADT
Signing an AIR intermediate file with ADT

You create an AIR installation file for both your SWF-based and HTML-based AIR applications using the AIR Developer Tool (ADT). (If you are using Adobe Flash CS3 to create your application, you can also use the Create AIR File command on the Commands menu to build the AIR package. For more information, see Adobe AIR Update for Flash CS3 Professional. If you’re using Flash CS4, select File > AIR Settings. For more infromation, see Publishing for Adobe AIR in Using Flash.)

ADT is a Java program that you can run from the command line or a build tool such as Ant. The AIR and Flex SDKs include command line scripts that execute the Java program for you.

Packaging an AIR installation file

Every AIR application must, at a minimum, have an application descriptor file and a main SWF or HTML file. Any other installed application assets must be packaged in the AIR file as well.

All AIR installer files must be signed using a digital certificate. The AIR installer uses the signature to verify that your application file has not been altered since you signed it. You can use a code signing certificate from a certification authority, such as VeriSign or Thawte, or a self-signed certificate. A certificate issued by a trusted certification authority provides users of your application some assurance of your identity as publisher. A self-signed certificate cannot be used to verify your identity as the signer. This drawback also weakens the assurance that the package hasn’t been altered, because a legitimate installation file could be substituted with a forgery before it reaches the user).

You can package and sign an AIR file in a single step using the ADT -package command. You can also create an intermediate, unsigned package with the -prepare command, and sign the intermediate package with the -sign command in a separate step.

When signing the installation package, ADT automatically contacts a time-stamp authority server to verify the time. The time-stamp information is included in the AIR file. An AIR file that includes a verified time stamp can be installed at any point in the future. If ADT cannot connect to the time-stamp server, then packaging is canceled. You can override the time-stamping option, but without a time stamp, an AIR application ceases to be installable after the certificate used to sign the installation file expires.

If you are creating a package to update an existing AIR application, the package must be signed with the same certificate as the original application or with a certificate that has the same identity. To have the same identity, two certificates must have the same distinguished name (all the informational fields match) and the same certificate chain to the root certificate. Therefore, you can use a renewed certificate from a certification authority as long as you do not change any of the identifying information.

As of AIR 1.1, you can migrate an application to use a new certificate using the -migrate command. Migrating the certificate requires signing the AIR file with both the new and the old certificates. Certificate migration allows you to change from a self-signed to a commercial code-signing certificate or from one self-signed or commercial certificate to another. When you migrate a certificate, your existing users do not have to uninstall their existing application before installing your new version. Migration signatures are time stamped, by default.

Note: The settings in the application descriptor file determine the identity of an AIR application and its default installation path. See The application descriptor file structure.

Package and sign an AIR file in one step

Use the -package command with the following syntax (on a single command line):

adt -package SIGNING_OPTIONSair_fileapp_xml [file_or_dir | -C dirfile_or_dir | -e file dir ...] ...

SIGNING_OPTIONS The signing options identify the keystore containing the private key and certificate used to sign the AIR file. To sign an AIR application with a self-signed certificate generated by ADT, the options to use are:

-storetype pkcs12 -keystore certificate.p12

In this example, certificate.p12 is the name of the keystore file. (ADT prompts you for the password since it is not supplied on the command line.) The signing options are fully described in ADT command line signing options.

air_file The name of the AIR file that is created.

app_xml The path to the application descriptor file. The path can be specified relative to the current directory or as an absolute path. (The application descriptor file is renamed as “application.xml” in the AIR file.)

file_or_dir The files and directories to package in the AIR file. Any number of files and directories can be specified, delimited by whitespace. If you list a directory, all files and subdirectories within, except hidden files, are added to the package. (In addition, if the application descriptor file is specified, either directly, or through wildcard or directory expansion, it is ignored and not added to the package a second time.) Files and directories specified must be in the current directory or one of its subdirectories. Use the -C option to change the current directory.

Important: Wild cards cannot be used in the file_or_dir arguments following the –C option. (Command shells expand the wildcards before passing the arguments to ADT, which causes ADT to look for files in the wrong location.) You can, however, still use the dot character, ".", to stand for the current directory. For example, "-C assets ." copies everything in the assets directory, including any subdirectories, to the root level of the application package.

-C dir Changes the working directory to the value of dir before processing subsequent files and directories added to the application package. The files or directories are added to the root of the application package. The –C option can be used any number of times to include files from multiple points in the file system. If a relative path is specified for dir, the path is always resolved from the original working directory.

As ADT processes the files and directories included in the package, the relative paths between the current directory and the target files are stored. These paths are expanded into the application directory structure when the package is installed. Therefore, specifying -C release/bin lib/feature.swf places the file release/bin/lib/feature.swf in the lib subdirectory of the root application folder.

-e file dir Places the specified file into the specified package directory.

Note: The <content> element of the application descriptor file must specify the final location of the main application file within the application package directory tree.

ADT Examples

Package specific application files in the current directory:

adt –package -storetype pkcs12 -keystore cert.p12 myApp.air myApp.xml myApp.swf components.swc

Package all files and subdirectories in the current working directory:

adt –package -storetype pkcs12 -keystore ../cert.p12 myApp.air myApp.xml .

Note: The keystore file contains the private key used to sign your application. Never include the signing certificate inside the AIR package! If you use wildcards in the ADT command, place the keystore file in a different location so that it is not included in the package. In this example the keystore file, cert.p12, resides in the parent directory.

Package only the main files and an images subdirectory:

adt –package -storetype pkcs12 -keystore cert.p12 myApp.air myApp.xml myApp.swf images

Package the application.xml file and main SWF located in a working directory (release/bin):

adt –package -storetype pkcs12 -keystore cert.p12 myApp.air release/bin/myApp.xml –C release/bin myApp.swf

Package assets from more than one place in your build file system. In this example, the application assets are located in the following folders before packaging:

/devRoot 
    /myApp 
        /release 
            /bin 
                myApp.xml 
                myApp.swf 
    /artwork 
        /myApp 
            /images 
                image-1.png 
                ... 
                image-n.png 
    /libraries 
        /release 
            /libs 
                lib-1.swf 
                ... 
                lib-n.swf 
                AIRAliases.js

Running the following ADT command from the /devRoot/myApp directory:

adt –package -storetype pkcs12 -keystore cert.p12 myApp.air release/bin/myApp.xml  
    –C release/bin myApp.swf 
    –C ../artwork/myApp images  
    –C ../libraries/release libs

Results in the following package structure:

/myAppRoot 
    /META-INF 
        /AIR 
            application.xml 
            hash 
    myApp.swf 
    mimetype 
    /images 
        image-1.png 
        ... 
        image-n.png 
    /libs 
        lib-1.swf 
        ... 
        lib-n.swf 
        AIRAliases.js

Run ADT as a Java program (without setting the classpath):

java –jar {AIRSDK}/lib/ADT.jar –package -storetype pkcs12 -keystore cert.p12 myApp.air myApp.xml myApp.swf

Run ADT as a Java program (with the Java classpath set to include the ADT.jar package):

java com.adobe.air.ADT –package -storetype pkcs12 -keystore cert.p12 myApp.air myApp.xml myApp.swf

ADT command line signing options

ADT uses the Java Cryptography Architecture (JCA) to access private keys and certificates for signing AIR applications. The signing options identify the keystore and the private key and certificate within that keystore.

The keystore must include both the private key and the associated certificate chain. The certificate chain is used to establish the publisher ID for the application. If the signing certificate chains to a trusted certificate on a computer, then the common name of the certificate is displayed as the publisher name on the AIR installation dialog.

ADT requires that the certificate conform to the x509v3 standard (RFC3280) and include the Extended Key Usage extension with the proper values for code signing. Constraints within the certificate are respected and could preclude the use of some certificates for signing AIR applications.

Note: ADT uses the Java runtime environment proxy settings, when appropriate, for connecting to Internet resources for checking certificate revocation lists and obtaining time-stamps. If you encounter problems connecting to Internet resources when using ADT and your network requires specific proxy settings, you may need to configure the JRE proxy settings.

Specifying AIR signing options

To specify the ADT signing options for the -package and -prepare commands, use the following syntax:

[-alias aliasName] [-storetype type] [-keystore path] [-storepass password1] [-keypass password2] [-providerName className] [-tsa url]

-alias aliasName —The alias of a key in the keystore. Specifying an alias is not necessary when a keystore only contains a single certificate. If no alias is specified, ADT uses the first key in the keystore.

Not all keystore management applications allow an alias to be assigned to certificates. When using the Windows system keystore for example, use the distinguished name of the certificate as the alias. You can use the Java Keytool utility to list the available certificates so that you can determine the alias. For example, running the command:

keytool -list -storetype Windows-MY

produces output like the following for a certificate:

CN=TestingCert,OU=QE,O=Adobe,C=US, PrivateKeyEntry, 
Certificate fingerprint (MD5): 73:D5:21:E9:8A:28:0A:AB:FD:1D:11:EA:BB:A7:55:88

To reference this certificate on the ADT command line, set the alias to:

CN=TestingCert,OU=QE,O=Adobe,C=US

On Mac OS X, the alias of a certificate in the Keychain is the name displayed in the Keychain Access application.

-storetype type —The type of keystore, determined by the keystore implementation. The default keystore implementation included with most installations of Java supports the JKS and PKCS12 types. Java 5.0 includes support for the PKCS11 type, for accessing keystores on hardware tokens, and Keychain type, for accessing the Mac OS X keychain. Java 6.0 includes support for the MSCAPI type (on Windows). If other JCA providers have been installed and configured, additional keystore types might be available. If no keystore type is specified, the default type for the default JCA provider is used.

Store type	Keystore format	Minimum Java version
JKS	Java keystore file (.keystore)	1.2
PKCS12	PKCS12 file (.p12 or .pfx)	1.4
PKCS11	Hardware token	1.5
KeychainStore	Mac OS X Keychain	1.5
Windows-MY or Windows-ROOT	MSCAPI	1.6

-keystore path —The path to the keystore file for file-based store types.

-storepass password1 —The password required to access the keystore. If not specified, ADT prompts for the password.

-keypass password2 —The password required to access the private key that is used to sign the AIR application. If not specified, ADT prompts for the password.

-providerName className —The JCA provider for the specified keystore type. If not specified, then ADT uses the default provider for that type of keystore.

-tsa url —Specifies the URL of an RFC3161-compliant timestamp server to time-stamp the digital signature. If no URL is specified, a default time-stamp server provided by Geotrust is used. When the signature of an AIR application is time-stamped, the application can still be installed after the signing certificate expires, because the timestamp verifies that the certificate was valid at the time of signing.

If ADT cannot connect to the time-stamp server, then signing is canceled and no package is produced. Specify -tsa none to disable time-stamping. However, an AIR application packaged without a timestamp ceases to be installable after the signing certificate expires.

Note: The signing options are like the equivalent options of the Java Keytool utility. You can use the Keytool utility to examine and manage keystores on Windows. The Apple® security utility can also be used for this purpose on Mac OS X.

Signing option examples

Signing with a .p12 file:

-storetype pkcs12 -keystore cert.p12

Signing with the default Java keystore:

-alias AIRcert -storetype jks

Signing with a specific Java keystore:

-alias AIRcert -storetype jks -keystore certStore.keystore

Signing with the Mac OS X keychain:

-alias AIRcert -storetype KeychainStore -providerName Apple

Signing with the Windows system keystore:

-alias cn=AIRCert -storeype Windows-MY

Signing with a hardware token (refer to the token manufacturer’s instructions on configuring Java to use the token and for the correct providerName value):

-alias AIRCert -storetype pkcs11 -providerName tokenProviderName

Signing without embedding a timestamp:

-storetype pkcs12 -keystore cert.p12 -tsa none

Creating an unsigned AIR intermediate file with ADT

Use the -prepare command to create an unsigned AIR intermediate file. An AIR intermediate file must be signed with the ADT -sign command to produce a valid AIR installation file.

The -prepare command takes the same flags and parameters as the -package command (except for the signing options). The only difference is that the output file is not signed. The intermediate file is generated with the filename extension: airi.

To sign an AIR intermediate file, use the ADT -sign command. (See Signing an AIR intermediate file with ADT.)

ADT example

adt –prepare unsignedMyApp.airi myApp.xml myApp.swf components.swc

Signing an AIR intermediate file with ADT

To sign an AIR intermediate file with ADT, use the -sign command. The sign command only works with AIR intermediate files (extension airi). An AIR file cannot be signed a second time.

To create an AIR intermediate file, use the adt -prepare command. (See Creating an unsigned AIR intermediate file with ADT.)

Sign an AIRI file

Use the ADT -sign command with following syntax:

adt -sign SIGNING_OPTIONSairi_fileair_file

SIGNING_OPTIONS The signing options identify the private key and certificate with which to sign the AIR file. These options are described in ADT command line signing options.

airi_file The path to the unsigned AIR intermediate file to be signed.

air_file The name of the AIR file to be created.

ADT Example

adt –sign -storetype pkcs12 -keystore cert.p12 unsignedMyApp.airi myApp.air

For more information, see Digitally signing an AIR file.