| Sun ONE Integration Server B2B 3.6.2 Update 1, ECXpert Support for AS2 Messaging |
Chapter 3
Creating Certificates for AS2 MessagingThis chapter explains how to use the keytool utility to acquire certificates from a third party certificate authority (CA) such as Verisign or Thawte. You also use keytool to import, export, and delete certificates. keytool is a security tool available with the Java™ 2 Software Development Kit (Java 2 SDK), Standard Edition that is used with this release.
This chapter covers the following topics:
- "Introduction to the keytool Utility" describes relevant options and output for the keytool utility.
- "Example: Managing Keystores for AS2" provides a detailed example of the steps necessary to enable secure messaging between two AS2 trading partners.
Introduction to the keytool UtilityThis section describes relevant options and output that you need to be familiar with when using keytool to manage a keystore for secure AS2 communication. For more detailed information about the keytool utility, see the docs directory of your Java 2 SDK installation. You may have to download the Java 2 SDK documentation separately. This documentation is also available online at the following URL:
http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/keytool.html
Creating a Keystore with keytool
Use the -genkey option with keytool to generate a keystore (private key). Typically, a keystore file has a .jks extension.
When generating the keystore you specify an alias and a name.
The alias you specify must match the AS2 party identifier (i.e. address) for the member that will use the key or certificate.
The name is an X.500 distinguished name and has the following format:
CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode
The CN you specify should be a fully qualified domain name of the host you are using for an ECXpert secure endpoint (for example, host.sun.com). The CN can also be an IP address. Check with the CA you are using to determine their requirements for CN names.
Caution
Make sure your keystore file, which contains your private key, is kept within a secure location on your system.
Issuing Certificate Requests
To issue certificate requests, which you send to the appropriate Certification Authority, use the -certreq option with keytool to generate a Certificate Signing Request (CSR) file that you send to a CA. The CA authenticates the certificate requestor and replies with a public certificate and one or more certificates that are trusted.
Typically, a certificate request file has a .csr extension. The CA returns certificate files with a .cer extension. One of the returned certificates is the public key that matches the private key created with the keytool -genkey command. The other certificate files are trusted certificates that verify your public key.
Importing Trusted Certificates
Import trusted certificates if the certificates obtained from the CA have not previously been imported into the truststore supplied with your Java 2 SDK (cacerts file).
Use the -import option to import the trusted certificates returned by the CA into the cacerts file.
Designating Public Keys for Other Parties as Trusted
Use the -trustcacerts option with the -import option to provide a chain of trust to your keystore file. You must specify your keystore alias and keystore password when doing this step.
Verifying that the Key Pair Match
Use the -printcert option to keytool to print information in your public certificate. Then use the -list option to print information in your private key. You can then compare the certificate fingerprints in the listings, as shown in the example of Table 3-1.
Example: Managing Keystores for AS2This section provides a detailed example of the steps necessary to manage secure messaging between two AS2 agents. This involves creating key pairs and importing and exporting certificates. You might also need to delete certificates, which you can also do using the keytool utility.
The steps illustrated in this section are as follows:
- Create new private/public key pair for partyA, Step 1.
- Export a self-signed X.509 certificate from partyA's keystore, Step 2.
- Create a private/public key pair for partyB, Step 3.
- Export a self-signed X.509 certificate from partyB's keystore, Step 4.
- Import partyB’s certificate into partyA's keystore, Step 1.
- Import partyA's certificate into partyB's keystore, Step 2.
- Modify the AS2 configurations to use the new keystores, "Modifying the AS2 Configurations for Keystore Use".
- Stop and restart the AS2 Servers, Step 3.
The example in this section uses the two trading partners created in Chapter 2, "Example: End-to-End Test for AS2 Messaging".
Preconditions
Ensure that the following preconditions are met before proceeding:
- The JDK/JRE version is 1.4 or later. You can execute the java -version command to check the version.
- The PATH environment variable points to your JDK/JRE 1.4 installation. If it does not, edit the appropriate configuration file or use the setenv PATH command on Solaris machines. On Windows, set the environment variable using the Advanced tab of the Control Panel’s System Tool.
- You have created a directory in which to store the new certificates and keys. Execute the procedures in this section so that the certificates and keys are created within this directory.
Creating Key Pairs and Exporting Certificates
The following steps create and export key pairs for each of two trading partners taking part in secure AS2 communication.
- Create a new private/public key pair for partyA.
This step assumes you do not have an existing keystore and creates a new one. Typically, you create additional key pairs within an existing keystore. The keytool utility automatically creates a keystore if one does not exist. Execute keytool from the partyA host machine.
After you issue the keytool command, the utility prompts for values. The combination of all the values should be unique across all keys and certificates in the keystore. The easiest way to ensure that they are unique is to specify a unique value set for first and last name parameter, which is used for the CN attribute in the X.509 certificate. Also make sure that the value supplied for the alias parameter is the same as the as2 identifier used for the ECXpert member.
The example session listed in Table 3-2 illustrates the use of the keytool command to create a 1024 bit key for RSA encryption. In this example, the AS2 identifier (PartyA) is used as the alias—this is the value specified as the ECXpert trading address in Figure 2-2, Trading Address Screen.
Table 3-2 Example Listing for Key Generation for partyA
ecxadmin@host% keytool -genkey -v -alias "PartyA" -keyalg RSA -keysize 1024 -keystore PartyA.jks
Enter keystore password: password
What is your first and last name?
[Unknown]: PartyA Message Security
What is the name of your organizational unit?
[Unknown]: PartyA
What is the name of your organization?
[Unknown]: PartyA
What is the name of your City or Locality?
[Unknown]: Phoenix
What is the name of your State or Province?
[Unknown]: AZ
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=PartyA Message Security, OU=PartyA, O=PartyA, L=Phoenix, ST=AZ, C=US correct?
[no]: y
Generating 1,024 bit RSA key pair and self-signed certificate (MD5WithRSA) for: CN=PartyA Message Security, OU=PartyA, O=PartyA, L=Phoenix, ST=AZ, C=US
Enter key password for <PartyA>
(RETURN if same as keystore password):
[Saving PartyA.jks]
- Export a self-signed X.509 certificate from partyA's keystore.
Use the keytool command to export a self-signed certificate based on the public/private key pair generated in Step 1. The parameters used in the keytool listing example of Table 3-4 are defined as follows in Table 3-3.
Table 3-3 Flag descriptions for the keytool command
Flag
Description
alias
The alias name for the certificate you want to export.
rfc
Output the certificate with base64 encoding.
file
The name of the file you want to output to (it is useful to use a .cer suffix for viewing the certificate in a Windows environment).
keystore
The keystore you are exporting from.
Table 3-4 Example Listing for Exporting a Certificate from partyA’s Keystore
ecxadmin@host% keytool -export -v -rfc -alias "PartyA" -file PartyA.cer -keystore PartyA.jks
Enter keystore password: password
Certificate stored in file <PartyA.cer>
After keytool exits, you can send the exported file (PartyA.cer in this example) to the trading partner (partyB). partyB uses the certificate to verify partyA’s signature and to encrypt messages that it sends back to partyA.
- Create a private/public key pair for partyB.
Repeat Step 1 on the partyB host machine, substituting the appropriate parameters (PartyB for PartyA, and so on). Be sure to use the correct AS2 party ID for the key alias.
If you are creating the keystores on the same machine (and not each on a different machine), use two distinct names for the keystores. Although this example does use two distinct machines, it explicitly illustrates the use of two names for the keystores, PartyA.jks and PartyB.jks.
The example session in Table 3-5 illustrates key generation for partyB. Make sure that you use the trading partner's AS2 identifier as the alias name and respond with y when keytool prompts Trust the certificate?.
Table 3-5 Example Listing for Key Generation for partyB
ecxadmin@kite% keytool -genkey -v -alias "PartyB" -keyalg RSA -keysize
1024 -keystore PartyB.jks
Enter keystore password: password
What is your first and last name?
[Unknown]: PartyB Message Security
What is the name of your organizational unit?
[Unknown]: PartyB
What is the name of your organization?
[Unknown]: PartyB
What is the name of your City or Locality?
[Unknown]: Phoenix
What is the name of your State or Province?
[Unknown]: AZ
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=PartyB Message Security, OU=PartyA, O=PartyA L=Phoenix, ST=AZ, C=US correct?
[no]: y
Generating 1,024 bit RSA key pair and self-signed certificate (MD5WithRSA) for: CN=PartyB Message Security, OU=PartyB, O=PartyB, L=Phoenix,
ST=AZ, C=US
Enter key password for <PartyB>
(RETURN if same as keystore password):
[Saving PartyB.jks]
- Export a self-signed X.509 certificate from partyB's keystore.
This step is similar to Step 2. The difference is that you substitute values for PartyB.
Importing Certificates
- Import partyB’s certificate into partyA’s keystore.
This step imports partyB's certificate (PartyB.cer) into the partyA keystore. Execute the keytool -import command from the partyA host machine. You must have access to the trading partner's X.509 certificate and be sure to use the trading partner’s AS2 identifier as the alias name. Table 3-7 shows how to use keytool to import the certificate.
Table 3-7 Listing for Importing partyB’s Certificate into partyA’s Keystore
ecxadmin@host% keytool -import -v -alias "PartyB" -file PartyB.cer -keystore PartyB.jks
Enter keystore password: password
Owner: CN=PartyB Message Security, OU=PartyB, O=PartyB, L=Phoenix, ST=AZ, C=uS
Issuer: CN=PartyB Message Security, OU=PartyB, O=PartyB, L=Phoenix, ST=AZ, C=US
Serial number: 3ee6b6f5 Valid from: Tue Jun 10 21:58:29 PDT 2003 until: Mon Sep 08 21:58:29 PDT 2003
Certificate fingerprints:
MD5: AD:40:07:9A:8B:A4:7F:D7:95:BB:73:00:5A:A4:2B:9A
SHA1: 66:3E:88:14:DE:1E:A9:9B:AF:80:29:93:45:
A2:71:5B:1C:29:15:D8
Trust this certificate? [no]: y
Certificate was added to keystore
[Saving PartyB.jks]
- Import partyA's certificate into partyB's keystore.
This step is similar to Step 1. The difference is that you substitute values for PartyB and execute the commands from the partyB host.
Make sure that you use the trading partner's AS2 identifier as the alias name and respond with y when keytool prompts Trust the certificate?.
Table 3-8 Listing for Importing partyA’s Certificate into partyB’s Keystore
ecxadmin@kite% keytool -import -v -alias "PartyA" -file PartyA.cer -keystore as2.jks
Enter keystore password: password
Owner: CN=PartyA Message Security, OU=PartyA, O=PartyA, L=Phoenix, ST=AZ, C=US
Issuer: CN=PartyB Message Security, OU=PartyA, O=PartyA, L=Phoenix, ST=AZ, C=US
Serial number: 3ee6b6f5
Valid from: Tue Jun 10 21:58:29 PDT 2003 until: Mon Sep 08 21:58:29 PDT 2003
Certificate fingerprints:
MD5: AD:40:07:9A:8B:A4:7F:D7:95:BB:73:00:5A:A4:2B:9A
SHA1: 66:3E:88:14:DE:1E:A9:9B:AF:80:29:93:45:
A2:71:5B:1C:29:15:D8
Trust this certificate? [no]: y
Certificate was added to keystore
[Saving as2.jks]
Modifying the AS2 Configurations for Keystore Use
You must modify the ecx.ini file for each AS2 installation so that the AS2 server recognizes the new keystore. This requires adding the following information:
For security purposes, the keystore password must be encrypted within the ecx.ini file. The following steps describe the process.
- Run the as2passwd utility in $BDGHOME/http_as2/bin to encrypt the keystore password as shown in the following example. Copy the resulting encrypted text into the ecx.ini file in the next step.
Table 3-9 Example Listing for as2passwd
ecxadmin@host% as2passwd
Text to encrypt -> password
Encrypted Text -> MbNRPeMoThN4TUTCoFoEmZoCNXUFm5pq
- Use a text editor to update the keystore_file and keystore_pass fields under the server section of the ecx.ini file on each machine as follows:
Table 3-10 Field Values for ecx.ini Security Fields
ecx.ini Field
Value
keystore_file
The fully qualified path to the keystore.
keystore_pass
The encrypted password for the keystore.
See Appendix A, "ECXpert’s Configuration File (ecx.ini)" for information about customizing the ecx.ini file for AS2.
The values for these fields for the example are as follows:
keystore_file = /export/home/actraadm/as2/PartyA.jks
keystore_pass = MbNRPeMoThN4TUTCoFoEmZoCNXUFm5pq
- Stop and start the AS2 server instance on each host for which you modified the ecx.ini file. See "Starting and Stopping the Servers" for detailed instructions on server startup and shutdown.
