Author: coheigea
Date: Wed Feb 26 11:08:29 2014
New Revision: 1572009
URL: http://svn.apache.org/r1572009
Log:
Adding more information to the user guide about using WSS4J
Modified:
webservices/wss4j/site/src/site/xdoc/config.xml
webservices/wss4j/site/src/site/xdoc/migration.xml
webservices/wss4j/site/src/site/xdoc/using.xml
Modified: webservices/wss4j/site/src/site/xdoc/config.xml
URL:
http://svn.apache.org/viewvc/webservices/wss4j/site/src/site/xdoc/config.xml?rev=1572009&r1=1572008&r2=1572009&view=diff
==============================================================================
--- webservices/wss4j/site/src/site/xdoc/config.xml (original)
+++ webservices/wss4j/site/src/site/xdoc/config.xml Wed Feb 26 11:08:29 2014
@@ -347,13 +347,13 @@ summarised here:
<td>The CallbackHandler implementation object used to construct SAML
Assertions.</td>
</tr>
<tr>
-<td>ENC_CALLBACK_CLASS</td>
+<td><b>WSS4J 1.6.X only</b> ENC_CALLBACK_CLASS</td>
<td>embeddedKeyCallbackClass</td>
<td>The CallbackHandler implementation class used to get the key associated
with a key name.</td>
</tr>
<tr>
-<td>ENC_CALLBACK_REF</td>
+<td><b>WSS4J 1.6.X only</b> ENC_CALLBACK_REF</td>
<td>embeddedKeyCallbackRef</td>
<td>The CallbackHandler implementation object used to get the key associated
with a key name.</td>
Modified: webservices/wss4j/site/src/site/xdoc/migration.xml
URL:
http://svn.apache.org/viewvc/webservices/wss4j/site/src/site/xdoc/migration.xml?rev=1572009&r1=1572008&r2=1572009&view=diff
==============================================================================
--- webservices/wss4j/site/src/site/xdoc/migration.xml (original)
+++ webservices/wss4j/site/src/site/xdoc/migration.xml Wed Feb 26 11:08:29 2014
@@ -173,6 +173,19 @@ See the ADD_USERNAMETOKEN_NONCE and ADD_
<td>The length of the secret (derived) key to use for the WSE UT_SIGN
functionality. Removed as it is not standard compliant.</td>
</tr>
+<tr>
+<td>ENC_CALLBACK_CLASS</td>
+<td>embeddedKeyCallbackClass</td>
+<td>The CallbackHandler implementation class used to get the key associated
+with a key name. KeyName is not supported in WSS4J 2.0.0.</td>
+</tr>
+<tr>
+<td>ENC_CALLBACK_REF</td>
+<td>embeddedKeyCallbackRef</td>
+<td>The CallbackHandler implementation object used to get the key associated
+with a key name. KeyName is not supported in WSS4J 2.0.0.</td>
+</tr>
+
</table>
<h3><p>New Configuration tags in WSS4J 2.0.0</p></h3>
Modified: webservices/wss4j/site/src/site/xdoc/using.xml
URL:
http://svn.apache.org/viewvc/webservices/wss4j/site/src/site/xdoc/using.xml?rev=1572009&r1=1572008&r2=1572009&view=diff
==============================================================================
--- webservices/wss4j/site/src/site/xdoc/using.xml (original)
+++ webservices/wss4j/site/src/site/xdoc/using.xml Wed Feb 26 11:08:29 2014
@@ -20,6 +20,127 @@ construct/sign/encrypt/etc. tokens direc
</ul>
<subsection name="Action based approach">
+<p>
+The WSHandler class in WSS4J is designed to configure WSS4J to secure an
+outbound SOAP request, by parsing configuration that is supplied to it via
+a subclass. Typically a web services stack that uses WSS4J for WS-Security
+will subclass WSHandler. An example of a subclass is the
+<a href="http://cxf.apache.org/docs/ws-security.html";>WSS4JOutInterceptor</a>
+in Apache CXF. The configuration tags are defined in the <a
href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-common/src/main/java/org/apache/wss4j/common/ConfigurationConstants.java?view=markup";>ConfigurationConstants</a>
class (WSHandlerConstants in WSS4J 1.6.x). For a more detailed explanation
+of the configuration tags, please refer to the
+<a href="config.html">configuration</a> page. The next few paragraphs will
+describe the most fundamental configuration tags that are used in most
+cases.
+</p>
+
+<h3><p>Common configuration tags</p></h3>
+<p>
+The "Action" based approach to using Apache WSS4J involves explicitly telling
+WSS4J what WS-Security functionality to perform on a request, by configuring
+the stack specific WSHandler implementation with the required properties. On
+the receiving side, the "actions" that are configured are matched against what
+was processed in the security header, and an error is thrown if they do not
+match (in some order). Typical actions include "UsernameToken, "Signature",
+"Encrypt", "Timestamp, "SAMLTokenSigned", etc.
+</p>
+<p>
+After specifying the action to perform on a request, the next task is typically
+to specify the "user". The "user" can be either the username to insert into a
+UsernameToken, or the keystore alias to use for either signature or encryption.
+If you are configuring more than one of these actions, the "signatureUser" and
+"encryptionUser" configuration tags override the more general "user" tag. The
+next task is often to specify a CallbackHandler implementation to use to
+retrieve passwords. On the sending side, this is used to retrieve a password
+to insert into a UsernameToken and to decrypt a private key from a keystore
+for Signature. On the receiving side, it is used to retrieve a password to
+validate a received UsernameToken, and to decrypt a private key from a
+keystore to use for decryption.
+</p>
+<p>
+The next task is to specify a Crypto implementation if you are using Signature
+or Encryption. See the <a href="configuration.html">configuration</a> page for
+more information on the Crypto interface. Typically, it is configured in a
+Crypto properties file, which specifies the Crypto implementation to use, as
+well as the keystore location, default alias/password, etc. For signature, the
+path of this properties file can be referred to by the tag "signaturePropFile"
+and "encryptionPropFile" for outbound request, and
+"signatureVerificationPropFile" and "decryptionPropFile" for inbound requests".
+How signing keys/certificates are referenced from a Signature can be
+controlled via the "signatureKeyIdentifier" configuration tag. This defaults
+to "IssuerSerial", but could be "DirectReference", "Thumbprint", etc. The
+"encryptionKeyIdentifier" tag performs the same function for encryption.
+</p>
+<p>
+Finally, the Elements to sign or encrypt can be specified by the
+"signatureParts" and "encryptionParts" configuration tags. Both default to the
+SOAP Body. The value of signatureParts/encryptionParts is a list of semi-colon
+separated values that identify the elements to sign/encrypt. The value is of
+the format of an encryption mode specifier, and a namespace URI, each inside a
+pair of curly brackets, and then the local name of the Element. For example,
+"{Content}{http://example.org/paymentv2}CreditCard;";. The encryption modifier
+can be either "Content" or "Element" and only applies to encryption.
+</p>
+<p>
+Here are some sample configuration values for various actions, as taken from
+some CXF system tests. The constructor of the
+WSS4JOutInterceptor/WSS4JInIntereptor interceptors in CXF takes a map of
+String/Object pairs which correspond to the key/value pairs given in the tables
+below. See the CXF configuration <a
href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob_plain;f=systests/ws-security/src/test/resources/org/apache/cxf/systest/ws/action/client.xml;hb=HEAD";>file</a>
for more information.
+</p>
+
+<h3><p>Sample Outbound UsernameToken configuration</p></h3>
+
+<table name="UsernameToken configuration">
+<tr>
+<th>Key</th>
+<th>Value</th>
+</tr>
+<tr>
+<td>action</td>
+<td>UsernameToken</td>
+</tr>
+<tr>
+<td>user</td>
+<td>Alice</td>
+</tr>
+<tr>
+<td>passwordCallbackClass</td>
+<td><a
href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob_plain;f=systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/UTPasswordCallback.java;hb=HEAD";>org.apache.cxf.systest.ws.common.UTPasswordCallback</a></td>
+</tr>
+</table>
+
+<h3><p>Sample Outbound Signature/Timestamp configuration</p></h3>
+
+<table name="Signature configuration">
+<tr>
+<th>Key</th>
+<th>Value</th>
+</tr>
+<tr>
+<td>action</td>
+<td>Signature Timestamp</td>
+</tr>
+<tr>
+<td>signatureUser</td>
+<td>alice</td>
+</tr>
+<tr>
+<td>passwordCallbackClass</td>
+<td><a
href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob_plain;f=systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/KeystorePasswordCallback.java;hb=HEAD";>org.apache.cxf.systest.ws.common.KeystorePasswordCallback</a></td>
+</tr>
+<tr>
+<td>signaturePropFile</td>
+<td><a
href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob_plain;f=systests/ws-security/src/test/resources/alice.properties;hb=HEAD";>alice.properties</a></td>
+</tr>
+<tr>
+<td>signatureKeyIdentifier</td>
+<td>DirectReference</td>
+</tr>
+<tr>
+<td>signatureParts</td>
+<td>{}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{}{http://schemas.xmlsoap.org/soap/envelope/}Body;</td>
+</tr>
+</table>
</subsection>
@@ -55,7 +176,9 @@ the test sources. For example:
</ul>
</subsection>
-<subsection name="Apache CXF">
+<subsection name="SOAP Stacks">
+
+<h3><p>Apache CXF</p></h3>
<p>
<a href="http://cxf.apache.org";>Apache CXF</a> is an open-source web services
stack. CXF uses WSS4J to perform the core WS-Security functionality, and
@@ -84,9 +207,8 @@ configuration</a>
articles</a>
</li>
</ul>
-</subsection>
-<subsection name="Apache Rampart/Axis">
+<h3><p>Apache Rampart/Axis</p></h3>
<p>
<a href="http://axis.apache.org/axis2/java/rampart/";>Apache Rampart</a> is the
security module for the Axis2 web services stack. Rampart uses WSS4J to
