org.apache.ws.security.util
Class WSSecurityUtil

java.lang.Object
  extended byorg.apache.ws.security.util.WSSecurityUtil

public class WSSecurityUtil
extends java.lang.Object

WS-Security Utility methods.

Author:
Davanum Srinivas (dims@yahoo.com).

Constructor Summary
WSSecurityUtil()
           
 
Method Summary
static org.w3c.dom.Element appendChildElement(org.w3c.dom.Document doc, org.w3c.dom.Element parent, org.w3c.dom.Element child)
          append a child element

static org.w3c.dom.Text createBase64EncodedTextNode(org.w3c.dom.Document doc, byte[] data)
          create a base64 test node

static int decodeAction(java.lang.String action, java.util.Vector actions)
           
static java.security.cert.X509Certificate ensureSignedTogether(java.util.Iterator results, org.w3c.dom.Element[] elements)
          Search through a WSS4J results vector for a single signature covering all these elements.
static WSSecurityEngineResult fetchActionResult(java.util.Vector wsResultVector, int action)
          Fetch the result of a given action from a given result vector

static java.util.Vector fetchAllActionResults(java.util.Vector wsResultVector, int action, java.util.Vector results)
          Fetch the result of a given action from a given result vector

static org.w3c.dom.Element findBodyElement(org.w3c.dom.Document doc, SOAPConstants sc)
          return the first soap "Body" element.
static org.w3c.dom.Node findElement(org.w3c.dom.Node startNode, java.lang.String name, java.lang.String namespace)
          Returns the first element that matches name and namespace.
static org.w3c.dom.Element findElementById(org.w3c.dom.Node startNode, java.lang.String value, java.lang.String namespace)
          Returns the single element that containes an Id with value uri and namespace.
static org.w3c.dom.Element findWsseSecurityHeaderBlock(org.w3c.dom.Document doc, org.w3c.dom.Element envelope, boolean doCreate)
          find the first ws-security header block

static org.w3c.dom.Element findWsseSecurityHeaderBlock(org.w3c.dom.Document doc, org.w3c.dom.Element envelope, java.lang.String actor, boolean doCreate)
          find a ws-security header block for a given actor

static byte[] generateNonce(int length)
          Generate a nonce of the given length
static javax.crypto.Cipher getCipherInstance(java.lang.String cipherAlgo)
           
static org.w3c.dom.Node getDirectChild(org.w3c.dom.Node fNode, java.lang.String localName, java.lang.String namespace)
          Gets a direct child with specified localname and namespace.
static org.w3c.dom.Element getElementByGenId(org.w3c.dom.Document doc, java.lang.String id)
          Search for an element given its generic id.
static org.w3c.dom.Element getElementByWsuId(org.w3c.dom.Document doc, java.lang.String id)
          Search for an element given its wsu:id.
static javax.xml.namespace.QName getFullQNameFromString(java.lang.String str, org.w3c.dom.Node e)
          Return a QName when passed a string like "foo:bar" by mapping the "foo" prefix to a namespace in the context of the given Node.
static java.lang.String getIDfromReference(java.lang.String ref)
          Deprecated. use getIDFromReference instead
static java.lang.String getIDFromReference(java.lang.String ref)
          Turn a reference (eg "#5") into an ID (eg "5").
static int getKeyLength(java.lang.String algorithm)
          Returns the length of the key in # of bytes
static java.lang.String getNamespace(java.lang.String prefix, org.w3c.dom.Node e)
           
static java.lang.String getPrefixNS(java.lang.String uri, org.w3c.dom.Node e)
           
static javax.xml.namespace.QName getQNameFromString(java.lang.String str, org.w3c.dom.Node e)
          Return a QName when passed a string like "foo:bar" by mapping the "foo" prefix to a namespace in the context of the given Node.
static org.w3c.dom.Element getSecurityHeader(org.w3c.dom.Document doc, java.lang.String actor, SOAPConstants sc)
          Returns the first WS-Security header element for a given actor.
static SOAPConstants getSOAPConstants(org.w3c.dom.Element startElement)
           
static java.lang.String getStringForQName(javax.xml.namespace.QName qname, org.w3c.dom.Element e)
          Return a string for a particular QName, mapping a new prefix if necessary.
static boolean isActorEqual(java.lang.String actor, java.lang.String hActor)
          Compares two actor strings and returns true if these are equal.
static javax.crypto.SecretKey prepareSecretKey(java.lang.String symEncAlgo, byte[] rawKey)
           
static org.w3c.dom.Element prependChildElement(org.w3c.dom.Document doc, org.w3c.dom.Element parent, org.w3c.dom.Element child, boolean addWhitespace)
          prepend a child element

static java.security.SecureRandom resolveSecureRandom()
           
static java.security.SecureRandom resolveSecureRandom(java.lang.String algorithm)
           
static java.lang.String setNamespace(org.w3c.dom.Element element, java.lang.String namespace, java.lang.String prefix)
          set the namespace if it is not set already.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WSSecurityUtil

public WSSecurityUtil()
Method Detail

getSecurityHeader

public static org.w3c.dom.Element getSecurityHeader(org.w3c.dom.Document doc,
                                                    java.lang.String actor,
                                                    SOAPConstants sc)
Returns the first WS-Security header element for a given actor. Only one WS-Security header is allowed for an actor.

Parameters:
doc -
actor -
Returns:
the wsse:Security element or null if not such element found

isActorEqual

public static boolean isActorEqual(java.lang.String actor,
                                   java.lang.String hActor)
Compares two actor strings and returns true if these are equal. Takes care of the null length strings and uses ignore case.

Parameters:
actor -
hActor -
Returns:
TODO

getDirectChild

public static org.w3c.dom.Node getDirectChild(org.w3c.dom.Node fNode,
                                              java.lang.String localName,
                                              java.lang.String namespace)
Gets a direct child with specified localname and namespace.

Parameters:
fNode - the node where to start the search
localName - local name of the child to get
namespace - the namespace of the child to get
Returns:
the node or null if not such node found

findBodyElement

public static org.w3c.dom.Element findBodyElement(org.w3c.dom.Document doc,
                                                  SOAPConstants sc)
return the first soap "Body" element.

Parameters:
doc -
Returns:
the body element or null if document does not contain a SOAP body

findElement

public static org.w3c.dom.Node findElement(org.w3c.dom.Node startNode,
                                           java.lang.String name,
                                           java.lang.String namespace)
Returns the first element that matches name and namespace.

This is a replacement for a XPath lookup //name with the given namespace. It's somewhat faster than XPath, and we do not deal with prefixes, just with the real namespace URI

Parameters:
startNode - Where to start the search
name - Local name of the element
namespace - Namespace URI of the element
Returns:
The found element or null

findElementById

public static org.w3c.dom.Element findElementById(org.w3c.dom.Node startNode,
                                                  java.lang.String value,
                                                  java.lang.String namespace)
Returns the single element that containes an Id with value uri and namespace.

This is a replacement for a XPath Id lookup with the given namespace. It's somewhat faster than XPath, and we do not deal with prefixes, just with the real namespace URI If there are multiple elements, we log a warning and return null as this can be used to get around the signature checking.

Parameters:
startNode - Where to start the search
value - Value of the Id attribute
namespace - Namespace URI of the Id
Returns:
The found element if there was exactly one match, or null otherwise

setNamespace

public static java.lang.String setNamespace(org.w3c.dom.Element element,
                                            java.lang.String namespace,
                                            java.lang.String prefix)
set the namespace if it is not set already.

Parameters:
element -
namespace -
prefix -
Returns:
TODO

getPrefixNS

public static java.lang.String getPrefixNS(java.lang.String uri,
                                           org.w3c.dom.Node e)

getNamespace

public static java.lang.String getNamespace(java.lang.String prefix,
                                            org.w3c.dom.Node e)

getQNameFromString

public static javax.xml.namespace.QName getQNameFromString(java.lang.String str,
                                                           org.w3c.dom.Node e)
Return a QName when passed a string like "foo:bar" by mapping the "foo" prefix to a namespace in the context of the given Node.

Returns:
a QName generated from the given string representation

getFullQNameFromString

public static javax.xml.namespace.QName getFullQNameFromString(java.lang.String str,
                                                               org.w3c.dom.Node e)
Return a QName when passed a string like "foo:bar" by mapping the "foo" prefix to a namespace in the context of the given Node. If default namespace is found it is returned as part of the QName.

Returns:
a QName generated from the given string representation

getStringForQName

public static java.lang.String getStringForQName(javax.xml.namespace.QName qname,
                                                 org.w3c.dom.Element e)
Return a string for a particular QName, mapping a new prefix if necessary.


getElementByWsuId

public static org.w3c.dom.Element getElementByWsuId(org.w3c.dom.Document doc,
                                                    java.lang.String id)
Search for an element given its wsu:id.

Parameters:
doc - the DOM document (SOAP request)
id - the Id of the element
Returns:
the found element or null if no element with the Id exists

getIDFromReference

public static java.lang.String getIDFromReference(java.lang.String ref)
Turn a reference (eg "#5") into an ID (eg "5").

Parameters:
ref -
Returns:
ref trimmed and with the leading "#" removed, or null if not correctly formed

getIDfromReference

public static java.lang.String getIDfromReference(java.lang.String ref)
Deprecated. use getIDFromReference instead

Turn a reference (eg "#5") into an ID (eg "5").

Parameters:
ref -
Returns:
ref trimmed and with the leading "#" removed, or null if not correctly formed

getElementByGenId

public static org.w3c.dom.Element getElementByGenId(org.w3c.dom.Document doc,
                                                    java.lang.String id)
Search for an element given its generic id.

Parameters:
doc - the DOM document (SOAP request)
id - the Id of the element
Returns:
the found element or null if no element with the Id exists

appendChildElement

public static org.w3c.dom.Element appendChildElement(org.w3c.dom.Document doc,
                                                     org.w3c.dom.Element parent,
                                                     org.w3c.dom.Element child)
append a child element

Parameters:
doc - the DOM document (SOAP request)
parent - element of this child element
child - the element to append
Returns:
the child element

prependChildElement

public static org.w3c.dom.Element prependChildElement(org.w3c.dom.Document doc,
                                                      org.w3c.dom.Element parent,
                                                      org.w3c.dom.Element child,
                                                      boolean addWhitespace)
prepend a child element

Parameters:
doc - the DOM document (SOAP request)
parent - element of this child element
child - the element to append
addWhitespace - if true prepend a newline before child
Returns:
the child element

findWsseSecurityHeaderBlock

public static org.w3c.dom.Element findWsseSecurityHeaderBlock(org.w3c.dom.Document doc,
                                                              org.w3c.dom.Element envelope,
                                                              boolean doCreate)
find the first ws-security header block

Parameters:
doc - the DOM document (SOAP request)
envelope - the SOAP envelope
doCreate - if true create a new WSS header block if none exists
Returns:
the WSS header or null if none found and doCreate is false

findWsseSecurityHeaderBlock

public static org.w3c.dom.Element findWsseSecurityHeaderBlock(org.w3c.dom.Document doc,
                                                              org.w3c.dom.Element envelope,
                                                              java.lang.String actor,
                                                              boolean doCreate)
find a ws-security header block for a given actor

Parameters:
doc - the DOM document (SOAP request)
envelope - the SOAP envelope
actor - the actor (role) name of the WSS header
doCreate - if true create a new WSS header block if none exists
Returns:
the WSS header or null if none found and doCreate is false

createBase64EncodedTextNode

public static org.w3c.dom.Text createBase64EncodedTextNode(org.w3c.dom.Document doc,
                                                           byte[] data)
create a base64 test node

Parameters:
doc - the DOM document (SOAP request)
data - to encode
Returns:
a Text node containing the base64 encoded data

prepareSecretKey

public static javax.crypto.SecretKey prepareSecretKey(java.lang.String symEncAlgo,
                                                      byte[] rawKey)

getSOAPConstants

public static SOAPConstants getSOAPConstants(org.w3c.dom.Element startElement)

getCipherInstance

public static javax.crypto.Cipher getCipherInstance(java.lang.String cipherAlgo)
                                             throws WSSecurityException
Throws:
WSSecurityException

fetchActionResult

public static WSSecurityEngineResult fetchActionResult(java.util.Vector wsResultVector,
                                                       int action)
Fetch the result of a given action from a given result vector

Parameters:
wsResultVector - The result vector to fetch an action from
action - The action to fetch
Returns:
The result fetched from the result vector, null if the result could not be found

fetchAllActionResults

public static java.util.Vector fetchAllActionResults(java.util.Vector wsResultVector,
                                                     int action,
                                                     java.util.Vector results)
Fetch the result of a given action from a given result vector

Parameters:
wsResultVector - The result vector to fetch an action from
action - The action to fetch
results - where to store the found results data for the action
Returns:
The result fetched from the result vector, null if the result could not be found

decodeAction

public static int decodeAction(java.lang.String action,
                               java.util.Vector actions)
                        throws WSSecurityException
Throws:
WSSecurityException

getKeyLength

public static int getKeyLength(java.lang.String algorithm)
                        throws WSSecurityException
Returns the length of the key in # of bytes

Parameters:
algorithm -
Returns:
the key length
Throws:
WSSecurityException

generateNonce

public static byte[] generateNonce(int length)
                            throws WSSecurityException
Generate a nonce of the given length

Returns:
a nonce of the given length
Throws:
java.lang.Exception
WSSecurityException

ensureSignedTogether

public static java.security.cert.X509Certificate ensureSignedTogether(java.util.Iterator results,
                                                                      org.w3c.dom.Element[] elements)
                                                               throws WSSecurityException
Search through a WSS4J results vector for a single signature covering all these elements. NOTE: it is important that the given elements are those that are referenced using wsu:Id. When the signed element is referenced using a transformation such as XPath filtering the validation is carried out in signature verification itself.

Parameters:
results - results (e.g., as stored as WSHandlerConstants.RECV_RESULTS on an Axis MessageContext)
elements - the elements to check
Returns:
the identity of the signer
Throws:
WSSecurityException - if no suitable signature could be found or if any element didn't have a wsu:Id attribute

resolveSecureRandom

public static java.security.SecureRandom resolveSecureRandom()
                                                      throws java.security.NoSuchAlgorithmException
Returns:
a SecureRandom instance initialized with the "SHA1PRNG" algorithm identifier
Throws:
java.security.NoSuchAlgorithmException

resolveSecureRandom

public static java.security.SecureRandom resolveSecureRandom(java.lang.String algorithm)
                                                      throws java.security.NoSuchAlgorithmException
Parameters:
algorithm -
Returns:
a SecureRandom instance initialize with the identifier specified in algorithm
Throws:
java.security.NoSuchAlgorithmException


Copyright © 2004-2008 The Apache Software Foundation. All Rights Reserved.