[jboss-cvs] JBossRemoting/docs/guide/en ...
Ron Sigal
ron_sigal at yahoo.com
Fri Jul 28 02:49:01 EDT 2006
User: rsigal
Date: 06/07/28 02:49:01
Modified: docs/guide/en master.xml
Log:
JBREM-520: Added section about configuring socket and server socket factories, incorporating and extending information about SSL configuration.
Revision Changes Path
1.30 +1366 -705 JBossRemoting/docs/guide/en/master.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: master.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/master.xml,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -b -r1.29 -r1.30
--- master.xml 27 Jul 2006 19:54:58 -0000 1.29
+++ master.xml 28 Jul 2006 06:49:01 -0000 1.30
@@ -1176,170 +1176,6 @@
if all the threads in the pool are in use until one is
released.</para>
- <section>
- <title>Socket factories and server socket factories</title>
-
- <para>All server invokers use server sockets, and it makes sense,
- therefore, to be able to configure server invokers with server
- socket factories. It is also true, though less obvious. that server
- invokers create sockets (other than by way of server sockets). When
- a server invoker makes an asynchronous callback to a client, it
- creates a client invoker, which creates a socket. Moreover, some
- server invokers, e.g., the RMI server invoker, have their own
- idiosyncratic uses for socket factories. Remoting offers a number of
- ways of configuring socket factories and server socket factories,
- and these apply to all server invokers.</para>
-
- <para>For <classname>ServerSocketFactory</classname>s, there are
- eight means of configuration:</para>
-
- <orderedlist>
- <listitem>
- <para>Call
- <methodname>Connector.setServerSocketFactory()</methodname>.</para>
- </listitem>
-
- <listitem>
- <para>Get the <classname>ServerInvoker</classname> from the
- <classname>Connector</classname> and call
- <methodname>ServerInvoker.setServerSocketFactory()</methodname>.</para>
- </listitem>
-
- <listitem>
- <para>Put a constructed
- <classname>ServerSocketFactory</classname> in a configuration
- map, using key
- <constant>Remoting.CUSTOM_SERVER_SOCKET_FACTORY</constant>, and
- pass the map to one of the <classname>Connector</classname>
- constructors.</para>
- </listitem>
-
- <listitem>
- <para>Put the <classname>ObjectName</classname> of a
- <classname>ServerSocketFactoryMBean</classname> in a
- configuration map, using key
- <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>, and
- pass the map to one of the <classname>Connector</classname>
- constructors.</para>
- </listitem>
-
- <listitem>
- <para>Put the class name of a
- <classname>ServerSocketFactory</classname> in a configuration
- map, using key
- <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>, and
- pass the map to one of the <classname>Connector</classname>
- constructors. In this case, an instance of the class will be
- created using the default constructor.</para>
- </listitem>
-
- <listitem>
- <para>Put a set of SSL parameters, using the keys in
- <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
- in a configuration map and pass the map to one of the
- <classname>Connector</classname> constructors. These will be
- used by <classname>SSLSocketBuilder</classname> to create a
- <classname>CustomSSLServerSocketFactory</classname>.</para>
- </listitem>
-
- <listitem>
- <para>Configure an appropriate set of SSL system properties and
- use one of the SSL transports (https, sslmultiplex, sslrmi, or
- sslsocket). The properties will be used to create some kind of
- <classname>SSLServerSocketFactory</classname>, as determined by
- the transport.</para>
- </listitem>
-
- <listitem>
- <para>Use one of the non-SSL transports and do nothing. A
- default <classname>ServerSocketFactory</classname> will be
- constructed.</para>
- </listitem>
- </orderedlist>
-
- <para>These methods are essentially in descending order of
- precedence. Methods 1) and 2) have equal precedence, and the last
- one to be used prior to calling
- <methodname>Connector.create()</methodname> will determine the
- <classname>ServerSocketFactory</classname> that gets used.
- Otherwise, if methods 3) and 6), for example, are both used, the
- factory passed in method 3) will prevail.</para>
-
- <para>For <classname>SocketFactory</classname>s, there are also
- eight means of configuration, and they are essentially the
- same:</para>
-
- <orderedlist>
- <listitem>
- <para>Call
- <methodname>Connector.setSocketFactory()</methodname>.</para>
- </listitem>
-
- <listitem>
- <para>Get the <classname>ServerInvoker</classname> from the
- <classname>Connector</classname> and call
- <methodname>ServerInvoker.setSocketFactory()</methodname>.</para>
- </listitem>
-
- <listitem>
- <para>Put a constructed <classname>SocketFactory</classname> in
- a configuration map, using key
- <constant>Remoting.CUSTOM_SOCKET_FACTORY</constant>, and pass
- the map to one of the <classname>Connector</classname>
- constructors.</para>
- </listitem>
-
- <listitem>
- <para>Put the <classname>ObjectName</classname> of a
- <classname>ServerSocketFactoryMBean</classname> in a
- configuration map, using key
- <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>, and
- pass the map to one of the <classname>Connector</classname>
- constructors. If the MBean has type
- <classname>SSLServerSocketFactoryServiceMBean</classname>, its
- configuration information will be gathered and used to construct
- a <classname>CustomSSLSocketFactory</classname>. <emphasis
- role="bold">Note.</emphasis> This method is guaranteed to work
- only for callback client invokers. For other, transport
- specific, socket factory uses, the transport may or may not use
- this information.</para>
- </listitem>
-
- <listitem>
- <para>Put the class name of a
- <classname>SocketFactory</classname> in a configuration map,
- using key <constant>Remoting.SOCKET_FACTORY_NAME</constant>, and
- pass the map to one of the <classname>Connector</classname>
- constructors. In this case, an instance of the class will be
- created using the default constructor.</para>
- </listitem>
-
- <listitem>
- <para>Put a set of SSL parameters, using the keys in
- <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
- in a configuration map and pass the map to one of the
- <classname>Connector</classname> constructors. These will be
- used by <classname>SSLSocketBuilder</classname> to create a
- <classname>CustomSSLSocketFactory</classname>.</para>
- </listitem>
-
- <listitem>
- <para>Configure an appropriate set of SSL system properties and
- use one of the SSL transports (https, sslmultiplex, sslrmi, or
- sslsocket). The properties will be used to create some kind of
- <classname>SSLSocketFactory</classname>, as determined by the
- transport.</para>
- </listitem>
-
- <listitem>
- <para>Use one of the non-SSL transports and do nothing. Ordinary
- <classname>Socket</classname>s will be used.</para>
- </listitem>
- </orderedlist>
-
- <para>Again, these are essentially in descending order of
- precedence.</para>
- </section>
</section>
<section>
@@ -1889,7 +1725,7 @@
</section>
<section>
- <title id="section:multiplex" xreflabel="Multiplex Invoker">Multiplex
+ <title id="section-multiplex" xreflabel="Multiplex Invoker">Multiplex
Invoker</title>
<para>The multiplex invoker is intended to replicate the functionality
@@ -2504,7 +2340,7 @@
demo.jboss.com:8080.</para>
<para>For complete examples see the section <xref
- linkend="section:multiplex-invokers" />.</para>
+ linkend="section-multiplex-invokers" />.</para>
<orderedlist>
<listitem>
@@ -2683,29 +2519,19 @@
<orderedlist numeration="arabic">
<listitem>
- The following properties are managed by ancestor classes of
-
- <classname>MultiplexServerInvoker</classname>
-
- . See the discussion under
-
- <classname>SocketServerInvoker</classname>
-
- for more information.
-
- <para><emphasis role="bold">timeout</emphasis> - The socket
- timeout value passed to the
+ <para>The following properties are managed by ancestor classes
+ of <classname>MultiplexServerInvoker</classname>. See the discussion
+ under <classname>SocketServerInvoker</classname> for more
+ information.</para>
+ <para><emphasis role="bold">socketTimeout</emphasis> - The
+ socket timeout value passed to the
<methodname>Socket.setSoTimeout()</methodname> method and the
<methodname>ServerSocket.setSoTimeout()</methodname> method. The
default is 60000 (or 1 minute).</para>
-
-
<para><emphasis role="bold">numAcceptThreads</emphasis> - The
number of threads that exist for accepting client connections.
The default is 1.</para>
-
-
</listitem>
<listitem>
@@ -3239,100 +3065,676 @@
</section>
<section>
- <title>SSL Support and configuration</title>
+ <title>Socket factories and server socket factories</title>
- <para>There are three transports that now support SSL: sslsocket,
- sslmultiplex, and https. This section will cover configuration,
- implementation, some samples, and some troubleshooting tips.</para>
-
- <para>Both the sslsocket and https transports are extensions of their
- non-ssl counterparts, socket and http transports, so the same basic
- configurations will apply. Therefore, only the ssl specific
- configurations will be covered here. Moreover, sslmultiplex has the same
- relationship to multiplex that sslsocket has to socket, so the
- discussion of sslsocket applies as well to sslmultiplex.</para>
+ <para>All current transports depend on sockets and server sockets, and the
+ ability to specify their implementation classes provides considerable
+ power in configuring Remoting. Notably, SSL sockets
+ and server sockets are the basis of secure communications in Remoting.
+ This section covers the configuration of socket factories and server
+ socket factories on both the server side and the client side, and then
+ focuses on SSL configuration.
+ </para>
- <para>An example of a service xml that covers all the different
- transport and service configurations can be found within the
- example-service.xml file under the etc directory of the JBoss Remoting
- distribution.</para>
+ <section>
+ <title>Server side programmatic configuration</title>
+ <para>
+ All server invokers use server sockets, and it makes sense,
+ therefore, to be able to configure server invokers with
+ server socket factories. It is also true, though less obvious.
+ that server invokers create sockets (other than by way of
+ server sockets). When a server invoker makes a push
+ callback to a client, it creates a client invoker, which creates a
+ socket. Moreover, some server invokers, e.g., the RMI server invoker,
+ have their own idiosyncratic uses for socket factories. Remoting offers a
+ number of ways of configuring socket factories and server socket
+ factories, and these apply to all transports.
+ </para>
- <bridgehead>sslsocket</bridgehead>
+ <section>
+ <title id="section-ssf-serverside" xreflabel="Server socket factories">
+ Server socket factories.
+ </title>
+ <para>For <classname>ServerSocketFactory</classname>s, there are
+ ten options for programmatic configuration:</para>
- <para>The sslsocket transport can be defined in one of two ways if using
- a service xml to declare the remoting server. The first is to use the
- sslsocket protocol keyword in the locator url of the InvokerLocator
- attribute value of the Connector service mbean. For example:</para>
+ <orderedlist>
- <programlisting>
- <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">
+ <listitem>
+ <para>Get the <classname>ServerInvoker</classname> by calling
+ <methodname>Connector.getServerInvoker()</methodname> and call
+ <methodname>ServerInvoker.setServerSocketFactory()</methodname>.</para>
+ </listitem>
- <attribute name="InvokerLocator">sslsocket://myhost:8084</attribute>
- </programlisting>
+ <listitem>
+ <para>Call <methodname>Connector.setServerSocketFactory()</methodname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put a constructed <classname>ServerSocketFactory</classname> in a
+ configuration map, using key
+ <constant>Remoting.CUSTOM_SERVER_SOCKET_FACTORY</constant>,
+ and pass the map to one of the <classname>Connector</classname>
+ constructors.
+ </para>
+ </listitem>
- <para>The other way is to not use the InvokerLocator attribute, but
- instead a more verbose Configuration attribute, which declares the
- invoker transport type as a sub-element. For example:</para>
+ <listitem>
+ <para>
+ Create an xml document with root element <code><config></code>,
+ setting the <code><serverSocketFactory></code> attribute to
+ the name of a <classname>ServerSocketFactoryMBean</classname> and pass
+ the document to <methodname>Connector.setConfiguration()</methodname>. For
+ example:
<programlisting>
- <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">
+ StringBuffer buf = new StringBuffer();
+ buf.append("<?xml version=\"1.0\"?>\n");
+ buf.append("<config>");
+ buf.append(" <invoker transport=\"sslsocket\">");
+ buf.append(" <attribute name=\"serverBindAddress\">" + getHostName() + "</attribute>");
+ buf.append(" <attribute name=\"serverBindPort\">" + freeport + "</attribute>");
+ buf.append(" <attribute name=\"serverSocketFactory\">" + socketFactoryObjName + "</attribute>");
+ buf.append(" </invoker>");
+ buf.append("</config>");
+ ByteArrayInputStream bais = new ByteArrayInputStream(buf.toString().getBytes());
+ Document xml = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(bais);
+ connector.setConfiguration(xml.getDocumentElement());
+ </programlisting>
+ </para>
+ </listitem>
- <attribute name="Configuration">
- <config>
- <invoker transport="sslsocket">
- <attribute name="numAcceptThreads">1</attribute>
- <attribute name="maxPoolSize">303</attribute>
+ <listitem>
+ <para>
+ Create an xml document with root element <code><config></code>,
+ setting the <code><serverSocketFactory></code> attribute to
+ the class name of a <classname>ServerSocketFactory</classname> and pass
+ the document to <methodname>Connector.setConfiguration()</methodname>.
+ The <code><serverSocketFactory></code> class must have a default
+ constructor, which will be used to create a
+ <classname>ServerSocketFactory</classname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put the <classname>ObjectName</classname> of a
+ <classname>ServerSocketFactoryMBean</classname> in a configuration map,
+ using key <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>,
+ and pass the map to one of the <classname>Connector</classname>
+ constructors.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put the class name of a <classname>ServerSocketFactory</classname>
+ in a configuration map, using key
+ <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>,
+ and pass the map to one of the <classname>Connector</classname> constructors.
+ The <code><serverSocketFactory></code> class must have a
+ default constructor, which will be used to create a
+ <classname>ServerSocketFactory</classname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put a set of SSL parameters, using the keys in
+ <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>, in a
+ configuration map and pass the map to one of the
+ <classname>Connector</classname> constructors. These will be used by
+ <classname>SSLSocketBuilder</classname> (see below) to create a
+ <classname>CustomSSLServerSocketFactory</classname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Configure an appropriate set of SSL system properties
+ and use one of the SSL transports (https, sslmultiplex,
+ sslrmi, or sslsocket). The properties will be used to
+ create some kind of <classname>SSLServerSocketFactory</classname>,
+ as determined by the transport.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use one of the non-SSL transports and do nothing. A default
+ <classname>ServerSocketFactory</classname> will be constructed.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ These options are essentially in descending order of precedence.
+ If options 3 and 6, for example, are both
+ used, the factory passed in option 3 will prevail.
+ Options 4 and 5 are mutually exclusive, as are options 6 and 7.
+ Options 1, 2, 3, 5, and 7 are illustrated in
+ <classname>FactoryConfigSample</classname>
+ and options 4, 6, 8, and 9 are illustrated in
+ <classname>FactoryConfigSSLSample</classname>,
+ both of which are in package
+ <classname>org.jboss.remoting.samples.config.factories</classname>.
+ </para>
+
+ <para>
+ <emphasis role="bold">Timing considerations.</emphasis> The
+ <classname>ServerInvoker</classname>, for any transport, is created
+ during the call to <methodname>Connector.create()</methodname>, before which
+ option 1 is unavailable. Option 2, on the other hand,
+ is only available before the call to
+ <methodname>Connector.create()</methodname>.
+ Once the <classname>ServerInvoker</classname> has been created, it
+ selects a <classname>ServerSocketFactory</classname>, according to
+ the rules enumerated above, during the <methodname>create()</methodname>
+ phase. For all current transports, the actual
+ <classname>ServerSocket</classname> is created during the call to
+ <methodname>Connector.start()</methodname>, so that a call to
+ <methodname>ServerInvoker.setServerSocketFactory()</methodname>
+ (option 1) can override the selected <classname>ServerSocketFactory</classname>
+ until <methodname>Connector.start()</methodname> is called.
+ </para>
+ </section>
+
+ <section>
+ <title>Socket factories</title>
+ <para>
+ For <classname>SocketFactory</classname>s, there are also ten options
+ for programmatic configuration, and they are essentially the same as
+ the previous ten:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Call <methodname>Connector.setSocketFactory()</methodname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Get the <classname>ServerInvoker</classname> by calling
+ <methodname>Connector.getServerInvoker()</methodname> and call
+ <methodname>ServerInvoker.setSocketFactory()</methodname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put a constructed <classname>SocketFactory</classname> in a
+ configuration map, using key
+ <constant>Remoting.CUSTOM_SOCKET_FACTORY</constant>, and pass
+ the map to one of the <classname>Connector</classname> constructors.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Create an xml document with root element <code><config></code>,
+ setting the <code><serverSocketFactory></code> attribute to
+ the name of a <classname>ServerSocketFactoryMBean</classname> and pass
+ the document to <methodname>Connector.setConfiguration()</methodname>.
+ If the MBean has type
+ <classname>SSLServerSocketFactoryServiceMBean</classname>, its
+ configuration information will be gathered and used to construct a
+ <classname>CustomSSLSocketFactory</classname>.
+ <emphasis role="bold">Note.</emphasis> This method is guaranteed to
+ work only for callback client invokers. For other, transport
+ specific, socket factory uses, the transport may or may not
+ use this information.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put the <classname>ObjectName</classname> of a
+ <classname>ServerSocketFactoryMBean</classname> in a configuration
+ map, using key <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>,
+ and pass the map to one of the <classname>Connector</classname>
+ constructors. If the MBean has type
+ <classname>SSLServerSocketFactoryServiceMBean</classname>, its
+ configuration information will be gathered and used to construct a
+ <classname>CustomSSLSocketFactory</classname>.
+ <emphasis role="bold">Note.</emphasis> This method is guaranteed to
+ work only for callback client invokers. For other, transport
+ specific, socket factory uses, the transport may or may not
+ use this information.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Create an xml document with root element <code><config></code>,
+ setting the <code><socketFactory></code> attribute to
+ the class name of a <classname>SocketFactory</classname> and pass
+ the document to <methodname>Connector.setConfiguration()</methodname>.
+ For example:
+
+ <programlisting>
+ StringBuffer buf = new StringBuffer();
+ buf.append("<?xml version=\"1.0\"?>\n");
+ buf.append("<config>");
+ buf.append(" <invoker transport=\"sslsocket\">");
+ buf.append(" <attribute name=\"serverBindAddress\">" + getHostName() + "</attribute>");
+ buf.append(" <attribute name=\"serverBindPort\">" + freeport + "</attribute>");
+ buf.append(" <attribute name=\"socketFactory\">" + socketFactoryClassname + "</attribute>");
+ buf.append(" </invoker>");
+ buf.append("</config>");
+ ByteArrayInputStream bais = new ByteArrayInputStream(buf.toString().getBytes());
+ Document xml = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(bais);
+ connector.setConfiguration(xml.getDocumentElement());
</programlisting>
- <para>If defining the remoting server programmatically, not from a
- server xml file, all that is needed is to create the InvokerLocator with
- sslsocket as the protocol. Of course the other Connector operations will
- be needed as well. A simple example would be:</para>
+ The <classname>SocketFactory</classname> class must have a
+ default constructor, which will be used to create a
+ <classname>SocketFactory</classname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put the class name of a <classname>SocketFactory</classname>
+ in a configuration map, using key
+ <constant>Remoting.SOCKET_FACTORY_NAME</constant>, and pass the map
+ to one of the <classname>Connector</classname> constructors. The
+ <classname>SocketFactory</classname> class
+ must have a default constructor.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put a set of SSL parameters, using the keys in
+ <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
+ in a configuration map and pass the map to one of the
+ <classname>Connector</classname> constructors. These will be used by
+ <classname>SSLSocketBuilder</classname> (see below) to create a
+ <classname>CustomSSLSocketFactory</classname>.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Configure an appropriate set of SSL system properties and use one of
+ the SSL transports (https, sslmultiplex, sslrmi, or sslsocket). The
+ properties will be used to create some kind of
+ <classname>SSLSocketFactory</classname>, as determined by the
+ transport.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use one of the non-SSL transports and do nothing. Ordinary
+ <classname>Socket</classname>s will be used.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>Again, these are essentially in descending order of precedence.
+ Options 1, 2, 3, 5, and 7 are illustrated in
+ <classname>FactoryConfigSample</classname>
+ and options 4, 6, 8, and 9 are illustrated in
+ <classname>FactoryConfigSSLSample</classname>,
+ both of which are in package
+ <classname>org.jboss.remoting.samples.config.factories</classname>.
+ </para>
+
+ <para>
+ <emphasis role="bold">Timing considerations.</emphasis> A new
+ <classname>Client</classname>, with a client invoker, is created
+ on the server side whenever a callback listener is registered by a
+ call to <methodname>Client.addListener()</methodname>. If a
+ <classname>SocketFactory</classname> is supplied by any of options 1 to 5,
+ it will be passed to the <classname>Client</classname>. Otherwise, any
+ information from options 6 to 9 will be passed to the client invoker,
+ which will create a <classname>SocketFactory</classname> according
+ to the rules given below in the section on client side socket factory
+ configuration. Once <methodname>Connector.create()</methodname>
+ has been called,
+ <methodname>ServerInvoker.setSocketFactory()</methodname>, may be
+ called at any time to determine the
+ <classname>SocketFactory</classname> used by the next callback
+ client invoker.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Client side programmatic configuration</title>
+ <para>
+ On the client side it is possible to configure socket factories for client
+ invokers and to configure server socket factories for callback server invokers.
+ Configuration on the client side is largely the same as configuration
+ on the server side, with the exception that no
+ <classname>MBeanServer</classname> is assumed to be present, and the
+ <classname>Client</classname> has no facilities for parsing xml
+ documents.
+ </para>
+
+ <section>
+ <title>Server socket factories.</title>
+ <para>For <classname>ServerSocketFactory</classname>s in callback
+ server invokers, there are
+ eight options for programmatic configuration, which are identical to
+ options 1-3, 5 and 7-10 on the server side (we don't assume the
+ existence of an <classname>MBeanServer</classname> on the client
+ side:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Get the <classname>ServerInvoker</classname> by calling
+ <methodname>Connector.getServerInvoker()</methodname> and call
+ <methodname>ServerInvoker.setServerSocketFactory()</methodname>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Call <methodname>Connector.setServerSocketFactory()</methodname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put a constructed <classname>ServerSocketFactory</classname> in a
+ configuration map, using key
+ <constant>Remoting.CUSTOM_SERVER_SOCKET_FACTORY</constant>,
+ and pass the map to one of the <classname>Connector</classname>
+ constructors.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Create an xml document with root element <code><config></code>,
+ setting the <code><serverSocketFactory></code> attribute to
+ the class name of a <classname>ServerSocketFactory</classname> and pass
+ the document to <methodname>Connector.setConfiguration()</methodname>.
+ For example:
<programlisting>
- Connector connector = new Connector();
- InvokerLocator locator = new InvokerLocator(“sslsocket://myhost:8084â€);
- connector.setInvokerLocator(locator.getLocatorURI());
- connector.create();
- connector.addInvocationHandler(getSubsystem(), getServerInvocationHandler());
- connector.start();
+ StringBuffer buf = new StringBuffer();
+ buf.append("<?xml version=\"1.0\"?>\n");
+ buf.append("<config>");
+ buf.append(" <invoker transport=\"sslsocket\">");
+ buf.append(" <attribute name=\"serverBindAddress\">" + getHostName() + "</attribute>");
+ buf.append(" <attribute name=\"serverBindPort\">" + freeport + "</attribute>");
+ buf.append(" <attribute name=\"serverSocketFactory\">" + serverSocketFactoryClassname + "</attribute>");
+ buf.append(" </invoker>");
+ buf.append("</config>");
+ ByteArrayInputStream bais = new ByteArrayInputStream(buf.toString().getBytes());
+ Document xml = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(bais);
+ connector.setConfiguration(xml.getDocumentElement());
</programlisting>
- <bridgehead>SSL Server Socket Selection</bridgehead>
+ The <classname>ServerSocketFactory</classname> class must
+ have a default constructor, which will be used to create a
+ <classname>ServerSocketFactory</classname>.
+ </para>
+ </listitem>
- <para>All of the forms of configuration mentioned previously will use
- the default configuration for selecting which SSL server socket factory
- to use. Technically, this is done by calling on the
- <code>javax.net.ssl.SSLServerSocketFactory</code> ’s
- <code>getDefault()</code> method. This will require that both the
- <code>javax.net.ssl.keyStore</code> and the
- <code>javax.net.ssl.keyStorePassword</code> system properties are set.
- This can be done by either calling the <code>System.setProperty()</code>
- or via JVM arguments. This also means that all the SSL configurations
- default to those of the JVM vendor.</para>
-
- <para>There are two ways in which to customize the SSL configuration to
- be used by the SSLSocketServerInvoker. The first is to explicitly set
- the server socket factory that the invoker should use to create its
- server sockets. This can be done programmatically via the following
- method (which is also exposed as a JMX operation):</para>
+ <listitem>
+ <para>
+ Put the class name of a <classname>ServerSocketFactory</classname>
+ in a configuration map, using key
+ <constant>ServerInvoker.SERVER_SOCKET_FACTORY</constant>,
+ and pass the map to one of the <classname>Connector</classname> constructors.
+ The <classname>ServerSocketFactory</classname> class must
+ have a default constructor, which will be used to create a
+ <classname>ServerSocketFactory</classname>.</para>
+ </listitem>
- <programlisting>public void setServerSocketFactory(ServerSocketFactory serverSocketFactory)</programlisting>
+ <listitem>
+ <para>
+ Put a set of SSL parameters, using the keys in
+ <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>, in a
+ configuration map and pass the map to one of the
+ <classname>Connector</classname> constructors. These will be used by
+ <classname>SSLSocketBuilder</classname> (see below) to create a
+ <classname>CustomSSLServerSocketFactory</classname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Configure an appropriate set of SSL system properties
+ and use one of the SSL transports (https, sslmultiplex,
+ sslrmi, or sslsocket). The properties will be used to
+ create some kind of <classname>SSLServerSocketFactory</classname>,
+ as determined by the transport.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use one of the non-SSL transports and do nothing. A default
+ <classname>ServerSocketFactory</classname> will be constructed.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ These options are essentially in descending order of precedence.
+ For example, if options 3 and 5, for example, are both
+ used, the factory passed in options 3 will prevail.
+ Options 1, 2, 3, 4, and 5 are illustrated in
+ <classname>FactoryConfigSample</classname>
+ and options 6 and 7 are illustrated in
+ <classname>FactoryConfigSSLSample</classname>,
+ both of which are in package
+ <classname>org.jboss.remoting.samples.config.factories</classname>.
+ </para>
+
+ <para>
+ <emphasis role="bold">Timing considerations.</emphasis> See the
+ discussion in the section on the creation of server socket factories
+ on the server side.
+ </para>
+ </section>
+
+ <section>
+ <title>Socket factories.</title>
+ <para>
+ For <classname>SocketFactory</classname>s in client invokers,
+ there are seven options
+ for programmatic configuration, and they are essentially the same as
+ 1-3 and 5-8 in the previous section (<classname>Client</classname>
+ has no facility for parsing xml documents:</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Get the <classname>ClientInvoker</classname> by calling
+ <methodname>Client.getInvoker()</methodname> and call
+ <methodname>ClientInvoker.setSocketFactory()</methodname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Call <methodname>Client.setSocketFactory()</methodname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put a constructed <classname>SocketFactory</classname> in a
+ configuration map, using key
+ <constant>Remoting.CUSTOM_SOCKET_FACTORY</constant>, and pass
+ the map to one of the <classname>Client</classname> constructors.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put the class name of a <classname>SocketFactory</classname>
+ in a configuration map, using key
+ <constant>Remoting.SOCKET_FACTORY_NAME</constant>, and pass the map
+ to one of the <classname>Client</classname> constructors.
+ The <classname>SocketFactory</classname> class must
+ have a default constructor, which will be used to create a
+ <classname>SocketFactory</classname>.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Put a set of SSL parameters, using the keys in
+ <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
+ in a configuration map and pass the map to one of the
+ <classname>Client</classname> constructors. These will be used by
+ <classname>SSLSocketBuilder</classname> (see below) to create a
+ <classname>CustomSSLSocketFactory</classname>.
+
+ </para>
+ </listitem>
- <para>The server socket factory to be used by the invoker can also be
+ <listitem>
+ <para>
+ Configure an appropriate set of SSL system properties and use one of
+ the SSL transports (https, sslmultiplex, sslrmi, or sslsocket). The
+ properties will be used to create some kind of
+ <classname>SSLSocketFactory</classname>, as determined by the
+ transport.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use one of the non-SSL transports and do nothing. Ordinary
+ <classname>Socket</classname>s will be used.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>Again, these are essentially in descending order of precedence.
+ Options 1, 2, 3, and 4 are illustrated in
+ <classname>FactoryConfigSample</classname>
+ and options 5 and 6 are illustrated in
+ <classname>FactoryConfigSSLSample</classname>,
+ both of which are in package
+ <classname>org.jboss.remoting.samples.config.factories</classname>.
+ </para>
+
+ <para>
+ <emphasis role="bold">Timing considerations.</emphasis> A
+ <classname>SocketFactory</classname> is created in the constructor
+ for <classname>RemoteClientInvoker</classname>, the ancestor of
+ all current remote client invokers (that is, all client invokers except
+ <classname>LocalClientInvoker</classname>, which can make a call
+ by reference on a server invoker in the same JVM), but it is
+ currently used only by SSL transports, for which the timing
+ considerations vary.</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">https: </emphasis>
+ <classname>HTTPSClientInvoker</classname> sets the
+ socket factory on its
+ <classname>HttpsURLConnection</classname> each time
+ <methodname>Client.invoke()</methodname> is called. Option
+ 1 may be used to reset the <classname>SocketFactory</classname>
+ for future invocations at any time.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">sslmultiplex: </emphasis> Whichever
+ of <classname>SSLMultiplexClientInvoker</classname> or
+ <classname>SSLMultiplexServerInvoker</classname> first
+ gets sufficient bind and connect information to create a
+ priming socket (see the section on the multiplex invoker for
+ a discussion of priming sockets) passes the
+ current <classname>SocketFactory</classname> to be
+ used to create the actual
+ socket that supports the multiplexed connection. This
+ happens during the call to either
+ <methodname>Client.connect()</methodname> or
+ <methodname>Connector.create()</methodname>. Once the
+ actual socket is created, no further configuration is
+ possible
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">sslrmi: </emphasis> A
+ <classname>SocketFactory</classname>
+ is either created or configured for future creation during
+ <methodname>Client.create()</methodname>. No further
+ configuration is possible.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">sslsocket: </emphasis>
+ <classname>SSLSocketClientInvoker</classname> uses the current
+ <classname>SocketFactory</classname> to create a new socket
+ whenever it runs out of available pooled connections. Option
+ 1 may be used to reset the <classname>SocketFactory</classname>
+ for future connections at any time.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+ </section>
+
+ <section>
+ <title>Server side configuration in the JBoss Application Server</title>
+
+ <para>
+ Everything in the previous two sections applies to configuring socket
+ and server socket factories in any environment, including inside the
+ JBoss Application Server (JBossAS), but JBossAS adds some new options.
+ In particular, the <classname>SARDeployer</classname> (see
+ <emphasis>The JBoss 4 Application Server Guide</emphasis>
+ on the labs.jboss.org web site) can read information
+ from a <code>*-service.xml</code> file, as discussed above in the
+ section "General Connector and Invoker configuration," and use it to
+ configure MBeans such as <classname>Connector</classname>s.</para>
+
+ <para>
+ An example of a service xml that covers all the different
+ transport and service configurations can be found within the
+ example-service.xml file under the etc directory of the JBoss Remoting
+ distribution.</para>
+
+ <para>The server socket factory to be used by a server invoker can be
set via configuration within the service xml. To do this, the
serverSocketFactory attribute will need to be set as a sub-element of
the invoker element (this cannot be done if just specifying the invoker
configuration using the InvokerLocator attribute). The attribute value
- must be the JMX ObjectName of an MBean that implements the
+ must be either</para>
+
+ <orderedlist>
+ <listitem>
+ <para>the JMX ObjectName of an MBean that implements the
<code>org.jboss.remoting.security.ServerSocketFactoryMBean</code>
- interface. An example of this configuration would be:</para>
+ interface, or</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ the class name of a <classname>ServerSocketFactory</classname>
+ with a default constructor.
+ </para>
+ </listitem>
+ </orderedlist>
+
+
+ <para>An example of the first case would be:</para>
<programlisting>
<mbean code="org.jboss.remoting.transport.Connector"
@@ -3349,61 +3751,90 @@
<attribute name="numAcceptThreads">1</attribute>
</programlisting>
+ <para>The <code>serverSocketFactory</code> attribute is processed
+ as follows:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Take its String value, create an <classname>ObjectName</classname>
+ from it, and look up an MBean with that name from the <classname>MBeanServer</classname>
+ that the invoker has been registered with (by
+ way of the <classname>Connector</classname>). If an MBean with that
+ name is found, create a proxy to it of type
+ <code>org.jboss.remoting.security.ServerSocketFactoryMBean</code>.
+ (Technically, a user could set the
+ <code>serverSocketFactory</code> property with the locator url, but the
+ preferred method is to use the explicit configuration via the invoker
+ element’s attribute, as discussed above.)</para>
+ </listitem>
+
+ <listitem>
+ <para>If no MBean is found with a matching
+ <classname>ObjectName</classname>,
+ treat the <code>serverSocketFactory</code> attribute as a class name
+ and try to create an instance using the default constructor.</para>
+ </listitem>
+ </orderedlist>
+
<para>The JBossRemoting project provides an implementation of the
ServerSocketFactoryMBean that can be used and should provide most of the
customization features that would be needed. More on this implementation
later.</para>
- <para>The order of selecting which server socket factory is:</para>
+ <para>Note that these two options correspond exactly to options 4 and 5
+ in section <xref linkend="section-ssf-serverside"/> (on the server side),
+ which is how these two new options are implemented.</para>
+
+ <para><emphasis role="bold">Timing considerations.</emphasis> If a
+ <classname>Connector</classname> is accessed by way of the
+ <classname>MBeanServer</classname>, then most of the options for
+ configuring the server socket factory discussed in
+ <xref linkend="section-ssf-serverside"/> are irrelevant since
+ <classname>ConnectorMBean</classname> does not expose methods for using
+ them. However, when a <classname>Connector</classname> that is registered
+ with an <classname>MBeanServer</classname> creates a
+ server invoker during a call to
+ <methodname>Connector.create()</methodname>, it also registers the
+ server invoker with the same <classname>MBeanServer</classname>, which
+ means that the server invoker is accessible by way of its
+ <classname>ObjectName</classname>, which has the form</para>
- <para>1.If a <code>javax.net.ServerSocketFactory</code> has been
- specified via the <code>setServerSocketFactory()</code> method, use
- this.</para>
-
- <para>2.If the <code>serverSocketFactory</code> property has been set,
- then take the String value, create an ObjectName from it, look up that
- MBean from the MBeanServer that the invoker has been registered with (by
- way of the Connector) and create a proxy to that MBean of type
- <code>org.jboss.remoting.security.ServerSocketFactoryMBean</code>. Then
- use this proxy. Technically, a user could set the
- <code>serverSocketFactory</code> property with the locator url, but the
- preferred method is to use the explicit configuration via the invoker
- element’s attribute, as discussed above.</para>
+ <programlisting>
+ jboss.remoting:service=invoker,transport=socket,host=www.jboss.com,port=8765
+ </programlisting>
- <para>3.If the server socket factory has not been set explicitly via the
- <code>serverSocketFactory</code> property, then use the
- <code>javax.net.ssl.SSLServerSocketFactory</code> ’s
- <code>getDefault()</code> method.</para>
-
- <para>Note: If want to set the server socket factory via the invoker’s
- <code>setServerSocketFactory()</code> method, it requires a bit of work,
- so would opt for using a configuration setting when possible. The
- following snippet of code shows how it can be done
- programmatically:</para>
+ <para>for example, followed by additional parameter=value pairs. (See
+ the jmx-console for a running instance of JBossAS at
+ http://localhost:8080/jmx-console/ to see examples of server invoker
+ <classname>ObjectName</classname>s.) Now, if another
+ MBean is configured in a <code>*-service.xml</code> file to be
+ dependent on the server invoker MBean, e.g.</para>
<programlisting>
- Connector connector = new Connector();
- InvokerLocator locator = new InvokerLocator(“sslsocket://myhost:8084â€);
- connector.setInvokerLocator(locator.getLocatorURI());
- connector.create();
- // create your server socket factory
- ServerSocketFactory svrSocketFactory = createServerSocketFactory();
- // notice that the invoker has to be explicitly cast to the
- // SSLSocketServerInvoker type
- SSLSocketServerInvoker socketSvrInvoker = (SSLSocketServerInvoker) connector.getServerInvoker();
- socketSvrInvoker.setServerSocketFactory(svrSocketFactory);
-
- connector.addInvocationHandler(getSubsystem(), getServerInvocationHandler());
- connector.start();
+ <mbean code="org.jboss.Blah" name="jboss.remoting:whatever,name=blah">
+ <depends optional-attribute-name="serverInvoker">
+ jboss.remoting:service=invoker,transport=socket,host=www.jboss.com,port=8765
+ </depends>
+ </mbean>
</programlisting>
- <para>The ordering is also important in that the call to the Connector’s
- create() method will create the invoker so that it is available via the
- getServerInvoker() method. However, the server socket factory MUST be
- set before the Connector’s start() method is called, because this will
- cause the invoker’s start() method to be called, which will create the
- server socket to listen on (and is too late to swap out the server
- socket factory being used).</para>
+ <para>then <methodname>org.jboss.Blah.create()</methodname> will have
+ access to the designated server invoker after the invoker has been
+ created but before it has been started, which means that
+ <methodname>ServerInvoker.setServerSocketFactory()</methodname> will be
+ effective. (See the <emphasis>The JBoss 4 Application Server
+ Guide</emphasis>, Chapter 2, for more information about the life cycle
+ of JBoss MBeans.)</para>
+ </section>
+
+ <section>
+ <title>SSL transports</title>
+
+ <para>There are now four transports that support SSL: https,
+ sslmultiplex, sslrmi, and sslsocket. All of preceding discussion
+ applies to each of these, and, moreover, they are all extensions of their
+ non-ssl counterparts, so only some ssl specific information will be
+ added here.</para>
<bridgehead>https</bridgehead>
@@ -3452,9 +3883,7 @@
<!-- This depends is included because need to make sure this mbean is running before configure invoker. -->
<depends>jboss.remoting:service=ServerSocketFactory,type=SSL</depends>
</mbean>
-
-
-</programlisting>
+ </programlisting>
<para>Notice that the 'serverSocketFactory' attribute has a value of
'jboss.remoting:service=ServerSocketFactory,type=SSL', which is not
@@ -3478,29 +3907,398 @@
based http processor and not with the APR based transport. See section
4.7 for more information on using the APR based transport.</para>
- <bridgehead>SSLSocketBuilder</bridgehead>
+ <bridgehead>sslmultiplex</bridgehead>
- <para>Although any server socket factory can be set on the SSL socket
- server invoker and the https server invoker, there is a customizable
- server socket factory service provided within JBossRemoting that
- supports SSL. This is the
- <code>org.jboss.remoting.security.SSLServerSocketFactoryService</code>
- class. The <code>SSLServerSocketFactoryService</code> class extends the
- <code>javax.net.ServerSocketFactory</code> class and also implements the
- <code>SSLServerSocketFactoryServiceMBean</code> interface (so that it
- can be set using the <code>socketServerFactory</code> attribute
- described previously). Other than providing the proper interfaces, this
- class is a simple wrapper around the
- <code>org.jboss.remoting.security.SSLSocketBuilder</code> class.</para>
+ <para>The sslmultiplex server invoker inherits from the socket server
+ invoker a method with signature</para>
+
+ <programlisting>
+ public void setNewServerSocketFactory(ServerSocketFactory serverSocketFactory)
+ </programlisting>
+
+ <para>which supports dynamic replacement of server socket factories. The
+ principal motivation for this facility is to be able to swap in a
+ new <classname>SSLServerSocketFactory</classname> configured with an
+ updated keystore.</para>
+
+ <bridgehead>sslsocket</bridgehead>
+ <para>In addition to the various configuration options discussed above,
+ the sslsocket transport exposes the</para>
+
+ <programlisting>public void setServerSocketFactory(ServerSocketFactory serverSocketFactory)</programlisting>
+
+ <para>method as a JMX operation.</para>
+
+ <para>Also, the sslsocket server invoker inherits from the socket server
+ invoker a method with signature</para>
+
+ <programlisting>
+ public void setNewServerSocketFactory(ServerSocketFactory serverSocketFactory)
+ </programlisting>
+
+ <para>which supports dynamic replacement of server socket factories. The
+ principal motivation for this facility is to be able to swap in a
+ new <classname>SSLServerSocketFactory</classname> configured with an
+ updated keystore.</para>
+
+ </section>
+
+ <section>
+ <title>SSLSocketBuilder</title>
+
+ <para>Throughout this section reference has been made to SSL
+ socket factory and server socket factory configuration parameters.
+ This subsection will introduce these parameters in the context of
+ configuring
+ <classname>org.jboss.remoting.security.SSLSocketBuilder</classname>,
+ Remoting's flexible, highly customizable master factory for creating
+ socket and server socket factories. It can be used programmatically on
+ both the client and server side, and it is also a service MBean, so it
+ can be configured and started from within a service xml in a JBossAS
+ environment.</para>
+
+ <para>Once a <classname>SSLSocketBuilder</classname> has been
+ constructed and configured, a call to its method
+ <methodname>createSSLServerSocketFactory()</methodname> will return a custom
+ instance of a <classname>SSLServerSocketFactory</classname>, and a
+ call to <methodname>createSSLSocketFactory()</methodname> will
+ return a custom instance of <classname>SSLSocketFactory</classname>.</para>
+
+ <para>
+ There are two modes in which the <classname>SSLSocketBuilder</classname>
+ can be run. The first is the default mode where all that is needed is to
+ declare the <classname>SSLSocketBuilder</classname> and set the system properties
+ <code>javax.net.ssl.keyStore</code> and
+ <code>javax.net.ssl.keyStorePassword</code>. This will use the JVM
+ vendor’s default configuration for creating the SSL server socket
+ factory.</para>
+
+ <para>In order to customize any of the SSL properties, the
+ first requirement is that the default mode is turned off. This is
+ <emphasis role="bold">IMPORTANT</emphasis> because otherwise, if the
+ default mode is not explicitly turned off, all other settings will be
+ IGNORED, even if they are explicitly set. To turn off the default mode
+ via service xml configuration, set the
+ <code>UseSSLServerSocketFactory</code> attribute to false. This can also
+ be done programmatically by calling the
+ <code>setUseSSLServerSocketFactory()</code> and passing false as the
+ parameter value.</para>
+
+ <para>There are two ways to configure a
+ <classname>SSLSocketBuilder</classname></para>
+
+ <orderedlist>
+ <listitem>
+ <para>set its bean attributes, either programmatically or by xml
+ configuration, or</para>
+ </listitem>
+
+ <listitem>
+ <para>pass to a <classname>SSLSocketBuilder</classname> constructor
+ a configuration map with keys defined in the
+ <classname>SSLSocketBuilder</classname> class.</para>
+ </listitem>
+ </orderedlist>
+
+
+ <para>The configuration properties for
+ <classname>SSLSocketBuilder</classname>are as follows:</para>
+
+ <table frame="all" id="SSLSocketBuilderTable" xreflabel="Table 1">
+ <title><classname>SSLSocketBuilder</classname> configuration
+ parameters.</title>
+
+ <tgroup cols="5">
+
+ <colspec colname="c1" colnum="1"/>
+ <colspec colname="c2" colnum="2"/>
+ <colspec colname="c3" colnum="3" align="center"/>
+ <colspec colname="c4" colnum="4" align="center"/>
+ <colspec colname="c5" colnum="5"/>
+
+ <thead>
+ <row>
+ <entry>
+ <para>attribute</para>
+ </entry>
+ <entry>
+ <para>key name</para>
+ </entry>
+ <entry>
+ <para>type</para>
+ </entry>
+ <entry>
+ <para>default</para>
+ </entry>
+ <entry>
+ <para>description</para>
+ </entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><para>ClientAuthMode</para></entry>
+ <entry><para>REMOTING_CLIENT_AUTH_MODE</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para>need</para></entry>
+ <entry>
+ <para>Determines if sockets need or want
+ client authentication. This configuration option is only
+ useful for sockets in the server mode. Value may be
+ "none", "want", or "need".</para></entry>
+ </row>
+
+ <row>
+ <entry><para>KeyAlias</para></entry>
+ <entry><para>REMOTING_KEY_ALIAS</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para></para></entry>
+ <entry>
+ <para>The preferred identity in key store to be used by
+ key managers</para></entry>
+ </row>
+
+ <row>
+ <entry><para>KeyPassword</para></entry>
+ <entry><para>REMOTING_KEY_PASSWORD</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para></para></entry>
+ <entry>
+ <para>Sets the password to use for the keys within the key store.
+ This only needs to be set if
+ <methodname>setUseSSLServerSocketFactory()</methodname> is set to false
+ (otherwise will be ignored). If this value is not set, but
+ the key store password is, it will use that value for the
+ key password.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>KeyStoreAlgorithm</para></entry>
+ <entry><para>REMOTING_KEY_STORE_ALGORITHM</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para>SunX509</para></entry>
+ <entry>
+ <para>The algorithm for the key manager factory.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>KeyStorePassword</para></entry>
+ <entry><para>REMOTING_KEY_STORE_PASSWORD</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para></para></entry>
+ <entry>
+ <para>The password
+ to use for the key store. This only needs to be set if
+ <methodname>setUseSSLServerSocketFactory()</methodname>
+ is set to false (otherwise will be
+ ignored). The value passed will also be used for the
+ key password if the latter attribute is not explicitly
+ set.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>KeyStoreType</para></entry>
+ <entry><para>REMOTING_KEY_STORE_TYPE</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para>JKS</para></entry>
+ <entry>
+ <para>The type to be
+ used for the key store. 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.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>KeyStoreURL</para></entry>
+ <entry><para>REMOTING_KEY_STORE_FILE_PATH</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para></para></entry>
+ <entry>
+ <para>Property used to define where
+ <classname>SSLSocketBuilder</classname> will
+ look for the keystore file. This can be relative to the thread's
+ classloader or can be an absolute path on the file system or
+ can be a URL.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>Provider</para></entry>
+ <entry><para>none</para></entry>
+ <entry><para>java.security.Provider</para></entry>
+ <entry><para></para></entry>
+ <entry>
+ <para>Java Security API implementation to use.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>ProviderName</para></entry>
+ <entry><para>REMOTING_SSL_PROVIDER_NAME</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para></para></entry>
+ <entry>
+ <para>Name of Java Security API implementation to use.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry><para>SecureRandom</para></entry>
+ <entry><para>none</para></entry>
+ <entry><para>java.security.SecureRandom</para></entry>
+ <entry><para><code>new SecureRandom()</code></para></entry>
+ <entry>
+ <para>Random number generator to use.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>SecureSocketProtocol</para></entry>
+ <entry><para>REMOTING_SSL_PROTOCOL</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para>TLS</para></entry>
+ <entry>
+ <para> The protocol for the <classname>SSLContext</classname>.
+ Some acceptable values are TLS, SSL, and SSLv3</para></entry>
+ </row>
+
+ <row>
+ <entry><para>ServerAuthMode</para></entry>
+ <entry><para>REMOTING_SERVER_AUTH_MODE</para></entry>
+ <entry><para>boolean/String</para></entry>
+ <entry><para>true</para></entry>
+ <entry>
+ <para>Determines if a client should attempt to
+ authenticate a server certificate as one it trusts.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>ServerSocketUseClientMode</para></entry>
+ <entry><para>REMOTING_SERVER_SOCKET_USE_CLIENT_MODE</para></entry>
+ <entry><para>boolean/String</para></entry>
+ <entry><para>false</para></entry>
+ <entry>
+ <para>Determines if the server sockets will be in
+ client or server mode.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>SocketUseClientMode</para></entry>
+ <entry><para>REMOTING_SOCKET_USE_CLIENT_MODE</para></entry>
+ <entry><para>boolean/String</para></entry>
+ <entry><para>true</para></entry>
+ <entry>
+ <para>Determines if the sockets will be in
+ client or server mode.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>TrustStoreAlgorithm</para></entry>
+ <entry><para>REMOTING_TRUST_STORE_ALGORITHM</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para>value of <code>KeyStoreAlgorithm</code>, or
+ SunX509 if <code>KeyStoreAlgorithm</code>
+ is not set</para></entry>
+ <entry>
+ <para>trust store key management algorithm</para></entry>
+ </row>
+
+ <row>
+ <entry><para>TrustStorePassword</para></entry>
+ <entry><para>REMOTING_TRUST_STORE_PASSWORD</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para></para></entry>
+ <entry>
+ <para>trust store password</para></entry>
+ </row>
+
+ <row>
+ <entry><para>TrustStoreType</para></entry>
+ <entry><para>REMOTING_TRUST_STORE_TYPE</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para>value of <code>KeyStoreType</code>, or
+ JKS if <code>KeyStoreType</code>
+ is not set</para></entry>
+ <entry>
+ <para>type of trust store</para></entry>
+ </row>
+
+ <row>
+ <entry><para>TrustStoreURL</para></entry>
+ <entry><para>REMOTING_TRUST_STORE_FILE_PATH</para></entry>
+ <entry><para>String</para></entry>
+ <entry><para></para></entry>
+ <entry>
+ <para>location of trust store</para></entry>
+ </row>
+
+ <row>
+ <entry><para>UseSSLServerSocketFactory</para></entry>
+ <entry><para>none</para></entry>
+ <entry><para>boolean</para></entry>
+ <entry><para>true</para></entry>
+ <entry>
+ <para>Determines if default
+ <classname>SSLServerSocketFactory</classname> should be
+ created.</para></entry>
+ </row>
+
+ <row>
+ <entry><para>UseSSLSocketFactory</para></entry>
+ <entry><para>none</para></entry>
+ <entry><para>boolean</para></entry>
+ <entry><para>true</para></entry>
+ <entry>
+ <para>Determines if default
+ <classname>SSLSocketFactory</classname> should be
+ created.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><emphasis role="bold">Note.</emphasis>
+ If any of the attributes <code>KeyStoreURL</code>,
+ <code>KeyStorePassword</code>, <code>KeyStoreType</code>,
+ <code>TrustStoreURL</code>, <code>TrustStorePassword</code>, or
+ <code>TrustStoreType</code> are left unconfigured,
+ <classname>SSLSocketBuilder</classname> will also examine the
+ corresponding standard SSL system properties "javax.net.ssl.keyStore",
+ "javax.net.ssl.keyStorePassword", "javax.net.ssl.keyStoreType",
+ "javax.net.ssl.trustStore", "javax.net.ssl.trustStorePassword",
+ "javax.net.ssl.trustStoreType". In the cases of
+ <code>KeyStoreType</code> and <code>TrustStoreType</code>,
+ <classname>SSLSocketBuilder</classname> will then
+ go on to use default values after checking the system
+ properties.</para>
+
+ <para>The following is an example of configuring a
+ <classname>SSLSocketBuilder</classname> and using it to create a custom
+ <classname>SSLSocketFactory</classname>:</para>
+
+ <programlisting>
+ protected SSLSocketFactory getSocketFactory() throws Exception
+ {
+ HashMap config = new HashMap();
+ config.put(SSLSocketBuilder.REMOTING_KEY_STORE_TYPE, "JKS");
+ String keyStoreFilePath = getKeystoreFilePath();
+ config.put(SSLSocketBuilder.REMOTING_KEY_STORE_FILE_PATH, keyStoreFilePath);
+ config.put(SSLSocketBuilder.REMOTING_KEY_STORE_PASSWORD, "unit-tests-server");
+ config.put(SSLSocketBuilder.REMOTING_SSL_PROTOCOL, "SSL");
+ SSLSocketBuilder builder = new SSLSocketBuilder(config);
+ builder.setUseSSLSocketFactory(false);
+ return builder.createSSLSocketFactory();
+ }
+ </programlisting>
- <para>The SSLSocketBuilder is where the ssl server socket (and ssl
- sockets for clients) originate and is where all the properties for the
- ssl server socket are configured (more on this further below). The
- SSLSocketBuilder is also a service MBean, so can be configured and
- started from within a service xml.</para>
+ <para>More examples of configuring <classname>SSLSocketBuilder</classname> can
+ be found in the class <classname>FactoryConfigSSLSample</classname> in the
+ package <code>org.jboss.remoting.samples.config.factories</code>.</para>
- <para>This is an example of both the configurations as might be found
- within a service xml:</para>
+ <para>The following is an example of configuring
+ <classname>SSLSocketBuilder</classname> in a *-service.xml file:</para>
<programlisting>
<!-- This service is used to build the SSL Server socket factory -->
@@ -3538,9 +4336,30 @@
<!-- These are not case sensitive. -->
<attribute name="KeyStoreType">JKS</attribute>
</mbean>
+ </programlisting>
+ </section>
+
+ <section>
+ <title>SSLServerSocketFactoryService</title>
+
+ <para>Although any server socket factory can be set for the various
+ transports, there is a customizable server socket factory service
+ provided within JBossRemoting that supports SSL. This is the
+ <code>org.jboss.remoting.security.SSLServerSocketFactoryService</code>
+ class. The <code>SSLServerSocketFactoryService</code> class extends the
+ <code>javax.net.ServerSocketFactory</code> class and also implements the
+ <code>SSLServerSocketFactoryServiceMBean</code> interface (so that it
+ can be set using the <code>socketServerFactory</code> attribute
+ described previously). Other than providing the proper interfaces, this
+ class is a simple wrapper around the
+ <code>org.jboss.remoting.security.SSLSocketBuilder</code> class.</para>
- <!-- The server socket factory mbean to be used as attribute to socket invoker -->
- <!-- See serverSocketFactory attribute above for where it is used -->
+ <para>The following is an example of configuring
+ <classname>SSLServerSocketFactoryService</classname> in a *-service.xml
+ file. Note that it depends on the <classname>SSLSocketBuilder</classname>
+ MBean defined in the xml fragment above:</para>
+
+ <programlisting>
<!-- This service provides the exact same API as the ServerSocketFactory, so -->
<!-- can be set as an attribute of that type on any MBean requiring an ServerSocketFactory. -->
<mbean code="org.jboss.remoting.security.SSLServerSocketFactoryService"
@@ -3551,171 +4370,10 @@
</mbean>
</programlisting>
- <para>There are two modes in which the SSLSocketBuilder can be run. The
- first is the default mode where all that is needed is to declare the
- SSLSocketBuilder and set the system properties
- <code>javax.net.ssl.keyStore</code> and
- <code>javax.net.ssl.keyStorePassword</code>. This will use the JVM
- vendor’s default configuration for creating the SSL server socket
- factory.</para>
-
- <para>If want to be able to customize any of the SSL properties, the
- first requirement is that the default mode is turned off. This is
- <emphasis role="bold">IMPORTANT</emphasis> because otherwise, if the
- default mode is not explicitly turned off, all other settings will be
- IGNORED, even if they are explicitly set. To turn off the default mode
- via service xml configuration, set the
- <code>UseSSLServerSocketFactory</code> attribute to false. This can be
- done programmatically by calling the
- <code>setUseSSLServerSocketFactory()</code> and passing false as the
- parameter value.</para>
-
- <para>The configuration properties are as follows:</para>
-
- <para><emphasis role="bold">SecureSocketProtocol</emphasis> - The
- protocol for the SSLContext. Some acceptable values are TLS, SSL, and
- SSLv3. Defaults to TLS (DEFAULT_SECURE_SOCKET_PROTOCOL)</para>
-
- <para><emphasis role="bold">KeyManagementAlgorithm</emphasis> - The
- algorithm for the key manager factory. Defaults to SunX509
- (DEFAULT_KEY_MANAGEMENT_ALGORITHM)</para>
-
- <para><emphasis role="bold">KeyStoreType</emphasis> - The type to be
- used for the key store. Defaults to JKS (DEFAULT_KEY_STORE_TYPE). 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.</para>
-
- <para><emphasis role="bold">KeyStorePassword</emphasis> - The password
- to use for the key store. This only needs to be set if
- setUseSSLServerSocketFactory() is set to false (otherwise will be
- ignored). The value passed will also be used for the key password if it
- is not explicitly set.</para>
-
- <para><emphasis role="bold">KeyPassword</emphasis> - Sets the password
- to use for the keys within the key store. This only needs to be set if
- setUseSSLServerSocketFactory() is set to false (otherwise will be
- ignored). If this value is not set, but the key store password is, it
- will use that value for the key password.</para>
-
- <para>Some other points of note:</para>
-
- <itemizedlist>
- <listitem>
- <para>A SecureRandom is NOT configurable. When calling SSLContext's
- init() method, it is actually null, so will use the default
- implementation.</para>
- </listitem>
-
- <listitem>
- <para>Note that there are currently no ways to specify providers, so
- will use the default provider (which is determined by the JVM
- vendor).</para>
- </listitem>
-
- <listitem>
- <para>If the key password is not set, will try to use the value of
- the key store password.</para>
- </listitem>
- </itemizedlist>
-
- <bridgehead>Configuring SSL sockets for the Client.</bridgehead>
-
- <para>There is a simple method for configuring SSL sockets on the client
- side that applies to all transports. A Map of parameters may be passed
- to Client with the usual SSL configuration parameters, and it will
- create an SSLSocketFactory that will be used to generate all sockets for
- connecting from the client to the server. The keys in the Map may be
- given by constants in the RemotingSSLSocketFactory class:</para>
-
- <para><emphasis role="bold">REMOTING_ALGORITHM</emphasis> - key store
- key management algorithm. Defaults to SunX509.</para>
-
- <para><emphasis role="bold">REMOTING_KEY_ALIAS</emphasis> - preferred
- identity in key store to be used by key managers</para>
-
- <para><emphasis role="bold">REMOTING_KEY_STORE_FILE_PATH</emphasis> -
- location of key store</para>
-
- <para><emphasis role="bold">REMOTING_KEY_STORE_PASSWORD</emphasis> - key
- store password</para>
-
- <para><emphasis role="bold">REMOTING_KEY_STORE_TYPE</emphasis> - type of
- key store. Defaults to JKS.</para>
-
- <para><emphasis role="bold">REMOTING_TRUST_ALGORITHM</emphasis> - trust
- store key management algorithm. Defaults to SunX509.</para>
-
- <para><emphasis role="bold">REMOTING_TRUST_STORE_FILE_PATH</emphasis> -
- location of trust store</para>
-
- <para><emphasis role="bold">REMOTING_TRUST_STORE_PASSWORD</emphasis> -
- trust store password</para>
-
- <para><emphasis role="bold">REMOTING_KEY_STORE_TYPE</emphasis> - type of
- trust store. Defaults to JKS.</para>
-
- <para>If any of REMOTING_KEY_STORE_FILE_PATH,
- REMOTING_KEY_STORE_PASSWORD, REMOTING_KEY_STORE_TYPE,
- REMOTING_TRUST_STORE_FILE_PATH, REMOTING_TRUST_STORE_PASSWORD,
- REMOTING_KEY_STORE_TYPE are omitted from the configuration Map,
- RemotingSSLSocketFactory will examine the corresponding standard SSL
- system properties "javax.net.ssl.keyStore",
- "javax.net.ssl.keyStorePassword", "javax.net.ssl.keyStoreType",
- "javax.net.ssl.trustStore", "javax.net.ssl.trustStorePassword",
- "javax.net.ssl.trustStoreType" instead.</para>
-
- <para>Here is a simple example, drawn from
- org.jboss.test.remoting.transport.socket.ssl.custom.InvokerClientTest.java:</para>
-
- <programlisting>
- Map config = new HashMap();
- config.put(RemotingSSLSocketFactory.REMOTING_TRUST_STORE_TYPE, "JKS");
- String trustStoreFilePath = this.getClass().getResource("../.truststore").getFile();
- config.put(RemotingSSLSocketFactory.REMOTING_TRUST_STORE_FILE_PATH, trustStoreFilePath);
- config.put(RemotingSSLSocketFactory.REMOTING_TRUST_STORE_PASSWORD, "unit-tests-client");
-
- InvokerLocator locator = new InvokerLocator(getTransport() + "://localhost:" + port);
- client = new Client(locator, config);
- client.connect();
- </programlisting>
-
- <para>As always in client-server systems, client and server roles are
- relative. In the case of push callbacks, the server acts as a client
- when it establishes a connection over which to transmit the callbacks,
- and the client acts as a server when it accepts the connection.
- Accordingly, there needs to be a way to configure the SSLSocket used by
- the server-side Connector to send callbacks. It works exactly like the
- configuration mechanism on the client side, but the Map is passed to the
- Connector() constructor instead of the Client() constructor. Here is an
- example drawn from
- org.jboss.test.remoting.transport.socket.ssl.custom.InvokerServerTest.java,
- which configures both the callback SSLSockets and the
- SSLServerSocket:</para>
-
- <programlisting>
-
- Map config = new HashMap();
- config.put(RemotingSSLSocketFactory.REMOTING_TRUST_STORE_TYPE, "JKS");
- String trustStoreFilePath = this.getClass().getResource("../.truststore").getFile();
- config.put(RemotingSSLSocketFactory.REMOTING_TRUST_STORE_FILE_PATH, trustStoreFilePath);
- config.put(RemotingSSLSocketFactory.REMOTING_TRUST_STORE_PASSWORD, "unit-tests-client");
-
- Connector connector = new Connector(config);
- InvokerLocator locator = new InvokerLocator(buildLocatorURI(metatdata));
- connector.setInvokerLocator(locator.getLocatorURI());
- connector.create();
-
- ServerSocketFactory svrSocketFactory = createServerSocketFactory();
- connector.getServerInvoker().setServerSocketFactory(svrSocketFactory);
-
- connector.addInvocationHandler(getSubsystem(), getServerInvocationHandler());
- connector.start();
- </programlisting>
+ </section>
- <bridgehead>General Security How To</bridgehead>
+ <section>
+ <title>General Security How To</title>
<para>Since we are talking about keystores and truststores, this section
will quickly go over how to quickly generate a test keystore and
@@ -3780,8 +4438,10 @@
<para>Now have two files, .keystore for the server and .truststore for
the client.</para>
+ </section>
- <bridgehead>Troubleshooting Tips</bridgehead>
+ <section>
+ <title>Troubleshooting Tips</title>
<para>Common errors when using server socket factory:</para>
@@ -3807,6 +4467,7 @@
configuration for the server socket factory) and the key store password
has not been set.</para>
</section>
+ </section>
<section>
<title>Configuration by properties</title>
@@ -6547,7 +7208,7 @@
</section>
<section>
- <title id="section:multiplex-invokers"
+ <title id="section-multiplex-invokers"
xreflabel="Multiplex invokers">Multiplex invokers</title>
<para>This section illustrates the construction of multiplex invoker
More information about the jboss-cvs-commits
mailing list