## Signing Adobe AIR® Applications

If you need to publish your Adobe Flash code for your AIR applications, an EV Code Signing Certificate is a great way to go. With an EV Code Signing Certificate, you get all the benefits of extended validation that you and your customers deserve.

Your customers get the assurance of knowing your company has gone through the rigorous vetting standards before you were issued your EV Code Signing Certificate. You get the assurance of knowing that your company has employed a hardware requirement to help keep your private key safe.

Buy an EV Code Signing Certificate Today!

Buy Now

## Configuring the Java JDK to Use the eToken

Before you can begin signing your applications with your EV Code Signing Certificate, you need to configure Java to use the PKCS#11 token.

If you are using different versions of the Java Runtime Environment (JRE) or Java Development Kit (JDK) than those listed below, you will need to modify the folder paths to match the particular version installed to your computer.

### How to Configure Java JDK to Use the eToken

Wherever you see the double asterisks (**) replace them (**) with the specific version of JRE or JDK that you are using, for example: C:\Program Files (x86)\Java\jdk1.7.0_67\bin.

1. Download the JDK from Oracle.com.

2. Open a text editor (such as Notepad) and do the following:

1. Copy and paste the following 2 lines into the text (Notepad) document:

 name=eToken library=c:\WINDOWS\system32\eTPKCS11.dll 
2. Save this file as eToken.cfg in the appropriate directory for your version of the JDK, for example:

• JDK 1.6
C:\Program Files (x86)\Java\jdk1.6.0_**\bin

• JDK 1.7
C:\Program Files (x86)\Java\jdk1.7.0_**\bin

• JDK 1.8
C:\Program Files (x86)\Java\jdk1.8.0_**\bin

Note:    If you are running a 32-bit version of Windows, the Java JDK is installed in C:\Program Files\Java\....

3. Run WordPad (Start > Accessories > WordPad), open the java.security file from your Java Runtime Environment (JRE) installation (e.g. C:\Program Files\Java\jdk1.7**\jre\lib\security), and then do the following:

1. Search the file (Ctrl + F) for the following line:

 security.provider.10=sun.security.mscapi.SunMSCAPI 
2. If the following line isn't already present in the file, add it right after the line above:

 security.provider.11=sun.security.pkcs11.SunPKCS11 ./etoken.cfg 

Note:    ./etoken.cfg is the path to the etoken.cfg file, and cannot contain a drive letter (i.e., it must be on the same drive as the JDK installation).

3. When WordPad asks if you want to save the file as a text-only document, select yes.

4. Open Windows explorer and go to the JDK installation folder (i.e. C:\Program Files\Java\jdk1.7**\).

5. Hold shift down and right-click on the bin folder and select Open command window here.

6. Run the following command to find out in which token slot your certificate is stored:

 keytool -keystore NONE -storetype PKCS11 -list -J-Djava.security.debug=sunpkcs11 

Note:    This command displays a lot of information.

7. Go to the top of the information display where the information starts, and search for a line similar to this:

 Slots with tokens:# 
• Where # is a number such as 0 or 2.

• If the slot used is "0", skip to Step 9.

8. Remove the eToken device from the USB drive for a few seconds and then plug it back since it only allows you to run one keytool command at a time.

9. Open the file etoken.cfg you created in Step 2, and change the value after slot= to match the slot from the previous keytool command then save the file.

 name=eToken library=c:\WINDOWS\system32\eTPKCS11.dll slot=0 

Note:    0 is the default slot. If you have added additional certificates to the token or re-keyed/re-issued your certificate, you may have a different number than the default.

## Sign Code through the Command-Line Utility ADT

### How to Configure the ADT Command to Use the 32-bit Version of Java

For JDKs Version 7 and Older: Before running the ADT command, make sure that it is using the 32-bit version of Java instead of the 64-bit one.

1. Go to the folder where you downloaded the Adobe Air SDK, and go to the bin subfolder.

2. Make a backup of the file adt.bat (e.g. make a copy so it says adt - copy.bat).

3. Edit adt.bat to point to the 32-bit JDK installation:

 "C:\Program Files (x86)\Java\jdk1.7.0_05\bin\java.exe" -jar "%~dp0\..\lib\adt.jar" %* 

### How to Sign Code through the Command-Line Utility ADT

Follow the steps below to use the command-line tool Air Development Tool to sign your Adobe AIR applications using your EV Code Signing Certificate.

1. Run the ADT command on a single line to sign your app:

 adt -sign -tsa http://timestamp.digicert.com -storetype PKCS11 -providerName SunPKCS11-eToken "path\to\YourApp.air" 
2. If the command runs successfully, it should ask you for your password and then have a blank line after completion and return you to the command line.

3. You have now signed your AIR file with your EV Code Signing Certificate.

## Changing Your Adobe Air EV Code Signing Certificate

There are situations where you must replace the EV Code Signing Certificate that you use to sign your applications for Adobe AIR.

• Renewing your EV Code Signing Certificate

• Moving from a standard code signing certificate to an EV Code Signing Certificate

• Moving from a self-signed certificate to a DigiCert EV Code Signing Certificate

• Choosing DigiCert as your new certificate provider

CAUTION:

• Adobe AIR pre-1.5.3

According to Adobe, you must change certificates and apply the migration signature to your updated AIR file before the original certificate expires. If you don't, users must uninstall their current version of the application before installing the updated version.

• Adobe AIR version 1.5.3 or later

For later versions, Adobe allows you to use an expired code-signing certificate (up to 365 days after it expires) to apply a migration signature. You cannot use the expired certificate to sign your updated application.

• See Adobe Documentation: Digitally signing an AIR file

When changing certificates, you need to help Adobe AIR recognize the AIR file as an update. You can do this by applying a migration signature to the updated AIR file.

To apply a migration signature, you must sign your updated AIR file with both the new certificate and the original certificate (migration signature). This migration signature helps Adobe AIR establish the connection between the old certificate and the new one.

After a user installs your updated AIR file with a migration signature, your new code signing certificate is then recognized as the primary certificate. The next time you update your Adobe AIR application, you can just sign it with your new certificate.

### How to Change Certificates

1. Update your application.

2. Package the AIR file, and then use your new EV Code Signing Certificate to sign it.

3. Finally, use your original certificate to sign the AIR file again.

Use the command below:

 ADT -migrate 
4. You have applied a migration signature to your updated Adobe AIR file.

## Additional Helpful Keytool and ADT Command Options

Make sure that your eToken is plugged in before running any of the commands below.

### List all Certificates in Current User Account

Run the following command to list all of the certificates in the current user account:

Note:   This includes personal certificates or standard (non-EV) Code Signing Certificates.

 keytool -list -storetype Windows-MY 

### List all Certificates by Their Alias

To list certificates by their alias, run the following command:

 keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg "c:\eToken.cfg" 

### Specify Which Certificate to Use

With the ADT -alias command, you can specify a particular certificate to use with -alias CN=YourCompany, Inc. as shown below:

 adt -alias "CN=YourCompany, Inc." -storetype PKCS11 -providerName sun.security.pkcs11.SunPKCS11 -tsa http://timestamp.digicert.com "path\to\AIRappToSign" 

## Troubleshooting

### Error Messages

• "requested provider is not available"

This error message could mean a couple different things:

(1) You might be trying to use the ADT command using the 64-bit java installation, or (2) you don't have security.lib file configured correctly pointing to the etoken.cfg file.

• "Could not generate timestamp: handshake alert: unrecognized_name"

This generally means the "-tsa" directive was not included in the signing command.

• "Unable to build a valid certificate chain for the signer"

This error means you don't have the chain certificate (i.e. intermediate and root certificates) installed onto your device. You need to reinitialize your device and re-key your certificate. See Re-keying/Reissuing your EV Code Signing Certificate.

• "keytool error: java.security.KeyStoreException: PKCS11 not found"

This error typically comes up when trying to run the keytool command from the 64 bit Java installation (C:\Program Files\Java\jdk**\bin\) instead of the 32 bit one (C:\Program Files (x86)\Java\jdk**\bin\).

### 64-bit Version of Windows Issues with Running ADT Command

If you are using a 64-bit version of Windows, you may be having issues when running the ADT command. Because PKCS11 access is only supported in the 32-bit version of the JRE, you may need to make sure the path listed for the JRE is pointing to the 32-bit version of Java instead of the 64-bit version.

#### How to Point JRE to the 32-bit Version of Java

1. Open Advanced System Settings.

Click Start > Control Panel > System > Advanced System Settings.

2. In the Advanced System Settings window, on the Advanced tab, click Environment Variables.

3. Add the path to your installed 32-bit version of the JDK to the end of the path Variable Value as shown below.

 {existing path variables};C:\Program Files\Java\jdk1.6.0_**\bin 
4. After editing that path, paste it into the Variable Value and click Ok.