001 /*
002 * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 /*
026 * $Id: Reference.java,v 1.9 2005/05/10 16:03:46 mullan Exp $
027 */
028 package javax.xml.crypto.dsig;
029
030 import javax.xml.crypto.Data;
031 import javax.xml.crypto.URIReference;
032 import javax.xml.crypto.XMLStructure;
033 import java.io.InputStream;
034 import java.util.List;
035
036 /**
037 * A representation of the <code>Reference</code> element as defined in the
038 * <a href="http://www.w3.org/TR/xmldsig-core/">
039 * W3C Recommendation for XML-Signature Syntax and Processing</a>.
040 * The XML schema is defined as:
041 * <code><pre>
042 * <element name="Reference" type="ds:ReferenceType"/>
043 * <complexType name="ReferenceType">
044 * <sequence>
045 * <element ref="ds:Transforms" minOccurs="0"/>
046 * <element ref="ds:DigestMethod"/>
047 * <element ref="ds:DigestValue"/>
048 * </sequence>
049 * <attribute name="Id" type="ID" use="optional"/>
050 * <attribute name="URI" type="anyURI" use="optional"/>
051 * <attribute name="Type" type="anyURI" use="optional"/>
052 * </complexType>
053 *
054 * <element name="DigestValue" type="ds:DigestValueType"/>
055 * <simpleType name="DigestValueType">
056 * <restriction base="base64Binary"/>
057 * </simpleType>
058 * </pre></code>
059 *
060 * <p>A <code>Reference</code> instance may be created by invoking one of the
061 * {@link XMLSignatureFactory#newReference newReference} methods of the
062 * {@link XMLSignatureFactory} class; for example:
063 *
064 * <pre>
065 * XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");
066 * Reference ref = factory.newReference
067 * ("http://www.ietf.org/rfc/rfc3275.txt",
068 * factory.newDigestMethod(DigestMethod.SHA1, null));
069 * </pre>
070 *
071 * @author Sean Mullan
072 * @author Erwin van der Koogh
073 * @author JSR 105 Expert Group
074 * @since 1.6
075 * @see XMLSignatureFactory#newReference(String, DigestMethod)
076 * @see XMLSignatureFactory#newReference(String, DigestMethod, List, String, String)
077 */
078 public interface Reference extends URIReference, XMLStructure {
079
080 /**
081 * Returns an {@link java.util.Collections#unmodifiableList unmodifiable
082 * list} of {@link Transform}s that are contained in this
083 * <code>Reference</code>.
084 *
085 * @return an unmodifiable list of <code>Transform</code>s
086 * (may be empty but never <code>null</code>)
087 */
088 List getTransforms();
089
090 /**
091 * Returns the digest method of this <code>Reference</code>.
092 *
093 * @return the digest method
094 */
095 DigestMethod getDigestMethod();
096
097 /**
098 * Returns the optional <code>Id</code> attribute of this
099 * <code>Reference</code>, which permits this reference to be
100 * referenced from elsewhere.
101 *
102 * @return the <code>Id</code> attribute (may be <code>null</code> if not
103 * specified)
104 */
105 String getId();
106
107 /**
108 * Returns the digest value of this <code>Reference</code>.
109 *
110 * @return the raw digest value, or <code>null</code> if this reference has
111 * not been digested yet. Each invocation of this method returns a new
112 * clone to protect against subsequent modification.
113 */
114 byte[] getDigestValue();
115
116 /**
117 * Returns the calculated digest value of this <code>Reference</code>
118 * after a validation operation. This method is useful for debugging if
119 * the reference fails to validate.
120 *
121 * @return the calculated digest value, or <code>null</code> if this
122 * reference has not been validated yet. Each invocation of this method
123 * returns a new clone to protect against subsequent modification.
124 */
125 byte[] getCalculatedDigestValue();
126
127 /**
128 * Validates this reference. This method verifies the digest of this
129 * reference.
130 *
131 * <p>This method only validates the reference the first time it is
132 * invoked. On subsequent invocations, it returns a cached result.
133 *
134 * @return <code>true</code> if this reference was validated successfully;
135 * <code>false</code> otherwise
136 * @param validateContext the validating context
137 * @throws NullPointerException if <code>validateContext</code> is
138 * <code>null</code>
139 * @throws XMLSignatureException if an unexpected exception occurs while
140 * validating the reference
141 */
142 boolean validate(XMLValidateContext validateContext)
143 throws XMLSignatureException;
144
145 /**
146 * Returns the dereferenced data, if
147 * <a href="XMLSignContext.html#Supported Properties">reference caching</a>
148 * is enabled. This is the result of dereferencing the URI of this
149 * reference during a validation or generation operation.
150 *
151 * @return the dereferenced data, or <code>null</code> if reference
152 * caching is not enabled or this reference has not been generated or
153 * validated
154 */
155 Data getDereferencedData();
156
157 /**
158 * Returns the pre-digested input stream, if
159 * <a href="XMLSignContext.html#Supported Properties">reference caching</a>
160 * is enabled. This is the input to the digest operation during a
161 * validation or signing operation.
162 *
163 * @return an input stream containing the pre-digested input, or
164 * <code>null</code> if reference caching is not enabled or this
165 * reference has not been generated or validated
166 */
167 InputStream getDigestInputStream();
168 }
|