Java SE security tutorial - Step 6

The following step explains how you can enable a security layer for communication between your environment's endpoints.

1. Create TLS/SSL keys and keystores.
   In order to enable transport security, you must create a keystore and trust store. This exercise only creates one key and trust-store pair. These stores are used for ObjectGrid clients, container servers, and catalog servers, and are created with the JDK keytool.

   • Create a private key in the keystore

     keytool -genkey -alias ogsample -keystore key.jks -storetype JKS -keyalg rsa -dname "CN=ogsample, OU=OGSample, O=acme, L=Your City, S=Your State, C=Your Country" -storepass ogpass -keypass ogpass -validity 3650

     Using this command, a keystore key.jks is created with a key "ogsample" stored in it. This keystore key.jks will be used as the SSL keystore.

   • Export the public certificate

     keytool -export -alias ogsample -keystore key.jks -file temp.key -storepass ogpass

     Using this command, the public certificate of key "ogsample" is extracted and stored in the file temp.key.

   • Import the client's public certificate to the trust store

     keytool -import -noprompt -alias ogsamplepublic -keystore trust.jks -file temp.key -storepass ogpass

     Using this command, the public certificate was added to keystore trust.jks. This trust.jks is used as the SSL trust store.

2. Configure ObjectGrid property files.

   In this step, you must configure the ObjectGrid property files to enable transport security.

   First, copy the key.jks and trust.jks files into the objectgridRoot/security directory.

   Set the following properties in the client.properties and server.properties file.

   transportType=SSL-Required
   
   alias=ogsample
   contextProvider=IBMJSSE2
   protocol=SSL
   keyStoreType=JKS
   keyStore=../security/key.jks
   keyStorePassword=ogpass
   trustStoreType=JKS
   trustStore=../security/trust.jks
   trustStorePassword=ogpass

   transportType: The value of transportType is set to "SSL-Required", which means the transport requires SSL. So all the ObjectGrid endpoints (clients, catalog servers, and container servers) should have SSL configuration set and all transport communication will be encrypted.

   The other properties are used to set the SSL configurations. See Transport layer security and secure sockets layer for a detailed explanation. Make sure you follow the instructions in this topic to update your orb.properties file.

   Make sure you follow this page to update your orb.properties file.

   In the server.properties file, you must add an additional property clientAuthentication and set it to false. On the server side, you do not need to trust the client.

   clientAuthentication=false

3. Run the application.

   The commands that you use in this step are the same as the commands in the Java SE security tutorial - Step 3 topic.

   1. Navigate to the cd objectgridRoot/bin directory, and use the following commands to start a catalog server:
      • 

        ./startOgServer.sh catalogServer -clusterSecurityFile ../security/security.xml 
        -serverProps ../security/server.properties -JMXServicePort 11001 
        -jvmArgs -Djava.security.auth.login.config="../security/og_jaas.config"

      • 

        startOgServer.bat catalogServer -clusterSecurityFile ..\security\security.xml 
        -serverProps ..\security\server.properties -JMXServicePort 11001 -jvmArgs 
        -Djava.security.auth.login.config="..\security\og_jaas.config"

      • 

        ./startXsServer.sh catalogServer -clusterSecurityFile ../security/security.xml 
        -serverProps ../security/server.properties -JMXServicePort 11001 
        -jvmArgs -Djava.security.auth.login.config="../security/og_jaas.config"

      • 

        startXsServer.bat catalogServer -clusterSecurityFile ..\security\security.xml 
        -serverProps ..\security\server.properties -JMXServicePort 11001 -jvmArgs 
        -Djava.security.auth.login.config="..\security\og_jaas.config"

      The security.xml and server.properties files were created in the Java SE security tutorial - Step 2 page.

      Use the -JMXServicePort option to explicitly specify the JMX port for the server. This option is required to use the xscmd utility.

   2. From the objectgridRoot/bin directory, start a secure ObjectGrid container server:
      • 

        ./startOgServer.sh c0 -objectGridFile ../xml/SecureSimpleApp.xml 
        -deploymentPolicyFile ../xml/SimpleDP.xml -catalogServiceEndPoints 
        localhost:2809 -serverProps ../security/server.properties 
        -JMXServicePort 11002 -jvmArgs 
        -Djava.security.auth.login.config="../security/og_jaas.config" 
        -Djava.security.policy="../security/og_auth.policy"

      • 

        startOgServer.bat c0 -objectGridFile ..\xml\SecureSimpleApp.xml 
        -deploymentPolicyFile ..\xml\SimpleDP.xml -catalogServiceEndPoints localhost:2809 
        -serverProps ..\security\server.properties -JMXServicePort 11002 
        -jvmArgs -Djava.security.auth.login.config="..\security\og_jaas.config" 
        -Djava.security.policy="..\security\og_auth.policy"

      • 

        ./startXsServer.sh c0 -objectGridFile ../xml/SecureSimpleApp.xml 
        -deploymentPolicyFile ../xml/SimpleDP.xml -catalogServiceEndPoints 
        localhost:2809 -serverProps ../security/server.properties 
        -JMXServicePort 11002 -jvmArgs 
        -Djava.security.auth.login.config="../security/og_jaas.config" 
        -Djava.security.policy="../security/og_auth.policy"

      • 

        startXsServer.bat c0 -objectGridFile ..\xml\SecureSimpleApp.xml 
        -deploymentPolicyFile ..\xml\SimpleDP.xml -catalogServiceEndPoints localhost:2809 
        -serverProps ..\security\server.properties -JMXServicePort 11002 
        -jvmArgs -Djava.security.auth.login.config="..\security\og_jaas.config" 
        -Djava.security.policy="..\security\og_auth.policy"

   3. From the objectgridRoot/bin directory, run the following command to complete client authentication:
      • 

        javaHome/java -classpath ../lib/objectgrid.jar:../applib/sec_sample.jar 
        com.ibm.websphere.objectgrid.security.sample.guide.SecureSimpleApp 
        ../security/client.properties manager manager1

      • 

        javaHome\java -classpath ..\lib\objectgrid.jar;..\applib\sec_sample.jar 
        com.ibm.websphere.objectgrid.security.sample.guide.SecureSimpleApp 
        ..\security\client.properties manager manager1

      Because user "manager" has permission to all the maps in the accounting ObjectGrid, the application runs successfully.

4. Use the xscmd utility to show the map sizes of the "accounting" data grid.
   1. From the objectgridRoot/bin directory, use the xscmd command to show the map sizes:
      • 

        ./xscmd.sh -c showMapsizes -g accounting -m customer -prot SSL 
        -ts ../security/trust.jks -tsp ogpass -tst jks 
        -user manager -pwd manager1 -ks ../security/key.jks -ksp ogpass -kst JKS 
        -cxpv IBMJSSE2 -tt SSL-Required
        
        

      • 

        xscmd.bat -c showMapsizes -g accounting -m customer -prot SSL 
        -ts ..\security\trust.jks -tsp ogpass -tst jks 
        -user manager -pwd manager1 -ks ..\security\key.jks -ksp ogpass -kst JKS 
        -cxpv IBMJSSE2 -tt SSL-Required
        

      You see the following output.

      This administrative utility is provided as a sample only and is not to 
      be considered a fully supported component of the WebSphere eXtreme Scale product.
      Connecting to Catalog service at localhost:1099
      *********** Displaying Results for Grid - accounting, MapSet - customer ***********
      *** Listing Maps for c0 ***
      Map Name: customer Partition #: 0 Map Size: 1 Shard Type: Primary
      Server Total: 1
      Total Domain Count: 1

5. Troubleshoot running the application with an incorrect keystore.

   If your truststore does not contain the public certificate of the private key in the keystore, an exception that the key cannot be trusted occurs.

   To show this exception, create another keystore key2.jks.

   keytool -genkey -alias ogsample -keystore key2.jks -storetype JKS -keyalg rsa -dname "CN=ogsample, OU=Your Organizational Unit, O=Your Organization, L=Your City, S=Your State, C=Your Country" -storepass ogpass -keypass ogpass -validity 3650

   Then modify the server.properties file to make the keystore point to this new keystore key2.jks:

   keyStore=../security/key2.jks

   1. From the cd objectgridRoot/bin directory, assume that you run the following commands, which use an incorrect keystore, to start the catalog server:
      • 

        ./startOgServer.sh c0 -objectGridFile ../xml/SecureSimpleApp.xml 
        -deploymentPolicyFile ../xml/SimpleDP.xml -catalogServiceEndPoints localhost:2809 
        -serverProps ../security/server.properties -JMXServicePort 11002 -jvmArgs 
        -Djava.security.auth.login.config="../security/og_jaas.config" 
        -Djava.security.policy="../security/og_auth.policy"

      • 

        startOgServer.bat c0 -objectGridFile ..\xml\SecureSimpleApp.xml 
        -deploymentPolicyFile ..\xml/SimpleDP.xml -catalogServiceEndPoints localhost:2809
         -serverProps ..\security\server.properties -JMXServicePort 11002 -jvmArgs 
        -Djava.security.auth.login.config="..\security\og_jaas.config" 
        -Djava.security.policy="..\security\og_auth.policy"

      • 
        

        ./startXsServer.sh c0 -objectGridFile ../xml/SecureSimpleApp.xml 
        -deploymentPolicyFile ../xml/SimpleDP.xml -catalogServiceEndPoints localhost:2809 
        -serverProps ../security/server.properties -JMXServicePort 11002 -jvmArgs 
        -Djava.security.auth.login.config="../security/og_jaas.config" 
        -Djava.security.policy="../security/og_auth.policy"

      • 
        

        startXsServer.bat c0 -objectGridFile ..\xml\SecureSimpleApp.xml 
        -deploymentPolicyFile ..\xml/SimpleDP.xml -catalogServiceEndPoints localhost:2809
         -serverProps ..\security\server.properties -JMXServicePort 11002 -jvmArgs 
        -Djava.security.auth.login.config="..\security\og_jaas.config" 
        -Djava.security.policy="..\security\og_auth.policy"

      You receive the following exception:

      CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN "CN=ogsample, 
      OU=Your Organizational Unit, O=Your Organization, L=Your City, ST=Your State, 
      C=Your Country" was sent from target host:port "9.23.39.177:36407". The signer may 
      need to be added to local trust store 
      "/opt/IBM/WebSphere/eXtremeScale/ObjectGrid/security/trust.jks" 
      located in SSL configuration alias "DefaultSystemProperties" loaded from SSL 
      configuration file "System Properties". The extended error message from the SSL 
      handshake exception is: "PKIX path building failed: java.security.cert.CertPathBuilderException: 
      unable to find valid certification path to requested target".
      
      CWPKI0040I: An SSL handshake failure occurred from a secure client. The server's SSL signer 
      has to be added to the client's trust store. A retrieveSigners utility is provided to download 
      signers from the server but requires administrative permission. Check with your administrator 
      to have this utility run to setup the secure environment before running the client. Alternatively, 
      the com.ibm.ssl.enableSignerExchangePrompt can be enabled in ssl.client.props for "DefaultSSLSettings" 
      in order to allow acceptance of the signer during the connection attempt.

      To correct the exception, change the server.properties file back to use the key.jks file.