[jboss-cvs] JBossAS SVN: r105237 - projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed May 26 01:41:18 EDT 2010
Author: jaredmorgs
Date: 2010-05-26 01:41:17 -0400 (Wed, 26 May 2010)
New Revision: 105237
Modified:
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/Book_Info.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/Revision_History.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Consoles_And_Invokers.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Firewalls.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Java_EE_Security_Manager.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Secure_Socket_Layer.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Static_Security_Domains.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/part-Security_Overview.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Configure_Secure_Remote_Password_Information.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-IdentiyLoginModule.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-LdapLoginModule.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Password_Hashing.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-RunAsLoginModule.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Secure_Remote_Password_Example.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Security_Identity.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Subject_Usage_Pattern_Support.xml
projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Understanding_The_Algorithm.xml
Log:
copied over the files from the old Security Guide repo into the new one here
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/Book_Info.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/Book_Info.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -6,8 +6,8 @@
<subtitle>Configuring platform and application security</subtitle>
<productname>JBoss Enterprise Application Platform</productname>
<productnumber>5.1</productnumber>
- <edition>0</edition>
- <pubsnumber>0</pubsnumber>
+ <edition>1.0</edition>
+ <pubsnumber>3</pubsnumber>
<abstract>
<para>
The JBoss Security Guide is aimed at System Administrators and Developers, and explains how to implement security in JBoss Enterprise Application Platform. The guide covers Java EE Declarative Security; an introduction to Java
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/Revision_History.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/Revision_History.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -6,6 +6,24 @@
<simpara>
<revhistory>
<revision>
+ <revnumber> 0.3</revnumber>
+ <date>Wed May 19 2010</date>
+ <author>
+ <firstname>Jared </firstname>
+ <surname>Morgan </surname>
+ <email>jmorgan at example.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Updated Pubsnumber only for demo purposes.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </simpara>
+ <simpara>
+ <revhistory>
+ <revision>
<revnumber> 0.2</revnumber>
<date>Wed May 19 2010</date>
<author>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Consoles_And_Invokers.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Consoles_And_Invokers.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Consoles_And_Invokers.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -6,7 +6,7 @@
<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.
+ JBoss comes with several admin access points that must 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>
@@ -23,7 +23,7 @@
<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.
+ 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 secure this access point you would must 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-invo!
ker.sar/invoker.war/WEB-INF/jboss-web.xml</literal> descriptor.
</para>
</section>
<section id="How_to_Secure_the_JBoss_Server-The_JMX_Invoker">
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Firewalls.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Firewalls.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Firewalls.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -6,7 +6,7 @@
<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.
+ JBoss comes with many socket based services that open listening ports. In this section we list the services that open ports that might must 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>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Java_EE_Security_Manager.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Java_EE_Security_Manager.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Java_EE_Security_Manager.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -5,39 +5,40 @@
]>
<chapter id="chap-Java_EE_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>To restrict code privileges using Java EE permissions, you must configure the JBoss server to run under a security manager. This is done by configuring the Java VM options in the <filename>run.bat</filename> or <filename>run.sh</filename> 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.
+ <variablelist>
+ <varlistentry>
+ <term>java.security.manager</term>
+ <listitem>
+ <para>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.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>java.security.policy</term>
+ <listitem>
+ <para>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>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<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>The next element of Java EE security is establishing the allowed permissions. If you look at the <filename>server.policy</filename> file that is contained in the default configuration file set you will notice 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>This statement effectively disables security permission checking for all code, which is not a reasonable default. You must define the permissions scope according to the requirements of your production implementation.
</para>
- <para>
- The current set of JBoss specific <literal>java.lang.RuntimePermissions</literal> that are required include:
+ <para>The current set of JBoss specific <literal>java.lang.RuntimePermissions</literal> are described in <xref linkend="table-RuntimePermissions"/>:
</para>
- <informaltable>
+ <table id="table-RuntimePermissions">
+ <title>java.lang.RuntimePermissions</title>
<tgroup cols="3">
<thead>
<row>
@@ -48,30 +49,37 @@
</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>
+ <entry>
+ <classname> org.jboss.security.SecurityAssociation.getPrincipalInfo</classname>
+ </entry>
+ <entry> Access to the <methodname>org.jboss.security.SecurityAssociation getPrincipal() </methodname>and <methodname>getCredentials()</methodname> 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>
+ <entry>
+ <classname> org.jboss.security.SecurityAssociation.setPrincipalInfo </classname>
+ </entry>
+ <entry> Access to the <methodname>org.jboss.security.SecurityAssociation setPrincipal()</methodname> and <methodname>setCredentials()</methodname> 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>
+ <entry>
+ <classname> org.jboss.security.SecurityAssociation.setServer</classname>
+ </entry>
+ <entry> Access to the <methodname>org.jboss.security.SecurityAssociation setServer </methodname>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>
+ <entry>
+ <classname> org.jboss.security.SecurityAssociation.setRunAsRole</classname>
+ </entry>
+ <entry> Access to the <methodname>org.jboss.security.SecurityAssociation pushRunAsRole</methodname> and <methodname>popRunAsRole</methodname> 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:
+ </table>
+ <para>A number of Java debugging flags are available to assist you in determining how the security manager is using your security policy file, and 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
@@ -92,6 +100,6 @@
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>Running with <literal>-Djava.security.debug=all</literal> provides the most output, but the output volume is acutely verbose. This might be a good place to start if you don't understand a given security failure at all. For less verbose output that will still assist with debugging permission failures, use <literal>-Djava.security.debug=access,failure</literal>.
</para>
</chapter>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -65,47 +65,48 @@
<varlistentry>
<term>principalClassName</term>
<listitem>
- <para>This option is no longer supported. The principal class is now always <literal>org.jboss.security.srp.jaas.SRPPrincipal</literal>.</para>
+ <para>Constant value, always set to <literal>org.jboss.security.srp.jaas.SRPPrincipal</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>srpServerJndiName</term>
<listitem>
- <para>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>
+ <para> JNDI name of the <literal>SRPServerInterface</literal> object used to communicate with the SRP authentication server. If both <literal>srpServerJndiName</literal> and <literal>srpServerRmiUrl</literal> options are specified, <literal>srpServerJndiName</literal> takes priority over <literal>srpServerRmiUrl</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>srpServerRmiUrl</term>
<listitem>
- <para>The RMI protocol URL string for the location of the <literal>SRPServerInterface</literal> proxy to use for communicating with the SRP authentication server.</para>
+ <para> RMI protocol URL string for the location of the <literal>SRPServerInterface</literal> proxy used to communicate with the SRP authentication server.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>externalRandomA</term>
<listitem>
- <para>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>
+ <para>Flag that specifies whether 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. If set to <literal>true</literal>, the feature is activated. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>hasAuxChallenge</term>
<listitem>
- <para>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>
+ <para>Flag that specifies whether 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>. If set to <literal>true</literal>, the feature is activated. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>multipleSessions</term>
<listitem>
- <para>a true/false flag indicating if a given client may have multiple SRP login sessions active simultaneously.
- </para>
+ <para>Flag that specifies whether a given client may have multiple SRP login sessions active simultaneously.
+ If set to <literal>true</literal>, the feature is activated.</para>
</listitem>
</varlistentry>
</variablelist>
- <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>Any other passed options that do not match one of the previous named options are 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 {
+ The <literal>SRPLoginModule</literal> and the standard <literal>ClientLoginModule</literal> must be configured to allow SRP authentication credentials to be used for access validation to security Java EE components. An example login configuration is described in <xref linkend="exam-Login_Configuration_Entry"/>.</para>
+ <example id="exam-Login_Configuration_Entry">
+ <title>Login Configuration Entry</title>
+ <programlisting>srp {
org.jboss.security.srp.jaas.SRPLoginModule required
srpServerJndiName="SRPServerInterface"
;
@@ -115,78 +116,110 @@
;
};
</programlisting>
+ </example>
<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>.
+ <variablelist>
+ <varlistentry>
+ <term>JndiName</term>
+ <listitem>
+ <para>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>. The default value is <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>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>VerifierSourceJndiName</term>
+ <listitem>
+ <para>Name of the <literal>SRPVerifierSource</literal> implementation the <literal>SRPService</literal> should use. If not set, the source JNDI name 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>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>AuthenticationCacheJndiName</term>
+ <listitem>
+ <para>Name under which the <literal>org.jboss.util.CachePolicy</literal> authentication implementation used for caching authentication information is bound. The SRP session cache is made available for use through this binding. If not set, the authentication JNDI cache 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.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ServerPort</term>
+ <listitem>
+ <para>
+ RMI port for the <literal>SRPRemoteServerInterface</literal>. The default value is 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.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ClientSocketFactory</term>
+ <listitem>
+ <para>Optional custom <literal>java.rmi.server.RMIClientSocketFactory</literal> implementation class name used during the export of the <literal>SRPServerInterface</literal>. The default value is <literal>RMIClientSocketFactory</literal>.
</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.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ServerSocketFactory</term>
+ <listitem>
+ <para>Optional custom <literal>java.rmi.server.RMIServerSocketFactory</literal> implementation class name used during the export of the <literal>SRPServerInterface</literal>. The default value is <literal>RMIServerSocketFactory</literal>.
</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).
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>AuthenticationCacheTimeout</term>
+ <listitem>
+ <para>Cache policy timeout (in seconds). The defalut value is 1800 (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).
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>AuthenticationCacheResolution</term>
+ <listitem>
+ <para>Specifies the timed cache policy resolution (in seconds). This controls the interval between checks for timeouts. The defalut value is 60 (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.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RequireAuxChallenge</term>
+ <listitem>
+ <para>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:
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>OverwriteSessions</term>
+ <listitem>
+ <para>Flag that specifies whether 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. If set to <literal>false</literal>, the second user authentication attempt will succeed, however the resulting SRP session will not overwrite the previous SRP session state.
+ The default value is <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>VerifierStoreJndiName</term>
+ <listitem>
+ <para>Input setting attribute, which specifies the location of the SRP password information store implementation that must be provided and made available through JNDI. </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para><classname>org.jboss.security.srp.SRPVerifierStoreService</classname> 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. </para>
+ <para>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>.
+ <variablelist>
+ <varlistentry>
+ <term>JndiName</term>
+ <listitem>
+ <para>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>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>StoreFile</term>
+ <listitem>
+ <para>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>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<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:
+ The <literal>SRPVerifierStoreService</literal> MBean also supports <parameter>addUser</parameter> and <parameter>delUser</parameter> 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;
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Secure_Socket_Layer.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Secure_Socket_Layer.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Secure_Socket_Layer.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -7,17 +7,19 @@
<title>Secure Socket Layer</title>
<section id="sect-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>JBoss EJB3 uses a socket based invoker layer on port 3878 by default. This is set up in <filename><replaceable>$JBOSS_HOME</replaceable>/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>Generate 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.
+ For SSL to work you must 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/
+ <example id="exam-keytool_keygen_command_example">
+ <title>keytool -keygen command example</title>
+ <para>This example describes the command to use to create the public/private keypair.where <literal>alias</literal> is the name ("ejb2-ssl") of the key pair within the keystore. In the example, <literal>keypass</literal> is the password ("opensource") for the keystore, and <literal>keystore</literal> specifies the location <literal>localhost.keystore</literal> of the keystore to create, or append 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
@@ -35,18 +37,24 @@
[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
+ </example>
+ <para>Because the certificate is not signed through any certification authority, you must create a truststore for the client. Creating this truststore explicitly states that you trust the certificate you just created. </para>
+ <procedure>
+ <title>Create Truststore</title>
+ <para>This procedure explains the steps required to create a truststore for SSL certificates.</para>
+ <step>
+ <title>Export certificate</title>
+ <para>You must export the certificate you created using the JDK keytool. The keytool command is described below:</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
+ </step>
+ <step>
+ <title>Create Truststore</title>
+ <para>If you do not currently have an active truststore (for example, <filename>localhost.truststore</filename>), you must create it. </para>
+ <para>Onc the truststore is created, you must import the certificate into the truststore.</para>
+ <para>The commands described below use the information in <xref linkend="exam-keytool_keygen_command_example"/>. </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
@@ -57,12 +65,18 @@
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>
+ </step>
+ </procedure>
</section>
<section>
<title id="Adding_SSL_to_EJB3_Setting_up_the_SSL_transport">Configure 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>
+ 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.
+
+ </para>
+ <example>
+ <title>Defining New Remoting Connector</title>
+ <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">
@@ -76,10 +90,9 @@
</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:
+</programlisting>
+ </example>
+ <para>You must now define the keystore location that 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
@@ -123,7 +136,7 @@
<section id="Adding_SSL_to_EJB3_Setting_up_the_client_to_use_truststore">
<title>Define Truststore for Client</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:
+If not using a certificate signed by a certificate authorization authority, you must 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
@@ -141,14 +154,14 @@
<section id="Adding_SSL_to_EJB2.1_Setting_up_the_SSL_transport">
<title>Configure 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:
+Now you must 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.
+ If you wish to customize the SSLSocketBuilder you must 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"
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Static_Security_Domains.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Static_Security_Domains.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/chap-Static_Security_Domains.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -73,7 +73,7 @@
</variablelist>
<example>
<title>Security Domain using Multiple Login Modules</title>
- <para>This example shows the definition of a security domain that uses multiple login modules. Since both modules are marked as sufficient, only one of them need to succeed for login to proceed.
+ <para>This example shows the definition of a security domain that uses multiple login modules. Since both modules are marked as sufficient, only one of them must succeed for login to proceed.
</para>
<programlisting language="XML" role="XML"><application-policy name="todo">
<authentication>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/part-Security_Overview.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/part-Security_Overview.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/part-Security_Overview.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -5,7 +5,7 @@
<title>Security Overview</title>
<partintro>
<para>
- Security is a fundamental part of any enterprise application. You need to be able to restrict who is allowed to access your applications and control what operations application users may perform. </para>
+ Security is a fundamental part of any enterprise application. You must be able to restrict who is allowed to access your applications and control what operations application users may perform. </para>
<para>The Java EE specifications define a simple role-based security model for EJBs and web components. The JBoss component framework that handles security is the JBossSX extension framework. The JBossSX security extension provides support for both the role-based declarative Java EE security model and integration of custom security via a security proxy layer. </para>
<para>The default implementation of the declarative security model is based on Java Authentication and Authorization Service (JAAS) login modules and subjects. The security proxy layer allows custom security that cannot be described using the declarative model to be added to an EJB in a way that is independent of the EJB business object. Before getting into the JBoss security implementation details, we will review EJB and servlet specification security models, as well as JAAS to establish the foundation for these details.
</para>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Configure_Secure_Remote_Password_Information.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Configure_Secure_Remote_Password_Information.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Configure_Secure_Remote_Password_Information.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -5,10 +5,12 @@
]>
<section id="sect-Configure_Secure_Remote_Password_Information">
<title>Configure Secure Remote Password Information</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 create a 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>You must create a 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>
+ <note>
+ <para>
+ The default implementation of the <literal>SRPVerifierStore</literal> interface is not recommended for a production security environment because it requires all password hash information to be available as a file of serialized objects. </para>
+ </note>
<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;
@@ -65,41 +67,65 @@
<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.
+ <variablelist>
+ <varlistentry>
+ <term>
+ <markup>username</markup>
+ </term>
+ <listitem>
+ <para>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.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <markup>verifier</markup>
+ </term>
+ <listitem>
+ <para>One-way hash of the password or PIN the user enters as proof of identity. The <classname>org.jboss.security.Util</classname> class has a <methodname>calculateVerifier</methodname> method that performs that password hashing algorithm. The output password takes the form <literal>H(salt | H(username | ':' | password))</literal>, where <literal>H</literal> is the SHA secure hash function as defined by RFC2945. The username is converted from a string to a <literal>byte[]</literal> using 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.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>salt</term>
+ <listitem>
+ <para>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. The value 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>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>g</term>
+ <listitem>
+ <para>SRP algorithm primitive generator. This can be a well known fixed parameter rather than a per-user setting. The <classname>org.jboss.security.srp.SRPConf</classname> utility class provides several settings for <literal>g</literal>, including a suitable default 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>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>N</term>
+ <listitem>
+ <para>SRP algorithm safe-prime modulus. This can be a well known fixed parameter rather than a per-user setting. The <classname>org.jboss.security.srp.SRPConf</classname> 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 stored 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>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <procedure>
+ <title>Integrate Existing Password Store</title>
+ <para>This procedure discusses the steps involved to integrate your existing password store.</para>
+ <step>
+ <title>Create Hashed Password Information Store</title>
+ <para>If your passwords are already stored in an irreversible hashed form, then this can only be done on a per-user basis (for example, as part of an upgrade procedure).</para>
+ <para>You can implement <literal>setUserVerifier(String, VerifierInfo)</literal> as a no-op method, or a method that throws an exception stating that the store is read-only. </para>
+ </step>
+ <step>
+ <title>Create SRPVerifierStore Interface</title>
+ <para>You must create a custom <literal>SRPVerifierStore</literal> interface implementation that understands how to obtain the <literal>VerifierInfo</literal> from the store you created. </para>
+ <para>The <methodname>verifyUserChallenge(String, Object)</methodname> can be used to integrate existing hardware token based schemes like SafeWord or Radius into the SRP algorithm. This interface method is called only when the client <literal>SRPLoginModule</literal> configuration specifies the <literal>hasAuxChallenge</literal> option.</para>
+ </step>
+ <step>
+ <title>Create JNDI MBean</title>
+ <para>You must create a MBean that exposes the <literal>SRPVerifierStore</literal> interface available to JNDI, and exposes any configurable parameters required.</para>
+ <para>The default <literal>org.jboss.security.srp.SRPVerifierStoreService</literal> will allow you to implement this, however you can also implement the MBean using a Java properties file implementation of <literal>SRPVerifierStore</literal> (refer to <xref linkend="sect-Secure_Remote_Password_Example"/>). </para>
+ </step>
+ </procedure>
</example>
</section>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-IdentiyLoginModule.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-IdentiyLoginModule.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-IdentiyLoginModule.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -11,7 +11,7 @@
This module supports password stacking.
</para>
</note>
- <para>This login module is useful when you need to provide a fixed identity to a service and in development environments when you want to test the security associated with a given principal and associated roles.
+ <para>This login module is useful when you need to provide a fixed identity to a service, and in development environments when you want to test the security associated with a given principal and associated roles.
</para>
<para>
The supported login module configuration options include:
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-LdapLoginModule.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-LdapLoginModule.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-LdapLoginModule.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -216,11 +216,11 @@
</application-policy>
</programlisting>
</example>
+ <para>
+ An LDIF file representing the structure of the directory this data operates against is shown below.
+ </para>
<example id="exam-LDIF_File_Example">
<title>LDIF File Example</title>
- <para>
- An LDIF file representing the structure of the directory this data operates against is shown below.
- </para>
<programlisting>dn: dc=jboss,dc=org
objectclass: top
objectclass: dcObject
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Password_Hashing.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Password_Hashing.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Password_Hashing.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -6,7 +6,7 @@
<section id="Using_JBoss_Login_Modules-Password_Hashing">
<title>Password Hashing</title>
<para>
- Most login modules need to compare a client-supplied password to a password stored in a user management system. These modules generally work with plain text passwords, but can be configured to support hashed passwords to prevent plain text passwords from being stored on the server side.
+ Most login modules must compare a client-supplied password to a password stored in a user management system. These modules generally work with plain text passwords, but can be configured to support hashed passwords to prevent plain text passwords from being stored on the server side.
</para>
<example>
<title/>
@@ -60,7 +60,7 @@
</varlistentry>
</variablelist>
<para>
- If you need to generate passwords in code, <classname>the org.jboss.security.Util</classname> class provides a static helper method that will hash a password using the specified encoding.
+ If you must generate passwords in code, <classname>the org.jboss.security.Util</classname> class provides a static helper method that will hash a password using the specified encoding.
</para>
<programlisting>String hashedPassword = Util.createPasswordHash("MD5",
Util.BASE64_ENCODING,
@@ -73,6 +73,6 @@
</para>
<programlisting>echo -n password | openssl dgst -md5 -binary | openssl base64</programlisting>
<para>
- In both cases, the text password should hash to <literal>X03MO1qnZdYdgyfeuILPmQ==</literal>. This value would need to be stored in the user store.
+ In both cases, the text password should hash to <literal>X03MO1qnZdYdgyfeuILPmQ==</literal>. This value must be stored in the user store.
</para>
</section>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-RunAsLoginModule.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-RunAsLoginModule.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-RunAsLoginModule.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -6,7 +6,7 @@
<section id="sect-RunAsLoginModule">
<title>RunAsLoginModule</title>
<para><literal>RunAsLoginModule</literal> is a helper module that pushes a run as role for the duration of the login phase of authentication, and pops the run as role in either the commit or abort phase. </para>
- <para>The purpose of this login module is to provide a role for other login modules that need to access secured resources in order to perform their authentication (for example, a login module that accesses an secured EJB). <literal>RunAsLoginModule</literal> must be configured ahead of the login module(s) that require a run as role established.
+ <para>The purpose of this login module is to provide a role for other login modules that must access secured resources in order to perform their authentication (for example, a login module that accesses an secured EJB). <literal>RunAsLoginModule</literal> must be configured ahead of the login module(s) that require a run as role established.
</para>
<para>
The only login module configuration option is:
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Secure_Remote_Password_Example.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Secure_Remote_Password_Example.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Secure_Remote_Password_Example.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -6,7 +6,9 @@
<section id="sect-Secure_Remote_Password_Example">
<title>Secure Remote Password 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.
+ The example presented in this section 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. </para>
+ <para>The server side login module configuration is dynamically installed using the <literal>SecurityConfig</literal> MBean. A custom implementation of the <literal>SRPVerifierStore</literal> interface is also used in the example. The interface 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>. </para>
+ <para>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
@@ -19,10 +21,11 @@
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.
+ The key SRP related items in this example are the SRP MBean services configuration, and the SRP login module configurations. The <filename>jboss-service.xml</filename> descriptor of the <filename>security-ex3.sar</filename> is described in <xref linkend="An_SRP_example-The_security_ex3.sar_jboss_service.xml_descriptor_for_the_SRP_services"/>. </para>
+ <para>The example client side and server side login module configurations are described in <xref linkend="An_SRP_example-The_client_side_standard_JAAS_configuration"/> and <xref linkend="An_SRP_example-The_server_side_XMLLoginConfig_configuration"/> give .
</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>
+ <title>The security-ex3.sar jboss-service.xml Descriptor</title>
<programlisting language="XML" role="XML"><server>
<!-- The custom JAAS login configuration that installs
a Configuration capable of dynamically updating the
@@ -54,6 +57,9 @@
</server>
</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>
<example id="An_SRP_example-The_client_side_standard_JAAS_configuration">
<title>The client side standard JAAS configuration</title>
<programlisting>srp {
@@ -67,6 +73,9 @@
};
</programlisting>
</example>
+ <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>
<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">
@@ -83,18 +92,19 @@
</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>There are two issues to note about the server side login module configuration: </para>
+ <orderedlist>
+ <listitem>
+ <para>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. </para>
+ </listitem>
+ <listitem>
+ <para>The configuration includes a <literal>UsersRolesLoginModule</literal> with the <literal>password-stacking=useFirstPass</literal> configuration option. You must use a second login module with the <literal>SRPCacheLoginModule</literal> because SRP is only an authentication technology. To set the principal's roles that in turn determine the associated permissions, a second login module must be configured to accept the authentication credentials validated by the <literal>SRPCacheLoginModule</literal> . </para>
+ </listitem>
+ </orderedlist>
+ <para>The <literal>UsersRolesLoginModule</literal> is augmenting the SRP authentication with properties file based authorization. The user's roles are obtained from the <literal>roles.properties</literal> file included in the EJB JAR.
</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>Run the example 3 client by executing the following command from the book examples directory:
</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:
@@ -103,10 +113,9 @@
[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>In the <literal>examples/logs</literal> directory, the <literal>ex3-trace.log</literal> file contains 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>You may have noted 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 longer when it first executes. Subsequent authentication attempts within the same VM are much faster. </para>
+ <para>You may have also noted 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 10 seconds to force this issue. As discussed in <xref linkend="sect-Secure_Remote_Password_Example"/> you must make the cache timeout very long, or handle re-authentication on failure.
</para>
</section>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Security_Identity.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Security_Identity.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Security_Identity.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -20,7 +20,7 @@
The invocation identity can be that of the current caller, or it can be a specific role. The application assembler uses the <literal>security-identity</literal> element with a <markup>use-caller-identity</markup> child element to indicate that the current caller's identity should be propagated as the security identity for method invocations made by the EJB. Propagation of the caller's identity is the default used in the absence of an explicit <markup>security-identity</markup> element declaration.
</para>
<para>
- Alternatively, the application assembler can use the <markup>run-as/role-name</markup> child element to specify that a specific security role given by the <markup>role-name</markup> value should be used as the security identity for method invocations made by the EJB. Note that this does not change the caller's identity as seen by the <methodname>EJBContext.getCallerPrincipal()</methodname> method. Rather, the caller's security roles are set to the single role specified by the <markup>run-as/role-name</markup> element value. One use case for the <markup>run-as</markup> element is to prevent external clients from accessing internal EJBs. You accomplish this by assigning the internal EJB <markup>method-permission</markup> elements that restrict access to a role never assigned to an external client. EJBs that need to use internal EJB are then configured with a <markup>run-as/role-name</markup> equal to the restricted role. The following descriptor fragment that il!
lustrates <markup>security-identity</markup> element usage.
+ Alternatively, the application assembler can use the <markup>run-as/role-name</markup> child element to specify that a specific security role given by the <markup>role-name</markup> value should be used as the security identity for method invocations made by the EJB. Note that this does not change the caller's identity as seen by the <methodname>EJBContext.getCallerPrincipal()</methodname> method. Rather, the caller's security roles are set to the single role specified by the <markup>run-as/role-name</markup> element value. One use case for the <markup>run-as</markup> element is to prevent external clients from accessing internal EJBs. You accomplish this by assigning the internal EJB <markup>method-permission</markup> elements that restrict access to a role never assigned to an external client. EJBs that must use internal EJB are then configured with a <markup>run-as/role-name</markup> equal to the restricted role. The following descriptor fragment that illus!
trates <markup>security-identity</markup> element usage.
</para>
<programlisting language="XML" role="XML"><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
@@ -47,7 +47,7 @@
</ejb-jar>
</programlisting>
<para>
- When you use <markup>run-as</markup> to assign a specific role to outgoing calls, JBoss associates a principal named <markup>anonymous</markup>. If you want another principal to be associated with the call, you need to associate a <markup>run-as-principal</markup> with the bean in the <filename>jboss.xml</filename> file. The following fragment associates a principal named <literal>internal</literal> with <literal>RunAsBean</literal> from the prior example.
+ When you use <markup>run-as</markup> to assign a specific role to outgoing calls, JBoss associates a principal named <markup>anonymous</markup>. If you want another principal to be associated with the call, you must associate a <markup>run-as-principal</markup> with the bean in the <filename>jboss.xml</filename> file. The following fragment associates a principal named <literal>internal</literal> with <literal>RunAsBean</literal> from the prior example.
</para>
<programlisting language="XML" role="XML"><session>
<ejb-name>RunAsBean</ejb-name>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Subject_Usage_Pattern_Support.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Subject_Usage_Pattern_Support.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Subject_Usage_Pattern_Support.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -228,7 +228,7 @@
</para>
</formalpara>
<para>
- When subclassing the <literal>AbstractServerLoginModule</literal>, you need to override the following:
+ When subclassing the <literal>AbstractServerLoginModule</literal>, you must override the following:
</para>
<itemizedlist>
<listitem>
@@ -253,7 +253,7 @@
</listitem>
</itemizedlist>
<para>
- When subclassing the <literal>UsernamePasswordLoginModule</literal>, you need to override the following:
+ When subclassing the <literal>UsernamePasswordLoginModule</literal>, you must override the following:
</para>
<itemizedlist>
<listitem>
Modified: projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Understanding_The_Algorithm.xml
===================================================================
--- projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Understanding_The_Algorithm.xml 2010-05-26 05:21:48 UTC (rev 105236)
+++ projects/docs/enterprise/trunk/EAP_5.0/JBoss_Security_Guide/en-US/sect-Understanding_The_Algorithm.xml 2010-05-26 05:41:17 UTC (rev 105237)
@@ -5,13 +5,17 @@
]>
<section id="sect-Understanding_The_Algorithm">
<title>Understanding the 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>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. </para>
+ <note>
+ <para>Additional information on the SRP algorithm and its history can be found at <ulink url="http://www-cs-students.stanford.edu/~tjw/srp/"/>.
+ </para>
+ </note>
+<!--TODO: Perhaps make this epic orderedlist a procedure and summarize each step. --> <para>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.
+ The client side <literal>SRPLoginModule</literal> retrieves from the naming service the SRPServerInterface instance for the remote authentication server.
</para>
</listitem>
<listitem>
@@ -40,31 +44,31 @@
</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>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>Where authentication is performed, the way in which JBoss detaches the method transport protocol from the component container could allow a user to snoop the SRP <literal>M1</literal> challenge and effectively use the challenge to make requests as the associated username. Custom interceptors can be used to prevent the issue, by encrypting the challenge using the SRP session key.
</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>
+ 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 quite high, or handle re-authentication in your code on failure. </para>
+ <note>
+ <para>While excessive, the SRPService supports timeout durations up to 2,147,483,647 seconds, or approximately 68 years.</para>
+ </note>
</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>There can only be one SRP session for a given username by default. The session is classed as stateful, because the negotiated SRP session produces a private session key that can be used for encryption and decryption between the client and server. JBoss supports multiple SRP sessions per user, however it is not possible to encrypt data with one session key, and 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.
+ To use end-to-end SRP authentication for Java EE component calls, you must configure the security domain under which the components are secured to use the <classname>org.jboss.security.srp.jaas.SRPCacheLoginModule</classname>. 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. </para>
+ <para>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="fig-SRPCacheLoginModule_with_SRP_Session_Cache"/> illustrates 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>
+ <figure id="fig-SRPCacheLoginModule_with_SRP_Session_Cache">
+ <title>SRPCacheLoginModule with SRP Session Cache</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/j2ee_chap8-14.jpg"/>
More information about the jboss-cvs-commits
mailing list