From 012d23e05f342412503fc6f91082b9d245b1a308 Mon Sep 17 00:00:00 2001
From: Arjen Poutsma <apoutsma@vmware.com>
Date: Thu, 28 Feb 2008 16:24:10 +0000
Subject: [PATCH] SWS-282 (Reference docs)

---
 src/docbkx/security.xml | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/src/docbkx/security.xml b/src/docbkx/security.xml
index d40527f9..a7d88afb 100644
--- a/src/docbkx/security.xml
+++ b/src/docbkx/security.xml
@@ -1389,6 +1389,38 @@
 					<literal>DirectReference</literal>, <literal>Thumbprint</literal>,
 					<literal>SKIKeyIdentifier</literal> or <literal>EmbeddedKeyName</literal>.
 				</para>
+				<para>
+					If the <literal>EmbeddedKeyName</literal> type is chosen, you need to specify the
+                    <emphasis>secret key</emphasis> to use for the encryption. The alias of the key is set via the
+                    <property>securementEncryptionUser</property> property just as for the other key identifier types.
+                    However, WSS4J requires a callback handler to fetch the secret key.
+					Thus, <property>securementCallbackHandler</property> must be provided with a 
+					<classname>KeyStoreCallbackHandler</classname> pointing to the appropriate keystore.
+					By default, the <literal>ds:KeyName</literal> element in the resulting WS-Security header takes the
+                    value of the <property>securementEncryptionUser</property> property. To indicate a different name,
+                    set the <property>securementEncryptionEmbeddedKeyName</property> with the desired value.
+					In the next example, the outgoing message will be encrypted with a key aliased
+                    <literal>secretKey</literal> whereas <literal>myKey</literal> will appear in
+                    <literal>ds:KeyName</literal> element:
+				</para>
+				<programlisting><![CDATA[<bean class="org.springframework.ws.soap.security.wss4j.Wss4jSecurityInterceptor">
+    <property name="securementActions" value="Encrypt"/>
+    <property name="securementEncryptionKeyIdentifier" value="EmbeddedKeyName"/> 
+    <property name="securementEncryptionUser" value="secretKey"/>
+    <property name="securementEncryptionEmbeddedKeyName" value="myKey"/>
+    <property name="securementCallbackHandler">
+        <bean class="org.springframework.ws.soap.security.wss4j.callback.KeyStoreCallbackHandler">
+            <property name="symmetricKeyPassword" value="keypass"/>
+            <property name="keyStore">
+                <bean class="org.springframework.ws.soap.security.support.KeyStoreFactoryBean">
+                    <property name="location" value="file:/keystore.jks"/>
+                    <property name="type" value="jceks"/>
+                    <property name="password" value="123456"/>
+                </bean>
+            </property>
+        </bean>
+    </property>
+</bean>]]></programlisting>
 				<para>
 					The <property>securementEncryptionKeyTransportAlgorithm</property> property
 					defines which algorithm to use to encrypt the generated symmetric key. Supported values are
@@ -1435,4 +1467,4 @@
 			</section>
 		</section>
     </section>
-</chapter>
\ No newline at end of file
+</chapter>