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 Flex Builder to create your application, you can also use the Flex Builder Export wizard to build the AIR file package. See Developing AIR applications with Flex Builder.)

ADT is a Java program that you can run from the command line or a build tool such as Ant. The SDK includes command-line scripts that execute the Java program for you. For information on configuring your system to run the ADT tool, see Setting up the Flex 3 SDK.

Contents

• 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

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 application assets to be installed with the application 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 certificate authority, such as VeriSign or Thawte, or a self-signed certificate. A certificate issued by a trusted certificate 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 (which 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 as long as the certificate was valid at the time of signing. If ADT cannot connect to the time stamp server, then packaging is aborted. 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, you must sign the package with the same certificate used to sign 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 renew a certificate from a certificate authority as long as you do not change any of the identifying information.

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_OPTIONS air_file app_xml [file_or_dir | -C dir file_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. The signing options are fully described in ADT command line signing options.

air_file The name of the AIR file to be 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.

-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 to be 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.

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 .

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

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

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.

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.

-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 will be 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 time stamp 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 time stamp verifies that the certificate was valid at the time of signing.

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

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 time stamp:

-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 file 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_OPTIONS airi_file air_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.