1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
/* * Copyright 2006 Sun Microsystems, Inc. All rights reserved. */ /* * $Id: Reference.java,v 1.9 2005/05/10 16:03:46 mullan Exp $ */ 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 <code>Reference</code> element as defined in the * <a href="http://www.w3.org/TR/xmldsig-core/"> * W3C Recommendation for XML-Signature Syntax and Processing</a>. * The XML schema is defined as: * <code><pre> * <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> * </pre></code> * * <p>A <code>Reference</code> instance may be created by invoking one of the * {@link XMLSignatureFactory#newReference newReference} methods of the * {@link XMLSignatureFactory} class; for example: * * <pre> * XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM"); * Reference ref = factory.newReference * ("http://www.ietf.org/rfc/rfc3275.txt", * factory.newDigestMethod(DigestMethod.SHA1, null)); * </pre> * * @author Sean Mullan * @author Erwin van der Koogh * @author JSR 105 Expert Group * @since 1.6 * @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 * <code>Reference</code>. * * @return an unmodifiable list of <code>Transform</code>s * (may be empty but never <code>null</code>) */ List getTransforms(); /** * Returns the digest method of this <code>Reference</code>. * * @return the digest method */ DigestMethod getDigestMethod(); /** * Returns the optional <code>Id</code> attribute of this * <code>Reference</code>, which permits this reference to be * referenced from elsewhere. * * @return the <code>Id</code> attribute (may be <code>null</code> if not * specified) */ String getId(); /** * Returns the digest value of this <code>Reference</code>. * * @return the raw digest value, or <code>null</code> 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 <code>Reference</code> * after a validation operation. This method is useful for debugging if * the reference fails to validate. * * @return the calculated digest value, or <code>null</code> 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. * * <p>This method only validates the reference the first time it is * invoked. On subsequent invocations, it returns a cached result. * * @return <code>true</code> if this reference was validated successfully; * <code>false</code> otherwise * @param validateContext the validating context * @throws NullPointerException if <code>validateContext</code> is * <code>null</code> * @throws XMLSignatureException if an unexpected exception occurs while * validating the reference */ boolean validate(XMLValidateContext validateContext) throws XMLSignatureException; /** * Returns the dereferenced data, if * <a href="XMLSignContext.html#Supported Properties">reference caching</a> * is enabled. This is the result of dereferencing the URI of this * reference during a validation or generation operation. * * @return the dereferenced data, or <code>null</code> if reference * caching is not enabled or this reference has not been generated or * validated */ Data getDereferencedData(); /** * Returns the pre-digested input stream, if * <a href="XMLSignContext.html#Supported Properties">reference caching</a> * 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 * <code>null</code> if reference caching is not enabled or this * reference has not been generated or validated */ InputStream getDigestInputStream(); }