[jboss-cvs] JBossAS SVN: r105082 - projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri May 21 00:00:05 EDT 2010
Author: jaredmorgs
Date: 2010-05-21 00:00:05 -0400 (Fri, 21 May 2010)
New Revision: 105082
Removed:
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/part-Encryption_and _Security.xml
Log:
just cleaning up the repo
Deleted: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/part-Encryption_and _Security.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/part-Encryption_and _Security.xml 2010-05-21 00:09:09 UTC (rev 105081)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/part-Encryption_and _Security.xml 2010-05-21 04:00:05 UTC (rev 105082)
@@ -1,1058 +0,0 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<part>
- <title>Encryption and Security</title>
- <chapter id="chap-The_Secure_Remote_Password_SRP_Protocol">
- <title>Secure Remote Password Protocol</title>
- <para>
- The Secure Remote Password (SRP) protocol is an implementation of a public key exchange handshake described in the Internet standards working group request for comments 2945(RFC2945). The RFC2945 abstract states:
- </para>
- <para>
- This document describes a cryptographically strong network authentication mechanism known as the Secure Remote Password (SRP) protocol. This mechanism is suitable for negotiating secure connections using a user-supplied password, while eliminating the security problems traditionally associated with reusable passwords. This system also performs a secure key exchange in the process of authentication, allowing security layers (privacy and/or integrity protection) to be enabled during the session. Trusted key servers and certificate infrastructures are not required, and clients are not required to store or manage any long-term keys. SRP offers both security and deployment advantages over existing challenge-response techniques, making it an ideal drop-in replacement where secure password authentication is needed.
- </para>
- <para>
- Note: The complete RFC2945 specification can be obtained from <ulink url="http://www.rfc-editor.org/rfc.html"/>. Additional information on the SRP algorithm and its history can be found at <ulink url="http://www-cs-students.stanford.edu/~tjw/srp/"/>.
- </para>
- <para>
- SRP is similar in concept and security to other public key exchange algorithms, such as Diffie-Hellman and RSA. SRP is based on simple string passwords in a way that does not require a clear text password to exist on the server. This is in contrast to other public key-based algorithms that require client certificates and the corresponding certificate management infrastructure.
- </para>
- <para>
- Algorithms like Diffie-Hellman and RSA are known as public key exchange algorithms. The concept of public key algorithms is that you have two keys, one public that is available to everyone, and one that is private and known only to you. When someone wants to send encrypted information to you, then encrpyt the information using your public key. Only you are able to decrypt the information using your private key. Contrast this with the more traditional shared password based encryption schemes that require the sender and receiver to know the shared password. Public key algorithms eliminate the need to share passwords.
- </para>
- <para>
- The JBossSX framework includes an implementation of SRP that consists of the following elements:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- An implementation of the SRP handshake protocol that is independent of any particular client/server protocol
- </para>
- </listitem>
- <listitem>
- <para>
- An RMI implementation of the handshake protocol as the default client/server SRP implementation
- </para>
- </listitem>
- <listitem>
- <para>
- A client side JAAS <literal>LoginModule</literal> implementation that uses the RMI implementation for use in authenticating clients in a secure fashion
- </para>
- </listitem>
- <listitem>
- <para>
- A JMX MBean for managing the RMI server implementation. The MBean allows the RMI server implementation to be plugged into a JMX framework and externalizes the configuration of the verification information store. It also establishes an authentication cache that is bound into the JBoss server JNDI namespace.
- </para>
- </listitem>
- <listitem>
- <para>
- A server side JAAS <literal>LoginModule</literal> implementation that uses the authentication cache managed by the SRP JMX MBean.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <xref linkend="The_Secure_Remote_Password_SRP_Protocol-The_JBossSX_components_of_the_SRP_client_server_framework."/> gives a diagram of the key components involved in the JBossSX implementation of the SRP client/server framework.
- </para>
- <figure id="The_Secure_Remote_Password_SRP_Protocol-The_JBossSX_components_of_the_SRP_client_server_framework.">
- <title>The JBossSX components of the SRP client-server framework.</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/j2ee_chap8-13.jpg"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- On the client side, SRP shows up as a custom JAAS <literal>LoginModule</literal> implementation that communicates to the authentication server through an <literal>org.jboss.security.srp.SRPServerInterface</literal> proxy. A client enables authentication using SRP by creating a login configuration entry that includes the <literal>org.jboss.security.srp.jaas.SRPLoginModule</literal>. This module supports the following configuration options:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">principalClassName</emphasis>: This option is no longer supported. The principal class is now always <literal>org.jboss.security.srp.jaas.SRPPrincipal</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">srpServerJndiName</emphasis>: The JNDI name of the <literal>SRPServerInterface</literal> object to use for communicating with the SRP authentication server. If both <literal>srpServerJndiName</literal> and <literal>srpServerRmiUrl</literal> options are specified, the <literal>srpServerJndiName</literal> is tried before <literal>srpServerRmiUrl</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">srpServerRmiUrl</emphasis>: The RMI protocol URL string for the location of the <literal>SRPServerInterface</literal> proxy to use for communicating with the SRP authentication server.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">externalRandomA</emphasis>: A true/false flag indicating if the random component of the client public key A should come from the user callback. This can be used to input a strong cryptographic random number coming from a hardware token for example.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">hasAuxChallenge</emphasis>: A true/false flag indicating that a string will be sent to the server as an additional challenge for the server to validate. If the client session supports an encryption cipher then a temporary cipher will be created using the session private key and the challenge object sent as a <literal>javax.crypto.SealedObject</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">multipleSessions</emphasis>: a true/false flag indicating if a given client may have multiple SRP login sessions active simultaneously.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Any other options passed in that do not match one of the previous named options is treated as a JNDI property to use for the environment passed to the <literal>InitialContext</literal> constructor. This is useful if the SRP server interface is not available from the default <literal>InitialContext</literal>.
- </para>
- <para>
- The <literal>SRPLoginModule</literal> needs to be configured along with the standard <literal>ClientLoginModule</literal> to allow the SRP authentication credentials to be used for validation of access to security Java EE components. An example login configuration entry that demonstrates such a setup is:
- </para>
- <programlisting>srp {
- org.jboss.security.srp.jaas.SRPLoginModule required
- srpServerJndiName="SRPServerInterface"
- ;
-
- org.jboss.security.ClientLoginModule required
- password-stacking="useFirstPass"
- ;
-};
-</programlisting>
- <para>
- On the JBoss server side, there are two MBeans that manage the objects that collectively make up the SRP server. The primary service is the <literal>org.jboss.security.srp.SRPService</literal> MBean, and it is responsible for exposing an RMI accessible version of the SRPServerInterface as well as updating the SRP authentication session cache. The configurable SRPService MBean attributes include the following:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">JndiName</emphasis>: The JNDI name from which the SRPServerInterface proxy should be available. This is the location where the <literal>SRPService</literal> binds the serializable dynamic proxy to the <literal>SRPServerInterface</literal>. If not specified it defaults to <literal>srp/SRPServerInterface</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">VerifierSourceJndiName</emphasis>: The JNDI name of the <literal>SRPVerifierSource</literal> implementation that should be used by the <literal>SRPService</literal>. If not set it defaults to <literal>srp/DefaultVerifierSource</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">AuthenticationCacheJndiName</emphasis>: The JNDI name under which the authentication <literal>org.jboss.util.CachePolicy</literal> implementation to be used for caching authentication information is bound. The SRP session cache is made available for use through this binding. If not specified it defaults to <literal>srp/AuthenticationCache</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">ServerPort</emphasis>: RMI port for the <literal>SRPRemoteServerInterface</literal>. If not specified it defaults to 10099.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">ClientSocketFactory</emphasis>: An optional custom <literal>java.rmi.server.RMIClientSocketFactory</literal> implementation class name used during the export of the <literal>SRPServerInterface</literal>. If not specified the default <literal>RMIClientSocketFactory</literal> is used.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">ServerSocketFactory</emphasis>: An optional custom <literal>java.rmi.server.RMIServerSocketFactory</literal> implementation class name used during the export of the <literal>SRPServerInterface</literal>. If not specified the default <literal>RMIServerSocketFactory</literal> is used.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">AuthenticationCacheTimeout</emphasis>: Specifies the timed cache policy timeout in seconds. If not specified this defaults to 1800 seconds(30 minutes).
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">AuthenticationCacheResolution</emphasis>: Specifies the timed cache policy resolution in seconds. This controls the interval between checks for timeouts. If not specified this defaults to 60 seconds(1 minute).
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">RequireAuxChallenge</emphasis>: Set if the client must supply an auxiliary challenge as part of the verify phase. This gives control over whether the <literal>SRPLoginModule</literal> configuration used by the client must have the <literal>useAuxChallenge</literal> option enabled.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">OverwriteSessions</emphasis>: A flag indicating if a successful user auth for an existing session should overwrite the current session. This controls the behavior of the server SRP session cache when clients have not enabled the multiple session per user mode. The default is false meaning that the second attempt by a user to authentication will succeed, but the resulting SRP session will not overwrite the previous SRP session state.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The one input setting is the <literal>VerifierSourceJndiName</literal> attribute. This is the location of the SRP password information store implementation that must be provided and made available through JNDI. The <literal>org.jboss.security.srp SRPVerifierStoreService</literal> is an example MBean service that binds an implementation of the <literal>SRPVerifierStore</literal> interface that uses a file of serialized objects as the persistent store. Although not realistic for a production environment, it does allow for testing of the SRP protocol and provides an example of the requirements for an <literal>SRPVerifierStore</literal> service. The configurable <literal>SRPVerifierStoreService</literal> MBean attributes include the following:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">JndiName</emphasis>: The JNDI name from which the <literal>SRPVerifierStore</literal> implementation should be available. If not specified it defaults to <literal>srp/DefaultVerifierSource</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">StoreFile</emphasis>: The location of the user password verifier serialized object store file. This can be either a URL or a resource name to be found in the classpath. If not specified it defaults to <literal>SRPVerifierStore.ser</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The <literal>SRPVerifierStoreService</literal> MBean also supports <literal>addUser</literal> and <literal>delUser</literal> operations for addition and deletion of users. The signatures are:
- </para>
- <programlisting language="Java" role="JAVA">public void addUser(String username, String password) throws IOException;
-public void delUser(String username) throws IOException;
-</programlisting>
- <para>
- An example configuration of these services is presented in <xref linkend="Providing_Password_Information_for_SRP-The_SRPVerifierStore_Interface"/>.
- </para>
- <section id="The_Secure_Remote_Password_SRP_Protocol-Providing_Password_Information_for_SRP">
- <title>Providing Password Information for SRP</title>
- <para>
- The default implementation of the <literal>SRPVerifierStore</literal> interface is not likely to be suitable for your production security environment as it requires all password hash information to be available as a file of serialized objects. </para>
- <para>You need to provide an MBean service that provides an implementation of the <literal>SRPVerifierStore</literal> interface that integrates with your existing security information stores. The <literal>SRPVerifierStore</literal> interface is shown in <xref linkend="Providing_Password_Information_for_SRP-The_SRPVerifierStore_Interface"/>.
- </para>
- <example id="Providing_Password_Information_for_SRP-The_SRPVerifierStore_Interface">
- <title>The SRPVerifierStore interface</title>
- <programlisting language="Java" role="JAVA">package org.jboss.security.srp;
-
-import java.io.IOException;
-import java.io.Serializable;
-import java.security.KeyException;
-
-public interface SRPVerifierStore
-{
- public static class VerifierInfo implements Serializable
- {
- /**
- * The username the information applies to. Perhaps redundant
- * but it makes the object self contained.
- */
- public String username;
-
- /** The SRP password verifier hash */
- public byte[] verifier;
- /** The random password salt originally used to verify the password */
- public byte[] salt;
- /** The SRP algorithm primitive generator */
- public byte[] g;
- /** The algorithm safe-prime modulus */
- public byte[] N;
- }
-
- /**
- * Get the indicated user's password verifier information.
- */
- public VerifierInfo getUserVerifier(String username)
- throws KeyException, IOException;
- /**
- * Set the indicated users' password verifier information. This
- * is equivalent to changing a user's password and should
- * generally invalidate any existing SRP sessions and caches.
- */
- public void setUserVerifier(String username, VerifierInfo info)
- throws IOException;
-
- /**
- * Verify an optional auxiliary challenge sent from the client to
- * the server. The auxChallenge object will have been decrypted
- * if it was sent encrypted from the client. An example of a
- * auxiliary challenge would be the validation of a hardware token
- * (SafeWord, SecureID, iButton) that the server validates to
- * further strengthen the SRP password exchange.
- */
- public void verifyUserChallenge(String username, Object auxChallenge)
- throws SecurityException;
-}
-</programlisting>
- <para>
- The primary function of a <literal>SRPVerifierStore</literal> implementation is to provide access to the <literal>SRPVerifierStore.VerifierInfo</literal> object for a given username. The <literal>getUserVerifier(String)</literal> method is called by the <literal>SRPService</literal> at that start of a user SRP session to obtain the parameters needed by the SRP algorithm. The elements of the <literal>VerifierInfo</literal> objects are:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">username</emphasis>: The user's name or id used to login.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">verifier</emphasis>: This is the one-way hash of the password or PIN the user enters as proof of their identity. The <literal>org.jboss.security.Util</literal> class has a <literal>calculateVerifier</literal> method that performs that password hashing algorithm. The output password <literal>H(salt | H(username | ':' | password))</literal> as defined by RFC2945. Here <literal>H</literal> is the SHA secure hash function. The username is converted from a string to a <literal>byte[]</literal> using the UTF-8 encoding.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">salt</emphasis>: This is a random number used to increase the difficulty of a brute force dictionary attack on the verifier password database in the event that the database is compromised. It is a value that should be generated from a cryptographically strong random number algorithm when the user's existing clear-text password is hashed.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">g</emphasis>: The SRP algorithm primitive generator. In general this can be a well known fixed parameter rather than a per-user setting. The <literal>org.jboss.security.srp.SRPConf</literal> utility class provides several settings for g including a good default which can obtained via <literal>SRPConf.getDefaultParams().g()</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">N</emphasis>: The SRP algorithm safe-prime modulus. In general this can be a well known fixed parameter rather than a per-user setting. The <literal>org.jboss.security.srp.SRPConf</literal> utility class provides several settings for <literal>N</literal> including a good default which can obtained via <literal>SRPConf.getDefaultParams().N()</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- So, step 1 of integrating your existing password store is the creation of a hashed version of the password information. If your passwords are already store in an irreversible hashed form, then this can only be done on a per-user basis as part of an upgrade procedure for example. Note that the <literal>setUserVerifier(String, VerifierInfo)</literal> method is not used by the current SRPSerivce and may be implemented as no-op method, or even one that throws an exception stating that the store is read-only.
- </para>
- <para>
- Step 2 is the creation of the custom <literal>SRPVerifierStore</literal> interface implementation that knows how to obtain the <literal>VerifierInfo</literal> from the store you created in step 1. The <literal>verifyUserChallenge(String, Object)</literal> method of the interface is only called if the client <literal>SRPLoginModule</literal> configuration specifies the <literal>hasAuxChallenge</literal> option. This can be used to integrate existing hardware token based schemes like SafeWord or Radius into the SRP algorithm.
- </para>
- <para>
- Step 3 is the creation of an MBean that makes the step 2 implementation of the <literal>SRPVerifierStore</literal> interface available via JNDI, and exposes any configurable parameters you need. In addition to the default <literal>org.jboss.security.srp.SRPVerifierStoreService</literal> example, the SRP example presented later in this chapter provides a Java properties file based <literal>SRPVerifierStore</literal> implementation. Between the two examples you should have enough to integrate your security store.
- </para>
- </example>
- </section>
- <section id="The_Secure_Remote_Password_SRP_Protocol-Inside_of_the_SRP_algorithm">
- <title>Inside of the SRP algorithm</title>
- <para>
- The appeal of the SRP algorithm is that is allows for mutual authentication of client and server using simple text passwords without a secure communication channel. You might be wondering how this is done. If you want the complete details and theory behind the algorithm, refer to the SRP references mentioned in a note earlier. There are six steps that are performed to complete authentication:
- </para>
- <orderedlist>
- <listitem>
- <para>
- The client side <literal>SRPLoginModule</literal> retrieves the SRPServerInterface instance for the remote authentication server from the naming service.
- </para>
- </listitem>
- <listitem>
- <para>
- The client side <literal>SRPLoginModule</literal> next requests the SRP parameters associated with the username attempting the login. There are a number of parameters involved in the SRP algorithm that must be chosen when the user password is first transformed into the verifier form used by the SRP algorithm. Rather than hard-coding the parameters (which could be done with minimal security risk), the JBossSX implementation allows a user to retrieve this information as part of the exchange protocol. The <literal>getSRPParameters(username)</literal> call retrieves the SRP parameters for the given username.
- </para>
- </listitem>
- <listitem>
- <para>
- The client side <literal>SRPLoginModule</literal> begins an SRP session by creating an <literal>SRPClientSession</literal> object using the login username, clear-text password, and SRP parameters obtained from step 2. The client then creates a random number A that will be used to build the private SRP session key. The client then initializes the server side of the SRP session by invoking the <literal>SRPServerInterface.init</literal> method and passes in the username and client generated random number <literal>A</literal>. The server returns its own random number <literal>B</literal>. This step corresponds to the exchange of public keys.
- </para>
- </listitem>
- <listitem>
- <para>
- The client side <literal>SRPLoginModule</literal> obtains the private SRP session key that has been generated as a result of the previous messages exchanges. This is saved as a private credential in the login <literal>Subject</literal>. The server challenge response <literal>M2</literal> from step 4 is verified by invoking the <literal>SRPClientSession.verify</literal> method. If this succeeds, mutual authentication of the client to server, and server to client have been completed. The client side <literal>SRPLoginModule</literal> next creates a challenge <literal>M1</literal> to the server by invoking <literal>SRPClientSession.response</literal> method passing the server random number <literal>B</literal> as an argument. This challenge is sent to the server via the <literal>SRPServerInterface.verify</literal> method and server's response is saved as <literal>M2</literal>. This step corresponds to an exchange of challenges. At this point the server has verified t!
hat the user is who they say they are.
- </para>
- </listitem>
- <listitem>
- <para>
- The client side <literal>SRPLoginModule</literal> saves the login username and <literal>M1</literal> challenge into the <literal>LoginModule</literal> sharedState map. This is used as the Principal name and credentials by the standard JBoss <literal>ClientLoginModule</literal>. The <literal>M1</literal> challenge is used in place of the password as proof of identity on any method invocations on Java EE components. The <literal>M1</literal> challenge is a cryptographically strong hash associated with the SRP session. Its interception via a third partly cannot be used to obtain the user's password.
- </para>
- </listitem>
- <listitem>
- <para>
- At the end of this authentication protocol, the SRPServerSession has been placed into the SRPService authentication cache for subsequent use by the <literal>SRPCacheLoginModule</literal>.
- </para>
- </listitem>
- </orderedlist>
- <para>
- Although SRP has many interesting properties, it is still an evolving component in the JBossSX framework and has some limitations of which you should be aware. Issues of note include the following:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Because of how JBoss detaches the method transport protocol from the component container where authentication is performed, an unauthorized user could snoop the SRP <literal>M1</literal> challenge and effectively use the challenge to make requests as the associated username. Custom interceptors that encrypt the challenge using the SRP session key can be used to prevent this issue.
- </para>
- </listitem>
- <listitem>
- <para>
- The SRPService maintains a cache of SRP sessions that time out after a configurable period. Once they time out, any subsequent Java EE component access will fail because there is currently no mechanism for transparently renegotiating the SRP authentication credentials. You must either set the authentication cache timeout very long (up to 2,147,483,647 seconds, or approximately 68 years), or handle re-authentication in your code on failure.
- </para>
- </listitem>
- <listitem>
- <para>
- By default there can only be one SRP session for a given username. Because the negotiated SRP session produces a private session key that can be used for encryption/decryption between the client and server, the session is effectively a stateful one. JBoss supports for multiple SRP sessions per user, but you cannot encrypt data with one session key and then decrypt it with another.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- To use end-to-end SRP authentication for Java EE component calls, you need to configure the security domain under which the components are secured to use the <literal>org.jboss.security.srp.jaas.SRPCacheLoginModule</literal>. The <literal>SRPCacheLoginModule</literal> has a single configuration option named <literal>cacheJndiName</literal> that sets the JNDI location of the SRP authentication <literal>CachePolicy</literal> instance. This must correspond to the <literal>AuthenticationCacheJndiName</literal> attribute value of the <literal>SRPService</literal> MBean. The <literal>SRPCacheLoginModule</literal> authenticates user credentials by obtaining the client challenge from the <literal>SRPServerSession</literal> object in the authentication cache and comparing this to the challenge passed as the user credentials. <xref linkend="Inside_of_the_SRP_algorithm-A_sequence_diagram_illustrating_the_interaction_of_the_SRPCacheLoginModule_with_the_SRP_session_cache."/> illustr!
ates the operation of the SRPCacheLoginModule.login method implementation.
- </para>
- <figure id="Inside_of_the_SRP_algorithm-A_sequence_diagram_illustrating_the_interaction_of_the_SRPCacheLoginModule_with_the_SRP_session_cache.">
- <title>A sequence diagram illustrating the interaction of the SRPCacheLoginModule with the SRP session cache.</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/j2ee_chap8-14.jpg"/>
- </imageobject>
- </mediaobject>
- </figure>
- <section id="Inside_of_the_SRP_algorithm-An_SRP_example">
- <title>An SRP example</title>
- <para>
- We have covered quite a bit of material on SRP and now its time to demonstrate SRP in practice with an example. The example demonstrates client side authentication of the user via SRP as well as subsequent secured access to a simple EJB using the SRP session challenge as the user credential. The test code deploys an EJB JAR that includes a SAR for the configuration of the server side login module configuration and SRP services. As in the previous examples we will dynamically install the server side login module configuration using the <literal>SecurityConfig</literal> MBean. In this example we also use a custom implementation of the <literal>SRPVerifierStore</literal> interface that uses an in memory store that is seeded from a Java properties file rather than a serialized object store as used by the <literal>SRPVerifierStoreService</literal>. This custom service is <literal>org.jboss.book.security.ex3.service.PropertiesVerifierStore</literal>. The following shows the !
contents of the JAR that contains the example EJB and SRP services.
- </para>
- <screen>[examples]$ jar tf output/security/security-ex3.jar
-META-INF/MANIFEST.MF
-META-INF/ejb-jar.xml
-META-INF/jboss.xml
-org/jboss/book/security/ex3/Echo.class
-org/jboss/book/security/ex3/EchoBean.class
-org/jboss/book/security/ex3/EchoHome.class
-roles.properties
-users.properties
-security-ex3.sar</screen>
- <para>
- The key SRP related items in this example are the SRP MBean services configuration, and the SRP login module configurations. The <literal>jboss-service.xml</literal> descriptor of the <literal>security-ex3.sar</literal> is given in <xref linkend="An_SRP_example-The_security_ex3.sar_jboss_service.xml_descriptor_for_the_SRP_services"/>, while <xref linkend="An_SRP_example-The_client_side_standard_JAAS_configuration"/> and <xref linkend="An_SRP_example-The_server_side_XMLLoginConfig_configuration"/> give the example client side and server side login module configurations.
- </para>
- <example id="An_SRP_example-The_security_ex3.sar_jboss_service.xml_descriptor_for_the_SRP_services">
- <title>The security-ex3.sar jboss-service.xml descriptor for the SRP services</title>
- <programlisting language="XML" role="XML"><server>
- <!-- The custom JAAS login configuration that installs
- a Configuration capable of dynamically updating the
- config settings -->
-
- <mbean code="org.jboss.book.security.service.SecurityConfig"
- name="jboss.docs.security:service=LoginConfig-EX3">
- <attribute name="AuthConfig">META-INF/login-config.xml</attribute>
- <attribute name="SecurityConfigName">jboss.security:name=SecurityConfig</attribute>
- </mbean>
-
- <!-- The SRP service that provides the SRP RMI server and server side
- authentication cache -->
- <mbean code="org.jboss.security.srp.SRPService"
- name="jboss.docs.security:service=SRPService">
- <attribute name="VerifierSourceJndiName">srp-test/security-ex3</attribute>
- <attribute name="JndiName">srp-test/SRPServerInterface</attribute>
- <attribute name="AuthenticationCacheJndiName">srp-test/AuthenticationCache</attribute>
- <attribute name="ServerPort">0</attribute>
- <depends>jboss.docs.security:service=PropertiesVerifierStore</depends>
- </mbean>
-
- <!-- The SRP store handler service that provides the user password verifier
- information -->
- <mbean code="org.jboss.security.ex3.service.PropertiesVerifierStore"
- name="jboss.docs.security:service=PropertiesVerifierStore">
- <attribute name="JndiName">srp-test/security-ex3</attribute>
- </mbean>
-</server>
-</programlisting>
- </example>
- <example id="An_SRP_example-The_client_side_standard_JAAS_configuration">
- <title>The client side standard JAAS configuration</title>
- <programlisting>srp {
- org.jboss.security.srp.jaas.SRPLoginModule required
- srpServerJndiName="srp-test/SRPServerInterface"
- ;
-
- org.jboss.security.ClientLoginModule required
- password-stacking="useFirstPass"
- ;
-};
-</programlisting>
- </example>
- <example id="An_SRP_example-The_server_side_XMLLoginConfig_configuration">
- <title>The server side XMLLoginConfig configuration</title>
- <programlisting language="XML" role="XML"><application-policy name="security-ex3">
- <authentication>
- <login-module code="org.jboss.security.srp.jaas.SRPCacheLoginModule"
- flag = "required">
- <module-option name="cacheJndiName">srp-test/AuthenticationCache</module-option>
- </login-module>
- <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
- flag = "required">
- <module-option name="password-stacking">useFirstPass</module-option>
- </login-module>
- </authentication>
-</application-policy>
-</programlisting>
- </example>
- <para>
- The example services are the <literal>ServiceConfig</literal> and the <literal>PropertiesVerifierStore</literal> and <literal>SRPService</literal> MBeans. Note that the <literal>JndiName</literal> attribute of the <literal>PropertiesVerifierStore</literal> is equal to the <literal>VerifierSourceJndiName</literal> attribute of the <literal>SRPService</literal>, and that the <literal>SRPService</literal> depends on the <literal>PropertiesVerifierStore</literal>. This is required because the <literal>SRPService</literal> needs an implementation of the <literal>SRPVerifierStore</literal> interface for accessing user password verification information.
- </para>
- <para>
- The client side login module configuration makes use of the <literal>SRPLoginModule</literal> with a <literal>srpServerJndiName</literal> option value that corresponds to the JBoss server component <literal>SRPService</literal> JndiName attribute value(<literal>srp-test/SRPServerInterface</literal>). Also needed is the <literal>ClientLoginModule</literal> configured with the <literal>password-stacking="useFirstPass"</literal> value to propagate the user authentication credentials generated by the <literal>SRPLoginModule</literal> to the EJB invocation layer.
- </para>
- <para>
- There are two issues to note about the server side login module configuration. First, note the <literal>cacheJndiName=srp-test/AuthenticationCache</literal> configuration option tells the <literal>SRPCacheLoginModule</literal> the location of the <literal>CachePolicy</literal> that contains the <literal>SRPServerSession</literal> for users who have authenticated against the <literal>SRPService</literal>. This value corresponds to the <literal>SRPService</literal><literal>AuthenticationCacheJndiName</literal> attribute value. Second, the configuration includes a <literal>UsersRolesLoginModule</literal> with the <literal>password-stacking=useFirstPass</literal> configuration option. It is required to use a second login module with the <literal>SRPCacheLoginModule</literal> because SRP is only an authentication technology. A second login module needs to be configured that accepts the authentication credentials validated by the <literal>SRPCacheLoginModule</literal> to set!
the principal's roles that determines the principal's permissions. The <literal>UsersRolesLoginModule</literal> is augmenting the SRP authentication with properties file based authorization. The user's roles are coming the <literal>roles.properties</literal> file included in the EJB JAR.
- </para>
- <para>
- Now, run the example 3 client by executing the following command from the book examples directory:
- </para>
- <screen>[examples]$ ant -Dchap=security -Dex=3 run-example
-...
-run-example3:
- [echo] Waiting for 5 seconds for deploy...
- [java] Logging in using the 'srp' configuration
- [java] Created Echo
- [java] Echo.echo()#1 = This is call 1
- [java] Echo.echo()#2 = This is call 2</screen>
- <para>
- In the <literal>examples/logs</literal> directory you will find a file called <literal>ex3-trace.log</literal>. This is a detailed trace of the client side of the SRP algorithm. The traces show step-by-step the construction of the public keys, challenges, session key and verification.
- </para>
- <para>
- Note that the client has taken a long time to run relative to the other simple examples. The reason for this is the construction of the client's public key. This involves the creation of a cryptographically strong random number, and this process takes quite a bit of time the first time it occurs. If you were to log out and log in again within the same VM, the process would be much faster. Also note that <literal>Echo.echo()#2</literal> fails with an authentication exception. The client code sleeps for 15 seconds after making the first call to demonstrate the behavior of the <literal>SRPService</literal> cache expiration. The <literal>SRPService</literal> cache policy timeout has been set to a mere 10 seconds to force this issue. As stated earlier, you need to make the cache timeout very long, or handle re-authentication on failure.
- </para>
- </section>
- </section>
- </chapter>
- <chapter id="chap-Java_2_security_manager">
- <title>Java EE Security Manager</title>
- <para>
- By default the JBoss server does not start with a Java EE security manager. If you want to restrict privileges of code using Java EE permissions you need to configure the JBoss server to run under a security manager. This is done by configuring the Java VM options in the <literal>run.bat</literal> or <literal>run.sh</literal> scripts in the JBoss server distribution bin directory. The two required VM options are as follows:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">java.security.manager</emphasis>: This is used without any value to specify that the default security manager should be used. This is the preferred security manager. You can also pass a value to the <literal>java.security.manager</literal> option to specify a custom security manager implementation. The value must be the fully qualified class name of a subclass of <literal>java.lang.SecurityManager</literal>. This form specifies that the policy file should augment the default security policy as configured by the VM installation.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">java.security.policy</emphasis>: This is used to specify the policy file that will augment the default security policy information for the VM. This option takes two forms: <literal>java.security.policy=policyFileURL</literal> and <literal>java.security.policy==policyFileURL</literal>. The first form specifies that the policy file should augment the default security policy as configured by the VM installation. The second form specifies that only the indicated policy file should be used. The <literal>policyFileURL</literal> value can be any URL for which a protocol handler exists, or a file path specification.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Both the <literal>run.bat</literal> and <literal>run.sh</literal> start scripts reference an JAVA_OPTS variable which you can use to set the security manager properties.
- </para>
- <para>
- Enabling Java EE security is the easy part. The difficult part of Java EE security is establishing the allowed permissions. If you look at the <literal>server.policy</literal> file that is contained in the default configuration file set, you'll see that it contains the following permission grant statement:
- </para>
- <programlisting language="Java" role="JAVA">grant {
- // Allow everything for now
- permission java.security.AllPermission;
-};
-</programlisting>
- <para>
- This effectively disables security permission checking for all code as it says any code can do anything, which is not a reasonable default. What is a reasonable set of permissions is entirely up to you.
- </para>
- <para>
- The current set of JBoss specific <literal>java.lang.RuntimePermissions</literal> that are required include:
- </para>
- <informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry> TargetName </entry>
- <entry> What the permission allows </entry>
- <entry> Risks </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry> org.jboss.security.SecurityAssociation.getPrincipalInfo </entry>
- <entry> Access to the org.jboss.security.SecurityAssociation getPrincipal() and getCredentials() methods. </entry>
- <entry> The ability to see the current thread caller and credentials. </entry>
- </row>
- <row>
- <entry> org.jboss.security.SecurityAssociation.setPrincipalInfo </entry>
- <entry> Access to the org.jboss.security.SecurityAssociation setPrincipal() and setCredentials() methods. </entry>
- <entry> The ability to set the current thread caller and credentials. </entry>
- </row>
- <row>
- <entry> org.jboss.security.SecurityAssociation.setServer </entry>
- <entry> Access to the org.jboss.security.SecurityAssociation setServer method. </entry>
- <entry> The ability to enable or disable multithread storage of the caller principal and credential. </entry>
- </row>
- <row>
- <entry> org.jboss.security.SecurityAssociation.setRunAsRole </entry>
- <entry> Access to the org.jboss.security.SecurityAssociation pushRunAsRole and popRunAsRole methods. </entry>
- <entry> The ability to change the current caller run-as role principal. </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>
- To conclude this discussion, here is a little-known tidbit on debugging security policy settings. There are various debugging flag that you can set to determine how the security manager is using your security policy file as well as what policy files are contributing permissions. Running the VM as follows shows the possible debugging flag settings:
- </para>
- <screen>[bin]$ java -Djava.security.debug=help
-
-all turn on all debugging
-access print all checkPermission results
-combiner SubjectDomainCombiner debugging
-jar jar verification
-logincontext login context results
-policy loading and granting
-provider security provider debugging
-scl permissions SecureClassLoader assigns
-
-The following can be used with access:
-
-stack include stack trace
-domain dumps all domains in context
-failure before throwing exception, dump stack
- and domain that didn't have permission
-
-Note: Separate multiple options with a comma</screen>
- <para>Running with <literal>-Djava.security.debug=all</literal> provides the most output, but the output volume is torrential. This might be a good place to start if you don't understand a given security failure at all. A less verbose setting that helps debug permission failures is to use <literal>-Djava.security.debug=access,failure</literal>. This is still relatively verbose, but not nearly as bad as the all mode as the security domain information is only displayed on access failures.
- </para>
- </chapter>
- <chapter id="chap-Secure_Socket_Layer">
- <title>Secure Socket Layer</title>
- <section id="Adding_SSL_to_EJB3">
- <title>Adding SSL to EJB3</title>
- <para>
- By default JBoss EJB3 uses a socket based invoker layer on port 3878. This is set up in <filename> $JBOSS_HOME/server/<replaceable><serverconfig></replaceable>/deploy/ejb3.deployer/META-INF/jboss-service.xml</filename>. In some cases you may wish to use SSL as the protocol. In order to do this you must generate a keystore and then configure your beans to use SSL transport.
- </para>
- <section id="Adding_SSL_to_EJB3_Generating_the_keystore_and_truststore">
- <title>Generating the keystore and truststore</title>
- <para>
- For SSL to work you need to create a public/private key pair, which will be stored in a keystore. Generate this using the <literal>genkey</literal> command that comes with the JDK.
-
- where <literal>alias</literal> is the name ("ejb2-ssl") of the key pair within the keystore. <literal>keypass</literal> is the password ("opensource") for the keystore, and <literal>keystore</literal> specifies the location ("localhost.keystore") of the keystore to create/add to.
- </para>
- <screen>[home]$ cd <replaceable>[install_directory]</replaceable>/server/production/conf/
-
-[conf]$ keytool -genkey -alias ejb3-ssl -keypass opensource -keystore localhost.keystore
- Enter keystore password: opensource
- What is your first and last name?
- [Unknown]:
- What is the name of your organizational unit?
- [Unknown]:
- What is the name of your organization?
- [Unknown]:
- What is the name of your City or Locality?
- [Unknown]:
- What is the name of your State or Province?
- [Unknown]:
- What is the two-letter country code for this unit?
- [Unknown]:
- Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
- [no]: yes</screen>
- <para>
- Since you have not signed our certificate through any certification authoritiy, you also need to create a truststore for the client, explicitly saying that you trust the certificate you just created. The first step is to export the certificate using the JDK keytool:
-
- </para>
- <screen>[conf]$ keytool -export -alias ejb3-ssl -file mycert.cer -keystore localhost.keystore
- Enter keystore password: opensource
- Certificate stored in file <mycert.cer></screen>
- <para>
- Then you need to create the truststore if it does not exist and import the certificate into the trueststore:
-
- </para>
- <screen>[conf]$ keytool -import -alias ejb3-ssl -file mycert.cer -keystore localhost.truststore
- Enter keystore password: opensource
- Owner: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
- Issuer: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
- Serial number: 43bff927
- Valid from: Sat Jan 07 18:23:51 CET 2006 until: Fri Apr 07 19:23:51 CEST 2006
- Certificate fingerprints:
- MD5: CF:DC:71:A8:F4:EA:8F:5A:E9:94:E3:E6:5B:A9:C8:F3
- SHA1: 0E:AD:F3:D6:41:5E:F6:84:9A:D1:54:3D:DE:A9:B2:01:28:F6:7C:26
- Trust this certificate? [no]: yes
- Certificate was added to keystore</screen>
- </section>
- <section>
- <title id="Adding_SSL_to_EJB3_Setting_up_the_SSL_transport">Setting up the SSL transport</title>
- <para>
- The simplest way to define an SSL transport is to define a new Remoting connector using the <literal>sslsocket</literal> protocol as follows. This transport will listen on port 3843:
-<programlisting>
- <mbean code="org.jboss.remoting.transport.Connector"
- xmbean-dd="org/jboss/remoting/transport/Connector.xml"
- name="jboss.remoting:type=Connector,transport=socket3843,handler=ejb3">
- <depends>jboss.aop:service=AspectDeployer</depends>
- <attribute name="InvokerLocator">sslsocket://0.0.0.0:3843</attribute>
- <attribute name="Configuration">
- <handlers>
- <handler subsystem="AOP">
- org.jboss.aspects.remoting.AOPRemotingInvocationHandler
- </handler>
- </handlers>
- </attribute>
- </mbean>
-</programlisting>
- </para>
- <para>
- Now you need to tell JBoss Remoting where to find the keystore to be used for SSl and its password. This is done using <literal>javax.net.ssl.keyStore</literal> and <literal>javax.net.ssl.keyStorePassword=opensource</literal> system properties when starting JBoss, as the following example shows:
-
- </para>
- <screen>[home]$ cd [install_directory]/bin
-[bin]$ run -Djavax.net.ssl.keyStore=../server/production/conf/localhost.keystore
- -Djavax.net.ssl.keyStorePassword=opensource</screen>
- </section>
- <section id="Adding_SSL_to_EJB3_Configuring_your_beans">
- <title>Configuring your beans to use the SSL transport</title>
- <para>
- By default all the beans will use the default connector on <literal>socket://0.0.0.0:3873</literal>. By using the <literal>@org.jboss.annotation.ejb.RemoteBinding</literal> annotation you can have the bean invokable via SSL.
-<programlisting language="Java" role="JAVA">
- @RemoteBinding(clientBindUrl="sslsocket://0.0.0.0:3843", jndiBinding="StatefulSSL"),
- @Remote(BusinessInterface.class)
- public class StatefulBean implements BusinessInterface
- {
- ...
- }
-</programlisting>
- </para>
- <para>
- This bean will be bound under the JNDI name <literal>StatefulSSL</literal> and the proxy implementing the remote interface returned to the client will communicate with the server via SSL.
- </para>
- <para>
- You can also enable different types of communication for your beans
-<programlisting language="Java" role="JAVA">
- @RemoteBindings({
- @RemoteBinding(clientBindUrl="sslsocket://0.0.0.0:3843", jndiBinding="StatefulSSL"),
- @RemoteBinding(jndiBinding="StatefulNormal")
- })
- @Remote(BusinessInterface.class)
- public class StatefulBean implements BusinessInterface
- {
- ...
- }
-</programlisting>
- </para>
- <para>
- Now if you look up <literal>StatefulNormal</literal> the returned proxy implementing the remote interface will communicate with the server via the normal unencrypted socket protocol, and if you look up <literal>StatefulSSL</literal> the returned proxy implementing the remote interface will communicate with the server via SSL.
- </para>
- </section>
- <section id="Adding_SSL_to_EJB3_Setting_up_the_client_to_use_truststore">
- <title>Setting up the client to use the truststore</title>
- <para>
-If not using a certificate signed by a certificate authorization authority, you need to point the client to the truststore using the <literal>javax.net.ssl.trustStore</literal> system property and specify the password using the <literal>javax.net.ssl.trustStorePassword</literal> system property:
-
- </para>
- <screen>[home]$ java -Djavax.net.ssl.trustStore=${resources}/test/ssl/localhost.truststore
- -Djavax.net.ssl.trustStorePassword=opensource com.acme.RunClient</screen>
- </section>
- </section>
- <section id="Adding_SSL_to_EJB2.1">
- <title>Adding SSL to EJB 2.1 calls</title>
- <section id="Adding_SSL_to_EJB2.1_Generating_the_keystore_and_truststore">
- <title>Generating the keystore and truststore</title>
- <para>
- This is similar to the steps described for Adding SSL to EJB3 calls.
- </para>
- </section>
- <section id="Adding_SSL_to_EJB2.1_Setting_up_the_SSL_transport">
- <title>Setting up the SSL transport</title>
- <para>
-Now you need to tell JBoss Remoting where to find the keystore to be used for SSl and its password. This is done using <literal>javax.net.ssl.keyStore</literal> and <literal>javax.net.ssl.keyStorePassword=opensource</literal> system properties when starting JBoss, as the following example shows:
-
- </para>
- <screen>[home]$ cd <replaceable>[install_directory]</replaceable>/bin
-[bin]$ run -Djavax.net.ssl.keyStore=../server/production/conf/localhost.keystore
--Djavax.net.ssl.keyStorePassword=opensource</screen>
- <para>
- If you wish to customize the SSLSocketBuilder you need to add the following to your <literal><replaceable>[install_directory]</replaceable>/server/<replaceable>$SERVERS</replaceable>/conf/jboss-service.xml</literal> file.
-<programlisting language="XML" role="XML">
- <!-- This section is for custom (SSL) server socket factory -->
- <mbean code="org.jboss.remoting.security.SSLSocketBuilder"
- name="jboss.remoting:service=SocketBuilder,type=SSL"
- display-name="SSL Server Socket Factory Builder">
- <!-- IMPORTANT - If making ANY customizations, this MUST be set to false. -->
- <!-- Otherwise, will used default settings and the following attributes will be ignored. -->
- <attribute name="UseSSLServerSocketFactory">false</attribute>
- <!-- This is the url string to the key store to use -->
- <attribute name="KeyStoreURL">localhost.keystore</attribute>
- <!-- The password for the key store -->
- <attribute name="KeyStorePassword">sslsocket</attribute>
- <!-- The password for the keys (will use KeystorePassword if this is not set explicitly. -->
- <attribute name="KeyPassword">sslsocket</attribute>
- <!-- The protocol for the SSLContext. Default is TLS. -->
- <attribute name="SecureSocketProtocol">TLS</attribute>
- <!-- The algorithm for the key manager factory. Default is SunX509. -->
- <attribute name="KeyManagementAlgorithm">SunX509</attribute>
- <!-- The type to be used for the key store. -->
- <!-- Defaults to JKS. Some acceptable values are JKS (Java Keystore - Sun's keystore format), -->
- <!-- JCEKS (Java Cryptography Extension keystore - More secure version of JKS), and -->
- <!-- PKCS12 (Public-Key Cryptography Standards #12
- keystore - RSA's Personal Information Exchange Syntax Standard). -->
- <!-- These are not case sensitive. -->
- <attribute name="KeyStoreType">JKS</attribute>
- </mbean>
-</programlisting>
-<programlisting>
-<mbean code="org.jboss.remoting.security.SSLServerSocketFactoryService"
- name="jboss.remoting:service=ServerSocketFactory,type=SSL"
- display-name="SSL Server Socket Factory">
- <depends optional-attribute-name="SSLSocketBuilder"
- proxy-type="attribute">jboss.remoting:service=SocketBuilder,type=SSL</depends>
- </mbean>
-</programlisting>
- </para>
- </section>
- <section id="Adding_SSL_to_EJB2.1_configuring_your_beans">
- <title>Configuring your beans to use the SSL transport</title>
- <para>
- In your <literal>$JBOSS_HOME/server/${serverConf}/conf/jboss-service.xml</literal> file, comment out the following lines:
-
- and add the following in it's place:
-
- </para>
- <programlisting language="XML" role="XML">
-<mbean code="org.jboss.remoting.transport.Connector"
- name="jboss.remoting:service=Connector,transport=socket"
- display-name="Socket transport Connector">
-
- <!-- Can either just specify the InvokerLocator attribute and not the invoker element in the -->
- <!-- Configuration attribute, or do the full invoker configuration in the in invoker element -->
- <!-- of the Configuration attribute. -->
-
- <!-- Remember that if you do use more than one param on the uri, will have to include as a CDATA, -->
- <!-- otherwise, parser will complain. -->
- <!--
- <attribute name="InvokerLocator">
- <![CDATA[socket://${jboss.bind.address}:4446/?datatype=invocation]]>
- </attribute>
- -->
-
- <attribute name="Configuration">
- <!-- Using the following
- <invoker>
- element instead of the InvokerLocator above because specific attributes needed.
- -->
- <!-- If wanted to use any of the parameters below, can
- just add them as parameters to the url above if wanted use
- the InvokerLocator attribute. -->
- <config>
- <!-- Other than transport type and handler, none of these configurations are required
- (will just use defaults). -->
- <invoker transport="socket">
- <attribute name="dataType" isParam="true">invocation</attribute>
- <attribute name="marshaller"
- isParam="true">org.jboss.invocation.unified.marshall.InvocationMarshaller</attribute>
- <attribute name="unmarshaller"
- isParam="true">org.jboss.invocation.unified.marshall.InvocationUnMarshaller</attribute>
- <!-- This will be port on which the marshall loader port runs on. -->
- <!-- <attribute name="loaderport" isParam="true">4447</attribute> -->
- <!-- The following are specific to socket invoker -->
- <!-- <attribute name="numAcceptThreads">1</attribute>-->
- <!-- <attribute name="maxPoolSize">303</attribute>-->
- <!-- <attribute name="clientMaxPoolSize" isParam="true">304</attribute>-->
- <attribute name="socketTimeout" isParam="true">600000</attribute>
- <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
- <attribute name="serverBindPort">4446</attribute>
- <!-- <attribute name="clientConnectAddress">216.23.33.2</attribute> -->
- <!-- <attribute name="clientConnectPort">7777</attribute> -->
- <attribute name="enableTcpNoDelay" isParam="true">true</attribute>
- <!-- <attribute name="backlog">200</attribute>-->
- <!-- The following is for callback configuration and is independant of invoker type -->
- <!-- <attribute name="callbackMemCeiling">30</attribute>-->
- <!-- indicates callback store by fully qualified class name -->
- <!-- <attribute name="callbackStore">org.jboss.remoting.CallbackStore</attribute>-->
- <!-- indicates callback store by object name -->
- <!--
- <attribute name="callbackStore">
- jboss.remoting:service=CallbackStore,type=Serializable
- </attribute>
- -->
- <!-- config params for callback store. if were declaring callback store via object name, -->
- <!-- could have specified these config params there. -->
- <!-- StoreFilePath indicates to which directory to write the callback objects. -->
- <!-- The default value is the property value of 'jboss.server.data.dir' and
- if this is not set, -->
- <!-- then will be 'data'. Will then append 'remoting' and the callback client's session id. -->
- <!-- An example would be 'data\remoting\5c4o05l-9jijyx-e5b6xyph-1-e5b6xyph-2'. -->
- <!-- <attribute name="StoreFilePath">callback</attribute>-->
- <!-- StoreFileSuffix indicates the file suffix to use
- for the callback objects written to disk. -->
- <!-- The default value for file suffix is 'ser'. -->
- <!-- <attribute name="StoreFileSuffix">cst</attribute>-->
- </invoker>
-
- <!-- At least one handler is required by the connector. If have more than one, must decalre -->
- <!-- different subsystem values. Otherwise, all invocations will be routed to the only one -->
- <!-- that is declared. -->
- <handlers>
- <!-- can also specify handler by fully qualified classname -->
- <handler subsystem="invoker">jboss:service=invoker,type=unified</handler>
- </handlers>
- </config>
- </attribute>
- <depends>jboss.remoting:service=NetworkRegistry</depends>
- </mbean>
-</programlisting>
- <programlisting language="XML" role="XML">
- <mbean code="org.jboss.remoting.transport.Connector"
- xmbean-dd="org/jboss/remoting/transport/Connector.xml"
- name="jboss.remoting:service=Connector,transport=sslsocket">
- display-name="SSL Socket transport Connector">
-
- <attribute name="Configuration">
- <config>
- <invoker transport="sslsocket">
- <attribute name="serverSocketFactory">
- jboss.remoting:service=ServerSocketFactory,type=SSL
- </attribute>
- <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
- <attribute name="serverBindPort">3843</attribute>
- </invoker>
- <handlers>
- <handler subsystem="invoker">jboss:service=invoker,type=unified</handler>
- </handlers>
- </config>
- </attribute>
- <!--If you specify the keystore and password in the command line and you're
- not using the custom ServerSocketFactory, you should take out the following line-->
- <depends>jboss.remoting:service=ServerSocketFactory,type=SSL</depends>
- <depends>jboss.remoting:service=NetworkRegistry</depends>
- </mbean>
-</programlisting>
- </section>
- <section id="Adding_SSL_to_EJB2.1_Setting_up_the_client_to_use_truststore">
- <title>Setting up the client to use the truststore</title>
- <para>
- This is similar to the steps described for EJB3.
- </para>
- </section>
- </section>
- </chapter>
- <chapter id="chap-Firewalls">
- <title>Firewalls</title>
- <para>
- JBoss comes with many socket based services that open listening ports. In this section we list the services that open ports that might need to be configured to work when accessing JBoss behind a firewall. The following table shows the ports, socket type, associated service for the services in the default configuration file set. <xref linkend="Configuring_JBoss_for_use_Behind_a_Firewall-Additional_ports_in_the_all_configuration"/> shows the same information for the additional ports that exist in the all configuration file set.
- </para>
- <table id="Configuring_JBoss_for_use_Behind_a_Firewall-The_ports_found_in_the_default_configuration">
- <title>The ports found in the default configuration</title>
- <tgroup cols="3">
- <colspec colnum="1" colname="c1" colwidth=".25*"/>
- <colspec colnum="2" colname="c2" colwidth=".25*"/>
- <colspec colnum="3" colname="c3" colwidth="1*"/>
- <thead>
- <row>
- <entry> Port </entry>
- <entry> Type </entry>
- <entry> Service </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry> 1098 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.naming.NamingService</literal>
- </entry>
- </row>
- <row>
- <entry> 1099 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.naming.NamingService</literal>
- </entry>
- </row>
- <row>
- <entry> 4444 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.invocation.jrmp.server.JRMPInvoker</literal>
- </entry>
- </row>
- <row>
- <entry> 4445 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.invocation.pooled.server.PooledInvoker</literal>
- </entry>
- </row>
- <row>
- <entry> 8009 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.web.tomcat.tc4.EmbeddedTomcatService</literal>
- </entry>
- </row>
- <row>
- <entry> 8080 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.web.tomcat.tc4.EmbeddedTomcatService</literal>
- </entry>
- </row>
- <row>
- <entry> 8083 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.web.WebService</literal>
- </entry>
- </row>
- <row>
- <entry> 8093 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.mq.il.uil2.UILServerILService</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table id="Configuring_JBoss_for_use_Behind_a_Firewall-Additional_ports_in_the_all_configuration">
- <title>Additional ports in the all configuration</title>
- <tgroup cols="3">
- <colspec colnum="1" colname="c1" colwidth=".25*"/>
- <colspec colnum="2" colname="c2" colwidth=".25*"/>
- <colspec colnum="3" colname="c3" colwidth="1*"/>
- <thead>
- <row>
- <entry> Port </entry>
- <entry> Type </entry>
- <entry> Service </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry> 1100 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.ha.jndi.HANamingService</literal>
- </entry>
- </row>
- <row>
- <entry> 1101 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.ha.jndi.HANamingService</literal>
- </entry>
- </row>
- <row>
- <entry> 1102 </entry>
- <entry> UDP </entry>
- <entry>
- <literal>org.jboss.ha.jndi.HANamingService</literal>
- </entry>
- </row>
- <row>
- <entry> 1161 </entry>
- <entry> UDP </entry>
- <entry>
- <literal>org.jboss.jmx.adaptor.snmp.agent.SnmpAgentService</literal>
- </entry>
- </row>
- <row>
- <entry> 1162 </entry>
- <entry> UDP </entry>
- <entry>
- <literal>org.jboss.jmx.adaptor.snmp.trapd.TrapdService</literal>
- </entry>
- </row>
- <row>
- <entry> 3528 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.invocation.iiop.IIOPInvoker</literal>
- </entry>
- </row>
- <row>
- <entry> 4447 </entry>
- <entry> TCP </entry>
- <entry>
- <literal>org.jboss.invocation.jrmp.server.JRMPInvokerHA</literal>
- </entry>
- </row>
- <row>
- <entry> 45566<footnote>
- <para>
- Plus two additional anonymous UDP ports, one can be set using the <literal>rcv_port</literal>, and the other cannot be set.
- </para>
- </footnote></entry>
- <entry> UDP </entry>
- <entry>
- <literal>org.jboss.ha.framework.server.ClusterPartition</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </chapter>
- <chapter id="chap-Consoles_and_Invokers">
- <title>Consoles and Invokers</title>
- <para>
- JBoss comes with several admin access points that need to be secured or removed to prevent unauthorized access to administrative functions in a deployment. This chapter discusses the various admin services and how to secure them.
- </para>
- <section id="sect-The_JMX_Console">
- <title>JMX Console</title>
- <para>
- The <literal>jmx-console.war</literal> found in the deploy directory provides an html view into the JMX microkernel. As such, it provides access to arbitrary admin type access like shutting down the server, stopping services, deploying new services, etc. It should either be secured like any other web application, or removed.
- </para>
- </section>
- <section id="How_to_Secure_the_JBoss_Server-The_Web_Console">
- <title>Web Console</title>
- <para>
- The <literal>web-console.war</literal> found in the <literal>deploy/management</literal> directory is another web application view into the JMX microkernel. This uses a combination of an applet and a HTML view and provides the same level of access to admin functionality as the <literal>jmx-console.war</literal>. As such, it should either be secured or removed. The <literal>web-console.war</literal> contains commented out templates for basic security in its <literal>WEB-INF/web.xml</literal> as well as commented out setup for a security domain in <literal>WEB-INF/jboss-web.xml</literal>.
- </para>
- </section>
- <section id="How_to_Secure_the_JBoss_Server-The_HTTP_Invokers">
- <title>HTTP Invokers</title>
- <para>
- The <literal>http-invoker.sar</literal> found in the deploy directory is a service that provides RMI/HTTP access for EJBs and the JNDI <literal>Naming</literal> service. This includes a servlet that processes posts of marshalled <literal>org.jboss.invocation.Invocation</literal> objects that represent invocations that should be dispatched onto the <literal>MBeanServer</literal>. Effectively this allows access to MBeans that support the detached invoker operation via HTTP since one could figure out how to format an appropriate HTTP post. To security this access point you would need to secure the <literal>JMXInvokerServlet</literal> servlet found in the <literal>http-invoker.sar/invoker.war/WEB-INF/web.xml</literal> descriptor. There is a secure mapping defined for the <literal>/restricted/JMXInvokerServlet</literal> path by default, one would simply have to remove the other paths and configure the <literal>http-invoker</literal> security domain setup in the <literal>http!
-invoker.sar/invoker.war/WEB-INF/jboss-web.xml</literal> descriptor.
- </para>
- </section>
- <section id="How_to_Secure_the_JBoss_Server-The_JMX_Invoker">
- <title>JMX Invoker</title>
- <para>
- The <literal>jmx-invoker-adaptor-server.sar</literal> is a service that exposes the JMX MBeanServer interface via an RMI compatible interface using the RMI/JRMP detached invoker service. The only way for this service to be secured currently would be to switch the protocol to RMI/HTTP and secure the <literal>http-invoker.sar</literal> as described in the previous section. In the future this service will be deployed as an XMBean with a security interceptor that supports role based access checks.
- </para>
- </section>
- </chapter>
-</part>
More information about the jboss-cvs-commits
mailing list