Securing Communications with CentraSite for Synchronous Deployment
Configuring CentraSite to use SSL authentication provides secure communications for the deployment.
An administrator can configure CentraSite to use either of the following kinds of authentication:
HTTP Basic authentication
HTTPS (Secure Sockets Layer (SSL)) authentication
This section explains how SSL works with CentraSite (which acts as the client) and API Gateway (which acts as the server). This section also provides the information you need to configure both the client and server sides for SSL authentication.
Anatomy of a SSL Connection
It is useful to conceptualize a CentraSite SSL connection in terms of a SSL client and a SSL server. The request for an SSL connection originates from a client.
During the SSL handshake process, the API Gateway acting as the SSL server responds to the request for a connection by presenting its SSL credentials (an X.509 certificate) to the requesting CentraSite client. If those credentials are authenticated by the CentraSite client, either:
An SSL connection is established and information can be exchanged between the
CentraSite and
API Gateway.
—OR—
The next phase of the authentication process occurs, and the
API Gateway requests the SSL credentials of the
CentraSite. If the
API Gateway verifies those credentials (that is, the client’s identity), an SSL connection is established and information exchange can take place.
SSL Connection Type
The types of SSL connection referred to above are termed one-way and two-way SSL authentication:
In a
one-way SSL connection, client authenticates the credentials of server in preparation for setting up a secure transaction. In most cases, the server knows nothing about the client’s identity because verification of its credentials is not required. When desired, however the client can be authenticated by means such as basic username or password.
This type of connection is where CentraSite needs to verify the authenticity of API Gateway without itself needing to be authenticated. As a result, configurations on the CentraSite side are not actually required for this one-way connection.
In a
two-way SSL connection, both client and server must authenticate each other’s credentials before an SSL connection is established and information can be exchanged.
Unlike a one-way SSL connection, both CentraSite and API Gateway require access to each other’s SSL certificates in order to authenticate each other, establish an SSL connection, and transmit information. Compared to a one-way connection, a two-way SSL connection provides a much higher level of security.
As an SSL Client
When CentraSite submits a HTTPS request to API Gateway, CentraSite is the SSL client and API Gateway with which it is communicating acts as the SSL server.
As an SSL ServerWhen API Gateway submits a request to CentraSite through HTTPS, and a two-way SSL connection is established, the API Gateway acts as the SSL client and the CentraSite acts as the SSL server.
Roadmap for Configuring SSL
The following table provides a high-level roadmap for configuring SSL on CentraSite.
Task | Activities | Notes |
Create CentraSite keys and certificates | Generate a public key/private key pair. Generate a certificate signing request (CSR) and send to the certificate authority (CA) for signing. Receive validated certificate from the CA. Import signed certificate into a keystore. | Required for one-way and two-way SSL connections. Refer to the documentation for Java keytool or your certificate management tool. |
Create keystore and truststore for CentraSite | Create a keystore and import the signed certificate and private key. Create a truststore and import the certificate of the signing CA. Store the keystore and truststore in a secure CentraSite certificates directory. Important:
If you use a Java keytool to create the keystore, you cannot import an existing private key. You can use other tools such as OpenSSL or Portecle. | Required for one-way and two-way SSL connections. Refer to the documentation for your certificate management tool. |
Obtain certificates of webMethods API Gateway | Use the CentraSite truststore to save: Signed certificate of the API Gateway. Signed certificate of the CA for the API Gateway's SSL certificate. | Required for one-way and two-way SSL connections. |
Creating Keys and Certificates
Use a standard certificate management tool, such as OpenSSL or Portecle, to generate a private/public key pair for CentraSite. Then, place the public key in a certificate signing request (CSR).
After creating the CSR, send to the CA to sign the CSR. Request the certificate in DER format. If you receive a certificate in PEM format (or any format other than DER), you need to convert it to DER format.
The signing CA’s certificate attests to the identity of the CA that signed the digital certificate for the CentraSite. The CA should send this certificate to you when it sends you the digital certificate for the CentraSite.
Once you receive your signed certificate from the CA, you need to import the certificate into a keystore. You will then have an SSL certificate and private key to use with CentraSite.
Note:
The above process is described in general terms. The procedures may vary somewhat, depending upon the CA that you use. Creating a Keystore and Truststore
Keystores and truststores are files that function as repositories for storage of keys and certificates necessary for SSL authentication, encryption/decryption, and digital signing/verification services. Keystores and truststores provide added layers of security and ease of administration, compared to maintaining the keys and certificates in separate files.
For information about creating keystores and truststores, importing keys and certificates into keystores and truststores, and other operations with these files, refer to the documentation for your certificate management tool.
Obtaining the Certificates and Keys of the webMethods API Gateway
If your CentraSite will submit HTTPS requests to the API Gateway, the CentraSite will be acting as a client and will receive certificates from this API Gateway. In order for these transactions to work, your CentraSite must have copies of their public keys and signing CA certificates. For information on importing API Gateway certificates to CentraSite and setting up client authentication, see webMethods Integration Server Administrator’s Guide.
Keystores and Truststores
CentraSite stores its private keys and SSL certificates in keystore files and the trusted roots for the certificates in truststore files. Keystores and truststores are secure files with industry-standard file formats.
Keystore File
CentraSite uses a special file called a keystore to store SSL certificates and keys.
A keystore file contains one or more pairs of a private key and signed certificate for its corresponding public key. The keystore should be strongly protected with a password, and stored (either on the file system or elsewhere) so that it is accessible only to administrators.
Keystore File Formats
The default, certificate file format for a CentraSite keystore is. JKS (Java keystore). Java keystore is a commonly used, standardized, certificate file format that provides a high degree of portability. PKCS#12 is another format you can use for a keystore. Other keystore types can be made available by:
Loading additional security providers
Setting the watt.security.keyStore.supportedTypes property.
HSM-Based Keystores
Under certain conditions, Mediator supports the use of keystore files stored on a Hardware Security Module (HSM). Integration Server supports HSM-based keystores for ports, but not for other components. You cannot use HSM-based keystores with remote server aliases, outbound certificates, an internal server port, WS-Security, or Integration Server public services.
Creating a Keystore
You can create and manage CentraSite keystores at the command line using keytool, a Java certificate editor.
You can also use other standard tools such as OpenSSL and Portecle.
Note:
Software AG does not provide its own set of keystore utilities for creating or managing keystore files.
Truststore File
CentraSite uses a truststore to store its trusted root certificates, which are the public keys for the signing CAs. Although a truststore can contain the trusted roots for entire certificate chains, there is no requirement for the organization of certificates within a CentraSite truststore. It simply functions as a database containing all the public keys for CAs within a specified trusted directory.
Truststore File Formats
CentraSite uses a truststore to store its trusted root certificates, which are the public keys for the signing CAs. Although a truststore can contain the trusted roots for entire certificate chains, there is no requirement for the organization of certificates within a CentraSite truststore. It simply functions as a database containing all the public keys for CAs within a specified trusted directory.
How CentraSite Uses a Keystore and Truststore
For a CentraSite service to be SSL authenticated, it must have a valid, authorized X.509 certificate installed in a keystore file and the private key and signing certificate for the certificate issuer (CA) installed in a truststore file. The following figure illustrates these requirements and the relationship between the two files.
Example Truststore File and Keystore File Showing Relationship
As illustrated in the figure, the same truststore file can contain multiple trusted root certificates (public keys for the signing CAs). These trusted roots might be associated with numerous keystore files. A keystore file can contain the key pairs for multiple CentraSite services, and the entire certificate chain required for a service’s authentication.
With a certificate chain, it is necessary to validate each subsequent signature in the list until a trusted CA certificate is reached. For CentraSite, you must include the entire chain of certificates in a keystore and truststore. Also, any root CA certificates in use by clients must be in a CentraSite truststore.
Protecting Keystore and Truststore Files
Keystore and truststore files exist within the file system of your operating system, and since these are critically important files, you want to maintain them in a secure directory path. If either of the these files cannot be located, CentraSite authentication is disabled and no connection with CentraSite can be made. It is recommended that only users serving as CentraSite administrators have access to these certificate files.
