This chapter provides an overview of the SSL keystore and truststore, and describes how to configure SSL between MSAS and other system components. Topics include:
Mobile Security Access Server supports an SSL keystore and SSL truststore. The SSL keystore holds the identity key for the server and the SSL truststore serves as the repository for trusted certificates. The SSL truststore is used for trusting or authenticating client certificates (for two-way SSL).
Configuration of the SSL keystore and truststore is performed when you execute the idmConfigTool. For details about running the idmConfigTool, see "Configuring the Identity Store for the MSAS Instance" in Installing Oracle Mobile Security Access Server.
When you execute the idmConfigTool, it:
Creates the SSL keystore and truststore for the MSAS instance.
Creates an SSL key which is signed by a self-signed CA (certificate authority).
Imports SSL certificates into the truststore that are required for Mobile Device Management/Mobile Application Management (MDM/MAM) flow and for two-way SSL communication with mobile clients.
Note:
Mobile Security Access Server supports only the OPSS KSS keystore for the SSL keystore and truststore.The SSL keystore and truststores are created at the logical instance level in the following locations:
SSL keystore—kss://msas_instance_id/sslkeystore (KSS stripe)
This location is identified by the configuration property:
Category: ServerSettings
Property Name: ssl.keystore.location
SSL truststore—kss://msas_instance_id/ssltruststore (KSS stripe).
This location is identified by the configuration property:
Category: ServerSettings
Property Name: ssl.truststore.location
For details about setting these properties, see "Configuring Server Settings Using WLST".
Note:
In both KSS stripes,msas_instance_id is the name of the logical MSAS instance with which the keystore and truststore are associated. Do not change these locations.You can manage the SSL keystore and truststore using the MSAS console pages in the OAM console. Using the console you can import keys into the SSL keystore, or generate keys. You can also import certificates into the SSL truststore. For details, see "Configuring the SSL Keystore and Truststore".
For advanced management of the KSS SSL keystore and truststore, you can also use Keystore Service commands provided by Oracle Platform Security Service (OPSS). The Keystore Service uses a dedicated set of command-line commands for keystore operations such as creating and managing keystores, exporting certificates, and generating keypairs. While their usage is similar, these commands are distinct from other WLST commands. Details about these commands and their usage are provided in "About Keystore Service Commands" in Securing Applications with Oracle Platform Security Services.
Note:
By default, two-way SSL is not enabled on the MSAS server, and is controlled by the configuration property:Category: MSASConfig
Property Name: security.clientAuthenticationRequired
The settings for this property are as follows:
NO (the default)—Client authentication is not required and two-way SSL is disabled at the MSAS server level.
YES—Client authentication is required and two-way SSL is enabled at the MSAS server level. In this case, all clients must provide client certificates with each request, regardless of whether the URLs they are accessing require a client certificate or not.
MAY—Client authentication optional.
For details about setting this property, see "Configuring Additional Server Settings Using WLST".
No additional SSL configuration is required for communication between the following components:
MSAS and the Mobile Security Manager
MSAS and Oracle Access Manager and OAuth Server
For SSL configuration details between other components, refer to the following sections:
By default, SSL is mandatory in MSAS and the SSL port is always enabled for one-way SSL. You configure the SSL port when you run the MSAS configuration tool configMSAS to create the MSAS instance. The SSL keystore, which is configured when you run the idmConfigTool, will contain one key, signed by the self-signed certificate authority (CA), that is used as the identity key for the instance. For details about running the configMSAS tool and the idmConfigTool, refer to the following topics in Installing Oracle Mobile Security Access Server:
If the SSL keystore has more than one key, then the alias of the identity key must be specified in the configuration property MSASConfig:security.keystoreAlias. Keys can be imported or generated using the MSAS console or WLST commands.
For scenarios such as PKINIT-based authentication and mobile device registration, the client certificate is requested and authenticated, therefore the issuer certificate chains must be trusted in the SSL truststore. The client certificate must have a Subject Alternative Name extension that contains the User Principal Name (UPN) of the client.
You can import the signer's certificate chain for the client certificate into the SSL truststore using the MSAS console as described in "Configuring the SSL Keystore and Truststore". You can also use OPSS Keystore Service commands to import the signer's certificate chain for the client certificate into the SSL truststore. Details about these commands and their usage are provided in "About Keystore Service Commands" in Securing Applications with Oracle Platform Security Services.
The default identity key of the MSAS instance is signed by a self-signed CA. You can replace the certificate with one signed by a well known CA, if required, as described in the following procedure:
Export the existing KSS keystore entry into a JKS keystore using the Keystore Service commands:
Connect to the running server as described in "Accessing the MSAS WLST Commands".
Execute the getOpssService command to access the Keystore Service commands:
wls:/base_domain/serverConfig>svc = getOpssService(name='KeyStoreService')
Export the KSS keystore using the exportKeyStore command:
svc.exportKeyStore(appStripe='<msas-id>', name='sslkeystore', password='<keystore-password>', aliases='<msas-id>_msasidentity', keypasswords='<key-password>', type='JKS',filepath='/tmp/<msas-id>_sslkeystore.jks')
The password and keypasswords arguments in the command apply to the JKS keystore and key password. This password is used to protect the exported key and the JKS keystore.
Generate the server certificate request to create a Certificate Signing Request (CSR) file using the keytool -certreq command:
keytool -keystore /tmp/<msas-id>_sslkeystore.jks -storepass <keystore-password> -alias <msas-id>_msasidentity -certreq -file /tmp/msasidentity.csr -keypass <key-password>
Submit the CSR file to a CA. The CA will authenticate the request, issue a certificate for the MSAS instance, and return the certificate and a certificate chain.
Update the MSAS identity certificate on the server. To do so you must first update the JKS keystore that you exported in Step 1, and then import the JKS keystore into the KSS keystore.
Import the new CA certificate chain into the JKS keystore. This is required to create a complete chain.
keytool -keystore /tmp/<msas-id>_sslkeystore.jks -import -file <CA_CERT>.crt -alias ca -storepass <keystore-password>
Import the updated MSAS identity certificate into same JKS keystore. This command assumes that the signed certificate is available at /tmp/msasidentity.crt.
keytool -keystore /tmp/<msas-id>_sslkeystore.jks -import -file /tmp/msasidentity.crt -alias <msas-id>_msasidentity -storepass <keystore-password>
Import the JKS keystore into the KSS keystore using the Keystore Service commands. Connect to the running server as described in "Accessing the MSAS WLST Commands", then execute the following commands:
svc = getOpssService(name='KeyStoreService') svc.deleteKeyStoreEntry(appStripe='<msas-id>',name='sslkeystore',password='', alias='<msas-id>_msasidentity', keypassword='') svc.importKeyStore(appStripe='<msas-id>',name='sslkeystore',password='<keystore-password>', aliases='<msas-id>_msasidentity', keypasswords='<key-password>', type='JKS',permission=true, filepath='/tmp/<msas-id<_keystore.jks')
Restart the MSAS server.
Note:
Any changes in the SSL keystore or truststore require that you restart the MSAS server.The entity signing the MSAS identity certificate must be trusted in the mobile device. If not, the mobile device will not be able to connect to MSAS. If the entity signing the certificate is a well known certificate authority (CA), then ensure that the signer is already trusted in the mobile device.
To simplify the process of downloading the MSAS identity certificate chain from the SSL keystore, MSAS provides the following URL:
https://msas_host:msas_port/bmax/msas_cert[n].pem
where [n] represents a certificate in the chain from 0 to 4. The certificate at index zero is the issuer of the server certificate, and the certificate at index one is the issuer of the certificate at index zero and so on.
For example:
https://msas_host:msas_port/bmax/msas_cert0.pem https://msas_host:msas_port/bmax/msas_cert1.pem
Note:
Because the SSL keystore contains the single self-signed root certificate, by defaulthttp://msas_host:msas_port/bmax/msas_cert0.pem provides the root certificate to install on the device.By default, certificate authentication for back-end servers is turned off on MSAS. As a result, the SSL certificates of back-end resources are not required to be trusted in the MSAS SSL truststore and no configuration is required.
This behavior is controlled by the configuration property:
Category: ClientConfiguration
Property Name: ssl.security.level
The default value of this property is loose. Changing the value of this property to strict will require that the SSL certificates of the back-end resources be trusted in MSAS SSL truststore, otherwise MSAS will not be able to connect to them.
For information about setting this and other properties in the ClientConfiguration category, see "Configuring Outbound Message Settings Using WLST".
Note:
Two-way SSL with back-end resources is not supported in this release.If the identity store is configured on an SSL port, then the SSL certificate for the identity store must be trusted in MSAS SSL truststore. You can import the self-signed SSL certificate or the signer's certificate chain for the identity store (required for production environments) using the MSAS console, as described in "Configuring the SSL Keystore and Truststore".
You can also use OPSS Keystore Service commands to import the self-signed certificate or signer's certificate chain for the identity store into the SSL truststore. Details about these commands and their usage are provided in "About Keystore Service Commands" in Securing Applications with Oracle Platform Security Services.
Note:
Any changes in the SSL keystore or truststore require that you restart the MSAS server.