Product overview > Tutorials, examples, and samples > Java SE security tutorial: overview



Java SE security tutorial - Step 4

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


Before you begin

Be sure you have completed Java SE security tutorial - Step 3 prior to proceeding with this task.

The eXtreme Scale topology supports both Transport Layer Security/Secure Sockets Layer (TLS/SSL) for secure communication between ObjectGrid endpoints (client, container servers, and catalog servers). This step of the tutorial builds upon the previous steps to enable transport security.


Procedure

  1. Create TLS/SSL keys and key stores

    In order to enable transport security, create a key store 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 key store

      keytool -genkey -alias ogsample -keystore key.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

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

    • Export the public certificate

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

      Use 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

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

  2. Configure ObjectGrid property files

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

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

    We 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, 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 are the same as the commands in the Java SE security tutorial - Step 3 topic.

    Use the following commands to start a catalog server.

    1. Navigate to the bin directory: cd objectgridRoot/bin

    2. Start the catalog server:

      • [Linux][Unix] 

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

      • [Windows] 

        startOgServer.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 xsadmin command.

      Run a secure ObjectGrid container server:

    3. Navigate to the bin directory again: cd objectgridRoot/bin

      • [Linux][Unix] 

        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.auth.policy="../security/og_auth.policy"

      • [Windows] 

        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.auth.policy="../security/og_auth.policy"

    Notice the following differences from the previous container server start command:

    • Use SecureSimpleApp.xml instead of SimpleApp.xml

    • Add another -Djava.security.auth.policy to set the JAAS authorization policy file to the container server process.

    Run the following command for client authentication:

    1. cd objectgridRoot/bin 

    2. javaHome/java -classpath ../lib/objectgrid.jar;../applib/secsample.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.

    You may also use xsadmin to show the mapsizes of the "accounting" grid.

    • Navigate to the directory objectgridRoot/bin.

    • Use the xsadmin command with option -mapSizes as follows.

      • [Unix][Linux] 

        xsadmin.sh -g accounting -m mapSet1 -mapsizes -p 11001 -ssl 
-trustpath ..\security\trust.jks -trustpass ogpass -trusttype jks 
-username manager -password manager1

      • [Windows] 

        xsadmin.bat -g accounting -m mapSet1 -mapsizes -p 11001 -ssl 
-trustpath ..\security\trust.jks -trustpass ogpass -trusttype jks 
-username manager -password manager1

      Notice we specify the JMX port of the catalog service using -p 11001 here.

      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 - mapSet1 ***********
*** Listing Maps for c0 ***
Map Name: customer Partition #: 0 Map Size: 1 Shard Type: Primary
Server Total: 1
Total Domain Count: 1


    Run the application with an incorrect key store

    If your trust store does not contain the public certificate of the private key in the key store, we will get an exception complaining that the key cannot be trusted.

    In order to show this, create another key store 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 to make the keyStore point to this new key store key2.jks:

    keyStore=../security/key2.jks

    Run the following command to start the catalog server:

    1. Navigate to bin: cd objectgridRoot/bin

    2. Start the catalog server:

      [Linux][Unix] 

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

      [Windows] 

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

      You see the following exception: 

      Caused by: com.ibm.websphere.objectgrid.ObjectGridRPCException:
    com.ibm.websphere.objectgrid.ObjectGridRuntimeException:
        SSL connection fails and plain socket cannot be used.

      Finally, change the server.properties file back to use the key.jks file.


Parent topic:

Java SE security tutorial: overview


Previous topic:

Java SE security tutorial - Step 3


+

Search Tips   |   Advanced Search