org.apache.ws.security
Class WSSecurityEngine

java.lang.Object
  extended byorg.apache.ws.security.WSSecurityEngine

public class WSSecurityEngine
extends java.lang.Object

WS-Security Engine.

Author:
Davanum Srinivas (dims@yahoo.com)., Werner Dittmann (Werner.Dittmann@siemens.com).

Field Summary
protected  javax.xml.namespace.QName binaryToken
          wsse:BinarySecurityToken as defined by WS Security specification
protected static javax.xml.namespace.QName ENCRYPTED_KEY
          xenc:EncryptedKey as defined by XML Encryption specification, enhanced by WS Security specification
protected static javax.xml.namespace.QName REFERENCE_LIST
          xenc:ReferenceList as defined by XML Encryption specification,
protected static javax.xml.namespace.QName SAML_TOKEN
          saml:Assertion as defined by SAML specification
protected static javax.xml.namespace.QName SIGNATURE
          ds:Signature as defined by XML Signature specification, enhanced by WS Security specification
protected  javax.xml.namespace.QName timeStamp
          wsu:Timestamp as defined by OASIS WS Security specification,
protected  javax.xml.namespace.QName usernameToken
          wsse:UsernameToken as defined by WS Security specification
protected  WSSConfig wssConfig
           
 
Constructor Summary
WSSecurityEngine()
           
WSSecurityEngine(WSSConfig wssConfig)
           
 
Method Summary
 void decryptDataRefEmbedded(org.w3c.dom.Document doc, java.lang.String dataRefURI, javax.security.auth.callback.CallbackHandler cb)
           
protected  java.security.cert.X509Certificate[] getCertificatesFromSAML(org.w3c.dom.Element elem, Crypto crypto)
          Extracts the certificate(s) from the SAML token reference.
 java.security.cert.X509Certificate[] getCertificatesTokenReference(org.w3c.dom.Element elem, Crypto crypto)
          Extracts the certificate(s) from the Binary Security token reference.
static byte[] getDecodedBase64EncodedData(org.w3c.dom.Element element)
          Method getDecodedBase64EncodedData
 byte[] getDecryptedBytes()
           
static WSSecurityEngine getInstance()
          Get a singleton instance of security engine.
static WSSecurityEngine getInstance(WSSConfig wssConfig)
          Get a singleton instance of security engine with specified configuration settings.
protected  javax.crypto.SecretKey getSharedKey(org.w3c.dom.Element keyInfoElem, java.lang.String algorithm, javax.security.auth.callback.CallbackHandler cb)
           
 void handleEncryptedKey(org.w3c.dom.Element xencEncryptedKey, javax.security.auth.callback.CallbackHandler cb, Crypto crypto)
           
 void handleEncryptedKey(org.w3c.dom.Element xencEncryptedKey, javax.security.auth.callback.CallbackHandler cb, Crypto crypto, java.security.PrivateKey privateKey)
           
 void handleEncryptedKey(org.w3c.dom.Element xencEncryptedKey, java.security.PrivateKey privatekey)
           
 org.opensaml.SAMLAssertion handleSAMLToken(org.w3c.dom.Element token)
           
 void handleTimestamp(Timestamp timestamp)
           
 WSUsernameTokenPrincipal handleUsernameToken(org.w3c.dom.Element token, javax.security.auth.callback.CallbackHandler cb)
          Check the UsernameToken element.
 java.util.Vector processSecurityHeader(org.w3c.dom.Document doc, java.lang.String actor, javax.security.auth.callback.CallbackHandler cb, Crypto crypto)
          Process the security header given the soap envelope as W3C document.
 java.util.Vector processSecurityHeader(org.w3c.dom.Document doc, java.lang.String actor, javax.security.auth.callback.CallbackHandler cb, Crypto sigCrypto, Crypto decCrypto)
          Process the security header given the soap envelope as W3C document.
protected  java.util.Vector processSecurityHeader(org.w3c.dom.Element securityHeader, javax.security.auth.callback.CallbackHandler cb, Crypto sigCrypto, Crypto decCrypto)
          Process the security header given the wsse:Security DOM Element.
protected  java.security.Principal verifyXMLSignature(org.w3c.dom.Element elem, Crypto crypto, java.security.cert.X509Certificate[] returnCert, java.util.Vector[] returnQname)
          Verify the WS-Security signature.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

wssConfig

protected WSSConfig wssConfig

binaryToken

protected javax.xml.namespace.QName binaryToken
wsse:BinarySecurityToken as defined by WS Security specification


usernameToken

protected javax.xml.namespace.QName usernameToken
wsse:UsernameToken as defined by WS Security specification


timeStamp

protected javax.xml.namespace.QName timeStamp
wsu:Timestamp as defined by OASIS WS Security specification,


SIGNATURE

protected static final javax.xml.namespace.QName SIGNATURE
ds:Signature as defined by XML Signature specification, enhanced by WS Security specification


ENCRYPTED_KEY

protected static final javax.xml.namespace.QName ENCRYPTED_KEY
xenc:EncryptedKey as defined by XML Encryption specification, enhanced by WS Security specification


REFERENCE_LIST

protected static final javax.xml.namespace.QName REFERENCE_LIST
xenc:ReferenceList as defined by XML Encryption specification,


SAML_TOKEN

protected static final javax.xml.namespace.QName SAML_TOKEN
saml:Assertion as defined by SAML specification

Constructor Detail

WSSecurityEngine

public WSSecurityEngine()

WSSecurityEngine

public WSSecurityEngine(WSSConfig wssConfig)
Method Detail

getInstance

public static WSSecurityEngine getInstance()
Get a singleton instance of security engine.

Returns:
ws-security engine.

getInstance

public static WSSecurityEngine getInstance(WSSConfig wssConfig)
Get a singleton instance of security engine with specified configuration settings.

Parameters:
wssConfig - the configuration parameters to use.
Returns:
ws-security engine.

processSecurityHeader

public java.util.Vector processSecurityHeader(org.w3c.dom.Document doc,
                                              java.lang.String actor,
                                              javax.security.auth.callback.CallbackHandler cb,
                                              Crypto crypto)
                                       throws WSSecurityException
Process the security header given the soap envelope as W3C document.

This is the main entry point to verify or decrypt a SOAP enevelope. First check if a wsse:Security is availabe with the defined actor.

Parameters:
doc - the SOAP envelope as Document
actor - the engine works on behalf of this actor. Refer to the SOAP specification about actor or role
cb - a callback hander to the caller to resolve passwords during encryption and UsernameToken handling
crypto - the object that implements the access to the keystore and the handling of certificates.
Returns:
a result vector
Throws:
WSSecurityException
See Also:
processSecurityHeader(Element securityHeader, CallbackHandler cb,Crypto sigCrypto, Crypto decCrypto)

processSecurityHeader

public java.util.Vector processSecurityHeader(org.w3c.dom.Document doc,
                                              java.lang.String actor,
                                              javax.security.auth.callback.CallbackHandler cb,
                                              Crypto sigCrypto,
                                              Crypto decCrypto)
                                       throws WSSecurityException
Process the security header given the soap envelope as W3C document.

This is the main entry point to verify or decrypt a SOAP enevelope. First check if a wsse:Security is availabe with the defined actor.

Parameters:
doc - the SOAP envelope as Document
actor - the engine works on behalf of this actor. Refer to the SOAP specification about actor or role
cb - a callback hander to the caller to resolve passwords during encryption and UsernameToken handling
sigCrypto - the object that implements the access to the keystore and the handling of certificates for Signature
decCrypto - the object that implements the access to the keystore and the handling of certificates for Decryption
Returns:
a result vector
Throws:
WSSecurityException
See Also:
processSecurityHeader(Element securityHeader, CallbackHandler cb,Crypto sigCrypto, Crypto decCrypto)

processSecurityHeader

protected java.util.Vector processSecurityHeader(org.w3c.dom.Element securityHeader,
                                                 javax.security.auth.callback.CallbackHandler cb,
                                                 Crypto sigCrypto,
                                                 Crypto decCrypto)
                                          throws WSSecurityException
Process the security header given the wsse:Security DOM Element.

This function loops over all direct child elements of the wsse:Security header. If it finds a knwon element, it transfers control to the appropriate handling function. The mehtod processes the known child elements in the same order as they appear in the wsse:Security element. This is in accordance to the WS Security specification.

Currently the functions can handle the following child elements: here:

Parameters:
securityHeader - the wsse:Security header element
cb - a callback hander to the caller to resolve passwords during encryption and UsernameTokenhandling
sigCrypto - the object that implements the access to the keystore and the handling of certificates used for Signature
decCrypto - the object that implements the access to the keystore and the handling of certificates used for Decryption
Returns:
a Vector of WSSecurityEngineResult. Each element in the the Vector represents the result of a security action. The elements are ordered according to the sequence of the security actions in the wsse:Signature header. The Vector maybe empty if no security processing was performed.
Throws:
WSSecurityException

verifyXMLSignature

protected java.security.Principal verifyXMLSignature(org.w3c.dom.Element elem,
                                                     Crypto crypto,
                                                     java.security.cert.X509Certificate[] returnCert,
                                                     java.util.Vector[] returnQname)
                                              throws WSSecurityException
Verify the WS-Security signature.

The functions at first checks if then KeyInfo that is contained in the signature contains standard X509 data. If yes then get the certificate data via the standard KeyInfo methods.

Otherwise, if the KeyInfo info does not contain X509 data, check if we can find a wsse:SecurityTokenReference element. If yes, the next step is to check how to get the certificate. Two methods are currently supported here:

The methods checks is the certificate is valid and calls the verfication function.

Parameters:
elem - the XMLSignature DOM Element.
crypto - the object that implements the access to the keystore and the handling of certificates.
returnCert - verifyXMLSignature stores the certificate in the first entry of this array. Ther caller may then further validate the certificate
returnQname - verifyXMLSignature store the Qnames of all signed elements in this Vector ordered according the sequence in the Signature header.
Returns:
the subject principal of the validated X509 certificate (the authenticated subject). The calling function may use this principal for further authentication or authorization.
Throws:
WSSecurityException

getCertificatesTokenReference

public java.security.cert.X509Certificate[] getCertificatesTokenReference(org.w3c.dom.Element elem,
                                                                          Crypto crypto)
                                                                   throws WSSecurityException
Extracts the certificate(s) from the Binary Security token reference.

Parameters:
elem - The element containing the binary security token. This is either X509 certificate(s) or a PKIPath.
Returns:
an array of X509 certificates
Throws:
WSSecurityException

getCertificatesFromSAML

protected java.security.cert.X509Certificate[] getCertificatesFromSAML(org.w3c.dom.Element elem,
                                                                       Crypto crypto)
                                                                throws WSSecurityException
Extracts the certificate(s) from the SAML token reference.

Parameters:
elem - The element containing the SAML token.
Returns:
an array of X509 certificates
Throws:
WSSecurityException

handleUsernameToken

public WSUsernameTokenPrincipal handleUsernameToken(org.w3c.dom.Element token,
                                                    javax.security.auth.callback.CallbackHandler cb)
                                             throws WSSecurityException
Check the UsernameToken element. Depending on the password type contained in the element the processing differs. If the password type is password digest (a hashed password) then process the password commpletely here. Use the callback class to get a stored password perform hash algorithm and compare the result with the transmitted password.

If the password is of type password text or any other yet unknown password type the delegate the password validation to the callback class. To do so the security engine hands over all necessary data to the callback class via the WSPasswordCallback object. To distinguish from digested usernam token the usage parameter of WSPasswordCallback is set to USERNAME_TOKEN_UNKNOWN

Parameters:
token - the DOM element that contains the UsernameToken
cb - the refernce to the callback object
Returns:
WSUsernameTokenPrincipal that contain data that an application may use to further validate the password/user combination.
Throws:
WSSecurityException

handleSAMLToken

public org.opensaml.SAMLAssertion handleSAMLToken(org.w3c.dom.Element token)
                                           throws WSSecurityException
Throws:
WSSecurityException

handleTimestamp

public void handleTimestamp(Timestamp timestamp)
                     throws WSSecurityException
Throws:
WSSecurityException

handleEncryptedKey

public void handleEncryptedKey(org.w3c.dom.Element xencEncryptedKey,
                               javax.security.auth.callback.CallbackHandler cb,
                               Crypto crypto)
                        throws WSSecurityException
Throws:
WSSecurityException

handleEncryptedKey

public void handleEncryptedKey(org.w3c.dom.Element xencEncryptedKey,
                               java.security.PrivateKey privatekey)
                        throws WSSecurityException
Throws:
WSSecurityException

handleEncryptedKey

public void handleEncryptedKey(org.w3c.dom.Element xencEncryptedKey,
                               javax.security.auth.callback.CallbackHandler cb,
                               Crypto crypto,
                               java.security.PrivateKey privateKey)
                        throws WSSecurityException
Throws:
WSSecurityException

decryptDataRefEmbedded

public void decryptDataRefEmbedded(org.w3c.dom.Document doc,
                                   java.lang.String dataRefURI,
                                   javax.security.auth.callback.CallbackHandler cb)
                            throws WSSecurityException
Throws:
WSSecurityException

getSharedKey

protected javax.crypto.SecretKey getSharedKey(org.w3c.dom.Element keyInfoElem,
                                              java.lang.String algorithm,
                                              javax.security.auth.callback.CallbackHandler cb)
                                       throws WSSecurityException
Throws:
WSSecurityException

getDecodedBase64EncodedData

public static byte[] getDecodedBase64EncodedData(org.w3c.dom.Element element)
                                          throws WSSecurityException
Method getDecodedBase64EncodedData

Parameters:
element -
Returns:
Throws:
WSSecurityException

getDecryptedBytes

public byte[] getDecryptedBytes()
Returns: