Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Adding a security best practices page

git-svn-id: https://svn.apache.org/repos/asf/webservices/wss4j/trunk@1413566 13f79535-47bb-0310-9956-ffa450edef68
  • Loading branch information...
commit 9986e8cb3225b8835fb1cb8156e75d88a1999097 1 parent 5ac4819
coheigea authored
79  src/site/xdoc/best_practice.xml
... ...
@@ -0,0 +1,79 @@
  1
+<?xml version="1.0" encoding="ISO-8859-1"?>
  2
+<document>
  3
+<body>
  4
+<section name="Security Best Practices">
  5
+<p>
  6
+This page describes a number of steps which should be taken to ensure that security best
  7
+practices are followed and enforced.
  8
+</p>
  9
+<subsection name="Upgrade from WSS4J 1.5.x to WSS4J 1.6.x">
  10
+<p>
  11
+The 1.5.x series of releases of WSS4J is deprecated. You should switch to a 1.6.x release
  12
+as a matter of priority, as this branch contains up to date security fixes. For example,
  13
+WSS4J 1.6.x uses the "secure validation" mode of Apache XML Security for Java, which protects
  14
+against a number of <a href="http://santuario.apache.org/java150releasenotes.html">attacks</a>
  15
+on XML Signature.
  16
+</p>
  17
+</subsection>
  18
+<subsection name="Upgrade to the latest minor release as soon as possible">
  19
+<p>
  20
+You should always upgrade to the latest minor release in a timely manner, in order to pick up 
  21
+security fixes.
  22
+</p>
  23
+</subsection>
  24
+<subsection name="Use WS-SecurityPolicy to enforce security requirements">
  25
+<p>
  26
+WSS4J can be used with a web services stack such as Apache CXF or Apache Axis in one of two
  27
+ways: either by specifying security actions directly, or via WS-SecurityPolicy. 
  28
+WS-SecurityPolicy is a much richer way of specifying security constraints when processing
  29
+messages, and gives you more "automatic" protection against various attacks then when
  30
+configuring via security actions. See for example, this blog 
  31
+<a href="http://coheigea.blogspot.ie/2012/10/xml-signature-wrapping-attacks-on-web.html">post</a>
  32
+on XML signature wrapping attacks. Therefore, you should always try to use WSS4J with a
  33
+WS-SecurityPolicy requirement.
  34
+</p>
  35
+</subsection>
  36
+<subsection name="Use RSA-OAEP for the Key Transport Algorithm">
  37
+<p>
  38
+WSS4J supports two key transport algorithms, RSA v1.5 and RSA-OAEP. A number of attacks
  39
+exist on RSA v1.5. Therefore, you should always use RSA-OAEP as the key transport algorithm,
  40
+and enforce this decision. For WS-SecurityPolicy, this means to avoid using any AlgorithmSuite
  41
+that ends with "Rsa15" (e.g. "Basic128Rsa15"). For the direct configuration case, you should
  42
+explicitly configure WSHandlerConstants.ENC_KEY_TRANSPORT ("encryptionKeyTransportAlgorithm")
  43
+to be "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p". This latter point requires the
  44
+web services stack to set this property on the Request (is it known that Apache CXF does this).
  45
+</p>
  46
+</subsection>
  47
+<subsection name="Avoid using a cbc Symmetric Encryption Algorithm">
  48
+<p>
  49
+There are some attacks that exploit the "cbc" mode of a Symmetric Encryption Algorithm. 
  50
+WSS4J has support for "gcm" mode algorithms as well. This can be specified via
  51
+WSHandlerConstants.ENC_SYM_ALGO ("encryptionSymAlgorithm"), for example to 
  52
+"http://www.w3.org/2009/xmlenc11#aes128-gcm".
  53
+</p>
  54
+</subsection>
  55
+<subsection name="Use Subject DN regular expressions with chain trust">
  56
+<p>
  57
+WSS4J 1.6.7 introduced the ability to specify regular expressions on the Subject DN of a 
  58
+certificate used for signature validation. It is important to add this constraint when you
  59
+are supporting "chain trust", which is where you are establishing trust in a certificate 
  60
+based on the fact that the Issuer of the certificate is in your trust store. Otherwise, any
  61
+certificate of this issuer will pass trust validation. See 
  62
+<a href="http://coheigea.blogspot.ie/2012/08/subject-dn-certificate-constraint.html">here</a>
  63
+for more information. 
  64
+</p>
  65
+</subsection>
  66
+<subsection name="Specify signature algorithm on receiving side">
  67
+<p>
  68
+When not using WS-SecurityPolicy (see point above about favouring the WS-SecurityPolicy
  69
+approach), you should specify a signature algorithm to use on the receiving side. This
  70
+can be done via WSHandlerConstants.SIG_ALGO ("signatureAlgorithm"). Setting this property
  71
+to (e.g.) "http://www.w3.org/2000/09/xmldsig#rsa-sha1" will ensure that the signature
  72
+algorithm allowed is RSA-SHA1 and not (e.g.) HMAC-SHA1. This latter point requires the
  73
+web services stack to set this property on the Request (is it known that Apache CXF does 
  74
+this). See also the previous point about setting the key encryption transport algorithm.
  75
+</p>
  76
+</subsection>
  77
+</section>            
  78
+</body>
  79
+</document>
1  ws-security-common/src/site/site.xml
@@ -15,6 +15,7 @@
15 15
       <item name="Using WSS4J" href="using.html"/>
16 16
       <item name="WSS4J Configuration" href="config.html"/>
17 17
       <item name="Special Topics" href="topics.html"/>
  18
+      <item name="Security Best Practices" href="best_practice.html"/>
18 19
       <item name="WSS4J 1.6 Release Notes" href="wss4j16.html"/>
19 20
     </menu>
20 21
 

0 notes on commit 9986e8c

Please sign in to comment.
Something went wrong with that request. Please try again.