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 .

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

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

ADT example

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

 
adt –prepare unsignedMyApp.airi myApp.xml myApp.html AIRAliases.js image.gif

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.