src/site/xdoc/best_practice.xml - ws-wss4j - Git at Google

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <document>
 <body>
 <section name="Security Best Practices">
 <p>
 This page describes a number of steps which should be taken to ensure that security best
 practices are followed and enforced.
 </p>
 <subsection name="Upgrade to WSS4J 2.0.x or 1.6.x">
 <p>
 The 1.5.x series of releases of WSS4J is deprecated. You should switch to
 either the 2.0.x or the latest 1.6.x release as a matter of priority, as these
 branches 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="http://santuario.apache.org/java150releasenotes.html">attacks</a> on XML Signature.
 </p>
 </subsection>
 <subsection name="Upgrade to the latest minor release as soon as possible">
 <p>
 You should always upgrade to the latest minor release in a timely manner, in order to pick up
 security fixes.
 </p>
 </subsection>
 <subsection name="Use WS-SecurityPolicy to enforce security requirements">
 <p>
 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="http://coheigea.blogspot.ie/2012/10/xml-signature-wrapping-attacks-on-web.html">post</a>
 on XML signature wrapping attacks. Therefore, you should always try to use WSS4J with a
 WS-SecurityPolicy requirement.
 </p>
 </subsection>
 <subsection name="Use RSA-OAEP for the Key Transport Algorithm">
 <p>
 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").
 </p>
 <p>
 For the "Action" based approach, there are different ways of enforcing that
 RSA v1.5 cannot be used for key transport depending on the version of WSS4J.
 In WSS4J 2.0.0, it is not allowed by default and no action is required. If you
 wish to allow it, then you must set the
 WSHandlerConstants.ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM property to "true". For
 WSS4J 1.6.x, the RSA v1.5 key transport algorithm is allowed by default. In
 this case, you should explicitly configure WSHandlerConstants.ENC_KEY_TRANSPORT
 ("encryptionKeyTransportAlgorithm") to be
 "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p". This latter point requires
 the web services stack to set this property on the Request (it is known that
 Apache CXF does this).
 </p>
 </subsection>
 <subsection name="Avoid using a cbc Symmetric Encryption Algorithm">
 <p>
 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
 "http://www.w3.org/2009/xmlenc11#aes128-gcm".
 </p>
 </subsection>
 <subsection name="Use Subject DN regular expressions with chain trust">
 <p>
 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="http://coheigea.blogspot.ie/2012/08/subject-dn-certificate-constraint.html">here</a>
 for more information.
 </p>
 </subsection>
 <subsection name="Specify signature algorithm on receiving side">
 <p>
 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.) "http://www.w3.org/2000/09/xmldsig#rsa-sha1" 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 (it is known that Apache CXF does
 this). See also the previous point about setting the key encryption transport algorithm.
 </p>
 </subsection>
 </section>
 </body>
 </document>
	<?xml version="1.0" encoding="ISO-8859-1"?>
	<document>
	<body>
	<section name="Security Best Practices">
	<p>
	This page describes a number of steps which should be taken to ensure that security best
	practices are followed and enforced.
	</p>
	<subsection name="Upgrade to WSS4J 2.0.x or 1.6.x">
	<p>
	The 1.5.x series of releases of WSS4J is deprecated. You should switch to
	either the 2.0.x or the latest 1.6.x release as a matter of priority, as these
	branches 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="http://santuario.apache.org/java150releasenotes.html">attacks</a> on XML Signature.
	</p>
	</subsection>
	<subsection name="Upgrade to the latest minor release as soon as possible">
	<p>
	You should always upgrade to the latest minor release in a timely manner, in order to pick up
	security fixes.
	</p>
	</subsection>
	<subsection name="Use WS-SecurityPolicy to enforce security requirements">
	<p>
	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="http://coheigea.blogspot.ie/2012/10/xml-signature-wrapping-attacks-on-web.html">post</a>
	on XML signature wrapping attacks. Therefore, you should always try to use WSS4J with a
	WS-SecurityPolicy requirement.
	</p>
	</subsection>
	<subsection name="Use RSA-OAEP for the Key Transport Algorithm">
	<p>
	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").
	</p>
	<p>
	For the "Action" based approach, there are different ways of enforcing that
	RSA v1.5 cannot be used for key transport depending on the version of WSS4J.
	In WSS4J 2.0.0, it is not allowed by default and no action is required. If you
	wish to allow it, then you must set the
	WSHandlerConstants.ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM property to "true". For
	WSS4J 1.6.x, the RSA v1.5 key transport algorithm is allowed by default. In
	this case, you should explicitly configure WSHandlerConstants.ENC_KEY_TRANSPORT
	("encryptionKeyTransportAlgorithm") to be
	"http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p". This latter point requires
	the web services stack to set this property on the Request (it is known that
	Apache CXF does this).
	</p>
	</subsection>
	<subsection name="Avoid using a cbc Symmetric Encryption Algorithm">
	<p>
	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
	"http://www.w3.org/2009/xmlenc11#aes128-gcm".
	</p>
	</subsection>
	<subsection name="Use Subject DN regular expressions with chain trust">
	<p>
	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="http://coheigea.blogspot.ie/2012/08/subject-dn-certificate-constraint.html">here</a>
	for more information.
	</p>
	</subsection>
	<subsection name="Specify signature algorithm on receiving side">
	<p>
	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.) "http://www.w3.org/2000/09/xmldsig#rsa-sha1" 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 (it is known that Apache CXF does
	this). See also the previous point about setting the key encryption transport algorithm.
	</p>
	</subsection>
	</section>
	</body>
	</document>