Module java.xml.crypto
Package javax.xml.crypto.dsig

# Interface XMLSignature

All Superinterfaces:
  `XMLStructure`

public interface XMLSignature extends XMLStructure
A representation of the XML `Signature` element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. This class contains methods for signing and validating XML signatures with behavior as defined by the W3C specification. The XML Schema Definition is defined as:

     <element name="Signature" type="ds:SignatureType"/>
     <complexType name="SignatureType">
        <sequence>
          <element ref="ds:SignedInfo"/>
          <element ref="ds:SignatureValue"/>
          <element ref="ds:KeyInfo" minOccurs="0"/>
          <element ref="ds:Object" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
        <attribute name="Id" type="ID" use="optional"/>
     </complexType>

An `XMLSignature` instance may be created by invoking one of the `newXMLSignature` methods of the `XMLSignatureFactory` class.

If the contents of the underlying document containing the `XMLSignature` are subsequently modified, the behavior is undefined.

Note that this class is named `XMLSignature` rather than `Signature` to avoid naming clashes with the existing `java.security.Signature` class.

Since:
  1.6
See Also:
  - `XMLSignatureFactory.newXMLSignature(SignedInfo, KeyInfo)`
  - `XMLSignatureFactory.newXMLSignature(SignedInfo, KeyInfo, List, String, String)`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `XMLSignature.SignatureValue`
  A representation of the XML `SignatureValue` element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `XMLNS`
  The XML Namespace URI of the W3C Recommendation for XML-Signature Syntax and Processing.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getId()`
  Returns the optional Id of this `XMLSignature`.
  `KeyInfo`
  `getKeyInfo()`
  Returns the key info of this `XMLSignature`.
  `KeySelectorResult`
  `getKeySelectorResult()`
  Returns the result of the `KeySelector`, if specified, after this `XMLSignature` has been signed or validated.
  `List<XMLObject>`
  `getObjects()`
  Returns an `unmodifiable list` of `XMLObject`s contained in this `XMLSignature`.
  `XMLSignature.SignatureValue`
  `getSignatureValue()`
  Returns the signature value of this `XMLSignature`.
  `SignedInfo`
  `getSignedInfo()`
  Returns the signed info of this `XMLSignature`.
  `void`
  `sign(XMLSignContext signContext)`
  Signs this `XMLSignature`.
  `boolean`
  `validate(XMLValidateContext validateContext)`
  Validates the signature according to the core validation processing rules.

  ### Methods declared in interface javax.xml.crypto.XMLStructure

  `isFeatureSupported`

- ## Field Details

  - ### XMLNS

    static final String XMLNS
    The XML Namespace URI of the W3C Recommendation for XML-Signature Syntax and Processing.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### validate

    boolean validate(XMLValidateContext validateContext) throws XMLSignatureException
    Validates the signature according to the core validation processing rules. This method validates the signature using the existing state, it does not unmarshal and reinitialize the contents of the `XMLSignature` using the location information specified in the context.

    This method only validates the signature the first time it is invoked. On subsequent invocations, it returns a cached result.

    Parameters:
      `validateContext` - the validating context
    Returns:
      `true` if the signature passed core validation, otherwise `false`
    Throws:
      `ClassCastException` - if the type of `validateContext` is not compatible with this `XMLSignature`
      `NullPointerException` - if `validateContext` is `null`
      `XMLSignatureException` - if an unexpected error occurs during validation that prevented the validation operation from completing

  - ### getKeyInfo

    KeyInfo getKeyInfo()
    Returns the key info of this `XMLSignature`.
    Returns:
      the key info (may be `null` if not specified)

  - ### getSignedInfo

    SignedInfo getSignedInfo()
    Returns the signed info of this `XMLSignature`.
    Returns:
      the signed info (never `null`)

  - ### getObjects

    List<XMLObject> getObjects()
    Returns an `unmodifiable list` of `XMLObject`s contained in this `XMLSignature`.
    Returns:
      an unmodifiable list of `XMLObject`s (may be empty but never `null`)

  - ### getId

    String getId()
    Returns the optional Id of this `XMLSignature`.
    Returns:
      the Id (may be `null` if not specified)

  - ### getSignatureValue

    XMLSignature.SignatureValue getSignatureValue()
    Returns the signature value of this `XMLSignature`.
    Returns:
      the signature value

  - ### sign

    void sign(XMLSignContext signContext) throws MarshalException, XMLSignatureException
    Signs this `XMLSignature`.

    If this method throws an exception, this `XMLSignature` and the `signContext` parameter will be left in the state that it was in prior to the invocation.

    Parameters:
      `signContext` - the signing context
    Throws:
      `ClassCastException` - if the type of `signContext` is not compatible with this `XMLSignature`
      `NullPointerException` - if `signContext` is `null`
      `MarshalException` - if an exception occurs while marshalling
      `XMLSignatureException` - if an unexpected exception occurs while generating the signature

  - ### getKeySelectorResult

    KeySelectorResult getKeySelectorResult()
    Returns the result of the `KeySelector`, if specified, after this `XMLSignature` has been signed or validated.
    Returns:
      the key selector result, or `null` if a key selector has not been specified or this `XMLSignature` has not been signed or validated