diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml
index 958d704c..10589a9d 100644
--- a/src/docbkx/index.xml
+++ b/src/docbkx/index.xml
@@ -15,6 +15,10 @@
Rick
Evans
+
+ Tareq
+ Abed Rabbo
+
diff --git a/src/docbkx/resources/xsl/fopdf.xsl b/src/docbkx/resources/xsl/fopdf.xsl
index 34089df7..6ca1a684 100644
--- a/src/docbkx/resources/xsl/fopdf.xsl
+++ b/src/docbkx/resources/xsl/fopdf.xsl
@@ -27,7 +27,9 @@
-
+
+
+
diff --git a/src/docbkx/security.xml b/src/docbkx/security.xml
index aad2e611..d40527f9 100644
--- a/src/docbkx/security.xml
+++ b/src/docbkx/security.xml
@@ -44,7 +44,7 @@
Note that WS-Security (especially encryption and signing) requires substantial amounts of memory, and
will also decrease performance. If performance is important to you, you might want to consider not using
- WS-Security.
+ WS-Security, or simply use HTTP-based security.
@@ -58,11 +58,17 @@
Like any other endpoint interceptor, it is defined in the endpoint mapping (see
-
- ). This means that you can be selective about adding WS-Security support: some endpoint mappings require it,
- while others do not.
+ ). This means that you can be selective about adding WS-Security
+ support: some endpoint mappings require it, while others do not.
-
+
+
+ Note that the XWSS requires both a SUN 1.5 JDK and the SUN SAAJ reference implementation.
+ The WSS4J interceptor does not have these requirements (see
+ ).
+
+
+
The XwsSecurityInterceptor requires a security policy file
to operate. This XML file tells the interceptor what security aspects to require from incoming SOAP
messages, and what aspects to add to outgoing messages. The basic format of the policy file will be
@@ -102,12 +108,11 @@
This interceptor is configured using the securityPolicy.xml file on the classpath. It
uses two callback handlers which are defined further on in the file.
-
Keystores
- For most cryptographic operations, you will use standard java.security.KeyStore
+ For most cryptographic operations, you will use the standard java.security.KeyStore
objects. This includes certificate verification, message signing, signature verification, and encryption, but
excludes username and time-stamp verification. This section aims to give you some background knowledge on
keystores, and the Java tools that you can use to store keys and certificates in a keystore file. This
@@ -842,8 +847,7 @@
keys, the handler uses the trustStore property. For encryption based on
symmetric keys, it will use the symmetricStore.
-
+
@@ -855,7 +859,580 @@
]]>
-
+
-
+
+ <classname>Wss4jSecurityInterceptor</classname>
+
+ The Wss4jSecurityInterceptor is an EndpointInterceptor
+ (see ) that is based on
+ Apache's WSS4J.
+
+
+ WSS4J implements the following standards:
+
+ OASIS Web Serives Security: SOAP Message Security 1.0 Standard 200401, March 2004
+ Username Token profile V1.0
+ X.509 Token Profile V1.0
+
+
+
+ This inteceptor supports messages created by the AxiomSoapMessageFactory and the
+ SaajSoapMessageFactory.
+
+
+ Configuring <classname>Wss4jSecurityInterceptor</classname>
+
+ WSS4J uses no external configuration file; the interceptor is entirely configured by properties.
+ The validation and securement actions executed by this interceptor are specified via
+ validationActions and securementActions properties, respectively.
+ Actions are passed as a space-separated strings. Here is an example configuration:
+
+
+
+ ...
+
+ ...
+]]>
+ Validation actions are:
+
+
+
+
+ Validation action
+ Description
+
+
+
+
+ UsernameToken
+ Validates username token
+
+
+ Timestamp
+ Validates the timestamp
+
+
+ Encrypt
+ Decrypts the message
+
+
+ Signature
+ Validates the signature
+
+
+ NoSecurity
+ No action performed
+
+
+
+
+ Securement actions are:
+
+
+
+
+ Securement action
+ Description
+
+
+
+
+ UsernameToken
+ Adds a username token
+
+
+ UsernameTokenSignature
+ Adds a username token and a signature username token secret key
+
+
+ Timestamp
+ Adds a timestamp
+
+
+ Encrypt
+ Encrypts the response
+
+
+ Signature
+ Signs the response
+
+
+ NoSecurity
+ No action performed
+
+
+
+
+
+ The order of the actions is significant and is enforced by the interceptor. The interceptor
+ will reject an incoming SOAP message if its security actions were performed in a different order than
+ the one specified by validationActions.
+
+
+
+ Handling Digital Certificates
+
+ For cryptographic operations requiring interaction with a keystore or certificate handling
+ (signature, encryption and decryption operations), WSS4J
+ requires an instance of org.apache.ws.security.components.crypto.Crypto.
+
+
+ Crypto instances can be obtained from WSS4J's
+ CryptoFactory or more conveniently
+ with the Spring-WS CryptoFactoryBean.
+
+
+ CryptoFactoryBean
+
+ Spring-WS provides a convenient factory bean, CryptoFactoryBean
+ that constructs and configures Crypto instances via strong-typed properties
+ (prefered) or through a Properties object.
+
+
+ By default, CryptoFactoryBean returns instances of
+ org.apache.ws.security.components.crypto.Merlin.
+ This can be changed by setting the cryptoProvider property
+ (or its equivalent org.apache.ws.security.crypto.provider string property).
+
+
+ Here is a simple example configuration:
+
+
+
+
+
+ ]]>
+
+
+
+ Authentication
+
+ Validating Username Token
+
+ Spring-WS provides a set of callback handlers to integrate with Acegi Security (and Spring Security).
+ Additionally, a simple callback handler SimplePasswordValidationCallbackHandler
+ is provided to configure users and passwords with an in-memory Properties object.
+
+
+ Callback handlers are configured via Wss4jSecurityInterceptor's
+ validationCallbackHandler property.
+
+
+ SimplePasswordValidationCallbackHandler
+
+ SimplePasswordValidationCallbackHandler validates plain text and digest
+ username tokens against an in-memory Properties object. It is configured
+ as follows:
+
+
+
+
+ Ernie
+
+
+]]>
+
+
+ AcegiPlainTextPasswordValidationCallbackHandler
+
+ The AcegiPlainTextPasswordValidationCallbackHandler requires an Acegi
+ AuthenticationManager to operate. It uses this manager to
+ authenticate against a UsernamePasswordAuthenticationToken that it
+ creates. If authentication is successful, the token is stored in the
+ SecurityContextHolder. You can set the
+ authentication manager using the authenticationManager property:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ...
+]]>
+
+
+ AcegiDigestPasswordValidationCallbackHandler
+
+ The AcegiDigestPasswordValidationCallbackHandler requires an Acegi
+ UserDetailService to operate. It uses this service to retrieve the
+ password of the user specified in the token. The digest of the password contained in this
+ details object is then compared with the digest in the message. If they are equal, the user has
+ successfully authenticated, and a UsernamePasswordAuthenticationToken is
+ stored in the SecurityContextHolder. You can set the service using the
+ userDetailsService. Additionally, you can set a
+ userCache property, to cache loaded user details.
+
+
+
+
+
+
+
+ ...
+
+ ]]>
+
+
+
+ Adding Username Token
+
+ Adding a username token to an outgoing message is as simple as adding
+ UsernameToken to the securementActions property of the
+ Wss4jSecurityInterceptor and specifying
+ securementUsername and securementPassword.
+
+
+ The password type can be set via the securementPasswordType property. Possible
+ values are PasswordText for plain text passwords or
+ PasswordDigest for digest passwords, which is the default.
+
+
+ The following example generates a username token with a digest password:
+
+
+
+
+
+]]>
+
+ If plain text password type is chosen, it is possible to instruct the interceptor to add
+ Nonce and/or Created elements using the
+ securementUsernameTokenElements property. The value must be a list containing
+ the desired elements' names separated by spaces (case sensitive).
+
+
+ The next example generates a username token with a plain text password,
+ a Nonce and a Created element:
+
+
+
+
+
+
+
+]]>
+
+
+
+ Security Timestamps
+
+ This section describes the various timestamp options available in the
+ Wss4jSecurityInterceptor.
+
+
+ Validating Timestamps
+
+ To validate timestamps add Timestamp to the
+ validationActions property.
+ It is possible to override timestamp semantics specified by the initiator of the SOAP message
+ by setting timestampStrict to true and
+ specifying a server-side time to live in seconds (defaults to 300) via the
+ timeToLive property
+
+
+ The interceptor will always reject already expired timestamps whatever the value of
+ timeToLive is.
+
+ .
+
+
+ In the following example, the interceptor will limit the timestamp validity window to 10
+ seconds, rejecting any valid timestamp token outside that window:
+
+
+
+
+
+
+ ]]>
+
+
+ Adding Timestamps
+
+ Adding Timestamp to the securementActions property
+ generates a timestamp header in outgoing messages. The
+ timestampPrecisionInMilliseconds property specifies whether the precision
+ of the generated timestamp is in milliseconds. The default value is true.
+
+
+
+
+
+ ]]>
+
+
+
+ Digital Signatures
+
+ This section describes the various signature options available in the
+ Wss4jSecurityInterceptor.
+
+
+ Verifying Signatures
+
+ To instruct the Wss4jSecurityInterceptor,
+ validationActions must contain the Signature action.
+ Additionally, the validationSignatureCrypto property
+ must point to the keystore containing the public certificates of the initiator:
+
+
+
+
+
+
+
+
+
+]]>
+
+
+ Signing Messages
+
+ Signing outgoing messages is enabled by adding Signature action
+ to the securementActions. The alias and the password of the private key to use
+ are specified by the securementUsername and
+ securementPassword properties respectively.
+ securementSignatureCrypto must point to the keystore containing the private key:
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+ Furthermore, the signature algorithm can be defined
+ via the securementSignatureAlgorithm
+ (Currently this parameter is ignored - SHA1RSA is the only supported algorithm).
+
+
+ The key identifier type to use can be customized via the
+ securementSignatureKeyIdentifier property.
+ Only IssuerSerial and DirectReference
+ are valid for signature.
+
+
+ securementSignatureParts property controls which part of the message shall be
+ signed.
+ The value of this property is a list of semi-colon separated element names that identify the
+ elements to sign.
+ The general form of a signature part is {}{namespace}Element
+
+
+ The first empty brackets are used for encryption parts only.
+
+ .
+ The default behavior is to sign the SOAP body.
+
+
+ As an example, here is how to sign the echoResponse element
+ in the Spring Web Services echo sample:
+
+
+ ]]>
+
+ The WS Security specifications define several formats to transfer the signature tokens
+ (certificates) or references to these tokens. Thus, the plain element name
+ Token
+ signs the token and takes care of the different formats.
+ To sign the SOAP body and the signature token the value
+ of securementSignatureParts must contain:
+
+
+
+ {}{http://schemas.xmlsoap.org/soap/envelope/}Body;
+ Token
+
+]]>
+
+ To specify an element without a namespace use the string Null
+ as the namespace name (case sensitive).
+
+
+ If there is no other element in the request with a local name of Body then
+ the SOAP namespace identifier can be empty ({}).
+
+
+
+ Signature Confirmation
+
+ Signature confirmation is enabled by setting enableSignatureConfirmation to
+ true.
+ Note that signature confirmation action spans over the request and the response.
+ This implies that secureResponse and validateRequest
+ must be set to true (which is the default value) even if there are no corresponding security actions.
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+
+ Encryption and Decryption
+
+ This section describes the various encryption and descryption options available in the
+ Wss4jSecurityInterceptor.
+
+
+ Decryption
+
+ Decryption of incoming SOAP messages requires Encrypt action be added
+ to the securementActions property. The rest of the configuration
+ depends on the key information that appears in the message
+
+
+ This is because WSS4J needs only a Crypto for encypted keys, whereas embedded key name
+ validation is delegated to a callback handler.
+
+ .
+
+
+ To decrypt messages with an embedded encypted symmetric key
+ (xenc:EncryptedKey element),
+ validationDecryptionCrypto needs to point to a keystore containing the
+ decryption private key. Additionally,
+ validationCallbackHandler has to be injected
+ with a org.springframework.ws.soap.security.wss4j.callback.KeyStoreCallbackHandler
+ specifying the key's password:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+ To support decryption of messages with an embedded key name
+ (ds:KeyName element),
+ configure a KeyStoreCallbackHandler that
+ points to the keystore with the symmetric secret key. The property
+ symmetricKeyPassword indicates the key's password, the key name being the
+ one specified by ds:KeyName element:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+ Encryption
+
+ Adding Encrypt to the securementActions enables encryption
+ of outgoing messages.
+ The certifacte's alias to use for the encryption is set via the
+ securementEncryptionUser property.
+ The keystore where the certificate reside is accessed using the
+ securementEncryptionCrypto property.
+ As encryption relies on public certificates, no password needs to be passed.
+
+
+
+
+
+
+
+
+
+
+]]>
+
+ Encryption can be customized in several ways:
+ The key identifier type to use is defined by securementEncryptionKeyIdentifier.
+ Possible values are IssuerSerial, X509KeyIdentifier,
+ DirectReference, Thumbprint,
+ SKIKeyIdentifier or EmbeddedKeyName.
+
+
+ The securementEncryptionKeyTransportAlgorithm property
+ defines which algorithm to use to encrypt the generated symmetric key. Supported values are
+ http://www.w3.org/2001/04/xmlenc#rsa-1_5, which is the default, and
+ http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p.
+
+
+ The symmetric encryption algorithm to use can be set via the
+ securementEncryptionSymAlgorithm property.
+ Supported values are http://www.w3.org/2001/04/xmlenc#aes128-cbc (default value),
+ http://www.w3.org/2001/04/xmlenc#tripledes-cbc,
+ http://www.w3.org/2001/04/xmlenc#aes256-cbc,
+ http://www.w3.org/2001/04/xmlenc#aes192-cbc.
+
+
+ Finally, the securementEncryptionParts property defines which parts of the
+ message will be encrypted. The value of this property is a list of semi-colon separated element
+ names that identify the elements to encrypt. An encryption mode specifier and a namespace
+ identification, each inside a pair of curly brackets, may precede each element name.
+ The encryption mode specifier is either {Content} or
+ {Element}
+
+
+ Please refer to the W3C XML Encryption specification about the differences between
+ Element and Content encryption.
+
+ .
+ The following example identifies the echoResponse from the echo sample:
+
+ ]]>
+
+ Be aware that the element name, the namespace identifier, and the encryption modifier are case
+ sensitive.
+ The encryption modifier and the namespace identifier can be omitted. In this case the encryption
+ mode defaults to Content and the namespace is set to the SOAP namespace.
+
+
+ To specify an element without a namespace use the value Null as the namespace
+ name (case sensitive).
+ If no list is specified, the handler encrypts the SOAP Body in Content mode by
+ default.
+
+
+
+
+
\ No newline at end of file
diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml
index dbb447cf..be84108f 100644
--- a/src/docbkx/server.xml
+++ b/src/docbkx/server.xml
@@ -1109,5 +1109,6 @@ public class MyBusinessException extends Exception {
]]>
+