org.apache.ws.security.util
Class WSSecurityUtil

java.lang.Object
  org.apache.ws.security.util.WSSecurityUtil

public class WSSecurityUtil
extends Object

WS-Security Utility methods.

Author:

Davanum Srinivas (dims@yahoo.com).

Constructor Summary

WSSecurityUtil()

Method Summary

static Element	appendChildElement(Document doc, Element parent, Element child) Deprecated. use Node.appendChild(Node) instead
static Text	createBase64EncodedTextNode(Document doc, byte[] data) create a base64 test node
static int	decodeAction(String action, Vector actions)
static int	decodeAction(String action, Vector actions, WSSConfig wssConfig) Decode an action String.
static X509Certificate	ensureSignedTogether(Iterator results, Element[] elements) Search through a WSS4J results vector for a single signature covering all these elements.
static WSSecurityEngineResult	fetchActionResult(Vector wsResultVector, int action) Fetch the result of a given action from a given result vector
static Vector	fetchAllActionResults(Vector wsResultVector, int action, Vector results) Fetch the result of a given action from a given result vector
static Element	findBodyElement(Document doc, SOAPConstants sc) return the first soap "Body" element.
static Node	findElement(Node startNode, String name, String namespace) Returns the first element that matches name and namespace.
static Element	findElementById(Node startNode, String value, String namespace) Returns the single element that contains an Id with value uri and namespace.
static Element	findSAMLAssertionElementById(Node startNode, String value) Returns the single SAMLAssertion element that contains an AssertionID/ID that matches the supplied parameter.
static Element	findWsseSecurityHeaderBlock(Document doc, Element envelope, boolean doCreate) find the first ws-security header block
static Element	findWsseSecurityHeaderBlock(Document doc, Element envelope, 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 Cipher	getCipherInstance(String cipherAlgo)
static Node	getDirectChild(Node fNode, String localName, String namespace) Gets a direct child with specified localname and namespace.
static Element	getDirectChildElement(Node fNode, String localName, String namespace) Gets a direct child with specified localname and namespace.
static Element	getElementByGenId(Document doc, String id) Search for an element given its generic id.
static Element	getElementByWsuId(Document doc, String id) Search for an element given its wsu:id.
static QName	getFullQNameFromString(String str, 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 String	getIDfromReference(String ref) Deprecated. use getIDFromReference instead
static String	getIDFromReference(String ref) Turn a reference (eg "#5") into an ID (eg "5").
static int	getKeyLength(String algorithm) Returns the length of the key in # of bytes
static String	getNamespace(String prefix, Node e)
static String	getPrefixNS(String uri, Node e)
static QName	getQNameFromString(String str, 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 Element	getSecurityHeader(Document doc, String actor, SOAPConstants sc) Returns the first WS-Security header element for a given actor.
static SOAPConstants	getSOAPConstants(Element startElement)
static String	getStringForQName(QName qname, Element e) Return a string for a particular QName, mapping a new prefix if necessary.
static boolean	isActorEqual(String actor, String hActor) Compares two actor strings and returns true if these are equal.
static SecretKey	prepareSecretKey(String symEncAlgo, byte[] rawKey)
static Element	prependChildElement(Document doc, Element parent, Element child, boolean addWhitespace) Deprecated. use prependChildElement(Element, Element) instead
static Element	prependChildElement(Element parent, Element child) prepend a child element
static SecureRandom	resolveSecureRandom()
static SecureRandom	resolveSecureRandom(String algorithm)
static String	setNamespace(Element element, String namespace, String prefix) Set a namespace/prefix on an element 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 Element getSecurityHeader(Document doc,
                                        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(String actor,
                                   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:

true is the actor arguments are equal

getDirectChild

public static Node getDirectChild(Node fNode,
                                  String localName,
                                  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

getDirectChildElement

public static Element getDirectChildElement(Node fNode,
                                            String localName,
                                            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 Element findBodyElement(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 Node findElement(Node startNode,
                               String name,
                               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

findSAMLAssertionElementById

public static Element findSAMLAssertionElementById(Node startNode,
                                                   String value)

Returns the single SAMLAssertion element that contains an AssertionID/ID that matches the supplied parameter.

Parameters:

startNode - Where to start the search

value - Value of the AssertionID/ID attribute

Returns:

The found element if there was exactly one match, or null otherwise

findElementById

public static Element findElementById(Node startNode,
                                      String value,
                                      String namespace)

Returns the single element that contains 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 String setNamespace(Element element,
                                  String namespace,
                                  String prefix)

Set a namespace/prefix on an element if it is not set already. First off, it searches for the element for the prefix associated with the specified namespace. If the prefix isn't null, then this is returned. Otherwise, it creates a new attribute using the namespace/prefix passed as parameters.

Parameters:

element -

namespace -

prefix -

Returns:

the prefix associated with the set namespace

getPrefixNS

public static String getPrefixNS(String uri,
                                 Node e)

getNamespace

public static String getNamespace(String prefix,
                                  Node e)

getQNameFromString

public static QName getQNameFromString(String str,
                                       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 QName getFullQNameFromString(String str,
                                           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 String getStringForQName(QName qname,
                                       Element e)

Return a string for a particular QName, mapping a new prefix if necessary.

getElementByWsuId

public static Element getElementByWsuId(Document doc,
                                        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 String getIDFromReference(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 String getIDfromReference(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 Element getElementByGenId(Document doc,
                                        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 Element appendChildElement(Document doc,
                                         Element parent,
                                         Element child)

Deprecated. use Node.appendChild(Node) instead

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 Element prependChildElement(Element parent,
                                          Element child)

prepend a child element

Parameters:

parent - element of this child element

child - the element to append

Returns:

the child element

prependChildElement

public static Element prependChildElement(Document doc,
                                          Element parent,
                                          Element child,
                                          boolean addWhitespace)

Deprecated. use prependChildElement(Element, Element) instead

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 Element findWsseSecurityHeaderBlock(Document doc,
                                                  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 Element findWsseSecurityHeaderBlock(Document doc,
                                                  Element envelope,
                                                  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 Text createBase64EncodedTextNode(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 SecretKey prepareSecretKey(String symEncAlgo,
                                         byte[] rawKey)

getSOAPConstants

public static SOAPConstants getSOAPConstants(Element startElement)

getCipherInstance

public static Cipher getCipherInstance(String cipherAlgo)
                                throws WSSecurityException

Throws:

WSSecurityException

fetchActionResult

public static WSSecurityEngineResult fetchActionResult(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 Vector fetchAllActionResults(Vector wsResultVector,
                                           int action,
                                           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(String action,
                               Vector actions)
                        throws WSSecurityException

Throws:

WSSecurityException

decodeAction

public static int decodeAction(String action,
                               Vector actions,
                               WSSConfig wssConfig)
                        throws WSSecurityException

Decode an action String. This method should only be called on the outbound side.

Parameters:

action - The initial String of actions to perform

actions - The vector of created actions that will be performed

wssConfig - This object holds the list of custom actions to be performed.

Returns:

The or'd integer of all the actions (apart from the custom actions)

Throws:

WSSecurityException

getKeyLength

public static int getKeyLength(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:

Exception

WSSecurityException

ensureSignedTogether

public static X509Certificate ensureSignedTogether(Iterator results,
                                                   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 SecureRandom resolveSecureRandom()
                                        throws NoSuchAlgorithmException

Returns:

a SecureRandom instance initialized with the "SHA1PRNG" algorithm identifier

Throws:

NoSuchAlgorithmException

resolveSecureRandom

public static SecureRandom resolveSecureRandom(String algorithm)
                                        throws NoSuchAlgorithmException

Parameters:

algorithm -

Returns:

a SecureRandom instance initialized with the identifier specified in algorithm

Throws:

NoSuchAlgorithmException