org.apache.ws.security.util

Class WSSecurityUtil

java.lang.Object

org.apache.ws.security.util.WSSecurityUtil

public final class WSSecurityUtil
extends Object

WS-Security Utility methods.

Author:

Davanum Srinivas (dims@yahoo.com).

Method Summary

Methods

Modifier and Type	Method and Description
static void	checkAllElementsProtected(List<WSSecurityEngineResult> results, int action, QName[] requiredParts) Check that all of the QName[] requiredParts are protected by a specified action in the results list.
static void	checkSignsAllElements(WSSecurityEngineResult resultItem, String[] requiredIDs) Ensure that this covers all required elements (identified by their wsu:Id attributes).
static Text	createBase64EncodedTextNode(Document doc, byte[] data) create a base64 test node
static int	decodeAction(String action, List<Integer> actions)
static int	decodeAction(String action, List<Integer> actions, WSSConfig wssConfig) Decode an action String.
static WSSecurityEngineResult	fetchActionResult(List<WSSecurityEngineResult> resultList, int action) Fetch the result of a given action from a given result list
static List<WSSecurityEngineResult>	fetchAllActionResults(List<WSSecurityEngineResult> resultList, int action, List<WSSecurityEngineResult> actionResultList) Fetch the result of a given action from a given result list.
static Element	findBodyElement(Document doc) return the first soap "Body" element.
static Element	findElement(Node startNode, String name, String namespace) Returns the first element that matches name and namespace.
static Element	findElementById(Node startNode, String value, boolean checkMultipleElements) Returns the single element that contains an Id with value uri and namespace.
static List<Element>	findElements(Node startNode, String name, String namespace) Returns all elements that match name and namespace.
static List<Element>	findElements(WSEncryptionPart part, CallbackLookup callbackLookup, Document doc) Find the DOM Element in the SOAP Envelope that is referenced by the WSEncryptionPart argument.
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[]	generateDigest(byte[] inputBytes) Generate a (SHA1) digest of the input bytes.
static byte[]	generateNonce(int length) Generate a nonce of the given length using the SHA1PRNG algorithm.
static Cipher	getCipherInstance(String cipherAlgo) Translate the "cipherAlgo" URI to a JCE ID, and return a javax.crypto.Cipher instance of this type.
static Element	getDirectChildElement(Node parentNode, String localName, String namespace) Gets a direct child with specified localname and namespace.
static List<Element>	getDirectChildElements(Node fNode, String localName, String namespace) Gets all direct children with specified localname and namespace.
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) 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) Returns the first WS-Security header element for a given actor.
static SOAPConstants	getSOAPConstants(Element startElement)
static String	getSOAPNamespace(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 List<Node>	listChildren(Node parent)
static List<Node>	newNodes(List<Node> a, List<Node> b)
static SecretKey	prepareSecretKey(String symEncAlgo, byte[] rawKey) Convert the raw key bytes into a SecretKey object of type symEncAlgo.
static Element	prependChildElement(Element parent, Element child) prepend a child element
static String	setNamespace(Element element, String namespace, String prefix) Set a namespace/prefix on an element if it is not set already.
static void	storeElementInContext(DOMCryptoContext context, Element element) Store the element argument in the DOM Crypto Context if it has one of the standard "Id" attributes.
static void	storeElementInContext(DOMCryptoContext context, String uri, Element element) Store the element argument in the DOM Crypto Context if it has one of the standard "Id" attributes that matches the given uri
static void	verifySignedElement(Element elem, WSDocInfo wsDocInfo)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getSecurityHeader

public static Element getSecurityHeader(Document doc,
                        String actor)
                                 throws WSSecurityException

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

Throws:

WSSecurityException

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

getDirectChildElement

public static Element getDirectChildElement(Node parentNode,
                            String localName,
                            String namespace)

Gets a direct child with specified localname and namespace.

Parameters:

parentNode - 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

getDirectChildElements

public static List<Element> getDirectChildElements(Node fNode,
                                   String localName,
                                   String namespace)

Gets all direct children with specified localname and namespace.

Parameters:

fNode - the node where to start the search

localName - local name of the children to get

namespace - the namespace of the children to get

Returns:

the list of nodes or null if not such nodes are found

findBodyElement

public static Element findBodyElement(Document doc)

return the first soap "Body" element.

Parameters:

doc -

Returns:

the body element or null if document does not contain a SOAP body

findElements

public static List<Element> findElements(WSEncryptionPart part,
                         CallbackLookup callbackLookup,
                         Document doc)
                                  throws WSSecurityException

Find the DOM Element in the SOAP Envelope that is referenced by the WSEncryptionPart argument. The "Id" is used before the Element localname/namespace.

Parameters:

part - The WSEncryptionPart object corresponding to the DOM Element(s) we want

callbackLookup - The CallbackLookup object used to find Elements

doc - The owning document

Returns:

the DOM Element in the SOAP Envelope that is found

Throws:

WSSecurityException

findElement

public static Element 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

findElements

public static List<Element> findElements(Node startNode,
                         String name,
                         String namespace)

Returns all elements that match 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 elements (or an empty list)

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,
                      boolean checkMultipleElements)

Returns the single element that contains an Id with value uri and namespace. The Id can be either a wsu:Id or an Id with no 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 checkMultipleElements is true and 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

checkMultipleElements - If true then go through the entire tree and return null if there are multiple elements with the same 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.

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

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

findWsseSecurityHeaderBlock

public static Element findWsseSecurityHeaderBlock(Document doc,
                                  Element envelope,
                                  boolean doCreate)
                                           throws WSSecurityException

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

Throws:

WSSecurityException

findWsseSecurityHeaderBlock

public static Element findWsseSecurityHeaderBlock(Document doc,
                                  Element envelope,
                                  String actor,
                                  boolean doCreate)
                                           throws WSSecurityException

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

Throws:

WSSecurityException

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

getSOAPConstants

public static SOAPConstants getSOAPConstants(Element startElement)

getSOAPNamespace

public static String getSOAPNamespace(Element startElement)

prepareSecretKey

public static SecretKey prepareSecretKey(String symEncAlgo,
                         byte[] rawKey)

Convert the raw key bytes into a SecretKey object of type symEncAlgo.

getCipherInstance

public static Cipher getCipherInstance(String cipherAlgo)
                                throws WSSecurityException

Translate the "cipherAlgo" URI to a JCE ID, and return a javax.crypto.Cipher instance of this type.

Throws:

WSSecurityException

fetchActionResult

public static WSSecurityEngineResult fetchActionResult(List<WSSecurityEngineResult> resultList,
                                       int action)

Fetch the result of a given action from a given result list

Parameters:

resultList - The result list to fetch an action from

action - The action to fetch

Returns:

The last result fetched from the result list, null if the result could not be found

fetchAllActionResults

public static List<WSSecurityEngineResult> fetchAllActionResults(List<WSSecurityEngineResult> resultList,
                                                 int action,
                                                 List<WSSecurityEngineResult> actionResultList)

Fetch the result of a given action from a given result list.

Parameters:

resultList - The result list to fetch an action from

action - The action to fetch

actionResultList - where to store the found results data for the action

Returns:

The result fetched from the result list, null if the result could not be found

decodeAction

public static int decodeAction(String action,
               List<Integer> actions)
                        throws WSSecurityException

Throws:

WSSecurityException

decodeAction

public static int decodeAction(String action,
               List<Integer> 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 list 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 using the SHA1PRNG algorithm. The SecureRandom instance that backs this method is cached for efficiency.

Returns:

a nonce of the given length

Throws:

WSSecurityException

generateDigest

public static byte[] generateDigest(byte[] inputBytes)
                             throws WSSecurityException

Generate a (SHA1) digest of the input bytes. The MessageDigest instance that backs this method is cached for efficiency.

Parameters:

inputBytes - the bytes to digest

Returns:

the digest of the input bytes

Throws:

WSSecurityException

checkAllElementsProtected

public static void checkAllElementsProtected(List<WSSecurityEngineResult> results,
                             int action,
                             QName[] requiredParts)
                                      throws WSSecurityException

Check that all of the QName[] requiredParts are protected by a specified action in the results list.

Parameters:

results - The List of WSSecurityEngineResults from processing

action - The action that is required (e.g. WSConstants.SIGN)

requiredParts - An array of QNames that correspond to the required elements

Throws:

WSSecurityException

checkSignsAllElements

public static void checkSignsAllElements(WSSecurityEngineResult resultItem,
                         String[] requiredIDs)
                                  throws WSSecurityException

Ensure that this covers all required elements (identified by their wsu:Id attributes).

Parameters:

resultItem - the signature to check

requiredIDs - the list of wsu:Id values that must be covered

Throws:

WSSecurityException - if any required element is not included

listChildren

public static List<Node> listChildren(Node parent)

Returns:

a list of child Nodes

newNodes

public static List<Node> newNodes(List<Node> a,
                  List<Node> b)

Returns:

a list of Nodes in b that are not in a

storeElementInContext

public static void storeElementInContext(DOMCryptoContext context,
                         String uri,
                         Element element)

Store the element argument in the DOM Crypto Context if it has one of the standard "Id" attributes that matches the given uri

storeElementInContext

public static void storeElementInContext(DOMCryptoContext context,
                         Element element)

Store the element argument in the DOM Crypto Context if it has one of the standard "Id" attributes.

verifySignedElement

public static void verifySignedElement(Element elem,
                       WSDocInfo wsDocInfo)
                                throws WSSecurityException

Throws:

WSSecurityException