|
|
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 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. Packaging an AIR installation fileEvery 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 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_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 ExamplesPackage 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 error messagesThe following tables list the possible errors that can be reported by the ADT program and the probable causes: Application descriptor validation errors
See Setting AIR application properties for a information about the namespaces, elements, attributes, and their valid values. Application icon errors
Application file errors
Exit codes for other errors
ADT command line signing optionsADT 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.
-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 examplesSigning 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 ADTUse 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.) Signing an AIR intermediate file with ADTTo 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 Exampleadt –sign -storetype pkcs12 -keystore cert.p12 unsignedMyApp.airi myApp.air For more information, see Digitally signing an AIR file. 
|
