javax.xml.crypto.dsig.XMLSignature Maven / Gradle / Ivy
/**
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/*
* Portions copyright 2005 Sun Microsystems, Inc. All rights reserved.
*/
/*
* ===========================================================================
*
* (C) Copyright IBM Corp. 2003 All Rights Reserved.
*
* ===========================================================================
*/
/*
* $Id$
*/
package javax.xml.crypto.dsig;
import javax.xml.crypto.KeySelector;
import javax.xml.crypto.KeySelectorResult;
import javax.xml.crypto.MarshalException;
import javax.xml.crypto.XMLStructure;
import javax.xml.crypto.dsig.keyinfo.KeyInfo;
import java.security.Signature;
import java.util.List;
/**
* 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
* {@link XMLSignatureFactory#newXMLSignature newXMLSignature} methods of the
* {@link 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
* {@link Signature java.security.Signature} class.
*
* @see XMLSignatureFactory#newXMLSignature(SignedInfo, KeyInfo)
* @see XMLSignatureFactory#newXMLSignature(SignedInfo, KeyInfo, List, String, String)
* @author Joyce L. Leung
* @author Sean Mullan
* @author Erwin van der Koogh
* @author JSR 105 Expert Group
*/
public interface XMLSignature extends XMLStructure {
/**
* The XML Namespace URI of the W3C Recommendation for XML-Signature
* Syntax and Processing.
*/
String XMLNS = "http://www.w3.org/2000/09/xmldsig#";
/**
* 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.
*
* @param validateContext the validating context
* @return true if the signature passed core validation,
* otherwise false
* @throws ClassCastException if the type of validateContext
* is not compatible with this XMLSignature
* @throws NullPointerException if validateContext is
* null
* @throws XMLSignatureException if an unexpected error occurs during
* validation that prevented the validation operation from completing
*/
boolean validate(XMLValidateContext validateContext)
throws XMLSignatureException;
/**
* Returns the key info of this XMLSignature.
*
* @return the key info (may be null if not specified)
*/
KeyInfo getKeyInfo();
/**
* Returns the signed info of this XMLSignature.
*
* @return the signed info (never null)
*/
SignedInfo getSignedInfo();
/**
* Returns an {@link java.util.Collections#unmodifiableList unmodifiable
* list} of {@link XMLObject}s contained in this XMLSignature.
*
* @return an unmodifiable list of XMLObjects (may be empty
* but never null)
*/
List getObjects();
/**
* Returns the optional Id of this XMLSignature.
*
* @return the Id (may be null if not specified)
*/
String getId();
/**
* Returns the signature value of this XMLSignature.
*
* @return the signature value
*/
SignatureValue getSignatureValue();
/**
* 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.
*
* @param signContext the signing context
* @throws ClassCastException if the type of signContext is
* not compatible with this XMLSignature
* @throws NullPointerException if signContext is
* null
* @throws MarshalException if an exception occurs while marshalling
* @throws XMLSignatureException if an unexpected exception occurs while
* generating the signature
*/
void sign(XMLSignContext signContext) throws MarshalException,
XMLSignatureException;
/**
* Returns the result of the {@link KeySelector}, if specified, after
* this XMLSignature has been signed or validated.
*
* @return the key selector result, or null if a key
* selector has not been specified or this XMLSignature
* has not been signed or validated
*/
KeySelectorResult getKeySelectorResult();
/**
* A representation of the XML SignatureValue element as
* defined in the
* W3C Recommendation for XML-Signature Syntax and Processing.
* The XML Schema Definition is defined as:
*
*
* <element name="SignatureValue" type="ds:SignatureValueType"/>
* <complexType name="SignatureValueType">
* <simpleContent>
* <extension base="base64Binary">
* <attribute name="Id" type="ID" use="optional"/>
* </extension>
* </simpleContent>
* </complexType>
*
*
* @author Sean Mullan
* @author JSR 105 Expert Group
*/
public interface SignatureValue extends XMLStructure {
/**
* Returns the optional Id attribute of this
* SignatureValue, which permits this element to be
* referenced from elsewhere.
*
* @return the Id attribute (may be null if
* not specified)
*/
String getId();
/**
* Returns the signature value of this SignatureValue.
*
* @return the signature value (may be null if the
* XMLSignature has not been signed yet). Each
* invocation of this method returns a new clone of the array to
* prevent subsequent modification.
*/
byte[] getValue();
/**
* Validates the signature value. This method performs a
* cryptographic validation of the signature calculated over the
* SignedInfo of the XMLSignature.
*
* This method only validates the signature the first
* time it is invoked. On subsequent invocations, it returns a cached
* result.
*
* @return true if the signature was
* validated successfully; false otherwise
* @param validateContext the validating context
* @throws NullPointerException if validateContext is
* null
* @throws XMLSignatureException if an unexpected exception occurs while
* validating the signature
*/
boolean validate(XMLValidateContext validateContext)
throws XMLSignatureException;
}
}