1 /** 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 /* 20 * Portions copyright 2005 Sun Microsystems, Inc. All rights reserved. 21 */ 22 /* 23 * =========================================================================== 24 * 25 * (C) Copyright IBM Corp. 2003 All Rights Reserved. 26 * 27 * =========================================================================== 28 */ 29 /* 30 * $Id: XMLSignature.java 1333869 2012-05-04 10:42:44Z coheigea $ 31 */ 32 package javax.xml.crypto.dsig; 33 34 import javax.xml.crypto.KeySelector; 35 import javax.xml.crypto.KeySelectorResult; 36 import javax.xml.crypto.MarshalException; 37 import javax.xml.crypto.XMLStructure; 38 import javax.xml.crypto.dsig.keyinfo.KeyInfo; 39 import java.security.Signature; 40 import java.util.List; 41 42 /** 43 * A representation of the XML <code>Signature</code> element as 44 * defined in the <a href="http://www.w3.org/TR/xmldsig-core/"> 45 * W3C Recommendation for XML-Signature Syntax and Processing</a>. 46 * This class contains methods for signing and validating XML signatures 47 * with behavior as defined by the W3C specification. The XML Schema Definition 48 * is defined as: 49 * <pre><code> 50 * <element name="Signature" type="ds:SignatureType"/> 51 * <complexType name="SignatureType"> 52 * <sequence> 53 * <element ref="ds:SignedInfo"/> 54 * <element ref="ds:SignatureValue"/> 55 * <element ref="ds:KeyInfo" minOccurs="0"/> 56 * <element ref="ds:Object" minOccurs="0" maxOccurs="unbounded"/> 57 * </sequence> 58 * <attribute name="Id" type="ID" use="optional"/> 59 * </complexType> 60 * </code></pre> 61 * <p> 62 * An <code>XMLSignature</code> instance may be created by invoking one of the 63 * {@link XMLSignatureFactory#newXMLSignature newXMLSignature} methods of the 64 * {@link XMLSignatureFactory} class. 65 * 66 * <p>If the contents of the underlying document containing the 67 * <code>XMLSignature</code> are subsequently modified, the behavior is 68 * undefined. 69 * 70 * <p>Note that this class is named <code>XMLSignature</code> rather than 71 * <code>Signature</code> to avoid naming clashes with the existing 72 * {@link Signature java.security.Signature} class. 73 * 74 * @see XMLSignatureFactory#newXMLSignature(SignedInfo, KeyInfo) 75 * @see XMLSignatureFactory#newXMLSignature(SignedInfo, KeyInfo, List, String, String) 76 * @author Joyce L. Leung 77 * @author Sean Mullan 78 * @author Erwin van der Koogh 79 * @author JSR 105 Expert Group 80 */ 81 public interface XMLSignature extends XMLStructure { 82 83 /** 84 * The XML Namespace URI of the W3C Recommendation for XML-Signature 85 * Syntax and Processing. 86 */ 87 String XMLNS = "http://www.w3.org/2000/09/xmldsig#"; 88 89 /** 90 * Validates the signature according to the 91 * <a href="http://www.w3.org/TR/xmldsig-core/#sec-CoreValidation"> 92 * core validation processing rules</a>. This method validates the 93 * signature using the existing state, it does not unmarshal and 94 * reinitialize the contents of the <code>XMLSignature</code> using the 95 * location information specified in the context. 96 * 97 * <p>This method only validates the signature the first time it is 98 * invoked. On subsequent invocations, it returns a cached result. 99 * 100 * @param validateContext the validating context 101 * @return <code>true</code> if the signature passed core validation, 102 * otherwise <code>false</code> 103 * @throws ClassCastException if the type of <code>validateContext</code> 104 * is not compatible with this <code>XMLSignature</code> 105 * @throws NullPointerException if <code>validateContext</code> is 106 * <code>null</code> 107 * @throws XMLSignatureException if an unexpected error occurs during 108 * validation that prevented the validation operation from completing 109 */ validate(XMLValidateContext validateContext)110 boolean validate(XMLValidateContext validateContext) 111 throws XMLSignatureException; 112 113 /** 114 * Returns the key info of this <code>XMLSignature</code>. 115 * 116 * @return the key info (may be <code>null</code> if not specified) 117 */ getKeyInfo()118 KeyInfo getKeyInfo(); 119 120 /** 121 * Returns the signed info of this <code>XMLSignature</code>. 122 * 123 * @return the signed info (never <code>null</code>) 124 */ getSignedInfo()125 SignedInfo getSignedInfo(); 126 127 /** 128 * Returns an {@link java.util.Collections#unmodifiableList unmodifiable 129 * list} of {@link XMLObject}s contained in this <code>XMLSignature</code>. 130 * 131 * @return an unmodifiable list of <code>XMLObject</code>s (may be empty 132 * but never <code>null</code>) 133 */ getObjects()134 List getObjects(); 135 136 /** 137 * Returns the optional Id of this <code>XMLSignature</code>. 138 * 139 * @return the Id (may be <code>null</code> if not specified) 140 */ getId()141 String getId(); 142 143 /** 144 * Returns the signature value of this <code>XMLSignature</code>. 145 * 146 * @return the signature value 147 */ getSignatureValue()148 SignatureValue getSignatureValue(); 149 150 /** 151 * Signs this <code>XMLSignature</code>. 152 * 153 * <p>If this method throws an exception, this <code>XMLSignature</code> and 154 * the <code>signContext</code> parameter will be left in the state that 155 * it was in prior to the invocation. 156 * 157 * @param signContext the signing context 158 * @throws ClassCastException if the type of <code>signContext</code> is 159 * not compatible with this <code>XMLSignature</code> 160 * @throws NullPointerException if <code>signContext</code> is 161 * <code>null</code> 162 * @throws MarshalException if an exception occurs while marshalling 163 * @throws XMLSignatureException if an unexpected exception occurs while 164 * generating the signature 165 */ sign(XMLSignContext signContext)166 void sign(XMLSignContext signContext) throws MarshalException, 167 XMLSignatureException; 168 169 /** 170 * Returns the result of the {@link KeySelector}, if specified, after 171 * this <code>XMLSignature</code> has been signed or validated. 172 * 173 * @return the key selector result, or <code>null</code> if a key 174 * selector has not been specified or this <code>XMLSignature</code> 175 * has not been signed or validated 176 */ getKeySelectorResult()177 KeySelectorResult getKeySelectorResult(); 178 179 /** 180 * A representation of the XML <code>SignatureValue</code> element as 181 * defined in the <a href="http://www.w3.org/TR/xmldsig-core/"> 182 * W3C Recommendation for XML-Signature Syntax and Processing</a>. 183 * The XML Schema Definition is defined as: 184 * <p> 185 * <pre> 186 * <element name="SignatureValue" type="ds:SignatureValueType"/> 187 * <complexType name="SignatureValueType"> 188 * <simpleContent> 189 * <extension base="base64Binary"> 190 * <attribute name="Id" type="ID" use="optional"/> 191 * </extension> 192 * </simpleContent> 193 * </complexType> 194 * </pre> 195 * 196 * @author Sean Mullan 197 * @author JSR 105 Expert Group 198 */ 199 public interface SignatureValue extends XMLStructure { 200 /** 201 * Returns the optional <code>Id</code> attribute of this 202 * <code>SignatureValue</code>, which permits this element to be 203 * referenced from elsewhere. 204 * 205 * @return the <code>Id</code> attribute (may be <code>null</code> if 206 * not specified) 207 */ getId()208 String getId(); 209 210 /** 211 * Returns the signature value of this <code>SignatureValue</code>. 212 * 213 * @return the signature value (may be <code>null</code> if the 214 * <code>XMLSignature</code> has not been signed yet). Each 215 * invocation of this method returns a new clone of the array to 216 * prevent subsequent modification. 217 */ getValue()218 byte[] getValue(); 219 220 /** 221 * Validates the signature value. This method performs a 222 * cryptographic validation of the signature calculated over the 223 * <code>SignedInfo</code> of the <code>XMLSignature</code>. 224 * 225 * <p>This method only validates the signature the first 226 * time it is invoked. On subsequent invocations, it returns a cached 227 * result. 228 * 229 * @return <code>true</code> if the signature was 230 * validated successfully; <code>false</code> otherwise 231 * @param validateContext the validating context 232 * @throws NullPointerException if <code>validateContext</code> is 233 * <code>null</code> 234 * @throws XMLSignatureException if an unexpected exception occurs while 235 * validating the signature 236 */ validate(XMLValidateContext validateContext)237 boolean validate(XMLValidateContext validateContext) 238 throws XMLSignatureException; 239 } 240 } 241