oracle.security.xmlsec.saml

Class SAMLMessage

java.lang.Object

oracle.security.xmlsec.util.XMLNode

oracle.security.xmlsec.util.XMLElement

oracle.security.xmlsec.saml.SAMLMessage

Direct Known Subclasses:

Assertion, RequestType, ResponseType

public abstract class SAMLMessage
extends oracle.security.xmlsec.util.XMLElement

The base class for all the SAML and SAML extension messages that may be signed and contain an XML-DSIG structure.

Field Summary

Fields inherited from class oracle.security.xmlsec.util.XMLNode

node, systemId

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SAMLMessage(org.w3c.dom.Document owner, java.lang.String uri, java.lang.String localName) Creates a new SAMLMessage instance.
protected	SAMLMessage(org.w3c.dom.Element element) Creates a new SAMLMessage instance from the given Element node.
protected	SAMLMessage(org.w3c.dom.Element element, java.lang.String systemId) Creates a new SAMLMessage instance from the given Element node.

Method Summary

Modifier and Type	Method and Description
XSSignature	addSignature(java.lang.String signatureMethod, java.lang.String c14nMethod) Creates a new XML-DSIG Signature element and inserts it into this message, replacing any exisiting XML-DSIG Signature element.
XSSignature	addSignature(java.lang.String signatureMethod, java.lang.String c14nMethod, java.lang.String digestMethod) Creates a new XML-DSIG Signature element and inserts it into this message, replacing any exisiting XML-DSIG Signature element.
protected void	clearSignature() Removes any exisiting XML-DSIG Signature elements from this message.
protected abstract java.lang.String	getID() Returns the ID attribute if any of this SAML message to be used for the signature operations.
static SAMLMessage	getInstance(org.w3c.dom.Element element, java.lang.String ns) Instantiates a concrete SAMLMessage subclass implementation to wrap the given Element.
protected abstract java.lang.String[]	getLocalNamesPrecedeDSig() Obtains the ordered set of the local names of all the preceding sibling child elements of this Signature child element in the the Schema for the XML element that the implementing subclass targets for.
int	getMajorVersion() Returns the major version number of this SAML Message or -1 if the MajorVersion attribute is missing..
int	getMinorVersion() Returns the minor version number of this SAML Message or -1 if the MinorVersion attribute is missing.
protected abstract java.lang.String[]	getNSURIsPrecedeDSig() Obtains the ordered set of the the namespace URIs for all the preceding sibling child elements of this Signature child element in the the Schema for the XML element that the implementing subclass targets for.
XSSignature	getSignature() Returns the XML Signature child element from this SAMLMessage element.
boolean	isSigned() Indicates if this element was signed.
void	setVersion(int major, int minor) Sets the MajorVersion and MinorVersion attributes for this message.
void	sign(java.security.PrivateKey privateKey, java.security.cert.X509Certificate cert) Signs this SAMLMessage with the given private key, and includes the given certificate in the KeyInfo child element of the resulting XML-DSIG Signature element.
void	sign(java.security.PrivateKey privateKey, java.security.cert.X509Certificate cert, java.lang.String c14nMethod) Signs this SAMLMessage with the given private key, and includes the given certificate in the KeyInfo child element of the resulting XML-DSIG Signature element.
void	sign(java.lang.String signatureMethod, java.security.PrivateKey privateKey, java.security.cert.X509Certificate cert) Signs this SAMLMessage using given signature method, private key, and includes the given certificate in the KeyInfo child element of the resulting XML-DSIG Signature element.
void	sign(java.lang.String signatureMethod, java.lang.String digestMethod, java.security.PrivateKey privateKey, java.security.cert.X509Certificate cert, java.lang.String c14nMethod) Signs this SAMLMessage using the signature method, digest method, private key, and includes the given certificate in the KeyInfo child element of the resulting XML-DSIG Signature element.
boolean	verify() Verifies the signature using a key obtained either from the KeyInfo element (if any is present) or via the oracle.security.xmlsec.keys.retrieval.KeyRetriever mechanism.
boolean	verify(java.security.PublicKey publicKey) Verifies the signature with the given public key.

Methods inherited from class oracle.security.xmlsec.util.XMLElement

addNSPrefixAttr, addNSPrefixAttr, addNSPrefixAttrDefault, addNSPrefixAttrDefault, getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getChildElementsByTagName, getChildElementsByTagName, getChildElementsByTagNameNS, getChildElementsByTagNameNS, getDefaultNSPrefix, getElement, getElementsByTagName, getElementsByTagNameNS, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setDefaultNSPrefix

Methods inherited from class oracle.security.xmlsec.util.XMLNode

appendChild, appendChild, appendTo, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNode, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getSystemId, hasAttributes, hasChildNodes, insertBefore, insertBefore, isSupported, normalize, removeChild, removeChild, replaceChild, replaceChild, setNodeValue, setPrefix, setSystemId, toBytesXML, toStringXML

Methods inherited from class java.lang.Object

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

Constructor Detail

SAMLMessage

protected SAMLMessage(org.w3c.dom.Element element)
               throws org.w3c.dom.DOMException

Creates a new SAMLMessage instance from the given Element node.

Parameters:

element - A SAMLMessage element.

Throws:

org.w3c.dom.DOMException

SAMLMessage

protected SAMLMessage(org.w3c.dom.Element element,
                      java.lang.String systemId)
               throws org.w3c.dom.DOMException

Creates a new SAMLMessage instance from the given Element node.

Parameters:

element - A SAMLMessage element.

systemId - The URI string system ID for the Action.

Throws:

org.w3c.dom.DOMException

SAMLMessage

protected SAMLMessage(org.w3c.dom.Document owner,
                      java.lang.String uri,
                      java.lang.String localName)
               throws org.w3c.dom.DOMException

Creates a new SAMLMessage instance.

Parameters:

owner - The owner document of the new SAMLMessage.

uri - The namespace URI in which the new SAMLMessage is to be created.

localName - The localName of the element represented by the class that extends this class.

Throws:

org.w3c.dom.DOMException

Method Detail

getInstance

public static SAMLMessage getInstance(org.w3c.dom.Element element,
                                      java.lang.String ns)
                               throws org.w3c.dom.DOMException

Instantiates a concrete SAMLMessage subclass implementation to wrap the given Element.

Parameters:

element - An org.w3c.dom.Element representing an extension of one of the the following types: samlp:RequestAbstractType, samlp:ResponseAbstractType, saml:Assertion.

ns - The namespace URI for the element.

Returns:

A subclass of SAMLMessage, or null if no appropriate implementation class could be found.

Throws:

org.w3c.dom.DOMException

setVersion

public void setVersion(int major,
                       int minor)
                throws org.w3c.dom.DOMException

Sets the MajorVersion and MinorVersion attributes for this message. Version 1.0 is the default.

Parameters:

major - The major component of the version number.

minor - The minor component of the version number.

Throws:

org.w3c.dom.DOMException

getMajorVersion

public int getMajorVersion()

Returns the major version number of this SAML Message or -1 if the MajorVersion attribute is missing..

getMinorVersion

public int getMinorVersion()

Returns the minor version number of this SAML Message or -1 if the MinorVersion attribute is missing.

getNSURIsPrecedeDSig

protected abstract java.lang.String[] getNSURIsPrecedeDSig()

Obtains the ordered set of the the namespace URIs for all the preceding sibling child elements of this Signature child element in the the Schema for the XML element that the implementing subclass targets for.

getLocalNamesPrecedeDSig

protected abstract java.lang.String[] getLocalNamesPrecedeDSig()

Obtains the ordered set of the local names of all the preceding sibling child elements of this Signature child element in the the Schema for the XML element that the implementing subclass targets for.

getSignature

public XSSignature getSignature()

Returns the XML Signature child element from this SAMLMessage element.

Returns:

A XSSignature object or null if no signature is present.

isSigned

public boolean isSigned()

Indicates if this element was signed.

Returns:

true if a signature is present, false otherwise.

sign

public void sign(java.security.PrivateKey privateKey,
                 java.security.cert.X509Certificate cert)
          throws SigningException

Signs this SAMLMessage with the given private key, and includes the given certificate in the KeyInfo child element of the resulting XML-DSIG Signature element. The default canonicalization method is XML-EXCLUSIVE-C14N.

Parameters:

privateKey - The private key to use for the signature computation.

cert - The X509 certificate corresponding to the private key.

Throws:

SigningException

sign

public void sign(java.lang.String signatureMethod,
                 java.security.PrivateKey privateKey,
                 java.security.cert.X509Certificate cert)
          throws SigningException

Signs this SAMLMessage using given signature method, private key, and includes the given certificate in the KeyInfo child element of the resulting XML-DSIG Signature element. The default canonicalization method is XML-EXCLUSIVE-C14N.

Parameters:

signatureMethod - The value of the algorithm attribute of the SignatureMethod

privateKey - The private key to use for the signature computation.

cert - The X509 certificate corresponding to the private key.

Throws:

SigningException

sign

public void sign(java.lang.String signatureMethod,
                 java.lang.String digestMethod,
                 java.security.PrivateKey privateKey,
                 java.security.cert.X509Certificate cert,
                 java.lang.String c14nMethod)
          throws SigningException

Signs this SAMLMessage using the signature method, digest method, private key, and includes the given certificate in the KeyInfo child element of the resulting XML-DSIG Signature element. The default canonicalization method is XML-EXCLUSIVE-C14N.

Parameters:

signatureMethod - The value of the algorithm attribute of the SignatureMethod

digestMethod - The value of the Algorithm attribute of the DigestMethod

privateKey - The private key to use for the signature computation.

cert - The X509 certificate corresponding to the private key.

Throws:

SigningException

sign

public void sign(java.security.PrivateKey privateKey,
                 java.security.cert.X509Certificate cert,
                 java.lang.String c14nMethod)
          throws SigningException

Signs this SAMLMessage with the given private key, and includes the given certificate in the KeyInfo child element of the resulting XML-DSIG Signature element.

Parameters:

privateKey - The private key to use for the signature computation.

cert - The X509 certificate corresponding to the private key.

c14nMethod - The URI identifying the canonicalization method to be applied to the SignedInfo structure.

Throws:

SigningException

addSignature

public XSSignature addSignature(java.lang.String signatureMethod,
                                java.lang.String c14nMethod)

Creates a new XML-DSIG Signature element and inserts it into this message, replacing any exisiting XML-DSIG Signature element. The default message digest algorithm is SHA-1.

Note: This method does not compute the SignatureValue or create a KeyInfo child element for the Signature element so, at a minimum, one of the sign() methods must be invoked on the returned XSSignature object.

This method is intended for use by developers who need to customize the Signature element (e.g., add custom Transform elements) the computation of the SignatureValue (e.g., using an HMAC signature algorithm) or the KeyInfo element. For most developers, either the #sign(PrivateKey, X509) or #sign(PrivateKey, X509, String) method should be sufficient.

Parameters:

signatureMethod - The value of the Algorithm attribute of the SignatureMethod element contained within the new Signature element's SignedInfo child element (e.g., oracle.security.xmlsec.util.XMLURI.alg_rsaWithSHA1).

c14nMethod - The value of the Algorithm attribute of the CanonicalizationMethod element contained within the new Signature element's SignedInfo child element (e.g., oracle.security.xmlsec.util.XMLURI.alg_c14nWithComments).

Returns:

The new oracle.security.xmlsec.dsig.XSSignature object.

Since:

1.2

addSignature

public XSSignature addSignature(java.lang.String signatureMethod,
                                java.lang.String c14nMethod,
                                java.lang.String digestMethod)

Creates a new XML-DSIG Signature element and inserts it into this message, replacing any exisiting XML-DSIG Signature element.

Note: This method does not compute the SignatureValue or create a KeyInfo child element for the Signature element so, at a minimum, one of the sign() methods must be invoked on the returned XSSignature object.

This method is intended for use by developers who need to customize the Signature element (e.g., add custom Transform elements) the computation of the SignatureValue (e.g., using an HMAC signature algorithm) or the KeyInfo element. For most developers, either the #sign(PrivateKey, X509) or #sign(PrivateKey, X509, String) method should be sufficient.

Parameters:

signatureMethod - The value of the Algorithm attribute of the SignatureMethod element contained within the new Signature element's SignedInfo child element (e.g., oracle.security.xmlsec.util.XMLURI.alg_rsaWithSHA1).

c14nMethod - The value of the Algorithm attribute of the CanonicalizationMethod element contained within the new Signature element's SignedInfo child element (e.g., oracle.security.xmlsec.util.XMLURI.alg_c14nWithComments).

digestMethod - The value of the Algorithm attribute of the DigestMethod element contained within the new Signature element's Reference child element (e.g., oracle.security.xmlsec.util.XMLURI.alg_sha1).

Returns:

The new oracle.security.xmlsec.dsig.XSSignature object.

Since:

1.2

verify

public boolean verify()
               throws VerifyException

Verifies the signature using a key obtained either from the KeyInfo element (if any is present) or via the oracle.security.xmlsec.keys.retrieval.KeyRetriever mechanism. Any Manifests referenced by the signature will be validated.

Returns:

true if the verification succeeded, or false if the verification failed.

Throws:

VerifyException - If an error occurs while verifying the signature, or if no signature is present in this message.

verify

public boolean verify(java.security.PublicKey publicKey)
               throws VerifyException

Verifies the signature with the given public key. Any Manifests referenced by the signature will be validated.

Parameters:

publicKey - The public key used for verifying the signature.

Returns:

true if the verification succeeded, or false if the verification failed.

Throws:

VerifyException - If an error occurs while verifying the signature, or if no signature is present in this message.

clearSignature

protected void clearSignature()

Removes any exisiting XML-DSIG Signature elements from this message.

getID

protected abstract java.lang.String getID()

Returns the ID attribute if any of this SAML message to be used for the signature operations.