| Oracle® Retail Predictive Application Server Administration Guide for the Fusion Client Release 14.1 E59119-01 |
|
 Previous |
 Next |
| Oracle® Retail Predictive Application Server Administration Guide for the Fusion Client Release 14.1 E59119-01 |
|
Previous |
Next |
Secure Socket Layer (SSL), a protocol for securing network connections, is used by RPAS to provide secure communication between RPAS client and server processes. RPAS Fusion Client supports two-way SSL and two-way SSL with authentication only.
This chapter contains the following sections:
In order to use SSL with RPAS, you must configure both the server and the client. For two-way SSL, this involves setting up key stores and trust stores used to manage certificates. The key store contains a private key and its corresponding public certificate chain. The trust store contains trusted public certificates and certificate chains.
In order to enable the use of SSL on RPAS, you must use the Domain Daemon to set up the SSL type and the Oracle wallet location.
Oracle Wallet is managed by a command line utility called orapki, which is included in the RPAS installation. JKS Keystore is managed by the keytool utility that is included in the standard JDK. Oracle Wallet and JKS are in different formats and cannot be used interchangeably. However, the orapki utility can be used to convert between them.
A Certificate Authority (CA) certificate is the public certificate from the CA that issues the server certificate and the client certificate.
As part of the installation of the RPAS Fusion Client, the following SSL-related setup occurs:
The user-selected password for accessing the client-side key store and trust store files is saved.
The Fusion Client code has access to the password at run time.
After installation, the client-side key store and trust store files and the server-side wallet must be created.
Either before or after installation:
The client-side key store must be copied as fckey.jks into the <configroot>/idstores directory.
The client-side trust store files must be copied as fctrust.jks into the <configroot>/idstores directory.
In two-way SSL, the client and the server each request to verify the identity of the other. In addition, the server requires that the client certificate be pre-registered in its trust store.
Two-way SSL authenticates both the server and the client. Both sides must have a key store and a trust store. The same wallet may be used with multiple domain daemon instances. This effectively means that all RPAS servers within a single customer site can use the same server certificate. The customer therefore needs to obtain two certificates. The RPAS server uses one Oracle Wallet for both stores. Both the trust store and the key store are in the JKS format.
On the Fusion Client side, the key store and the trust store are two files that use the JKS format for storing the keys and the certificates. They cannot be read by the orapki utility. Orapki can only handle wallet files created in the proprietary orapki format. This format is used on the RPAS server side. In other words, the server side has one single wallet file that has the keys and the certificates, written in the orapki format.The trust store must contain the CA certificate in order to enable mutual authentication. In addition, the trust store of the server must contain the client certificate so that it can recognize and authorize that particular client. Both the client certificate and the server certificate typically have the same CA certificate since there is no reason to apply to different CAs for client and server.
To configure the RPAS Server for two-way SSL, you must set up a key store and a trust store, import the client certificate into the server wallet as trusted certificates, and then start the Domain Daemon. One Oracle wallet can act as both the key store and the trust store.
To set up the key store, complete the following steps:
Create an Oracle wallet with auto login. This type of wallet can be read without a password. The default file permissions for the wallet are 0300 (accessible by owner only).
orapki wallet create -wallet {server_wallet_directory} -auto_login -pwd {server_wallet_password}
Example:
orapki wallet create -wallet C:/wallets/server -auto_login -pwd serverpass1
Generate a private key.
orapki wallet add -wallet {server_wallet_directory} -keysize {key_len} -dn {server_dn} -pwd {server_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/server -keysize 2048 -dn "cn=rpas_qa_server,dc=us,dc=oracle,dc=com" -pwd serverpass1
Export a certificate request.
orapki wallet export -wallet {server_wallet_directory} -dn {server_dn} -request {server_cert_req_file} -pwd {server_wallet_password}
Example:
orapki wallet export -wallet C:/wallets/server -dn "cn=rpas_qa_server,dc=us,dc=oracle,dc=com" -request C:/wallets/server_cert_req.txt -pwd serverpass1
The certificate request must be digitally signed before it can be used. If the deployment of the RPAS Fusion Client and the RPAS server are both under the control of the customer, then a self-signed SSL certificate may be used as the signer. Otherwise, the certificate request must be sent out for signing by a well-known certificate authority.
A self-signed SSL certificate used in this manner may be referred to as a self-signed root certificate or as a private certificate authority.
This is the method for creating a self-signed root certificate:
Generate a private key for the root certificate:
orapki wallet add -wallet {root_wallet_directory} -keysize {key_len} -dn {root_dn} -self_signed -validity {validity_days} -pwd {root_wallet_password} -addext_ski
Example:
orapki wallet add -wallet C:/wallets/root -keysize 1024 -dn "cn=root,dc=us,dc=example,dc=com" -self_signed -validity 3650 -pwd rootpass1 -addext_ski
Export the root certificate chain to a file:
orapki wallet export_trust_chain -wallet {root_wallet_directory} -certchain {root_cert_chain_file} -dn {root_dn} -pwd {root_wallet_password}
Example:
orapki wallet export_trust_chain -wallet C:/wallets/root -certchain C:/wallets/root_chain.txt -dn "cn=root,dc=us,dc=example,dc=com" -pwd rootpass1
In the above example, the file containing the root certificate chain is c:/wallets/root_chain.txt.
If you are using an external root certificate, create the server certificate signed by a third-party CA. (Alternatively, see step 6.) To do this, send the server certificate request file ({server_cert_req_file}) to the CA. The CA sends back a certificate ({server_certificate_file}) for the server, along with the public certificate ({root_cert_chain_file}) of the CA.
If using a self-signed root certificate, the server certificate file is signed as follows:
orapki cert create -wallet {root_wallet_directory} -request {server_cert_req_file} -cert {server_certificate_file} -validity {validity_days} -pwd {root_wallet_password}
Example:
orapki cert create -wallet C:/wallets/root -request C:/wallets/server_cert_req.txt -cert C:/wallets/server_cert.txt -validity 3650 -pwd rootpass1
The file c:/wallets/server_cert.txt is the signed server certificate, in the form of a file.
Import the CA into the server wallet. Note that the public certificate chain may contain more than one certificate. In such cases, the certificates must be imported one by one, starting at the top of the chain.
orapki wallet add -wallet {server_wallet_directory} -trusted_cert -cert {root_cert_chain_file} -pwd {server_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/server -trusted_cert -cert C:/wallets/root_chain.txt -pwd serverpass1
Import the server certificate into the wallet.
orapki wallet add -wallet {server_wallet_directory} -user_cert -cert {server_certificate_file} -pwd {server_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/server -user_cert -cert C:/wallets/server_cert.txt -pwd serverpass1
To set up a trust store, complete the following steps:
Create an Oracle wallet with auto login.
orapki wallet create -wallet {client_wallet_directory} -auto_login -pwd {client_wallet_password}
Example:
orapki wallet create -wallet C:/wallets/client -auto_login -pwd clientpass1
Generate a private key.
orapki wallet add -wallet {client_wallet_directory} -keysize {key_len} -dn {client_dn} -pwd {client_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/client -keysize 1024 -dn "cn=fusionclient,dc=us,dc=example,dc=com" -pwd clientpass1
Export a certificate request.
orapki wallet export -wallet {client_wallet_directory} -dn {client_dn} -request {client_cert_req_file} -pwd {client_wallet_password}
Example:
orapki wallet export -wallet C:/wallets/client -dn "cn=fusionclient,dc=us,dc=example,dc=com" -request C:/wallets/client_cert_req.txt -pwd clientpass1
Create the client certificate in one of the two following ways:
If a third-party CA is used, send the client certificate request file ({client_cert_req_file}) to the CA. The CA will send back a certificate for the client (referred to as {client_certificate_file}) along with the public certificate of the CA (referred to as {root_cert_chain_file}).
If the self-signed root certificate is used (use the same one that was used for signing the server certificate), run the following command:
orapki cert create -wallet {root_wallet_directory} -request {client_cert_req_file} -cert {client_certificate_file} -validity {validity_days} -pwd {root_wallet_password}
Example:
orapki cert create -wallet C:/wallets/root -request C:/wallets/client_cert_req.txt -cert C:/wallets/client_cert.txt -validity 3650 -pwd clientpass1
Import the CA certificate from the server into the wallet. Note that the public certificate chain may contain more than one certificate. In such cases, the certificates must be imported one by one, starting at the top of the chain.
Typically, the CA certificates of both client and server will be one and the same. There is no reason for them to be different at the same customer site.
orapki wallet add -wallet {client_wallet_directory} -trusted_cert -cert {root_cert_chain_file} -pwd {client_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/client -trusted_cert -cert C:/wallets/root_chain.txt -pwd clientpass1
Convert the Oracle wallet to JKS format:
orapki wallet pkcs12_to_jks -wallet {client_wallet_directory} -pwd {client_wallet_password} -jksKeyStoreLoc {key_store_file} -jksKeyStorepwd {key_store_password} -jksTrustStoreLoc {trust_store_file} -jksTrustStorepwd {trust_store_password}
Example:
orapki wallet pkcs12_to_jks -wallet C:/wallets/client -pwd clientpass1 -jksKeyStoreLoc testkey.jks -jksKeyStorepwd welcome1 -jksTrustStoreLoc testtrust.jks -jksTrustStorepwd welcome1
For every client that connects to the RPAS server using two-way SSL, you must import its certificates into the server wallet as trusted certificates. If the client certificates are from a different CA than the certificates that are already in the server wallet, you must first import the new CA certificate.
Use the following command to import the certificates:
orapki wallet add -wallet {server_wallet_directory} -trusted_cert -cert {client_cert_file} -pwd {server_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/server -user_cert -cert C:/wallets/server_cert.txt -pwd serverpass1
To configure the Fusion Client for two-way SSL, you must set up a key store and a trust store in the JKS format. Then, import the CA server certificate into the trust store.
To set up a key store and a trust store, complete the following steps:
Create an Oracle wallet with auto login.
orapki wallet create -wallet {client_wallet_directory} -auto_login -pwd {client_wallet_password}
Example:
orapki wallet create -wallet C:/wallets/client -auto_login -pwd clientpass1
Generate a private key.
orapki wallet add -wallet {client_wallet_directory} -keysize {key_len} -dn {client_dn} -pwd {client_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/client -keysize 1024 -dn "cn=rpas_qa_client,dc=us,dc=oracle,dc=com" -pwd clientpass1
Export the certificate request.
orapki wallet export -wallet {client_wallet_directory} -dn {client_dn} -request {client_cert_req_file} -pwd {client_wallet_password}
Example:
orapki wallet export -wallet C:/wallets/client -dn "cn=rpas_qa_client,dc=us,dc=oracle,dc=com" -request C:/wallets/client_cert_req.txt -pwd clientpass1
Create the client certificate for a third-party CA. To do this, send the client certificate request file ({client_cert_req_file}) to the CA. The CA sends back a certificate ({client_certificate_file}) for the client, along with the public certificate ({root_cert_chain_file}) of the CA.
Import the CA into the wallet. Note that the public certificate chain may contain more than one certificate. In such cases, the certificates must be imported one by one, starting at the top of the chain.
orapki wallet add -wallet {client_wallet_directory} -trusted_cert -cert {root_cert_chain_file} -pwd {client_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/client -trusted_cert -cert C:/wallets/root_chain.txt -pwd clientpass1
Import the client certificate into the client wallet.
orapki wallet add -wallet {client_wallet_directory} -user_cert -cert {client_certificate_file} -pwd {client_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/client -user_cert -cert C:/wallets/client_cert.txt -pwd clientpass1
Import the CA for the server certificate into the wallet. You can skip this step if both the client and the server certificates are issued by the same CA.
orapki wallet add -wallet {client_wallet_directory} -trusted_cert -cert {root_cert_chain_file_for_the_server} -pwd {client_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/client -trusted_cert -cert C:/wallets/root_chain.txt -pwd clientpass1
Convert the Oracle wallet to the JKS format.
orapki wallet pkcs12_to_jks -wallet {client_wallet_directory} -pwd {client_wallet_password} -jksKeyStoreLoc {key_store_file} -jksKeyStorepwd {key_store_password} -jksTrustStoreLoc {trust_store_file} -jksTrustStorepwd {trust_store_password}
Example:
orapki wallet pkcs12_to_jks -wallet C:/wallets/client -pwd clientpass1 -jksKeyStoreLoc testkey.jks -jksKeyStorepwd welcome1 -jksTrustStoreLoc testtrust.jks -jksTrustStorepwd welcome1
Copy the client key and trust files into <fusion_client_install_dir>/config/idstores. The password must be kept inside the WebLogic credential store, which will be handled by the Fusion Client installer.
For every client that connects to the RPAS server using two-way SSL, you must import its certificates into the server wallet as trusted certificates. If the client certificates are from a different CA than the certificates that are already in the server wallet, you must first import the new CA certificate.
Use the following command to import the certificates:
orapki wallet add -wallet {server_wallet_directory} -trusted_cert -cert {client_cert_file} -pwd {server_wallet_password}
It is possible to run two-way SSL without encryption. To accomplish this, set up two-way SSL as described in the previous section for both the RPAS Server and the Fusion Client. Then, to start the Domain Daemon with two-way SSL authentication-only, execute the following command, where the <walletLocation> is the absolute path for the directory of the Oracle wallet:
DomainDaemon -port portNum -ssl 4 -wallet file:<walletLocation> start
You see the following warning message:
Warning: The client/server network communication is using two-way SSL authentication only. The data communication is not encrypted.
The input.userSelfSignedSSLCertificates property can be used to create SSL certificates automatically using the Fusion Client Installer.
Usage
If this property is set to yes, it will trigger the automatic creation of SSL certificates signed by a private certificate authority. At the end of the process, the server wallet directory must be copied to its correct destinations. The server wallet directory is the "walletdir/server" subdirectory of the installer's current directory.
Use this option only if deploying to a trusted hardware and software environment that is under the control of a single business entity. If the RPAS client or the server is not in the customer's control, externally signed SSL certificates are recommended. See the Installation Guide for details.
