Managing Resource Files
This chapter describes how to work with resource files in a policy used by the ACE XML Manager. It covers these topics:
•Types of Resource Files
•Generating a CSR
•Uploading a Keypair Resource
•Uploading a Certificate Authority Resource
Types of Resource Files
An ACE XML Gateway policy is made up of numerous objects and configuration settings that control how the ACE XML Gateway processes and validates traffic. Included in the artifacts that make up a policy are resource files.
The types of resource files a policy may have include:
•Private Keys—The private half of public/private key pairs, used for encryption and digital signing
•Trusted Certificate Authorities—X.509 certificate files that identity providers of certificates that the ACE XML Gateway instance is prepared to trust
•Server Certificates—X.509 certificate files used to identify protected servers
•Consumer Certificates—X.509 files used to identify consumers
•Password Files—htpasswd-style password files used to authenticate ACE XML Manager web console users
•Validation Resources—DTD and XML Schema files used to validate the contents of message
•XSLT—Used to transform messages at various points in the ACE XML Gateway processing sequence
This section describes how to upload and manage resource files. There is usually more than one way to upload a particular type of resource file in the ACE XML Manager web console—from the resource manager page or from the page where a resource is applied. These instructions describe in general terms how to upload resources using the resource manager. Once the resource has been uploaded, it appears as a menu choice in applicable locations of the console.
It is often preferable to load resources from a URL location rather than from a filesystem location. This allows you to take advantage of URL-based resource refreshing. Resource refreshing is a process by which the ACE XML Manager checks for updates to resources loaded in the policy by checking whether there are updates to the source. If so, the resource can be updated. For more information, see "Reloading URL-Based Resources Before Deployment" section on page 25-236.
Generating a CSR
A public/private keypair associated with the ACE XML Gateway enables you to secure the communication channel between the ACE XML Gateway and consumer or between the ACE XML Gateway and backend service. They are also needed for XML Encryption and XML Signature.
A self-signed certificate is usually suitable for securing channels between the ACE XML Gateway and internal customers or partners. For customers or partners that are external to your organization, it is recommended that you acquire an X.509 certificate that is signed by a trusted certificate authority.
The first step in acquiring a certificate is to create a certificate signing request, or CSR, for submission to a certificate authority.
To generate certificate requests in the ACE XML Manager web console:
Step 1 Click the Public/Private Keypairs link in the Resources section of the navigation menu.
Step 2 Click the Generate CSR button at the bottom of the page.
Step 3 In the Generate Certificate Signing Request page, type in the Resource Name field the name that is to identify this resource in the policy.
Step 4 Type appropriate values into the following fields in the Subject Identification Information section:
This field should contain the external hostname of the ACE XML Gateway. Note that for a clustered Gateway configuration this would be the common host name that consumers use to address the cluster.
The email address that is to receive the signed certificate in response to the CSR.
The name of the organization or company with which the CN is associated.
The name of an organizational unit or sub-group within the organization.
The locality or city of the entity being certified.
The state or province of the entity being certified.
ISO Country Code
The two-letter International Standards Organization (ISO) code for the country of the entity being certified.
Step 5 From the Key Type menu, choose the algorithm to use when generating the certificate's signature, from these options:
•RSA—The RSA public-key cryptosystem Secure Hash Algorithm. For more information, see the RSA-SHA1 Signature Suite page at the W3C web site.
•DSA—The Digital Signature Algorithm Secure Hash Algorithm. For more information, see the Digital Signature Standard (DSS) page at the US National Institute of Standards and Technology (NIST) web site.
Step 6 Optionally, choose an item from the Key Size menu to specify the size of the key to use when generating the certificate's signature:
•512 bits—Use a 512-bit key to generate the signature.
•1024 bits—Use a 1024-bit key to generate the signature. This is the default value.
•2048 bits—Use a 2048-bit key to generate the signature.
Step 7 Optionally, define additional attributes the certificate is to provide:
a. Click the Add Attribute button. An Attribute OID field and a Value field appear in the Additional Attributes section.
b. Type into the Attribute OID field the name of the additional attribute in OID format.
c. Type into the Value field the value of the additional attribute.
d. Repeat the preceding steps as necessary to add all of the attributes required.
To remove an attribute, click the Remove button that appears at the end of its row in the list of custom attributes.
Step 8 When finished entering the information, click the Generate Request button.
Using the information you supplied, the ACE XML Manager generates a Certificate Signing Request (CSR) and displays it on the Certificate Signing Request page.
The generated request page appears similar to the following.
Figure 24-1 Generated Request Form
Step 9 Copy the CSR data (the part between the -----BEGIN CERTIFICATE REQUEST----- and -----END CERTIFICATE REQUEST----- strings) into a text file or an email message.
Step 10 Send the CSR data to your preferred CA for transformation into a signed X.509 certificate.
Note When you are submitting a request, the CA may ask you to specify the type of certificate required. The ACE XML Gateway works with what are usually identified as Apache-style certificates.
When the signed certificate arrives, install it on the ACE XML Gateway as described in the following section.
Uploading a Keypair Resource
A keypair resource is a file that stores a PKI public/private keypair. The ACE XML Manager uses keypair resource files to implement SSL connectivity between it and a browser attempting to access the web console. Service traffic can also be secured by the system public/private keypair.
The Public/Private Keypairs page lists all keypair resources in the currently active subpolicy. Entries on this page represent keypair resources that reside on the system in encrypted form.
When the ACE XML Manager compiles and deploys a policy that uses keypair resources, it transmits keypair data to the target Gateways in a proprietary binary format. The keypair is never in clear-text form.
You can upload a keypair to the ACE XML Manager by itself or as part of a certificate. A certificate resource is a file that the ACE XML Manager uses to store digital certificate data; optionally, the certificate resource can store the certificate's associated keypair data. Like the keypair resource, a certificate resource exists in the policy in encrypted form only.
To upload a keypair resource to the policy in the ACE XML Manager:
Step 1 While logged in to the Manager web console as an Administrator user or a Privileged user with the Routing role, set the active subpolicy to the one that is to use the keypair.
Step 2 Click the Public/Private Keypairs link in the navigation menu.
Step 3 Click the Add New Public/Private Keypair button at the top of the page. (Alternatively, use the Upload Separate Certificate and Key Files if the certificate and key files are not in the same file.)
The Upload Public/Private Keypair Resource page appears. You can also reach this page from the HTTP(S) port settings page.
Step 4 In the Resource Name field, type a unique name for the keypair resource. This name identifies the keypair in the ACE XML Manager's user interface.
Step 5 Identify the keypair to use from a filesystem location or from a network location by URL.
Step 6 Type the password for the keypair in the Password field. Note that the password is obscured in the field as you type.
Step 7 Click the Upload button.
The ACE XML Manager uploads the keypair resource and displays it as a resource in the Public/Private Keypairs page. If the resource does not pass a basic validity test—for example, if it does not provides a pair of valid PEM keys—an error message appears in red text on the Upload Public/Private Keypair Resource page.
When complete, you can use the keypair when configuring SSL connections in the policy.
Uploading a Certificate Authority Resource
Uploading the certificate of a Certificate Authority (CA) suggests a trust relationship with that CA. You can configure a service definition to accept consumer certificates signed by any CA whose certificate has been loaded to the policy. The system does not include any pre-installed CA certificates. Therefore, you need to import the certificates of any CA to be trusted.
You can upload a CA resource to the ACE XML Manager as a file or URL. You can also import the necessary information from an LDAP server. The Trusted Certificate Authorities page lists all Certificate Authorities available to the currently active subpolicy. These resources appear as named items in menus on pages that create or edit services requiring digital certificates.
To upload a CA resource file to the ACE XML Manager web console:
Step 1 As an Administrator user or a Privileged user with the Routing role in the console, set the active subpolicy to the one in which you want to use the keypair.
To make the keypair available to all subpolicies, add it to the Shared subpolicy.
Step 2 Click the Trusted Certificate Authorities link in the Resources section of the navigation menu.
Step 3 In the Trusted Certificate Authorities page, click the Add a New Certificate Authority Resource button, near the top of the page.
The Upload Certificate Authority Resource page appears.
Step 4 Type a name for the certificate authority resource in the Resource Name field. This is simply a descriptive name for the resource used within the policy.
Step 5 Specify the certificate from either a file system location in the Local File field or from a network location, by typing the network address of the resource in the URL field.
You can populate the Local File field automatically by clicking the Browse button, and navigating to the certificate file.
Step 6 Optionally, type a URL for the certificate revocation list in the CRL URL field. The ACE XML Gateway rejects connections that use certificates that appear in the certificate revocation list.
Leave this field blank to not have the ACE XML Gateway check any certificate revocation list.
Step 7 If you configured a certificate revocation list, also specify how often the ACE XML Gateway should retrieve the list.
Step 8 When finished, click Upload to have the resource uploaded to the ACE XML Manager.
You can now use the CA certificate in the policy.