001 /*
002 * Copyright 2005-2006 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: XMLSignatureFactory.java,v 1.14 2005/09/15 14:29:01 mullan Exp $
027 */
028 package javax.xml.crypto.dsig;
029
030 import javax.xml.crypto.Data;
031 import javax.xml.crypto.MarshalException;
032 import javax.xml.crypto.NoSuchMechanismException;
033 import javax.xml.crypto.URIDereferencer;
034 import javax.xml.crypto.XMLStructure;
035 import javax.xml.crypto.dom.DOMStructure;
036 import javax.xml.crypto.dsig.keyinfo.KeyInfo;
037 import javax.xml.crypto.dsig.keyinfo.KeyInfoFactory;
038 import javax.xml.crypto.dsig.spec.*;
039 import javax.xml.crypto.dsig.dom.DOMValidateContext;
040 import javax.xml.crypto.dsig.dom.DOMSignContext;
041
042 import java.security.InvalidAlgorithmParameterException;
043 import java.security.NoSuchAlgorithmException;
044 import java.security.NoSuchProviderException;
045 import java.security.Provider;
046 import java.security.Security;
047 import java.util.List;
048
049 import sun.security.jca.*;
050 import sun.security.jca.GetInstance.Instance;
051
052 /**
053 * A factory for creating {@link XMLSignature} objects from scratch or
054 * for unmarshalling an <code>XMLSignature</code> object from a corresponding
055 * XML representation.
056 *
057 * <h2>XMLSignatureFactory Type</h2>
058 *
059 * <p>Each instance of <code>XMLSignatureFactory</code> supports a specific
060 * XML mechanism type. To create an <code>XMLSignatureFactory</code>, call one
061 * of the static {@link #getInstance getInstance} methods, passing in the XML
062 * mechanism type desired, for example:
063 *
064 * <blockquote><code>
065 * XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");
066 * </code></blockquote>
067 *
068 * <p>The objects that this factory produces will be based
069 * on DOM and abide by the DOM interoperability requirements as defined in the
070 * <a href="../../../../../technotes/guides/security/xmldsig/overview.html#DOM Mechanism Requirements">
071 * DOM Mechanism Requirements</a> section of the API overview. See the
072 * <a href="../../../../../technotes/guides/security/xmldsig/overview.html#Service Provider">
073 * Service Providers</a> section of the API overview for a list of standard
074 * mechanism types.
075 *
076 * <p><code>XMLSignatureFactory</code> implementations are registered and loaded
077 * using the {@link java.security.Provider} mechanism.
078 * For example, a service provider that supports the
079 * DOM mechanism would be specified in the <code>Provider</code> subclass as:
080 * <pre>
081 * put("XMLSignatureFactory.DOM", "org.example.DOMXMLSignatureFactory");
082 * </pre>
083 *
084 * <p>An implementation MUST minimally support the default mechanism type: DOM.
085 *
086 * <p>Note that a caller must use the same <code>XMLSignatureFactory</code>
087 * instance to create the <code>XMLStructure</code>s of a particular
088 * <code>XMLSignature</code> that is to be generated. The behavior is
089 * undefined if <code>XMLStructure</code>s from different providers or
090 * different mechanism types are used together.
091 *
092 * <p>Also, the <code>XMLStructure</code>s that are created by this factory
093 * may contain state specific to the <code>XMLSignature</code> and are not
094 * intended to be reusable.
095 *
096 * <h2>Creating XMLSignatures from scratch</h2>
097 *
098 * <p>Once the <code>XMLSignatureFactory</code> has been created, objects
099 * can be instantiated by calling the appropriate method. For example, a
100 * {@link Reference} instance may be created by invoking one of the
101 * {@link #newReference newReference} methods.
102 *
103 * <h2>Unmarshalling XMLSignatures from XML</h2>
104 *
105 * <p>Alternatively, an <code>XMLSignature</code> may be created from an
106 * existing XML representation by invoking the {@link #unmarshalXMLSignature
107 * unmarshalXMLSignature} method and passing it a mechanism-specific
108 * {@link XMLValidateContext} instance containing the XML content:
109 *
110 * <pre>
111 * DOMValidateContext context = new DOMValidateContext(key, signatureElement);
112 * XMLSignature signature = factory.unmarshalXMLSignature(context);
113 * </pre>
114 *
115 * Each <code>XMLSignatureFactory</code> must support the required
116 * <code>XMLValidateContext</code> types for that factory type, but may support
117 * others. A DOM <code>XMLSignatureFactory</code> must support {@link
118 * DOMValidateContext} objects.
119 *
120 * <h2>Signing and marshalling XMLSignatures to XML</h2>
121 *
122 * Each <code>XMLSignature</code> created by the factory can also be
123 * marshalled to an XML representation and signed, by invoking the
124 * {@link XMLSignature#sign sign} method of the
125 * {@link XMLSignature} object and passing it a mechanism-specific
126 * {@link XMLSignContext} object containing the signing key and
127 * marshalling parameters (see {@link DOMSignContext}).
128 * For example:
129 *
130 * <pre>
131 * DOMSignContext context = new DOMSignContext(privateKey, document);
132 * signature.sign(context);
133 * </pre>
134 *
135 * <b>Concurrent Access</b>
136 * <p>The static methods of this class are guaranteed to be thread-safe.
137 * Multiple threads may concurrently invoke the static methods defined in this
138 * class with no ill effects.
139 *
140 * <p>However, this is not true for the non-static methods defined by this
141 * class. Unless otherwise documented by a specific provider, threads that
142 * need to access a single <code>XMLSignatureFactory</code> instance
143 * concurrently should synchronize amongst themselves and provide the
144 * necessary locking. Multiple threads each manipulating a different
145 * <code>XMLSignatureFactory</code> instance need not synchronize.
146 *
147 * @author Sean Mullan
148 * @author JSR 105 Expert Group
149 * @since 1.6
150 */
151 public abstract class XMLSignatureFactory {
152
153 private String mechanismType;
154 private Provider provider;
155
156 /**
157 * Default constructor, for invocation by subclasses.
158 */
159 protected XMLSignatureFactory() {
160 }
161
162 /**
163 * Returns an <code>XMLSignatureFactory</code> that supports the
164 * specified XML processing mechanism and representation type (ex: "DOM").
165 *
166 * <p>This method uses the standard JCA provider lookup mechanism to
167 * locate and instantiate an <code>XMLSignatureFactory</code>
168 * implementation of the desired mechanism type. It traverses the list of
169 * registered security <code>Provider</code>s, starting with the most
170 * preferred <code>Provider</code>. A new <code>XMLSignatureFactory</code>
171 * object from the first <code>Provider</code> that supports the specified
172 * mechanism is returned.
173 *
174 * <p>Note that the list of registered providers may be retrieved via
175 * the {@link Security#getProviders() Security.getProviders()} method.
176 *
177 * @param mechanismType the type of the XML processing mechanism and
178 * representation. See the <a
179 * href="../../../../../technotes/guides/security/xmldsig/overview.html#Service Provider">
180 * Service Providers</a> section of the API overview for a list of
181 * standard mechanism types.
182 * @return a new <code>XMLSignatureFactory</code>
183 * @throws NullPointerException if <code>mechanismType</code> is
184 * <code>null</code>
185 * @throws NoSuchMechanismException if no <code>Provider</code> supports an
186 * <code>XMLSignatureFactory</code> implementation for the specified
187 * mechanism
188 * @see Provider
189 */
190 public static XMLSignatureFactory getInstance(String mechanismType) {
191 if (mechanismType == null) {
192 throw new NullPointerException(
193 "mechanismType cannot be null");
194 }
195 Instance instance;
196 try {
197 instance = GetInstance.getInstance("XMLSignatureFactory",
198 null, mechanismType);
199 } catch (NoSuchAlgorithmException nsae) {
200 throw new NoSuchMechanismException(nsae);
201 }
202 XMLSignatureFactory factory = (XMLSignatureFactory) instance.impl;
203 factory.mechanismType = mechanismType;
204 factory.provider = instance.provider;
205 return factory;
206 }
207
208 /**
209 * Returns an <code>XMLSignatureFactory</code> that supports the
210 * requested XML processing mechanism and representation type (ex: "DOM"),
211 * as supplied by the specified provider. Note that the specified
212 * <code>Provider</code> object does not have to be registered in the
213 * provider list.
214 *
215 * @param mechanismType the type of the XML processing mechanism and
216 * representation. See the <a
217 * href="../../../../../technotes/guides/security/xmldsig/overview.html#Service Provider">
218 * Service Providers</a> section of the API overview for a list of
219 * standard mechanism types.
220 * @param provider the <code>Provider</code> object
221 * @return a new <code>XMLSignatureFactory</code>
222 * @throws NullPointerException if <code>provider</code> or
223 * <code>mechanismType</code> is <code>null</code>
224 * @throws NoSuchMechanismException if an <code>XMLSignatureFactory</code>
225 * implementation for the specified mechanism is not available
226 * from the specified <code>Provider</code> object
227 * @see Provider
228 */
229 public static XMLSignatureFactory getInstance(String mechanismType,
230 Provider provider) {
231 if (mechanismType == null) {
232 throw new NullPointerException(
233 "mechanismType cannot be null");
234 } else if (provider == null) {
235 throw new NullPointerException("provider cannot be null");
236 }
237
238 Instance instance;
239 try {
240 instance = GetInstance.getInstance("XMLSignatureFactory",
241 null, mechanismType, provider);
242 } catch (NoSuchAlgorithmException nsae) {
243 throw new NoSuchMechanismException(nsae);
244 }
245 XMLSignatureFactory factory = (XMLSignatureFactory) instance.impl;
246 factory.mechanismType = mechanismType;
247 factory.provider = instance.provider;
248 return factory;
249 }
250
251 /**
252 * Returns an <code>XMLSignatureFactory</code> that supports the
253 * requested XML processing mechanism and representation type (ex: "DOM"),
254 * as supplied by the specified provider. The specified provider must be
255 * registered in the security provider list.
256 *
257 * <p>Note that the list of registered providers may be retrieved via
258 * the {@link Security#getProviders() Security.getProviders()} method.
259 *
260 * @param mechanismType the type of the XML processing mechanism and
261 * representation. See the <a
262 * href="../../../../../technotes/guides/security/xmldsig/overview.html#Service Provider">
263 * Service Providers</a> section of the API overview for a list of
264 * standard mechanism types.
265 * @param provider the string name of the provider
266 * @return a new <code>XMLSignatureFactory</code>
267 * @throws NoSuchProviderException if the specified provider is not
268 * registered in the security provider list
269 * @throws NullPointerException if <code>provider</code> or
270 * <code>mechanismType</code> is <code>null</code>
271 * @throws NoSuchMechanismException if an <code>XMLSignatureFactory</code>
272 * implementation for the specified mechanism is not
273 * available from the specified provider
274 * @see Provider
275 */
276 public static XMLSignatureFactory getInstance(String mechanismType,
277 String provider) throws NoSuchProviderException {
278 if (mechanismType == null) {
279 throw new NullPointerException(
280 "mechanismType cannot be null");
281 } else if (provider == null) {
282 throw new NullPointerException("provider cannot be null");
283 } else if (provider.length() == 0) {
284 throw new NoSuchProviderException();
285 }
286
287 Instance instance;
288 try {
289 instance = GetInstance.getInstance("XMLSignatureFactory",
290 null, mechanismType, provider);
291 } catch (NoSuchAlgorithmException nsae) {
292 throw new NoSuchMechanismException(nsae);
293 }
294 XMLSignatureFactory factory = (XMLSignatureFactory) instance.impl;
295 factory.mechanismType = mechanismType;
296 factory.provider = instance.provider;
297 return factory;
298 }
299
300 /**
301 * Returns an <code>XMLSignatureFactory</code> that supports the
302 * default XML processing mechanism and representation type ("DOM").
303 *
304 * <p>This method uses the standard JCA provider lookup mechanism to
305 * locate and instantiate an <code>XMLSignatureFactory</code>
306 * implementation of the default mechanism type. It traverses the list of
307 * registered security <code>Provider</code>s, starting with the most
308 * preferred <code>Provider</code>. A new <code>XMLSignatureFactory</code>
309 * object from the first <code>Provider</code> that supports the DOM
310 * mechanism is returned.
311 *
312 * <p>Note that the list of registered providers may be retrieved via
313 * the {@link Security#getProviders() Security.getProviders()} method.
314 *
315 * @return a new <code>XMLSignatureFactory</code>
316 * @throws NoSuchMechanismException if no <code>Provider</code> supports an
317 * <code>XMLSignatureFactory</code> implementation for the DOM
318 * mechanism
319 * @see Provider
320 */
321 public static XMLSignatureFactory getInstance() {
322 return getInstance("DOM");
323 }
324
325 /**
326 * Returns the type of the XML processing mechanism and representation
327 * supported by this <code>XMLSignatureFactory</code> (ex: "DOM").
328 *
329 * @return the XML processing mechanism type supported by this
330 * <code>XMLSignatureFactory</code>
331 */
332 public final String getMechanismType() {
333 return mechanismType;
334 }
335
336 /**
337 * Returns the provider of this <code>XMLSignatureFactory</code>.
338 *
339 * @return the provider of this <code>XMLSignatureFactory</code>
340 */
341 public final Provider getProvider() {
342 return provider;
343 }
344
345 /**
346 * Creates an <code>XMLSignature</code> and initializes it with the contents
347 * of the specified <code>SignedInfo</code> and <code>KeyInfo</code>
348 * objects.
349 *
350 * @param si the signed info
351 * @param ki the key info (may be <code>null</code>)
352 * @return an <code>XMLSignature</code>
353 * @throws NullPointerException if <code>si</code> is <code>null</code>
354 */
355 public abstract XMLSignature newXMLSignature(SignedInfo si,
356 KeyInfo ki);
357
358 /**
359 * Creates an <code>XMLSignature</code> and initializes it with the
360 * specified parameters.
361 *
362 * @param si the signed info
363 * @param ki the key info (may be <code>null</code>)
364 * @param objects a list of {@link XMLObject}s (may be empty or
365 * <code>null</code>)
366 * @param id the Id (may be <code>null</code>)
367 * @param signatureValueId the SignatureValue Id (may be <code>null</code>)
368 * @return an <code>XMLSignature</code>
369 * @throws NullPointerException if <code>si</code> is <code>null</code>
370 * @throws ClassCastException if any of the <code>objects</code> are not of
371 * type <code>XMLObject</code>
372 */
373 public abstract XMLSignature newXMLSignature(SignedInfo si,
374 KeyInfo ki, List objects, String id, String signatureValueId);
375
376 /**
377 * Creates a <code>Reference</code> with the specified URI and digest
378 * method.
379 *
380 * @param uri the reference URI (may be <code>null</code>)
381 * @param dm the digest method
382 * @return a <code>Reference</code>
383 * @throws IllegalArgumentException if <code>uri</code> is not RFC 2396
384 * compliant
385 * @throws NullPointerException if <code>dm</code> is <code>null</code>
386 */
387 public abstract Reference newReference(String uri, DigestMethod dm);
388
389 /**
390 * Creates a <code>Reference</code> with the specified parameters.
391 *
392 * @param uri the reference URI (may be <code>null</code>)
393 * @param dm the digest method
394 * @param transforms a list of {@link Transform}s. The list is defensively
395 * copied to protect against subsequent modification. May be
396 * <code>null</code> or empty.
397 * @param type the reference type, as a URI (may be <code>null</code>)
398 * @param id the reference ID (may be <code>null</code>)
399 * @return a <code>Reference</code>
400 * @throws ClassCastException if any of the <code>transforms</code> are
401 * not of type <code>Transform</code>
402 * @throws IllegalArgumentException if <code>uri</code> is not RFC 2396
403 * compliant
404 * @throws NullPointerException if <code>dm</code> is <code>null</code>
405 */
406 public abstract Reference newReference(String uri, DigestMethod dm,
407 List transforms, String type, String id);
408
409 /**
410 * Creates a <code>Reference</code> with the specified parameters and
411 * pre-calculated digest value.
412 *
413 * <p>This method is useful when the digest value of a
414 * <code>Reference</code> has been previously computed. See for example,
415 * the
416 * <a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dss">
417 * OASIS-DSS (Digital Signature Services)</a> specification.
418 *
419 * @param uri the reference URI (may be <code>null</code>)
420 * @param dm the digest method
421 * @param transforms a list of {@link Transform}s. The list is defensively
422 * copied to protect against subsequent modification. May be
423 * <code>null</code> or empty.
424 * @param type the reference type, as a URI (may be <code>null</code>)
425 * @param id the reference ID (may be <code>null</code>)
426 * @param digestValue the digest value. The array is cloned to protect
427 * against subsequent modification.
428 * @return a <code>Reference</code>
429 * @throws ClassCastException if any of the <code>transforms</code> are
430 * not of type <code>Transform</code>
431 * @throws IllegalArgumentException if <code>uri</code> is not RFC 2396
432 * compliant
433 * @throws NullPointerException if <code>dm</code> or
434 * <code>digestValue</code> is <code>null</code>
435 */
436 public abstract Reference newReference(String uri, DigestMethod dm,
437 List transforms, String type, String id, byte[] digestValue);
438
439 /**
440 * Creates a <code>Reference</code> with the specified parameters.
441 *
442 * <p>This method is useful when a list of transforms have already been
443 * applied to the <code>Reference</code>. See for example,
444 * the
445 * <a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dss">
446 * OASIS-DSS (Digital Signature Services)</a> specification.
447 *
448 * <p>When an <code>XMLSignature</code> containing this reference is
449 * generated, the specified <code>transforms</code> (if non-null) are
450 * applied to the specified <code>result</code>. The
451 * <code>Transforms</code> element of the resulting <code>Reference</code>
452 * element is set to the concatenation of the
453 * <code>appliedTransforms</code> and <code>transforms</code>.
454 *
455 * @param uri the reference URI (may be <code>null</code>)
456 * @param dm the digest method
457 * @param appliedTransforms a list of {@link Transform}s that have
458 * already been applied. The list is defensively
459 * copied to protect against subsequent modification. The list must
460 * contain at least one entry.
461 * @param result the result of processing the sequence of
462 * <code>appliedTransforms</code>
463 * @param transforms a list of {@link Transform}s that are to be applied
464 * when generating the signature. The list is defensively copied to
465 * protect against subsequent modification. May be <code>null</code>
466 * or empty.
467 * @param type the reference type, as a URI (may be <code>null</code>)
468 * @param id the reference ID (may be <code>null</code>)
469 * @return a <code>Reference</code>
470 * @throws ClassCastException if any of the transforms (in either list)
471 * are not of type <code>Transform</code>
472 * @throws IllegalArgumentException if <code>uri</code> is not RFC 2396
473 * compliant or <code>appliedTransforms</code> is empty
474 * @throws NullPointerException if <code>dm</code>,
475 * <code>appliedTransforms</code> or <code>result</code> is
476 * <code>null</code>
477 */
478 public abstract Reference newReference(String uri, DigestMethod dm,
479 List appliedTransforms, Data result, List transforms,
480 String type, String id);
481
482 /**
483 * Creates a <code>SignedInfo</code> with the specified canonicalization
484 * and signature methods, and list of one or more references.
485 *
486 * @param cm the canonicalization method
487 * @param sm the signature method
488 * @param references a list of one or more {@link Reference}s. The list is
489 * defensively copied to protect against subsequent modification.
490 * @return a <code>SignedInfo</code>
491 * @throws ClassCastException if any of the references are not of
492 * type <code>Reference</code>
493 * @throws IllegalArgumentException if <code>references</code> is empty
494 * @throws NullPointerException if any of the parameters
495 * are <code>null</code>
496 */
497 public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
498 SignatureMethod sm, List references);
499
500 /**
501 * Creates a <code>SignedInfo</code> with the specified parameters.
502 *
503 * @param cm the canonicalization method
504 * @param sm the signature method
505 * @param references a list of one or more {@link Reference}s. The list is
506 * defensively copied to protect against subsequent modification.
507 * @param id the id (may be <code>null</code>)
508 * @return a <code>SignedInfo</code>
509 * @throws ClassCastException if any of the references are not of
510 * type <code>Reference</code>
511 * @throws IllegalArgumentException if <code>references</code> is empty
512 * @throws NullPointerException if <code>cm</code>, <code>sm</code>, or
513 * <code>references</code> are <code>null</code>
514 */
515 public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
516 SignatureMethod sm, List references, String id);
517
518 // Object factory methods
519 /**
520 * Creates an <code>XMLObject</code> from the specified parameters.
521 *
522 * @param content a list of {@link XMLStructure}s. The list
523 * is defensively copied to protect against subsequent modification.
524 * May be <code>null</code> or empty.
525 * @param id the Id (may be <code>null</code>)
526 * @param mimeType the mime type (may be <code>null</code>)
527 * @param encoding the encoding (may be <code>null</code>)
528 * @return an <code>XMLObject</code>
529 * @throws ClassCastException if <code>content</code> contains any
530 * entries that are not of type {@link XMLStructure}
531 */
532 public abstract XMLObject newXMLObject(List content, String id,
533 String mimeType, String encoding);
534
535 /**
536 * Creates a <code>Manifest</code> containing the specified
537 * list of {@link Reference}s.
538 *
539 * @param references a list of one or more <code>Reference</code>s. The list
540 * is defensively copied to protect against subsequent modification.
541 * @return a <code>Manifest</code>
542 * @throws NullPointerException if <code>references</code> is
543 * <code>null</code>
544 * @throws IllegalArgumentException if <code>references</code> is empty
545 * @throws ClassCastException if <code>references</code> contains any
546 * entries that are not of type {@link Reference}
547 */
548 public abstract Manifest newManifest(List references);
549
550 /**
551 * Creates a <code>Manifest</code> containing the specified
552 * list of {@link Reference}s and optional id.
553 *
554 * @param references a list of one or more <code>Reference</code>s. The list
555 * is defensively copied to protect against subsequent modification.
556 * @param id the id (may be <code>null</code>)
557 * @return a <code>Manifest</code>
558 * @throws NullPointerException if <code>references</code> is
559 * <code>null</code>
560 * @throws IllegalArgumentException if <code>references</code> is empty
561 * @throws ClassCastException if <code>references</code> contains any
562 * entries that are not of type {@link Reference}
563 */
564 public abstract Manifest newManifest(List references, String id);
565
566 /**
567 * Creates a <code>SignatureProperty</code> containing the specified
568 * list of {@link XMLStructure}s, target URI and optional id.
569 *
570 * @param content a list of one or more <code>XMLStructure</code>s. The list
571 * is defensively copied to protect against subsequent modification.
572 * @param target the target URI of the Signature that this property applies
573 * to
574 * @param id the id (may be <code>null</code>)
575 * @return a <code>SignatureProperty</code>
576 * @throws NullPointerException if <code>content</code> or
577 * <code>target</code> is <code>null</code>
578 * @throws IllegalArgumentException if <code>content</code> is empty
579 * @throws ClassCastException if <code>content</code> contains any
580 * entries that are not of type {@link XMLStructure}
581 */
582 public abstract SignatureProperty newSignatureProperty(
583 List content, String target, String id);
584
585 /**
586 * Creates a <code>SignatureProperties</code> containing the specified
587 * list of {@link SignatureProperty}s and optional id.
588 *
589 * @param properties a list of one or more <code>SignatureProperty</code>s.
590 * The list is defensively copied to protect against subsequent
591 * modification.
592 * @param id the id (may be <code>null</code>)
593 * @return a <code>SignatureProperties</code>
594 * @throws NullPointerException if <code>properties</code>
595 * is <code>null</code>
596 * @throws IllegalArgumentException if <code>properties</code> is empty
597 * @throws ClassCastException if <code>properties</code> contains any
598 * entries that are not of type {@link SignatureProperty}
599 */
600 public abstract SignatureProperties newSignatureProperties(
601 List properties, String id);
602
603 // Algorithm factory methods
604 /**
605 * Creates a <code>DigestMethod</code> for the specified algorithm URI
606 * and parameters.
607 *
608 * @param algorithm the URI identifying the digest algorithm
609 * @param params algorithm-specific digest parameters (may be
610 * <code>null</code>)
611 * @return the <code>DigestMethod</code>
612 * @throws InvalidAlgorithmParameterException if the specified parameters
613 * are inappropriate for the requested algorithm
614 * @throws NoSuchAlgorithmException if an implementation of the
615 * specified algorithm cannot be found
616 * @throws NullPointerException if <code>algorithm</code> is
617 * <code>null</code>
618 */
619 public abstract DigestMethod newDigestMethod(String algorithm,
620 DigestMethodParameterSpec params)
621 throws NoSuchAlgorithmException,
622 InvalidAlgorithmParameterException;
623
624 /**
625 * Creates a <code>SignatureMethod</code> for the specified algorithm URI
626 * and parameters.
627 *
628 * @param algorithm the URI identifying the signature algorithm
629 * @param params algorithm-specific signature parameters (may be
630 * <code>null</code>)
631 * @return the <code>SignatureMethod</code>
632 * @throws InvalidAlgorithmParameterException if the specified parameters
633 * are inappropriate for the requested algorithm
634 * @throws NoSuchAlgorithmException if an implementation of the
635 * specified algorithm cannot be found
636 * @throws NullPointerException if <code>algorithm</code> is
637 * <code>null</code>
638 */
639 public abstract SignatureMethod newSignatureMethod(
640 String algorithm, SignatureMethodParameterSpec params)
641 throws NoSuchAlgorithmException,
642 InvalidAlgorithmParameterException;
643
644 /**
645 * Creates a <code>Transform</code> for the specified algorithm URI
646 * and parameters.
647 *
648 * @param algorithm the URI identifying the transform algorithm
649 * @param params algorithm-specific transform parameters (may be
650 * <code>null</code>)
651 * @return the <code>Transform</code>
652 * @throws InvalidAlgorithmParameterException if the specified parameters
653 * are inappropriate for the requested algorithm
654 * @throws NoSuchAlgorithmException if an implementation of the
655 * specified algorithm cannot be found
656 * @throws NullPointerException if <code>algorithm</code> is
657 * <code>null</code>
658 */
659 public abstract Transform newTransform(String algorithm,
660 TransformParameterSpec params)
661 throws NoSuchAlgorithmException,
662 InvalidAlgorithmParameterException;
663
664 /**
665 * Creates a <code>Transform</code> for the specified algorithm URI
666 * and parameters. The parameters are specified as a mechanism-specific
667 * <code>XMLStructure</code> (ex: {@link DOMStructure}). This method is
668 * useful when the parameters are in XML form or there is no standard
669 * class for specifying the parameters.
670 *
671 * @param algorithm the URI identifying the transform algorithm
672 * @param params a mechanism-specific XML structure from which to
673 * unmarshal the parameters from (may be <code>null</code> if
674 * not required or optional)
675 * @return the <code>Transform</code>
676 * @throws ClassCastException if the type of <code>params</code> is
677 * inappropriate for this <code>XMLSignatureFactory</code>
678 * @throws InvalidAlgorithmParameterException if the specified parameters
679 * are inappropriate for the requested algorithm
680 * @throws NoSuchAlgorithmException if an implementation of the
681 * specified algorithm cannot be found
682 * @throws NullPointerException if <code>algorithm</code> is
683 * <code>null</code>
684 */
685 public abstract Transform newTransform(String algorithm,
686 XMLStructure params) throws NoSuchAlgorithmException,
687 InvalidAlgorithmParameterException;
688
689 /**
690 * Creates a <code>CanonicalizationMethod</code> for the specified
691 * algorithm URI and parameters.
692 *
693 * @param algorithm the URI identifying the canonicalization algorithm
694 * @param params algorithm-specific canonicalization parameters (may be
695 * <code>null</code>)
696 * @return the <code>CanonicalizationMethod</code>
697 * @throws InvalidAlgorithmParameterException if the specified parameters
698 * are inappropriate for the requested algorithm
699 * @throws NoSuchAlgorithmException if an implementation of the
700 * specified algorithm cannot be found
701 * @throws NullPointerException if <code>algorithm</code> is
702 * <code>null</code>
703 */
704 public abstract CanonicalizationMethod newCanonicalizationMethod(
705 String algorithm, C14NMethodParameterSpec params)
706 throws NoSuchAlgorithmException,
707 InvalidAlgorithmParameterException;
708
709 /**
710 * Creates a <code>CanonicalizationMethod</code> for the specified
711 * algorithm URI and parameters. The parameters are specified as a
712 * mechanism-specific <code>XMLStructure</code> (ex: {@link DOMStructure}).
713 * This method is useful when the parameters are in XML form or there is
714 * no standard class for specifying the parameters.
715 *
716 * @param algorithm the URI identifying the canonicalization algorithm
717 * @param params a mechanism-specific XML structure from which to
718 * unmarshal the parameters from (may be <code>null</code> if
719 * not required or optional)
720 * @return the <code>CanonicalizationMethod</code>
721 * @throws ClassCastException if the type of <code>params</code> is
722 * inappropriate for this <code>XMLSignatureFactory</code>
723 * @throws InvalidAlgorithmParameterException if the specified parameters
724 * are inappropriate for the requested algorithm
725 * @throws NoSuchAlgorithmException if an implementation of the
726 * specified algorithm cannot be found
727 * @throws NullPointerException if <code>algorithm</code> is
728 * <code>null</code>
729 */
730 public abstract CanonicalizationMethod newCanonicalizationMethod(
731 String algorithm, XMLStructure params)
732 throws NoSuchAlgorithmException,
733 InvalidAlgorithmParameterException;
734
735 /**
736 * Returns a <code>KeyInfoFactory</code> that creates <code>KeyInfo</code>
737 * objects. The returned <code>KeyInfoFactory</code> has the same
738 * mechanism type and provider as this <code>XMLSignatureFactory</code>.
739 *
740 * @return a <code>KeyInfoFactory</code>
741 * @throws NoSuchMechanismException if a <code>KeyFactory</code>
742 * implementation with the same mechanism type and provider
743 * is not available
744 */
745 public final KeyInfoFactory getKeyInfoFactory() {
746 return KeyInfoFactory.getInstance(getMechanismType(),
747 getProvider());
748 }
749
750 /**
751 * Unmarshals a new <code>XMLSignature</code> instance from a
752 * mechanism-specific <code>XMLValidateContext</code> instance.
753 *
754 * @param context a mechanism-specific context from which to unmarshal the
755 * signature from
756 * @return the <code>XMLSignature</code>
757 * @throws NullPointerException if <code>context</code> is
758 * <code>null</code>
759 * @throws ClassCastException if the type of <code>context</code> is
760 * inappropriate for this factory
761 * @throws MarshalException if an unrecoverable exception occurs
762 * during unmarshalling
763 */
764 public abstract XMLSignature unmarshalXMLSignature(
765 XMLValidateContext context) throws MarshalException;
766
767 /**
768 * Unmarshals a new <code>XMLSignature</code> instance from a
769 * mechanism-specific <code>XMLStructure</code> instance.
770 * This method is useful if you only want to unmarshal (and not
771 * validate) an <code>XMLSignature</code>.
772 *
773 * @param xmlStructure a mechanism-specific XML structure from which to
774 * unmarshal the signature from
775 * @return the <code>XMLSignature</code>
776 * @throws NullPointerException if <code>xmlStructure</code> is
777 * <code>null</code>
778 * @throws ClassCastException if the type of <code>xmlStructure</code> is
779 * inappropriate for this factory
780 * @throws MarshalException if an unrecoverable exception occurs
781 * during unmarshalling
782 */
783 public abstract XMLSignature unmarshalXMLSignature(
784 XMLStructure xmlStructure) throws MarshalException;
785
786 /**
787 * Indicates whether a specified feature is supported.
788 *
789 * @param feature the feature name (as an absolute URI)
790 * @return <code>true</code> if the specified feature is supported,
791 * <code>false</code> otherwise
792 * @throws NullPointerException if <code>feature</code> is <code>null</code>
793 */
794 public abstract boolean isFeatureSupported(String feature);
795
796 /**
797 * Returns a reference to the <code>URIDereferencer</code> that is used by
798 * default to dereference URIs in {@link Reference} objects.
799 *
800 * @return a reference to the default <code>URIDereferencer</code> (never
801 * <code>null</code>)
802 */
803 public abstract URIDereferencer getURIDereferencer();
804 }
|