Signing AIR applicationsDigitally signing an AIR fileDigitally signing your AIR installation files with a certificate issued by a recognized certification authority (CA) provides significant assurance to your users that the application they are installing has not been accidentally or maliciously altered and identifies you as the signer (publisher). AIR displays the publisher name during installation when the AIR application has been signed with a certificate that is trusted, or which chains to a certificate that is trusted on the installation computer: ![]() Installation confirmation dialog for application signed by
a trusted certificate If you sign an application with a self-signed certificate (or a certificate that does not chain to a trusted certificate), the user must accept a greater security risk by installing your application. The installation dialogs reflect this additional risk: ![]() Installation confirmation dialog for application signed by
a self-signed certificate Important: A malicious entity could forge an AIR file
with your identity if it somehow obtains your signing keystore file
or discovers your private key.
Code-signing certificatesThe security assurances, limitations, and legal obligations involving the use of code-signing certificates are outlined in the Certificate Practice Statements (CPS) and subscriber agreements published by the issuing certification authority. For more information about the agreements for the certification authorities that currently issue AIR code signing certificates, refer to: ChosenSecurity (http://www.chosensecurity.com/products/tc_publisher_id_adobe_air.htm) ChosenSecurity CPS (http://www.chosensecurity.com/resource_center/repository.htm) GlobalSign (http://www.globalsign.com/developer/code-signing-certificate/index.htm) GlobalSign CPS (http://www.globalsign.com/repository/index.htm) Thawte CPS (http://www.thawte.com/cps/index.html) VeriSign CPS (http://www.verisign.com/repository/CPS/) VeriSign Subscriber's Agreement (https://www.verisign.com/repository/subscriber/SUBAGR.html) About AIR code signingWhen an AIR file is signed, a digital signature is included in the installation file. The signature includes a digest of the package, which is used to verify that the AIR file has not been altered since it was signed, and it includes information about the signing certificate, which is used to verify the publisher identity. AIR uses the public key infrastructure (PKI) supported through the operating system’s certificate store to establish whether a certificate can be trusted. The computer on which an AIR application is installed must either directly trust the certificate used to sign the AIR application, or it must trust a chain of certificates linking the certificate to a trusted certification authority in order for the publisher information to be verified. If an AIR file is signed with a certificate that does not chain to one of the trusted root certificates (and normally this includes all self-signed certificates), then the publisher information cannot be verified. While AIR can determine that the AIR package has not been altered since it was signed, there is no way to know who actually created and signed the file. Note: A user can choose to trust a self-signed certificate
and then any AIR applications signed with the certificate displays
the value of the common name field in the certificate as the publisher
name. AIR does not provide any means for a user to designate a certificate
as trusted. The certificate (not including the private key) must be
provided to the user separately and the user must use one of the
mechanisms provided by the operating system or an appropriate tool
to import the certificate into the proper location in system certificate
store.
About AIR publisher identifiersImportant: As of AIR 1.5.3 the publisher ID
is deprecated and no longer computed based on the code signing certificate.
New applications do not need and should not use a publisher ID.
When updating existing applications, you must specify the original
publisher ID in the application descriptor file.
Prior to AIR 1.5.3, the AIR application installer generated a publisher ID during the installation of an AIR file. This was an identifier that is unique to the certificate used to sign the AIR file. If you reused the same certificate for multiple AIR applications, they received the same publisher ID. Signing an application update with a different certificate and sometimes even a renewed instance of the original certificate changed the publisher ID. In AIR 1.5.3 and later, a publisher ID is not assigned by AIR. An application published with AIR 1.5.3 can specify a publisher ID string in the application descriptor. You should only specify a publisher ID when publishing updates for applications originally published for versions of AIR prior to 1.5.3. If you do not specifying the original ID in the application descriptor then the new AIR package is not treated as an update of the existing application. 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. The publisher ID, when present, is used for the following purposes:
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. The publisher ID for an installed application cannot change in AIR 1.5.3, or later. If you use a different publisher ID when publishing an AIR package, the installer treats the new package as a different application rather than as an update. About Certificate formatsThe AIR signing tools accept any keystores accessible through the Java Cryptography Architecture (JCA). This includes file-based keystores such as PKCS12-format files (which typically use a .pfx or .p12 file extension), Java .keystore files, PKCS11 hardware keystores, and the system keystores. The keystore formats that ADT can access depend on the version and configuration of the Java runtime used to run ADT. Accessing some types of keystore, such as PKCS11 hardware tokens, may require the installation and configuration of additional software drivers and JCA plug-ins. To sign AIR files, you can use most existing code signing certificates or you can obtain a new one issued expressly for signing AIR applications. For example, any of the following types of certificate from VeriSign, Thawte, GlobalSign, or ChosenSecurity can be used:
Note: The certificate must be created
for code signing. You cannot use an SSL or other type of certificate
to sign AIR files.
Time stampsWhen you sign an AIR file, the packaging tool queries the server of a timestamp authority to obtain an independently verifiable date and time of signing. The time stamp obtained is embedded in the AIR file. As long as the signing certificate is valid at the time of signing, the AIR file can be installed, even after the certificate has expired. On the other hand, if no time stamp is obtained, the AIR file ceases to be installable when the certificate expires or is revoked. By default, the AIR packaging tools obtain a time stamp. However, to allow applications to be packaged when the time-stamp service is unavailable, you can turn time stamping off. Adobe recommends that all publicly distributed AIR files include a time stamp. The default time-stamp authority used by the AIR packaging tools is Geotrust. Obtaining a certificateTo obtain a certificate, you would normally visit the certification authority web site and complete the company’s procurement process. The tools used to produce the keystore file needed by the AIR tools depend on the type of certificate purchased, how the certificate is stored on the receiving computer, and, in some cases, the browser used to obtain the certificate. For example, to obtain and export an Adobe Developer certificate certificate from Thawte you must use Mozilla Firefox. The certificate can then be exported as a .p12 or .pfx file directly from the Firefox user interface. Note: Java versions 1.5 and above do not accept high-ASCII characters
in passwords used to protect PKCS12 certificate files. Java is used
by the AIR development tools to create the signed AIR packages.
When you export the certificate as a .p12 or .pfx file, use only
regular ASCII characters in the password.
You can generate a self-signed certificate using the Air Development Tool (ADT) used to package AIR installation files. Some third-party tools can also be used. For instructions on how to generate a self-signed certificate, as well as instructions on signing an AIR file, see AIR Developer Tool (ADT). You can also export and sign AIR files using Flash Builder, Dreamweaver, and the AIR update for Flash. The following example describes how to obtain an AIR Developer Certificate from the Thawte Certification Authority and prepare it for use with ADT. Example: Getting an AIR Developer Certificate from ThawteNote: This example illustrates only one of the many ways to
obtain and prepare a code signing certificate for use. Each certification
authority has its own policies and procedures.
To purchase an AIR Developer Certificate, the Thawte web site requires you to use the Mozilla Firefox browser. The private key for the certificate is stored within the browser’s keystore. Ensure that the Firefox keystore is secured with a master password and that the computer itself is physically secure. (You can export and remove the certificate and private key from the browser keystore once the procurement process is complete.) As part of the certificate enrollment process a private/public key pair is generated. The private key is automatically stored within the Firefox keystore. You must use the same computer and browser to both request and retrieve the certificate from Thawte’s web site.
Important: The private key and certificate are still
stored within the Firefox keystore. While this permits you to export
an additional copy of the certificate file, it also provides another
point of access that must be protected to maintain the security
of your certificate and private key.
Changing certificatesIn some circumstances, you must change the certificate you use to sign updates for your AIR application. Such circumstances include:
For AIR to recognize an AIR file as an update, you must either sign both the original and update AIR files with the same certificate or apply a certificate migration signature to the update. A migration signature is a second signature applied to the update AIR package using the original certificate. The migration signature uses the original certificate to establish that the signer is the original publisher of the application. After an AIR file with a migration signature is installed, the new certificate becomes the primary certificate. Subsequent updates do not require a migration signature. However, you should apply migration signatures for as long as possible to accommodate users who skip updates. Important: The certificate must
be changed before the original certificate expires. If you do not
create an update signed with a migration signature before your certificate expires,
users will have to uninstall their existing version of your application
before installing a new version. As of AIR 1.5.3, an expired certificate
can be used to apply a migration signature within a 180 day grace
period after the certificate has expired. (You cannot use the expired
certificate to apply the main application signature.)
To change certificates:
An AIR file with a migration signature is, in other respects, a normal AIR file. If the application is installed on a system without the original version, AIR installs the new version in the usual manner. Note: Prior to AIR 1.5.3, signing an AIR application with a renewed
certificate did not always require a migration signature. Starting
with AIR 1.5.3, a migration signature is always required for renewed
certificates.
The procedure for applying a migration signature is described in Signing an AIR file to change the application certificate. Application identity changesPrior to AIR 1.5.3, the identity of an AIR application changed when an update signed with a migration signature was installed. Changing the identity of an application has the several repercussions, including:
When publishing an update with AIR 1.5.3, the application identity cannot change. The original application and publisher IDs must be specified in the application descriptor of the update AIR file. Otherwise, the new package is not recognized as an update. Note: When publishing
a new AIR application with AIR 1.5.3 or later, you should not specify
a publisher ID.
Expired certificatesAs of AIR 1.5.3, a certificate that has expired within the last 180 days can still be used to apply a migration signature to an application update. To take advantage of this grace period, and the update application descriptor must specify 1.5.3 in the namespace attribute. After the grace period, the certificate can no longer be used. Users updating to a new version of your application will have to uninstall their existing version. Note that there is no grace period in AIR versions before 1.5.3. TerminologyThis section provides a glossary of some of the key terminology you should understand when making decisions about how to sign your application for public distribution.
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 code 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 -sign command exampleadt –sign -storetype pkcs12 -keystore cert.p12 unsignedMyApp.airi myApp.air For more information, see Digitally signing an AIR file. Signing an AIR file to change the application certificateTo publish an update for an existing AIR application while using a new or renewed signing certificate, use the ADT -migrate command to apply a certificate migration signature. A migration signature is a second signature applied to an AIR file using the original certificate. The migration signature validates that an application update was produced by the owners of the original certificate. In order to apply a migration signature, the original certificate must still be valid or have expired within the last 180 days. Once the certificate has expired and the 180 day grace period has elapsed, a migration signature cannot be applied. Users of your application will have to uninstall the existing version before they can install the updated version. The migration signature is time stamped, by default, so AIR updates signed with a migration signature will remain valid even after the certificate expires. Note: The 180 day grace period only applies to applications specifying
AIR version 1.5.3, or higher, in the application descriptor namespace.
To migrate the application to use a new or renewed certificate:
An AIR file signed with the -migrate command can be used both to install a new version of the application and to update any previous versions, including those signed with the old certificate. Note: When updating an application published for a version of AIR
earlier than1.5.3, you must specify the original publisher ID in
the application descriptor. Otherwise, users of your application
must uninstall the earlier version before installing the update.
Migrate an AIR application to use a new certificate Use the ADT -migrate command with following
syntax:adt -migrate SIGNING_OPTIONS air_file_in air_file_out SIGNING_OPTIONS The signing options identify the private key and certificate with which to sign the AIR file. These options must identify the original signing certificate and are described in ADT code signing options. air_file_in The AIR file for the update, signed with the new certificate. air_file_out The AIR file to create. Note: The file names used for
the input and output AIR files must be different.
ADT Exampleadt –migrate -storetype pkcs12 -keystore cert.p12 myAppIn.air myApp.air For more information, see Digitally signing an AIR file. Note: The -migrate command
was added to ADT in the AIR 1.1 release.
Creating a self-signed certificate with ADTYou can use self-signed certificates to produce a valid AIR installation file. However, self-signed certificates only provide limited security assurances to your users. The authenticity of self-signed certificates cannot be verified. When a self-signed AIR file is installed, the publisher information is displayed to the user as Unknown. A certificate generated by ADT is valid for five years. If you create an update for an AIR application that was signed with a self-generated certificate, you must use the same certificate to sign both the original and update AIR files. The certificates that ADT produces are always unique, even if the same parameters are used. Thus, if you want to self-sign updates with an ADT-generated certificate, preserve the original certificate in a safe location. In addition, you will be unable to produce an updated AIR file after the original ADT-generated certificate expires. (You can publish new applications with a different certificate, but not new versions of the same application.) Important: Because of the limitations of self-signed
certificates, Adobe strongly recommends using a commercial certificate
issued by a reputable certification authority for signing publicly
released AIR applications.
The certificate and associated private key generated by ADT are stored in a PKCS12-type keystore file. The password specified is set on the key itself, not the keystore. Certificate generation examplesadt -certificate -cn SelfSign -ou QE -o "Example, Co" -c US 2048-RSA newcert.p12 39#wnetx3tl adt -certificate -cn ADigitalID 1024-RSA SigningCert.p12 39#wnetx3tl To use these certificates to sign AIR files, you use the following signing options with the ADT -package or -prepare commands: -storetype pkcs12 -keystore newcert.p12 -keypass 39#wnetx3tl -storetype pkcs12 -keystore SigningCert.p12 -keypass 39#wnetx3tl Note: Java
versions 1.5 and above do not accept high-ASCII characters in passwords used
to protect PKCS12 certificate files. Use only regular ASCII characters
in the password.
|
|