javax.xml.crypto.dsig.Reference Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of xmlsec Show documentation
Apache XML Security for Java supports XML-Signature Syntax and Processing, W3C Recommendation 12 February 2002, and XML Encryption Syntax and Processing, W3C Recommendation 10 December 2002. As of version 1.4, the library supports the standard Java API JSR-105: XML Digital Signature APIs.
There is a newer version: 4.0.2
Show newest version
/**
 * 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.
 */
/*
 * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
 */
/*
 * $Id: Reference.java 1092655 2011-04-15 10:24:18Z coheigea $
 */
package javax.xml.crypto.dsig;

import javax.xml.crypto.Data;
import javax.xml.crypto.URIReference;
import javax.xml.crypto.XMLStructure;
import java.io.InputStream;
import java.util.List;

/**
 * A representation of the Reference element as defined in the 
 * 
 * W3C Recommendation for XML-Signature Syntax and Processing. 
 * The XML schema is defined as: 
 *  * <element name="Reference" type="ds:ReferenceType"/>
 * <complexType name="ReferenceType">
 *   <sequence>
 *     <element ref="ds:Transforms" minOccurs="0"/>
 *     <element ref="ds:DigestMethod"/>
 *     <element ref="ds:DigestValue"/>
 *   </sequence>
 *   <attribute name="Id" type="ID" use="optional"/>
 *   <attribute name="URI" type="anyURI" use="optional"/>
 *   <attribute name="Type" type="anyURI" use="optional"/>
 * </complexType>
 *
 * <element name="DigestValue" type="ds:DigestValueType"/>
 * <simpleType name="DigestValueType">
 *   <restriction base="base64Binary"/>
 * </simpleType>
 * 
 *
 * A Reference instance may be created by invoking one of the 
 * {@link XMLSignatureFactory#newReference newReference} methods of the
 * {@link XMLSignatureFactory} class; for example:
 *
 * 
 *   XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");
 *   Reference ref = factory.newReference
 *     ("http://www.ietf.org/rfc/rfc3275.txt", 
 *	factory.newDigestMethod(DigestMethod.SHA1, null));
 * 
 *
 * @author Sean Mullan
 * @author Erwin van der Koogh 
 * @author JSR 105 Expert Group
 * @see XMLSignatureFactory#newReference(String, DigestMethod)
 * @see XMLSignatureFactory#newReference(String, DigestMethod, List, String, String)
 */
public interface Reference extends URIReference, XMLStructure {

    /**
     * Returns an {@link java.util.Collections#unmodifiableList unmodifiable 
     * list} of {@link Transform}s that are contained in this 
     * Reference.
     *
     * @return an unmodifiable list of Transforms
     *    (may be empty but never null)
     */
    List getTransforms();

    /**
     * Returns the digest method of this Reference.
     *
     * @return the digest method
     */
    DigestMethod getDigestMethod();

    /**
     * Returns the optional Id attribute of this 
     * Reference, which permits this reference to be 
     * referenced from elsewhere.
     *
     * @return the Id attribute (may be null if not 
     *    specified) 
     */
    String getId();

    /**
     * Returns the digest value of this Reference.
     * 
     * @return the raw digest value, or null if this reference has
     *    not been digested yet. Each invocation of this method returns a new
     *    clone to protect against subsequent modification.
     */
    byte[] getDigestValue();

    /**
     * Returns the calculated digest value of this Reference
     * after a validation operation. This method is useful for debugging if
     * the reference fails to validate.
     * 
     * @return the calculated digest value, or null if this 
     *    reference has not been validated yet. Each invocation of this method 
     *    returns a new clone to protect against subsequent modification.
     */
    byte[] getCalculatedDigestValue();

    /**
     * Validates this reference. This method verifies the digest of this 
     * reference.
     *
     * This method only validates the reference the first time it is 
     * invoked. On subsequent invocations, it returns a cached result.
     *
     * @return true if this reference 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 reference 
     */
    boolean validate(XMLValidateContext validateContext) 
        throws XMLSignatureException;

    /**
     * Returns the dereferenced data, if 
     * reference caching
     * is enabled. This is the result of dereferencing the URI of this 
     * reference during a validation or generation operation. 
     *
     * @return the dereferenced data, or null if reference 
     *    caching is not enabled or this reference has not been generated or
     *    validated
     */
    Data getDereferencedData();

    /**
     * Returns the pre-digested input stream, if
     * reference caching
     * is enabled. This is the input to the digest operation during a
     * validation or signing operation. 
     *
     * @return an input stream containing the pre-digested input, or
     *    null if reference caching is not enabled or this
     *    reference has not been generated or validated
     */
    InputStream getDigestInputStream();
}