org.apache.ws.security.util
Class WSSecurityUtil

java.lang.Object
  extended by 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 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(javax.xml.crypto.dom.DOMCryptoContext context, Element element)
          Store the element argument in the DOM Crypto Context if it has one of the standard "Id" attributes.
 
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)
                                 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(javax.xml.crypto.dom.DOMCryptoContext context,
                                         Element element)
Store the element argument in the DOM Crypto Context if it has one of the standard "Id" attributes.



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