Packaging an AIR installation file using the AIR Developer Tool (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 the Adobe® AIR® Extension for Dreamweaver® to create your application, you can also use the Create AIR File command on the AIR Application and Installer Settings dialog to build the AIR package. See Using the AIR Extension for Dreamweaver.)

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. See Setting up HTML development tools for information on configuring your system to run the ADT tool.

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 package 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 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. If the original certificate has been renewed or has expired within the last 180 days, or if you want to change to a new certificate, you can apply a migration signature. A migration signature involves signing the application AIR file with both the new and the old certificate. Use the -migrate command to apply the migration signature as described in Signing an AIR file to change the application certificate.

Important: There is a strict 180 day grace period for applying a migration signature after the original certificate expires. Without a migration signature, existing users must uninstall their existing application before installing your new version. The grace period only applies to applications that specify AIR version 1.5.3, or above, in the application descriptor namespace. There is no grace period when targeting earlier versions of the AIR runtime.

Prior to AIR 1.1, migration signatures were not supported. You must package an application with an SDK of version 1.1 or later to apply a migration signature.

Publisher IDs

As of AIR 1.5.3, publisher IDs are deprecated. New applications (originally published with AIR 1.5.3 or later) do not need and should not specify a publisher ID.

When updating applications published with earlier versions of AIR, you must specify the original publisher ID in the application descriptor file. Otherwise, the installed version of your application and the update version are treated as different applications. If you use a different ID or omit the publisherID tag, a user must uninstall the earlier version before installing the new version.

To determine the original publisher ID, find the publisherid file in the META-INF/AIR subdirectory where the original application is installed. The string within this file is the publisher ID. Your application descriptor must specify the AIR 1.5.3 runtime (or later) in the namespace declaration of the application descriptor file in order to specify the publisher ID manually.

For applications published prior to AIR 1.5.3 — or that are published with the AIR 1.5.3 SDK, while specifying an earlier version of AIR in the application descriptor namespace — a publisher ID is computed based on the signing certificate. This ID is used, along with the application ID, to determine the identity of an application. The publisher ID, when present, is used for the following purposes:

  • Verifying that an AIR file is an update rather than a new application to install

  • As part of the encryption key for the encrypted local store

  • As part of the path for the application storage directory

  • As part of the connection string for local connections

  • As part of the identity string used to invoke an application with the AIR in-browser API

  • As part of the OSID (used when creating custom install/uninstall programs)

Before AIR 1.5.3, the publisher ID of an application could change if you signed an application update with migration signature using a new or renewed certificate. When a publisher ID changes, the behavior of any AIR features relying on the ID also changes. For example, data in the existing encrypted local store can no longer be accessed and any Flash or AIR instances that create a local connection to the application must use the new ID in the connection string.

In AIR 1.5.3, or later, the publisher ID is not based on the signing certificate and is only assigned if the publisherID tag is included in the application descriptor. An application cannot be updated if the publisher ID specified for the update AIR package does not match its current publisher ID.

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. (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.html AIRAliases.js image.gif

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.html AIRAliases.js images

Package an HTML-based application and all files in the HTML, scripts, and images subdirectories:

adt –package -storetype pkcs12 -keystore cert.p12 myApp.air myApp.xml index.html AIRALiases.js html scripts images

Package the application.xml file and main HTML file located in a working directory (src):

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

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.html 
    /artwork 
        /myApp 
            /images 
                image-1.png 
                ... 
                image-n.png 
    /libraries 
        /release 
            /libs 
                lib-1.js 
                ... 
                lib-n.js 
                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 release/bin myApp.html  
    –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
/myAppRoot 
    /META-INF 
        /AIR 
            application.xml 
            hash 
    myApp.html 
    mimetype 
    /images 
        image-1.png 
        ... 
        image-n.png 
    /libs 
        lib-1.js 
        ... 
        lib-n.js 
        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 
java –jar {AIRSDK}/lib/ADT.jar –package -storetype pkcs12 -keystore cert.p12 myApp.air myApp.xml myApp.html AIRAliases.js

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 
java com.adobe.air.ADT –package -storetype pkcs12 -keystore cert.p12 myApp.air myApp.xml myApp.html AIRAliases.js

ADT error messages

The following tables list the possible errors that can be reported by the ADT program and the probable causes:

Application descriptor validation errors

Error code

Description

Notes

100

Application descriptor cannot be parsed

Check the application descriptor file for XML syntax errors such as unclosed tags.

101

Namespace is missing

Add the missing namespace.

102

Invalid namespace

Check the namespace spelling.

103

Unexpected element or attribute

Remove offending elements and attributes. Custom values are not allowed in the descriptor file.

Check the spelling of element and attribute names.

Make sure that elements are placed within the correct parent element and that attributes are used with the correct elements.

104

Missing element or attribute

Add the required element or attribute.

105

Element or attribute contains an invalid value

Correct the offending value.

106

Illegal window attribute combination

Some window settings, such as transparency = true and systemChrome = standard cannot be used together. Change one of the incompatible settings.

107

Window minimum size is larger than the window maximum size

Change either the minimum or the maximum size setting.

See Setting AIR application properties for a information about the namespaces, elements, attributes, and their valid values.

Application icon errors

Error code

Description

Notes

200

Icon file cannot be opened

Check that the file exists at the specified path.

Use another application to ensure that the file can be opened.

201

Icon is the wrong size

Icon size (in pixels) must match the XML tag. For example, given the application descriptor element:

<image32x32>icon.png</image32x32>

The image in icon.png must be exactly 32x32 pixels.

202

Icon file contains an unsupported image format

Only the PNG format is supported. Convert images in other formats before packaging your application.

Application file errors

Error code

Description

Notes

300

Missing file, or file cannot be opened

A file specified on the command line cannot be found, or cannot be opened.

301

Application descriptor file missing or cannot be opened

The application descriptor file cannot be found at the specified path or cannot opened.

302

Root content file missing from package

The SWF or HTML file referenced in the <content> element of the application descriptor must be added to the package by including it in the files listed on the ADT command line.

303

Icon file missing from package

The icon files specified in the application descriptor must be added to the package by including them among the files listed on the ADT command line. Icon files are not added automatically.

304

Initial window content is invalid

The file referenced in the <content> element of the application descriptor is not recognized as a valid HTML or SWF file.

305

Initial window content SWF version exceeds namespace version

The SWF version of the file referenced in the <content> element of the application descriptor is not supported by the version of AIR specified in the descriptor namespace. For example, attempting to package a SWF10 (Flash Player 10) file as the initial content of an AIR 1.1 application will generate this error.

Exit codes for other errors

Exit code

Description

Notes

2

Usage error

Check the command line arguments for errors

5

Unknown error

This error indicates a situation that cannot be explained by common error conditions. Possible root causes include incompatibility between ADT and the Java Runtime Environment, corrupt ADT or JRE installations, and programming errors within ADT.

6

Could not write to output directory

Make sure that the specified (or implied) output directory is accessible and that the containing drive is has sufficient disk space.

7

Could not access certificate

Make sure that the path to the keystore is specified correctly.

Check that the certificate within the keystore can be accessed. The Java 1.6 Keytool utility can be used to help troubleshoot certificate access issues.

8

Invalid certificate

The certificate file is malformed, modified, expired, or revoked.

9

Could not sign AIR file

Verify the signing options passed to ADT.

10

Could not create time stamp

ADT could not establish a connection to the timestamp server. If you connect to the internet through a proxy server, you may need to configure the JRE proxy settings.

11

Certificate creation error

Verify the command line arguments used for creating signatures.

12

Invalid input

Verify file paths and other arguments passed to ADT on the command line.

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 
 
adt –prepare unsignedMyApp.airi myApp.xml myApp.html AIRAliases.js image.gif

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.