Developer Guide

Procedure 1.1. Adding Custom Interceptors

1. Define Custom Interceptors

   All custom interceptors must extend org.jboss.cache.interceptors.base.CommandInterceptor. Use the customInterceptors method to add custom interceptors to the cache:

   <namedCache name="cacheWithCustomInterceptors">
      <customInterceptors>

   Copy to Clipboard Toggle word wrap

2. Define the Position of the New Custom Interceptor

   Interceptors must have a defined position. Valid options are:

   • FIRST - Specifies that the new interceptor is placed first in the chain.
   • LAST - Specifies that the new interceptor is placed last in the chain.
   • OTHER_THAN_FIRST_OR_LAST - Specifies that the new interceptor can be placed anywhere except first or last in the chain.

   <namedCache name="cacheWithCustomInterceptors">
      <customInterceptors>
         <interceptor position="FIRST" class="com.mycompany.CustomInterceptor1">

   Copy to Clipboard Toggle word wrap

   • Define Interceptor Properties

     Define specific interceptor properties.

     <namedCache name="cacheWithCustomInterceptors">
        <customInterceptors>
           <interceptor position="FIRST" class="com.mycompany.CustomInterceptor1">
              <properties>
                 <property name="attributeOne" value="value1" />
                 <property name="attributeTwo" value="value2" />
              </properties>
           </interceptor>

     Copy to Clipboard Toggle word wrap

3. Apply Other Custom Interceptors

   In this example, the next custom interceptor is called CustomInterceptor2.

   <namedCache name="cacheWithCustomInterceptors">
      <customInterceptors>
         <interceptor position="FIRST" class="com.mycompany.CustomInterceptor1">
            <properties>
               <property name="attributeOne" value="value1" />
               <property name="attributeTwo" value="value2" />
            </properties>
         </interceptor>
         <interceptor position="LAST" class="com.mycompany.CustomInterceptor2"/>

   Copy to Clipboard Toggle word wrap

4. Define the index, before, and after Attributes.

   • The index identifies the position of this interceptor in the chain, with 0 being the first position. This attribute is mutually exclusive with position, before, and after.
   • The after method places the new interceptor directly after the instance of the named interceptor specified via its fully qualified class name. This attribute is mutually exclusive with position, before, and index.
   • The before method places the new interceptor directly before the instance of the named interceptor specified via its fully qualified class name. This attribute is mutually exclusive with position, after, and index.

   <namedCache name="cacheWithCustomInterceptors">
      <customInterceptors>
         <interceptor position="FIRST" class="com.mycompany.CustomInterceptor1">
            <properties>
               <property name="attributeOne" value="value1" />
               <property name="attributeTwo" value="value2" />
            </properties>
         </interceptor>
         <interceptor position="LAST" class="com.mycompany.CustomInterceptor2"/>
         <interceptor index="3" class="com.mycompany.CustomInterceptor1"/>
         <interceptor before="org.infinispan.interceptors.CallInterceptor" class="com.mycompany.CustomInterceptor2"/>
         <interceptor after="org.infinispan.interceptors.CallInterceptor" class="com.mycompany.CustomInterceptor1"/>
      </customInterceptors>
   </namedCache>
   

   Copy to Clipboard Toggle word wrap

Procedure 8.1. Setup a new Java Security Manager Policy

1. Start policytool.

   Start the policytool tool in one of the following ways.

   • Red Hat Enterprise Linux

     From your GUI or a command prompt, run /usr/bin/policytool.

   • Microsoft Windows Server

     Run policytool.exe from your Start menu or from the bin\ of your Java installation. The location can vary.

2. Create a policy.

   To create a policy, select Add Policy Entry. Add the parameters you need, then click Done.

3. Edit an existing policy

   Select the policy from the list of existing policies, and select the Edit Policy Entry button. Edit the parameters as needed.

4. Delete an existing policy.

   Select the policy from the list of existing policies, and select the Remove Policy Entry button.

Procedure 8.2. Configure the Security Manager for JBoss Data Grid Server

1. Open the configuration file.

   Open the configuration file for editing. This file is located in one of two places, depending on whether you use a managed domain or standalone server. This is not the executable file used to start the server or domain.

   • Managed Domain

     • For Linux: JDG_HOME/bin/domain.conf
     • For Windows: JDG_HOME\bin\domain.conf.bat

   • Standalone Server

     • For Linux: JDG_HOME/bin/standalone.conf
     • For Windows: JDG_HOME\bin\standalone.conf.bat

2. Add the Java options to the file.

   To ensure the Java options are used, add them to the code block that begins with:

   if [ "x$JAVA_OPTS" = "x" ]; then
   

   Copy to Clipboard Toggle word wrap
   You can modify the -Djava.security.policy value to specify the exact location of your security policy. It should go onto one line only, with no line break. Using == when setting the -Djava.security.policy property specifies that the security manager will use only the specified policy file. Using = specifies that the security manager will use the specified policy combined with the policy set in the policy.url section of JAVA_HOME/lib/security/java.security.

   Important

   JBoss Enterprise Application Platform releases from 6.2.2 onwards require that the system property jboss.modules.policy-permissions is set to true.

   Example 8.8. domain.conf

   JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djava.security.policy==$PWD/server.policy -Djboss.home.dir=/path/to/JDG_HOME -Djboss.modules.policy-permissions=true"

   Copy to Clipboard Toggle word wrap

   Example 8.9. domain.conf.bat

   set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager -Djava.security.policy==\path\to\server.policy -Djboss.home.dir=\path\to\JDG_HOME -Djboss.modules.policy-permissions=true"

   Copy to Clipboard Toggle word wrap

   Example 8.10. standalone.conf

   JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djava.security.policy==$PWD/server.policy -Djboss.home.dir=$JBOSS_HOME -Djboss.modules.policy-permissions=true"

   Copy to Clipboard Toggle word wrap

   Example 8.11. standalone.conf.bat

   set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager -Djava.security.policy==\path\to\server.policy -Djboss.home.dir=%JBOSS_HOME% -Djboss.modules.policy-permissions=true"

   Copy to Clipboard Toggle word wrap

3. Start the domain or server.

   Start the domain or server as normal.

Procedure 8.3. Secure Hot Rod Using SSL/TLS

1. Generate a Keystore

   Create a Java Keystore using the keytool application distributed with the JDK and add your certificate to it. The certificate can be either self signed, or obtained from a trusted CA depending on your security policy.

2. Place the Keystore in the Configuration Directory

   Put the keystore in the ~/JDG_HOME/standalone/configuration directory with the standalone-hotrod-ssl.xml file from the ~/JDG_HOME/docs/examples/configs directory.

3. Declare an SSL Server Identity

   Declare an SSL server identity within a security realm in the management section of the configuration file. The SSL server identity must specify the path to a keystore and its secret key.

   <server-identities>
     <ssl protocol="...">
       <keystore path="..." relative-to="..." keystore-password="${VAULT::VAULT_BLOCK::ATTRIBUTE_NAME::ENCRYPTED_VALUE}" />
     </ssl>
     <secret value="..." />
   </server-identities>

   Copy to Clipboard Toggle word wrap
   See Section 8.7.7.4, “Configure Hot Rod Authentication (X.509)” for details about these parameters.

4. Add the Security Element

   Add the security element to the Hot Rod connector as follows:

   <hotrod-connector socket-binding="hotrod" cache-container="local">
       <encryption ssl="true" security-realm="ApplicationRealm" require-ssl-client-auth="false" />
   </hotrod-connector>

   Copy to Clipboard Toggle word wrap

   1. Server Authentication of Certificate

      If you require the server to perform authentication of the client certificate, create a truststore that contains the valid client certificates and set the require-ssl-client-auth attribute to true.

5. Start the Server

   Start the server using the following:

   bin/standalone.sh -c standalone-hotrod-ssl.xml

   Copy to Clipboard Toggle word wrap

   This will start a server with a Hot Rod endpoint on port 11222. This endpoint will only accept SSL connections.

Procedure 8.4. Configure SASL GSSAPI/Kerberos Authentication

1. Server-side Configuration

   The following steps must be configured on the server-side:
   1. Define a Kerberos security login module using the security domain subsystem:

      <system-properties>
          <property name="java.security.krb5.conf" value="/tmp/infinispan/krb5.conf"/>
          <property name="java.security.krb5.debug" value="true"/>
          <property name="jboss.security.disable.secdomain.option" value="true"/>
      </system-properties>
      
      <security-domain name="infinispan-server" cache-type="default">
          <authentication>
              <login-module code="Kerberos" flag="required">
                  <module-option name="debug" value="true"/>
                  <module-option name="storeKey" value="true"/>
                  <module-option name="refreshKrb5Config" value="true"/>
                  <module-option name="useKeyTab" value="true"/>
                  <module-option name="doNotPrompt" value="true"/>
                  <module-option name="keyTab" value="/tmp/infinispan/infinispan.keytab"/>
                  <module-option name="principal" value="HOTROD/localhost@INFINISPAN.ORG"/>
              </login-module>
          </authentication>
      </security-domain>

      Copy to Clipboard Toggle word wrap
   2. Configure a Hot Rod connector as follows:

      <hotrod-connector socket-binding="hotrod" 
      		  cache-container="default">
      	<authentication security-realm="ApplicationRealm">
      		<sasl server-name="node0" 
      		      mechanisms="{mechanism_name}" 
      		      qop="{qop_name}" 
      		      strength="{value}">
      			<policy>
      				<no-anonymous value="true" />
      			</policy>
      			<property name="com.sun.security.sasl.digest.utf8">true</property>
      		</sasl>
        </authentication>
      </hotrod-connector>

      Copy to Clipboard Toggle word wrap
      • The server-name attribute specifies the name that the server declares to incoming clients. The client configuration must also contain the same server name value.
      • The server-context-name attribute specifies the name of the login context used to retrieve a server subject for certain SASL mechanisms (for example, GSSAPI).
      • The mechanisms attribute specifies the authentication mechanism in use. See Section 8.7.7, “User Authentication over Hot Rod Using SASL” for a list of supported mechanisms.
      • The qop attribute specifies the SASL quality of protection value for the configuration. Supported values for this attribute are auth (authentication), auth-int (authentication and integrity, meaning that messages are verified against checksums to detect tampering), and auth-conf (authentication, integrity, and confidentiality, meaning that messages are also encrypted). Multiple values can be specified, for example, auth-int auth-conf. The ordering implies preference, so the first value which matches both the client and server's preference is chosen.
      • The strength attribute specifies the SASL cipher strength. Valid values are low, medium, and high.
      • The no-anonymous element within the policy element specifies whether mechanisms that accept anonymous login are permitted. Set this value to false to permit and true to deny.

2. Client-side Configuration

   The following steps must be configured on the client-side:
   1. Define a login module in a login configuration file (gss.conf) on the client side:

      GssExample {
          com.sun.security.auth.module.Krb5LoginModule required client=TRUE;
      };

      Copy to Clipboard Toggle word wrap
   2. Set up the following system properties:

      java.security.auth.login.config=gss.conf
      java.security.krb5.conf=/etc/krb5.conf

      Copy to Clipboard Toggle word wrap

      Note

      The krb5.conf file is dependent on the environment and must point to the Kerberos Key Distribution Center.
   3. Configure the Hot Rod Client:

      public class MyCallbackHandler implements CallbackHandler {
         final private String username;
         final private char[] password;
         final private String realm;
      
         public MyCallbackHandler() { }
      
         public MyCallbackHandler (String username, String realm, char[] password) {
            this.username = username;
            this.password = password;
            this.realm = realm;
         }
      
         @Override
         public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
            for (Callback callback : callbacks) {
               if (callback instanceof NameCallback) {
                  NameCallback nameCallback = (NameCallback) callback;
                  nameCallback.setName(username);
               } else if (callback instanceof PasswordCallback) {
                  PasswordCallback passwordCallback = (PasswordCallback) callback;
                  passwordCallback.setPassword(password);
               } else if (callback instanceof AuthorizeCallback) {
                  AuthorizeCallback authorizeCallback = (AuthorizeCallback) callback;
                  authorizeCallback.setAuthorized(authorizeCallback.getAuthenticationID().equals(
                        authorizeCallback.getAuthorizationID()));
               } else if (callback instanceof RealmCallback) {
                  RealmCallback realmCallback = (RealmCallback) callback;
                  realmCallback.setText(realm);
               } else {
                  throw new UnsupportedCallbackException(callback);
               }
            }
         }}
      LoginContext lc = new LoginContext("GssExample", new MyCallbackHandler("krb_user", "krb_password".toCharArray()));lc.login();Subject clientSubject = lc.getSubject();
      ConfigurationBuilder clientBuilder = new ConfigurationBuilder();clientBuilder
          .addServer()
              .host("127.0.0.1")
              .port(11222)
          .socketTimeout(1200000)
          .security()
              .authentication()
                  .enable()
                  .serverName("infinispan-server")
                  .saslMechanism("GSSAPI")
                  .clientSubject(clientSubject)
                  .callbackHandler(new MyCallbackHandler());remoteCacheManager = new RemoteCacheManager(clientBuilder.build());RemoteCache<String, String> cache = remoteCacheManager.getCache("secured");

      Copy to Clipboard Toggle word wrap

Procedure 8.5. Configure Hot Rod Authentication (MD5)

1. Set up the Hot Rod Connector configuration by adding the sasl element to the authentication element (for details on the authentication element, see Section 8.7.4, “Configuring Security Realms Declaratively”) as follows:

   <hotrod-connector socket-binding="hotrod" 
                               cache-container="default">
       <authentication security-realm="ApplicationRealm">
           <sasl server-name="myhotrodserver" 
                    mechanisms="DIGEST-MD5" 
                    qop="auth" />
       </authentication>
   </hotrod-connector>

   Copy to Clipboard Toggle word wrap
   • The server-name attribute specifies the name that the server declares to incoming clients. The client configuration must also contain the same server name value.
   • The mechanisms attribute specifies the authentication mechanism in use. See Section 8.7.7, “User Authentication over Hot Rod Using SASL” for a list of supported mechanisms.
   • The qop attribute specifies the SASL quality of production value for the configuration. Supported values for this attribute are auth, auth-int, and auth-conf.
2. Connect the client to the configured Hot Rod connector as follows:

   public class MyCallbackHandler implements CallbackHandler {
      final private String username;
      final private char[] password;
      final private String realm;
   
      public MyCallbackHandler (String username, String realm, char[] password) {
         this.username = username;
         this.password = password;
         this.realm = realm;
      }
   
      @Override
      public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
         for (Callback callback : callbacks) {
            if (callback instanceof NameCallback) {
               NameCallback nameCallback = (NameCallback) callback;
               nameCallback.setName(username);
            } else if (callback instanceof PasswordCallback) {
               PasswordCallback passwordCallback = (PasswordCallback) callback;
               passwordCallback.setPassword(password);
            } else if (callback instanceof AuthorizeCallback) {
               AuthorizeCallback authorizeCallback = (AuthorizeCallback) callback;
               authorizeCallback.setAuthorized(authorizeCallback.getAuthenticationID().equals(
                     authorizeCallback.getAuthorizationID()));
            } else if (callback instanceof RealmCallback) {
               RealmCallback realmCallback = (RealmCallback) callback;
               realmCallback.setText(realm);
            } else {
               throw new UnsupportedCallbackException(callback);
            }
         }
      }}
   ConfigurationBuilder clientBuilder = new ConfigurationBuilder();clientBuilder
       .addServer()
           .host("127.0.0.1")
           .port(11222)
       .socketTimeout(1200000)
       .security()
           .authentication()
               .enable()
               .serverName("myhotrodserver")
               .saslMechanism("DIGEST-MD5")
               .callbackHandler(new MyCallbackHandler("myuser", "ApplicationRealm", "qwer1234!".toCharArray()));remoteCacheManager = new RemoteCacheManager(clientBuilder.build());RemoteCache<String, String> cache = remoteCacheManager.getCache("secured");

   Copy to Clipboard Toggle word wrap