Browse files

Adding a security best practices page

git-svn-id: 13f79535-47bb-0310-9956-ffa450edef68
  • Loading branch information...
coheigea committed Nov 26, 2012
1 parent 5ac4819 commit 9986e8cb3225b8835fb1cb8156e75d88a1999097
Showing with 80 additions and 0 deletions.
  1. +79 −0 src/site/xdoc/best_practice.xml
  2. +1 −0 ws-security-common/src/site/site.xml
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<section name="Security Best Practices">
+This page describes a number of steps which should be taken to ensure that security best
+practices are followed and enforced.
+<subsection name="Upgrade from WSS4J 1.5.x to WSS4J 1.6.x">
+The 1.5.x series of releases of WSS4J is deprecated. You should switch to a 1.6.x release
+as a matter of priority, as this branch contains up to date security fixes. For example,
+WSS4J 1.6.x uses the "secure validation" mode of Apache XML Security for Java, which protects
+against a number of <a href="">attacks</a>
+on XML Signature.
+<subsection name="Upgrade to the latest minor release as soon as possible">
+You should always upgrade to the latest minor release in a timely manner, in order to pick up
+security fixes.
+<subsection name="Use WS-SecurityPolicy to enforce security requirements">
+WSS4J can be used with a web services stack such as Apache CXF or Apache Axis in one of two
+ways: either by specifying security actions directly, or via WS-SecurityPolicy.
+WS-SecurityPolicy is a much richer way of specifying security constraints when processing
+messages, and gives you more "automatic" protection against various attacks then when
+configuring via security actions. See for example, this blog
+<a href="">post</a>
+on XML signature wrapping attacks. Therefore, you should always try to use WSS4J with a
+WS-SecurityPolicy requirement.
+<subsection name="Use RSA-OAEP for the Key Transport Algorithm">
+WSS4J supports two key transport algorithms, RSA v1.5 and RSA-OAEP. A number of attacks
+exist on RSA v1.5. Therefore, you should always use RSA-OAEP as the key transport algorithm,
+and enforce this decision. For WS-SecurityPolicy, this means to avoid using any AlgorithmSuite
+that ends with "Rsa15" (e.g. "Basic128Rsa15"). For the direct configuration case, you should
+explicitly configure WSHandlerConstants.ENC_KEY_TRANSPORT ("encryptionKeyTransportAlgorithm")
+to be "". This latter point requires the
+web services stack to set this property on the Request (is it known that Apache CXF does this).
+<subsection name="Avoid using a cbc Symmetric Encryption Algorithm">
+There are some attacks that exploit the "cbc" mode of a Symmetric Encryption Algorithm.
+WSS4J has support for "gcm" mode algorithms as well. This can be specified via
+WSHandlerConstants.ENC_SYM_ALGO ("encryptionSymAlgorithm"), for example to
+<subsection name="Use Subject DN regular expressions with chain trust">
+WSS4J 1.6.7 introduced the ability to specify regular expressions on the Subject DN of a
+certificate used for signature validation. It is important to add this constraint when you
+are supporting "chain trust", which is where you are establishing trust in a certificate
+based on the fact that the Issuer of the certificate is in your trust store. Otherwise, any
+certificate of this issuer will pass trust validation. See
+<a href="">here</a>
+for more information.
+<subsection name="Specify signature algorithm on receiving side">
+When not using WS-SecurityPolicy (see point above about favouring the WS-SecurityPolicy
+approach), you should specify a signature algorithm to use on the receiving side. This
+can be done via WSHandlerConstants.SIG_ALGO ("signatureAlgorithm"). Setting this property
+to (e.g.) "" will ensure that the signature
+algorithm allowed is RSA-SHA1 and not (e.g.) HMAC-SHA1. This latter point requires the
+web services stack to set this property on the Request (is it known that Apache CXF does
+this). See also the previous point about setting the key encryption transport algorithm.
@@ -15,6 +15,7 @@
<item name="Using WSS4J" href="using.html"/>
<item name="WSS4J Configuration" href="config.html"/>
<item name="Special Topics" href="topics.html"/>
+ <item name="Security Best Practices" href="best_practice.html"/>
<item name="WSS4J 1.6 Release Notes" href="wss4j16.html"/>

0 comments on commit 9986e8c

Please sign in to comment.