[jboss-svn-commits] JBL Code SVN: r36513 - labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Mon Jan 10 18:59:00 EST 2011
Author: dlesage
Date: 2011-01-10 18:59:00 -0500 (Mon, 10 Jan 2011)
New Revision: 36513
Added:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/sect-Masking_Passwords.xml
Modified:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_the_Registry.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Revision_History.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Security.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Service_Orchestration.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/The_Message_Store.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_Content-Based_Routing.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml
Log:
SOA-2159 Merges from product doc QE process.
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_the_Registry.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_the_Registry.xml 2011-01-10 13:38:34 UTC (rev 36512)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_the_Registry.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -15,8 +15,16 @@
SOA Platform Registry.
</para>
-
+<note>
<para>
+ Release 5.1 of the JBoss SOA Platform includes JBoss Enterprise Data Services (based on Teiid). EDS is exposed as a JDBC driver or webservice, so that ESB services can consume them in that form. Note that the JDBS connection string for a EDS Virtual Database (VDB) differs some what from typical JDBC connection string. The correct format for a JBDC connection string for a VDB takes this form: <literal>jdbc:teiid:vdb_name at mm://localhost:31000</literal>
+ </para>
+
+<para>
+For details, refer to the <emphasis>EDS Developer Guide</emphasis>.
+ </para>
+</note>
+ <para>
The jUDDI registry is highly configurable. The
JBoss Enterprise Service Bus directs all
interaction with the registry through the Registry Interface, the
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml 2011-01-10 13:38:34 UTC (rev 36512)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -51,7 +51,7 @@
</listitem>
</itemizedlist>
-
+<!--
<important>
<para>
There is no native support for
@@ -61,7 +61,7 @@
<application>Smooks</application>.
</para>
</important>
-
+ -->
<para>
When a message is sent to the <systemitem>content-based
router</systemitem>, a certain <systemitem>rule
@@ -228,9 +228,11 @@
These expressions are defined in the
<filename>XPathLanguage.dsl</filename> file. To use, simply
reference it in the rule-set with:
- </para>
-<programlisting language="Java" role="JAVA"><xi:include href="extras/cbr_drools/code1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ </para>
+
+<programlisting language="Java"><xi:include href="extras/cbr_drools/code1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
<para>
Currently, the XPath Language makes sure the message is of the
@@ -312,7 +314,7 @@
<orderedlist>
<listitem><para><command>xpathMatch expr "<expression>" use namespaces "<namepaces>"</command></para></listitem>
<listitem><para><command>xpathEquals expr "<expression>", "<value>" use namespaces "<namspaces>"</command></para></listitem>
- <listitem><para><command>xpathGreaterThan "<expression>", "<value>" use namespaces "<namspaces>"</command></para></listitem>
+ <listitem><para><command>xpathGreaterThan expr "<expression>", "<value>" use namespaces "<namspaces>"</command></para></listitem>
<listitem><para><command>xpathLowerThan expr "<expression>", "<value>" use namespaces "<namespaces>"</command></para></listitem>
</orderedlist>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Revision_History.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Revision_History.xml 2011-01-10 13:38:34 UTC (rev 36512)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Revision_History.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -8,28 +8,66 @@
<title>Revision History</title>
<simpara>
<revhistory>
-
- <revision>
- <revnumber>1</revnumber>
- <date>Fri Jul 16 2010</date>
+
+ <revision>
+ <revnumber>1.3</revnumber>
+ <date>Thu Dec 23 2010</date>
<author>
<firstname>David</firstname>
<surname>Le Sage</surname>
<email>dlesage at redhat.com</email>
- </author>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Updated for SOA 5.1</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+
+ <revision>
+ <revnumber>1.2</revnumber>
+ <date>Wed May 26 2010</date>
<author>
- <firstname>Darrin</firstname>
- <surname>Mison</surname>
- <email>dmison at redhat.com</email>
+ <firstname>David</firstname>
+ <surname>Le Sage</surname>
+ <email>dlesage at redhat.com</email>
</author>
-
<revdescription>
<simplelist>
- <member>Initial conversion from OpenOffice ODT files.</member>
+ <member>Updated for SOA 5.0.2</member>
</simplelist>
</revdescription>
</revision>
-
+
+ <revision>
+ <revnumber>1.1</revnumber>
+ <date>Tue Apr 20 2010</date>
+ <author>
+ <firstname>David</firstname>
+ <surname>Le Sage</surname>
+ <email>dlesage at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Updated for SOA 5.0.1</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>1.0</revnumber>
+ <date>Fri Jan 22 2010</date>
+ <author>
+ <firstname>David</firstname>
+ <surname>Le Sage</surname>
+ <email>dlesage at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Created</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+
</revhistory>
</simpara>
</appendix>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml 2011-01-10 13:38:34 UTC (rev 36512)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -73,9 +73,8 @@
<para>
Create a rule-set by using <application>JBoss Developer
- Studio</application>. Since the message is added as a global, there
- is a needs to add the <filename>jbossesb-rosetta.jar</filename> file
- to the <application>Drools</application> project.
+ Studio</application>. Since the message is added as a global, you must add the <filename>jbossesb-rosetta.jar</filename> file
+ to the <application>JBoss Rules</application> project.
</para>
@@ -118,17 +117,15 @@
other services in the flow, so the BusinessRulesProcessor /
DroolsRuleService will always set the message as a global.
</para>
-</listitem>
-
- <listitem>
+
<para>
- The BusinessRulesProcessor / DroolsRuleService does not
- provide a means to set globals in the jboss-esb.xml and
+ The BusinessRulesProcessor/DroolsRuleService does not
+ provide a means to set globals in the jboss-esb.xml file and
have them set in working memory. This would have made for
additional configuration support in the jboss-esb.xml, and
could be supported in the future. For now, if additional
globals (other than the ESB Message) need to be set, they
- can be done in higher salience rule. E.g.,
+ can be done in higher salience rule. Here is an example:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/declareglobalssalience.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -169,9 +166,9 @@
<para>
A <firstterm>rule service consumer</firstterm> has little to do.
- There is no need for it to create <firstterm>rule-bases</firstterm>
+ There is no need for it to create <firstterm>knowledge-bases</firstterm>
or <firstterm>working memories</firstterm>, to insert facts or to
- execute the rules. It only has to add facts and, on occassions,
+ execute the rules. It only has to add facts and, on occasions,
properties, to the message.
</para>
@@ -679,7 +676,7 @@
<para>
- Note that <application>Droolss</application> treats objects as
+ Note that <application>Drools</application> treats objects as
though they are <firstterm>shallow</firstterm>. This is in order to achieve highly-optimized
performance. Use the optional <property>object-paths</property>
property to evaluate an object residing in a location that is "deeper" down
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Security.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Security.xml 2011-01-10 13:38:34 UTC (rev 36512)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Security.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -34,62 +34,62 @@
</listitem>
<listitem>
<para>
- directly via the <application>Enterprise Service
- Bus</application> via the
+ directly via the Enterprise Service
+ Bus'
<firstterm>ServiceInvoker</firstterm>.
</para>
</listitem>
</orderedlist>
<para>
- When one uses the first option, the gateway is responsible for
+ When one uses the gateway option, it is responsible for
obtaining the security information needed to authenticate the
- caller. It does this by extracting the information from the
- transport that it handles. Once it has obtained this information, it
- creates an authentication request that is encrypted and then
- passed to the <application>Enterprise Service Bus</application>.
+ caller. It does this by extracting this information from the
+ transport. Once it has done so, it
+ creates an authentication request that is encrypted and
+ passed to the Enterprise Service Bus.
</para>
<para>
- If one uses the <classname>ServiceInvoker</classname> instead, the
- gateway is not utilised. Instead, it becomes the client's responsibility
+ If one uses the <classname>ServiceInvoker</classname> instead, it is the client's responsibility
to create the authentication request prior to invoking
the service.
</para>
- <para>
- Both of these options will be discussed in more detail
- the following sections.
- </para>
-
-
- <para>
+ <para>
The default security implementation is based on the <firstterm>Java
- Authentication and Authorization Service</firstterm> (JAAS). (It
- can be reconfigured if one wishes to use an alternative system.)
- The following sections describe how to set the JAAS security
- components.
+ Authentication and Authorization Service</firstterm> (JAAS).
</para>
- </section>
-
-
- <section>
- <title>
- Security Service Configuration
- </title>
-
-
- <para>
- The Security Service is configured along with everything else in
- jbossesb-properties.xml:
+
+ <procedure>
+ <title>Configuring the Security Implementation</title>
+ <step>
+ <para>edit the
+ <filename>jbossesb-properties.xml</filename> file.
</para>
-<programlisting language="XML" role="XML"><xi:include href="extras/security/jbossesb-properties_security.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+<programlisting language="XML"><xi:include href="extras/security/jbossesb-properties_security.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <table>
+
+
+
+ </step>
+
+<step>
+
+ <para>
+ Configure the JAAS log-in modules via the
+ <filename><replaceable>$SOA_ROOT</replaceable>/server/<replaceable>$PROFILE</replaceable>/conf/login-config.xml</filename>
+ file. Use either a pre-configured option or create a custom solution.
+ </para>
+ </step>
+ </procedure>
+
+
+ <table orient="land">
<title><filename>jbossesb-properties.xml</filename> Security Settings</title>
<tgroup cols="3" colsep="1" rowsep="1">
<colspec colwidth="22*"/>
@@ -220,7 +220,7 @@
This is the path to the <firstterm>Keystore</firstterm> which
holds the keys used to encrypt and decrypt that data which is
external to the Enterprise Service Bus. The Keystore is used to
- encrypt the <classname>AuthenticationRequest</classname>.
+ encrypt the <classname>AuthenticationRequest</classname>.
</para>
</entry>
<entry>
@@ -236,7 +236,7 @@
</entry>
<entry>
<para>
- Password to the public keystore.
+ This is the password for the public keystore.
</para>
</entry>
<entry>
@@ -252,7 +252,7 @@
</entry>
<entry>
<para>
- Alias to use.
+ This is the alias to use.
</para>
</entry>
<entry>
@@ -312,10 +312,10 @@
<warning>
<para>
The <application>JBoss Enterprise Service Bus</application>
- ships with an example key-store. Do not be use this in a
+ ships with an example key-store, found in <filename>/samples/quickstarts/security_cert/keystore</filename>. Do not be use this in a
production environment. It is only provided as a sample to help
users achieve a working security configuration
- “out-of-the-box.”
+ "out-of-the-box."
</para>
</warning>
@@ -338,7 +338,7 @@
<para>
To configure a service, find it in the
- <filename>jbossesb.xml</filename> file and add a
+ <filename>jboss-esb.xml</filename> file and add a
<property>security</property> element there. This code sample
demonstrates this:
</para>
@@ -376,7 +376,7 @@
</entry>
<entry>
<para>
- An optional runAs role.
+ This is the <property>runAs</property> role.
</para>
</entry>
<entry>No</entry>
@@ -421,8 +421,8 @@
</entry>
<entry>
<para>
- Optional properties can be defined which will be made
- available to the CallbackHandler implementation.
+ These are optional properties that, once defined, will be made available
+ to the <classname>CallbackHandler</classname> implementation.
</para>
</entry>
<entry>No</entry>
@@ -449,9 +449,9 @@
</entry>
<entry>
<para>
- Optional property that lets the service override the
- global security context timeout (ms) specified in
- jbossesb-properties.xml.
+ This property lets the service over-ride the
+ global security context time-out (milliseconds) that is specified in
+ the <filename>jbossesb-properties.xml</filename> file.
</para>
</entry>
<entry>No</entry>
@@ -603,23 +603,16 @@
</title>
<para>
- Propagation, in this case, refers to propagating security context
- information in a way specific to an external system. For example,
- you might want to have the credentials that were used to call the
- ESB, be used as the credentials when calling an EJB method. This
- can be accomplished by specifying a SecurityContextPropagator that
- will perform the security context propagation specific to the
- destination environment.
+ In this case, the term "<firstterm>propagation</firstterm>" refers
+ to the process of propagating security context information in a way
+ specific to an external system. For example, one might want to use
+ the same credentials to call both the Enterprise Service Bus and an
+ <firstterm>Enterprise Java Beans</firstterm> (<abbrev>EJB</abbrev>)
+ method. One can accomplish this by specifying a
+ <classname>SecurityContextPropagator</classname>, which, as its name
+ suggests, will perform the security-context propagation specific to
+ the destination environment.
</para>
-
- <para>
- A SecurityContextPropagator can be configured globally by
- specifying the
- 'org.jboss.soa.esb.services.security.contextPropagatorImplementationClass'
- in jbossesb-properties.xml, or per-service by specifying the same
- property in jboss-esb.xml. Please see “Configuring Security on a
- Service” and “SecurityService Configuration” for examples of this.
- </para>
<table>
@@ -726,7 +719,7 @@
<para>
This section lists the log-in modules provided with JBoss Enterprise
Service Bus. Please note that all of the log-in modules available
- with JBoss Application Server are also available here. Custom log-in
+ with JBoss Enterprise Application Platform are also available here. Custom log-in
modules should also be easy to add.
</para>
@@ -919,11 +912,7 @@
Password Encryption
</title>
<para>
- <application>JBoss Enterprise Service Bus</application> configuration files sometimes require
- passwords. In the past, these had been stored in clear text in
- the configuration files themselves. This was obviously a security risk. There is now the option to
- specify a path to a file that contains an encrypted password that can be
- read whenever it is required.
+ Configuration files in JBoss Enterprise Service Bus sometimes require passwords. In The JBoss Enterprise SOA Platform there is the option to specify a path to a file that contains an encrypted password that can be read whenever it is required.
</para>
<section>
@@ -1011,10 +1000,12 @@
Configuring Encrypted Password Files
</title>
<para>
- To configure encrypted passwords files, simply replace the existing clear-text password
- with the path to the other file containing the
- encrypted password.
+ To configure encrypted passwords files, use the instructions in the following section.
</para>
+
+<xi:include href="sect-Masking_Passwords.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
</section>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Service_Orchestration.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Service_Orchestration.xml 2011-01-10 13:38:34 UTC (rev 36512)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Service_Orchestration.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -53,7 +53,7 @@
</para>
-->
- <note>
+ <note>
<para>
JBoss and the Enterprise Service Bus team have a special
support agreement with <ulink
@@ -88,8 +88,8 @@
</title>
<para>
- An orchestration diagram is a flow-chart that must be used to plan
- and desploy service orchestration processes. Utilise the jBPM
+ An orchestration diagram is a flow-chart. Use it to plan
+ and deploy service orchestration processes. Utilise the jBPM
Integrated Development Environment to create these diagrams.
</para>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/The_Message_Store.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/The_Message_Store.xml 2011-01-10 13:38:34 UTC (rev 36512)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/The_Message_Store.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -40,7 +40,7 @@
<para>
The <classname>MessageStore</classname> is
also used for holding messages that need to be re-delivered in
- the event of a failure. Additional information on this topic si
+ the event of a failure. Additional information on this topic is
found in the <emphasis>Programmers' Guide</emphasis>.
</para>
</important>
@@ -185,7 +185,7 @@
<para>
The scripts for the "required database" schema are found in the
- <filename>lib/jbossesb.esb/message-store-sql/<db_type>/create_database.sql</filename>
+ <filename>/jboss-as/server/<server profile>/deploy/jbossesb.esb/message-store-sql/<db_type>/create_database.sql</filename>
file in the <application>JBoss Enterprise Service
Bus</application> installation.
</para>
@@ -261,9 +261,9 @@
<firstterm>C3PO</firstterm> to manage the connection pooling
logic whilst the <firstterm>J2eeConnectionManager</firstterm>,
by contrast, employs a data-source. Use this when deploying
- Enterprise Service Bus end points inside a container such as the
- <application>JBoss Application Server</application> or
- <application>Tomcat</application>. To plug ina custom connection manager,
+ Enterprise Service Bus end points inside a container such as a
+ <application>JBoss Application Server</application>. To plug
+ ina custom connection manager,
use this interface:
</para>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_Content-Based_Routing.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_Content-Based_Routing.xml 2011-01-10 13:38:34 UTC (rev 36512)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_Content-Based_Routing.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -25,7 +25,7 @@
to <firstterm>End Point References</firstterm> (which are either
services or clients.) An <abbrev>EPR</abbrev>'s role is to
identify the machine or process or object that will ultimately
- deal with the content of the message. However, what happen will
+ deal with the content of the message. However, what happens
if the specified address is no longer valid? Situations that may
lead to this scenario include those in which the service has
failed or been removed. It is also possible that the service no
@@ -118,11 +118,6 @@
destination(s).
</para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/what_is_cbr/Routing_Image1.png" />
- </imageobject>
- </mediaobject>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml 2011-01-10 13:38:34 UTC (rev 36512)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -140,7 +140,7 @@
may change in the future, when there are better ways to
identify a stateful conversation over the ESB.
</para>
-
+<!--
<note>
<para>
In ESB 4.8 and prior releases, the Drools Rule* API was used.
@@ -156,7 +156,7 @@
KnowledgeAgents.
</para>
</note>
-
+ -->
<para>
Most rule services will be "stateless." In the stateless
model, a message is sent to the <systemitem>rule
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/sect-Masking_Passwords.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/sect-Masking_Passwords.xml (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/sect-Masking_Passwords.xml 2011-01-10 23:59:00 UTC (rev 36513)
@@ -0,0 +1,382 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Services_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<!-- Author: Joshua Wulf -->
+<!-- Author email: jwulf at redhat.com -->
+
+<!-- SME: Marcus Moyses <mmoyses at redhat.com> -->
+
+<!-- Verified by: Marcus Moyses <mmoyses at redhat.com> -->
+<!-- Verified on: 9 Sep 2010 -->
+
+<!-- License: CC-SA-BY -->
+<!-- Contains content from: Anil Saldhana http://community.jboss.org/wiki/maskingpasswordsinjbossasxmlconfiguration -->
+
+<section id="Masking_Passwords">
+ <title>Masking Passwords in XML Configuration</title>
+ <para>
+ Follow the instructions in this chapter to increase the security of your JBoss Enterprise Application Installation
+ by masking passwords that would otherwise be stored on the file system as clear text.
+ </para>
+ <section>
+ <title>Password Masking Overview</title>
+ <para>
+ Passwords are secret authentication tokens that are used to limit access to resources to authorized parties only.
+ For JBoss services to access password protected resources, the password must be made available to the JBoss service.
+ This can be done by means of command line arguments passed to the JBoss Application Server on start up, however
+ this is not practical in a production environment. In production environments, typically, passwords are made
+ available to JBoss services through inclusion in configuration files.
+ </para>
+ <para>
+ All JBoss Enterprise Application Platform configuration files should be stored on secure file systems, and should
+ be readable by the JBoss Application Server process owner only. Additionally, you can mask the password in the
+ configuration file for an added level of security. Follow the instructions in this chapter to replace a clear text
+ password in a Microcontainer bean configuration with a password mask.
+ <!-- Refer to <xref linkend="Encrypting_Data_Source_Passwords"/> for instructions on encrypting Data Source passwords;
+ to <xref linkend="Encrypting_The_Keystore_Password_In_Tomcat"/> for instructions on encrypting the key store
+ password in Tomcat; and to <xref linkend="Using_LdapExtLoginModule_with_JaasSecurityDomain"/> for instructions
+ on encrypting the password for LdapExtLoginModule. -->
+ </para>
+ <note>
+ <para>There is no such thing as impenetrable security. All good security measures merely increase the cost
+ involved in unauthorized access of a system. Masking passwords is no exception - it is not impenetrable, but does
+ defeat casual inspection of configuration files, and increases the amount of effort that will be required to
+ extract the password in clear text.
+ </para>
+ </note>
+ <procedure>
+ <title>Masking a clear text password overview</title>
+ <step>
+ <para>
+ Generate a key pair to use to encrypt passwords.
+ </para>
+ </step>
+ <step>
+ <para>
+ Encrypt the key store password.
+ </para>
+ </step>
+ <step>
+ <para>
+ Create password masks.
+ </para>
+ </step>
+ <step>
+ <para>
+ Replace clear text passwords with their password masks.
+ </para>
+ </step>
+ </procedure>
+ </section>
+ <section>
+ <title> Generate a key store and a masked password </title>
+ <para>
+ Password masking uses a public/private key pair to encrypt passwords. You need to generate a key pair for use in
+ password masking. By default JBoss Enterprise Application Platform 5 expects a key pair with the alias
+ <filename>jboss</filename> in a key store at <filename>jboss-as/bin/password/password.keystore</filename>.
+ </para>
+ <para>The following procedures follow this default configuration. <!-- If you wish to change the key store location or
+ key alias you will need to change the default configuration, and should refer to
+ <xref linkend="sect-changing-password-masking-keystore"/> for instructions. -->
+ </para>
+ <procedure id="proc-generate-keystore">
+ <title>Generate a key pair and key store for password masking</title>
+ <step>
+ <para>
+ At the command line, change directory to the <filename>jboss-as/bin/password</filename> directory.
+ </para>
+ </step>
+ <step>
+ <para>Use <command>keytool</command> to generate the key pair with the following command:</para>
+ <screen><command>keytool -genkey -alias jboss -keyalg RSA -keysize 1024 -keystore password.keystore</command></screen>
+ <formalpara>
+ <title>Important:</title>
+ <para>You must specify the same password for the key store and key pair</para>
+ </formalpara>
+ </step>
+ <step>
+ <formalpara>
+ <title>Optional:</title>
+ <para>Make the resulting password.keystore readable by the JBoss Application Server process owner only.</para>
+ </formalpara>
+ <para>On Unix-based systems this is accomplished by using the <command>chown</command> command to change
+ ownership to the JBoss Application Server process owner, and <command>chmod 600 password.keystore</command> to
+ make the file readable only by the owner.</para>
+ <para>This step is recommended to increase the security of your server.</para>
+ <para>
+ Note: the JBoss Application Server process owner should not have interactive console login access. In that
+ case you will be performing these operations as another user. Creating masked passwords requires read access
+ to the key store, so you may wish to complete configuration of masked passwords before restricting the key
+ store file permissions.
+ </para>
+ </step>
+ </procedure>
+<!-- <para>For more on key stores and the <command>keytool</command> command, refer to <xref linkend="sect-keystore-background"/>.</para> -->
+ </section>
+ <section id="sect-encrypt-key-store-password">
+ <title>Encrypt the key store password</title>
+ <para>
+ With password masking, passwords needed by JBoss services are not stored in clear text in xml configuration files.
+ Instead they are stored in a file that is encrypted using a key pair that you provide.
+ </para>
+ <para>
+ In order to decrypt this file and access the masked passwords at run time, JBoss Application Server needs to be
+ able to use the key pair you created. You provide the key store password to JBoss Application Server by means of
+ the JBoss Password Tool, <command>password_tool</command>. This tool will encrypt and store your key store password.
+ Your key store password will then be available to the JBoss Password Tool for masking passwords, and to the
+ JBoss Application Server for decrypting them at run time.
+ </para>
+ <procedure id="proc-encrypt-key-store-password">
+ <title>Encrypt the key store password</title>
+ <step>
+ <para>At the command line, change to the <filename>jboss-as/bin</filename> directory.</para>
+ </step>
+ <step>
+ <para>Run the password tool, using the command <command>./password_tool.sh</command> for Unix-based systems,
+ or <command>password_tool.bat</command> for Windows-based systems.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The JBoss Password Tool will start, and will report '<command>Keystore is null. Please specify keystore below:</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Select '<command>0: Encrypt Keystore Password</command>' by pressing 0, then Enter.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter keystore password</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter the key store password you specified in <xref linkend="proc-generate-keystore"/>.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter Salt (String should be at least 8 characters)</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter a random string of characters to aid with encryption strength.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter Iterator Count (integer value)</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter a whole number to aid with encryption strength.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with: '<command>Keystore Password encrypted into password/jboss_keystore_pass.dat</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Select '<command>5:Exit</command>' to exit.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool will exit with the message: '<command>Keystore is null. Cannot store.</command>'.
+ This is normal.</para>
+ </formalpara>
+ </step>
+ <step>
+ <formalpara>
+ <title>Optional:</title>
+ <para>Make the resulting file <filename>password/jboss_keystore_pass.dat</filename> readable by the JBoss
+ Application Server process owner only.</para>
+ </formalpara>
+ <para>On Unix-based systems this is accomplished by using the <command>chown</command> command to change
+ ownership to the JBoss Application Server process owner, and <command>chmod 600 jboss-keystore_pass.dat</command>
+ to make the file readable only by the owner.</para>
+ <para>This step is recommended to increase the security of your server. Be aware that if this encrypted key is
+ compromised, the security offered by password masking is significantly reduced. This file should be stored on a
+ secure file system.</para>
+ <para>
+ Note: the JBoss Application Server process owner should not have interactive console login access. In this
+ case you will be performing these operations as another user. Creating masked passwords requires read access
+ to the key store, so you may wish to complete configuration of masked passwords before restricting the key
+ store file permissions.
+ </para>
+ </step>
+ </procedure>
+ <formalpara>
+ <title>Note:</title>
+ <para>
+ You should only perform this key store password encryption procedure once. If you make a mistake entering the
+ keystore password, or you change the key store at a later date, you should delete the
+ <filename>jboss-keystore_pass.dat</filename> file and repeat the procedure. Be aware that if you change the key
+ store any masked passwords that were previously generated will no longer function.
+ </para>
+ </formalpara>
+ </section>
+ <section>
+ <title>Create password masks</title>
+<!-- I opened https://jira.jboss.org/browse/JBPAPP-5046 about this - we need conceptual consistency here.
+You create a password mask using the password_tool.
+The password mask is then placed into the configuration file instead of the clear text password.
+
+At the moment the terminology in the tool is a mix of "passwords" and "domains". And "mask" and the idea of "masking" is
+ not really used as a metaphor except in the chapter title. It's a mixed bag of metaphors that needs to be thinned out.
+
+To introduce the concepts we should stick to the masking metaphor, and introduce domains when we get to bean annotation,
+ where we can just say: "put the password mask in as the value of the Securitydomain". Done. :-)
+--> <para>
+ The JBoss Password Tool maintains an encrypted password file <filename>jboss-as/bin/password/jboss_password_enc.dat</filename>.
+ This file is encrypted using a key pair you provide to the password tool, and it contains the passwords that will
+ be masked in configuration files. Passwords are stored and retrieved from this file by 'domain', an arbitrary
+ unique identifier that you specify to the Password Tool when storing the password, and that you specify as part
+ of the annotation that replaces that clear text password in configuration files. This allows the JBoss Application
+ Server to retrieve the correct password from the file at run time.
+ </para>
+ <note>
+ <para>If you previously made the key store and encrypted key store password file readable only by the JBoss
+ Application Server process owner, then you need to perform the following procedure as the JBoss Application
+ Server process owner, or else make the keystore (<filename>jboss-as/bin/password/password.keystore</filename>)
+ and encrypted key store password file (<filename>jboss-as/bin/password/jboss_keystore_pass.dat</filename>)
+ readable by your user, and the encrypted passwords file <filename>jboss-as/bin/password/jboss_password_enc.dat</filename>
+ (if it already exists) read and writeable, while you perform this operation.</para>
+ </note>
+ <procedure id="proc-create-password-masks">
+ <title>Create password masks</title>
+ <itemizedlist>
+ <title>Prerequisites:</title>
+ <listitem>
+ <para>
+ <xref linkend="proc-generate-keystore"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="proc-encrypt-key-store-password"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <step>
+ <para>At the command line, change to the <filename>jboss-as/bin</filename> directory.</para>
+ </step>
+ <step>
+ <para>Run the password tool, using the command <command>./password_tool.sh</command> for Unix-based systems, or
+ <command>password_tool.bat</command> for Windows-based systems.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The JBoss Password Tool will start, and will report '<command>Keystore is null. Please specify keystore below:</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Select '<command>1:Specify KeyStore</command>' by pressing 1 then Enter.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter Keystore location including the file name</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter the path to the key store you created in <xref linkend="proc-generate-keystore"/>. You can specify
+ an absolute path, or the path relative to <filename>jboss-as/bin</filename>. This should be
+ <filename>password/password.keystore</filename>, unless you have performed an advanced installation and changed
+ the defaults as per <xref linkend="sect-changing-password-masking-keystore"/>.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter Keystore alias</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter the key alias. This should be <classname>jboss</classname>, unless you have performed an advanced
+ installation and changed the defaults as per <xref linkend="sect-changing-password-masking-keystore"/>. </para>
+ <formalpara>
+ <title>Result:</title>
+ <para>If the key store and key alias are accessible, the password tool will respond with some log4j WARNING
+ messages, then the line '<command>Loading domains [</command>', followed by any existing password masks, and
+ the main menu.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>
+ Select '<command>2:Create Password</command>' by pressing 2, then Enter
+ </para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with: '<command>Enter security domain:</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>
+ Enter a name for the password mask. This is an arbitrary unique name that you will use to identify the
+ password mask in configuration files.
+ </para>
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ The password tool responds with: '<command>Enter passwd:</command>'.
+ </para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter the password that you wish to mask.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ The password tool responds with: '<command>Password created for domain:<replaceable>mask name</replaceable></command>'
+ </para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Repeat the password mask creation process to create masks for all passwords you wish to mask.</para>
+ </step>
+ <step>
+ <para>Exit the program by choosing '<command>5:Exit</command>'</para>
+ </step>
+ </procedure>
+ </section>
+ <section>
+ <title>Replace clear text passwords with their password masks</title>
+ <para>
+ Clear text passwords in XML configuration files can be replaced with password masks by changing the property
+ assignment for an annotation. Generate password masks for any clear text password that you wish to mask in
+ Microcontainer bean configuration files by following <xref linkend="proc-create-password-masks"/>. Then replace
+ the configuration occurrence of each clear text password with an annotation referencing its mask.
+ </para>
+ <para>The general form of the annotation is:</para>
+ <example>
+ <title>General form of password mask annotation</title>
+ <programlisting language="XML"><annotation>@org.jboss.security.integration.password.Password(securityDomain=<replaceable>MASK_NAME</replaceable>, methodName=set<replaceable>PROPERTY_NAME</replaceable>)</annotation></programlisting>
+ </example>
+ <para>
+ As a concrete example, the JBoss Messaging password is stored in the server profile in the file
+ <filename>deploy/messaging/messaging-jboss-beans.xml</filename>. If you create a password mask named "messaging",
+ then the before and after snippet of the configuration file looks like this:
+ </para>
+ <example>
+ <title>JBoss Messaging Microcontainer Bean Configuration Before</title>
+ <screen><![CDATA[<property name="suckerPassword">CHANGE ME!!</property>]]></screen>
+ </example>
+ <example>
+ <title>JBoss Messaging Microcontainer Bean Configuration After</title>
+ <screen><![CDATA[<annotation>@org.jboss.security.integration.password.Password(securityDomain=messaging,
+methodName=setSuckerPassword)</annotation>]]></screen>
+ </example>
+ </section>
+ <section id="sect-changing-password-masking-keystore">
+ <title>Changing the password masking defaults</title>
+ <para>
+ JBoss Enterprise Application Platform 5 ships with server profiles configured for password masking. By default
+ the server profiles are configured to use the keystore <filename>jboss-as/bin/password/password.keystore</filename>,
+ and the key alias <filename>jboss</filename>. If you store the key pair used for password masking elsewhere, or
+ under a different alias, you will need to update the server profiles with the new location or key alias.
+ </para>
+ <para>
+ The password masking key store location and key alias is specified in the file
+ <filename>deploy/security/security-jboss-beans.xml</filename> under each of the included JBoss Application Server
+ server profiles.
+ </para>
+ <example>
+ <title>Password Masking defaults in security-jboss-beans.xml</title>
+ <screen><![CDATA[<!-- Password Mask Management Bean-->
+ <bean name="JBossSecurityPasswordMaskManagement"
+ class="org.jboss.security.integration.password.PasswordMaskManagement" >
+ <property name="keyStoreLocation">password/password.keystore</property>
+ <property name="keyStoreAlias">jboss</property>
+ <property name="passwordEncryptedFileName">password/jboss_password_enc.dat</property>
+ <property name="keyStorePasswordEncryptedFileName">password/jboss_keystore_pass.dat</property>
+ </bean>]]>
+ </screen>
+ </example>
+ </section>
+</section>
More information about the jboss-svn-commits
mailing list