KeyInfoFactory


1   /*
2    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
3    */
4   /*
5    * $Id: KeyInfoFactory.java,v 1.12 2005/05/10 16:35:35 mullan Exp $
6    */
7   package javax.xml.crypto.dsig.keyinfo;
8   
9   import java.math.BigInteger  ;
10  import java.security.KeyException  ;
11  import java.security.NoSuchAlgorithmException  ;
12  import java.security.NoSuchProviderException  ;
13  import java.security.Provider  ;
14  import java.security.PublicKey  ;
15  import java.security.Security  ;
16  import java.security.cert.X509CRL  ;
17  import java.util.List  ;
18  import javax.xml.crypto.MarshalException;
19  import javax.xml.crypto.NoSuchMechanismException;
20  import javax.xml.crypto.URIDereferencer;
21  import javax.xml.crypto.XMLStructure;
22  import javax.xml.crypto.dom.DOMStructure;
23  import javax.xml.crypto.dsig.*;
24  
25  import sun.security.jca.*;
26  import sun.security.jca.GetInstance.Instance;
27  
28  /**
29   * A factory for creating {@link KeyInfo} objects from scratch or for
30   * unmarshalling a <code>KeyInfo</code> object from a corresponding XML 
31   * representation.
32   *
33   * <p>Each instance of <code>KeyInfoFactory</code> supports a specific
34   * XML mechanism type. To create a <code>KeyInfoFactory</code>, call one of the
35   * static {@link #getInstance getInstance} methods, passing in the XML 
36   * mechanism type desired, for example:
37   *
38   * <blockquote><code>
39   *   KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");
40   * </code></blockquote>
41   *
42   * <p>The objects that this factory produces will be based
43   * on DOM and abide by the DOM interoperability requirements as defined in the
44   * <a HREF="../../../../../../technotes/guides/security/xmldsig/overview.html#DOM Mechanism Requirements">
45   * DOM Mechanism Requirements</a> section of the API overview. See the
46   * <a HREF="../../../../../../technotes/guides/security/xmldsig/overview.html#Service Provider">
47   * Service Providers</a> section of the API overview for a list of standard 
48   * mechanism types.
49   *
50   * <p><code>KeyInfoFactory</code> implementations are registered and loaded
51   * using the {@link java.security.Provider} mechanism.
52   * For example, a service provider that supports the
53   * DOM mechanism would be specified in the <code>Provider</code> subclass as:
54   * <pre>
55   *     put("KeyInfoFactory.DOM", "org.example.DOMKeyInfoFactory");
56   * </pre>
57   *
58   * <p>Also, the <code>XMLStructure</code>s that are created by this factory
59   * may contain state specific to the <code>KeyInfo</code> and are not
60   * intended to be reusable.
61   *
62   * <p>An implementation MUST minimally support the default mechanism type: DOM.
63   *
64   * <p>Note that a caller must use the same <code>KeyInfoFactory</code>
65   * instance to create the <code>XMLStructure</code>s of a particular
66   * <code>KeyInfo</code> object. The behavior is undefined if 
67   * <code>XMLStructure</code>s from different providers or different mechanism 
68   * types are used together.
69   *
70   * <p><b>Concurrent Access</b>
71   * <p>The static methods of this class are guaranteed to be thread-safe. 
72   * Multiple threads may concurrently invoke the static methods defined in this 
73   * class with no ill effects.
74   *
75   * <p>However, this is not true for the non-static methods defined by this 
76   * class. Unless otherwise documented by a specific provider, threads that 
77   * need to access a single <code>KeyInfoFactory</code> instance concurrently 
78   * should synchronize amongst themselves and provide the necessary locking. 
79   * Multiple threads each manipulating a different <code>KeyInfoFactory</code> 
80   * instance need not synchronize.
81   *
82   * @author Sean Mullan
83   * @author JSR 105 Expert Group
84   * @since 1.6
85   */
86  public abstract class KeyInfoFactory {
87  
88      private String   mechanismType;
89      private Provider   provider;
90  
91      /**
92       * Default constructor, for invocation by subclasses.
93       */
94      protected KeyInfoFactory() {}
95  
96      /**
97       * Returns a <code>KeyInfoFactory</code> that supports the
98       * specified XML processing mechanism and representation type (ex: "DOM").
99       *
100      * <p>This method uses the standard JCA provider lookup mechanism to 
101      * locate and instantiate a <code>KeyInfoFactory</code> implementation of 
102      * the desired mechanism type. It traverses the list of registered security 
103      * <code>Provider</code>s, starting with the most preferred 
104      * <code>Provider</code>. A new <code>KeyInfoFactory</code> object 
105      * from the first <code>Provider</code> that supports the specified 
106      * mechanism is returned. 
107      * 
108      * <p> Note that the list of registered providers may be retrieved via 
109      * the {@link Security#getProviders() Security.getProviders()} method. 
110      *
111      * @param mechanismType the type of the XML processing mechanism and
112      *    representation. See the <a 
113      *    HREF="../../../../../../technotes/guides/security/xmldsig/overview.html#Service Provider">
114      *    Service Providers</a> section of the API overview for a list of 
115      *    standard mechanism types.
116      * @return a new <code>KeyInfoFactory</code>
117      * @throws NullPointerException if <code>mechanismType</code> is
118      *    <code>null</code>
119      * @throws NoSuchMechanismException if no <code>Provider</code> supports a
120      *    <code>KeyInfoFactory</code> implementation for the specified mechanism
121      * @see Provider
122      */
123     public static KeyInfoFactory getInstance(String   mechanismType) {
124     if (mechanismType == null) {
125             throw new NullPointerException  ("mechanismType cannot be null");
126     }
127         Instance instance;
128         try {
129             instance = GetInstance.getInstance
130                 ("KeyInfoFactory", null, mechanismType);
131         } catch (NoSuchAlgorithmException   nsae) {
132             throw new NoSuchMechanismException(nsae);
133         }
134         KeyInfoFactory factory = (KeyInfoFactory) instance.impl;
135         factory.mechanismType = mechanismType;
136         factory.provider = instance.provider;
137         return factory;
138     }
139 
140     /**
141      * Returns a <code>KeyInfoFactory</code> that supports the
142      * requested XML processing mechanism and representation type (ex: "DOM"),
143      * as supplied by the specified provider. Note that the specified 
144      * <code>Provider</code> object does not have to be registered in the 
145      * provider list. 
146      *
147      * @param mechanismType the type of the XML processing mechanism and
148      *    representation. See the <a 
149      *    HREF="../../../../../../technotes/guides/security/xmldsig/overview.html#Service Provider">
150      *    Service Providers</a> section of the API overview for a list of 
151      *    standard mechanism types.
152      * @param provider the <code>Provider</code> object
153      * @return a new <code>KeyInfoFactory</code>
154      * @throws NullPointerException if <code>mechanismType</code> or
155      *    <code>provider</code> are <code>null</code>
156      * @throws NoSuchMechanismException if a <code>KeyInfoFactory</code> 
157      *    implementation for the specified mechanism is not available from the 
158      *    specified <code>Provider</code> object
159      * @see Provider
160      */
161     public static KeyInfoFactory getInstance(String   mechanismType,
162     Provider   provider) {
163     if (mechanismType == null) {
164             throw new NullPointerException  ("mechanismType cannot be null");
165     } else if (provider == null) {
166         throw new NullPointerException  ("provider cannot be null");
167     }
168 
169         Instance instance;
170         try {
171             instance = GetInstance.getInstance
172                 ("KeyInfoFactory", null, mechanismType, provider);
173         } catch (NoSuchAlgorithmException   nsae) {
174             throw new NoSuchMechanismException(nsae);
175         }
176         KeyInfoFactory factory = (KeyInfoFactory) instance.impl;
177         factory.mechanismType = mechanismType;
178         factory.provider = instance.provider;
179         return factory;
180     }
181 
182     /**
183      * Returns a <code>KeyInfoFactory</code> that supports the
184      * requested XML processing mechanism and representation type (ex: "DOM"),
185      * as supplied by the specified provider. The specified provider must be 
186      * registered in the security provider list. 
187      *
188      * <p>Note that the list of registered providers may be retrieved via 
189      * the {@link Security#getProviders() Security.getProviders()} method. 
190      *
191      * @param mechanismType the type of the XML processing mechanism and
192      *    representation. See the <a 
193      *    HREF="../../../../../../technotes/guides/security/xmldsig/overview.html#Service Provider">
194      *    Service Providers</a> section of the API overview for a list of 
195      *    standard mechanism types.
196      * @param provider the string name of the provider
197      * @return a new <code>KeyInfoFactory</code>
198      * @throws NoSuchProviderException if the specified provider is not 
199      *    registered in the security provider list
200      * @throws NullPointerException if <code>mechanismType</code> or
201      *    <code>provider</code> are <code>null</code>
202      * @throws NoSuchMechanismException if a <code>KeyInfoFactory</code> 
203      *    implementation for the specified mechanism is not available from the 
204      *    specified provider
205      * @see Provider
206      */
207     public static KeyInfoFactory getInstance(String   mechanismType,
208     String   provider) throws NoSuchProviderException   {
209     if (mechanismType == null) {
210             throw new NullPointerException  ("mechanismType cannot be null");
211     } else if (provider == null) {
212             throw new NullPointerException  ("provider cannot be null");
213     } else if (provider.length() == 0) {
214         throw new NoSuchProviderException  ();
215     }
216 
217         Instance instance;
218         try {
219             instance = GetInstance.getInstance
220                 ("KeyInfoFactory", null, mechanismType, provider);
221         } catch (NoSuchAlgorithmException   nsae) {
222             throw new NoSuchMechanismException(nsae);
223         }
224         KeyInfoFactory factory = (KeyInfoFactory) instance.impl;
225         factory.mechanismType = mechanismType;
226         factory.provider = instance.provider;
227         return factory;
228     }
229 
230     /**
231      * Returns a <code>KeyInfoFactory</code> that supports the
232      * default XML processing mechanism and representation type ("DOM").
233      *
234      * <p>This method uses the standard JCA provider lookup mechanism to 
235      * locate and instantiate a <code>KeyInfoFactory</code> implementation of 
236      * the default mechanism type. It traverses the list of registered security 
237      * <code>Provider</code>s, starting with the most preferred
238      * <code>Provider</code>.  A new <code>KeyInfoFactory</code> object
239      * from the first <code>Provider</code> that supports the DOM mechanism is 
240      * returned. 
241      * 
242      * <p> Note that the list of registered providers may be retrieved via 
243      * the {@link Security#getProviders() Security.getProviders()} method. 
244      *
245      * @return a new <code>KeyInfoFactory</code>
246      * @throws NoSuchMechanismException if no <code>Provider</code> supports a 
247      *    <code>KeyInfoFactory</code> implementation for the DOM mechanism
248      * @see Provider
249      */
250     public static KeyInfoFactory getInstance() {
251         return getInstance("DOM");
252     }
253 
254     /**
255      * Returns the type of the XML processing mechanism and representation
256      * supported by this <code>KeyInfoFactory</code> (ex: "DOM")
257      *
258      * @return the XML processing mechanism type supported by this
259      *    <code>KeyInfoFactory</code>
260      */
261     public final String   getMechanismType() {
262         return mechanismType;
263     }
264 
265     /**
266      * Returns the provider of this <code>KeyInfoFactory</code>.
267      *
268      * @return the provider of this <code>KeyInfoFactory</code>
269      */
270     public final Provider   getProvider() {
271     return provider;
272     }
273 
274     /**
275      * Creates a <code>KeyInfo</code> containing the specified list of
276      * key information types.
277      *
278      * @param content a list of one or more {@link XMLStructure}s representing 
279      *    key information types. The list is defensively copied to protect
280      *    against subsequent modification.
281      * @return a <code>KeyInfo</code>
282      * @throws NullPointerException if <code>content</code> is <code>null</code>
283      * @throws IllegalArgumentException if <code>content</code> is empty
284      * @throws ClassCastException if <code>content</code> contains any entries
285      *    that are not of type {@link XMLStructure}
286      */
287     public abstract KeyInfo newKeyInfo(List   content);
288 
289     /**
290      * Creates a <code>KeyInfo</code> containing the specified list of key
291      * information types and optional id. The
292      * <code>id</code> parameter represents the value of an XML
293      * <code>ID</code> attribute and is useful for referencing
294      * the <code>KeyInfo</code> from other XML structures. 
295      *
296      * @param content a list of one or more {@link XMLStructure}s representing 
297      *    key information types. The list is defensively copied to protect
298      *    against subsequent modification.
299      * @param id the value of an XML <code>ID</code> (may be <code>null</code>)
300      * @return a <code>KeyInfo</code>
301      * @throws NullPointerException if <code>content</code> is <code>null</code>
302      * @throws IllegalArgumentException if <code>content</code> is empty
303      * @throws ClassCastException if <code>content</code> contains any entries
304      *    that are not of type {@link XMLStructure}
305      */
306     public abstract KeyInfo newKeyInfo(List   content, String   id);
307 
308     /**
309      * Creates a <code>KeyName</code> from the specified name.
310      *
311      * @param name the name that identifies the key
312      * @return a <code>KeyName</code>
313      * @throws NullPointerException if <code>name</code> is <code>null</code>
314      */
315     public abstract KeyName newKeyName(String   name);
316 
317     /**
318      * Creates a <code>KeyValue</code> from the specified public key.
319      *
320      * @param key the public key
321      * @return a <code>KeyValue</code>
322      * @throws KeyException if the <code>key</code>'s algorithm is not 
323      *    recognized or supported by this <code>KeyInfoFactory</code>
324      * @throws NullPointerException if <code>key</code> is <code>null</code>
325      */
326     public abstract KeyValue newKeyValue(PublicKey   key) throws KeyException  ;
327 
328     /**
329      * Creates a <code>PGPData</code> from the specified PGP public key
330      * identifier.
331      *
332      * @param keyId a PGP public key identifier as defined in <a HREF=
333      *    "http://www.ietf.org/rfc/rfc2440.txt">RFC 2440</a>, section 11.2.
334      *    The array is cloned to protect against subsequent modification.
335      * @return a <code>PGPData</code>
336      * @throws NullPointerException if <code>keyId</code> is <code>null</code>
337      * @throws IllegalArgumentException if the key id is not in the correct
338      *    format
339      */
340     public abstract PGPData newPGPData(byte[] keyId);
341 
342     /**
343      * Creates a <code>PGPData</code> from the specified PGP public key
344      * identifier, and optional key material packet and list of external 
345      * elements.
346      *
347      * @param keyId a PGP public key identifier as defined in <a HREF=
348      *    "http://www.ietf.org/rfc/rfc2440.txt">RFC 2440</a>, section 11.2.
349      *    The array is cloned to protect against subsequent modification.
350      * @param keyPacket a PGP key material packet as defined in <a HREF=
351      *    "http://www.ietf.org/rfc/rfc2440.txt">RFC 2440</a>, section 5.5.
352      *    The array is cloned to protect against subsequent modification. May 
353      *    be <code>null</code>.
354      * @param other a list of {@link XMLStructure}s representing elements from
355      *    an external namespace. The list is defensively copied to protect
356      *    against subsequent modification. May be <code>null</code> or empty.
357      * @return a <code>PGPData</code>
358      * @throws NullPointerException if <code>keyId</code> is <code>null</code>
359      * @throws IllegalArgumentException if the <code>keyId</code> or 
360      *    <code>keyPacket</code> is not in the correct format. For 
361      *    <code>keyPacket</code>, the format of the packet header is 
362      *    checked and the tag is verified that it is of type key material. The
363      *    contents and format of the packet body are not checked.
364      * @throws ClassCastException if <code>other</code> contains any
365      *    entries that are not of type {@link XMLStructure}
366      */
367     public abstract PGPData newPGPData(byte[] keyId, byte[] keyPacket,
368     List   other);
369 
370     /**
371      * Creates a <code>PGPData</code> from the specified PGP key material
372      * packet and optional list of external elements.
373      *
374      * @param keyPacket a PGP key material packet as defined in <a HREF=
375      *    "http://www.ietf.org/rfc/rfc2440.txt">RFC 2440</a>, section 5.5.
376      *    The array is cloned to protect against subsequent modification.
377      * @param other a list of {@link XMLStructure}s representing elements from
378      *    an external namespace. The list is defensively copied to protect 
379      *    against subsequent modification. May be <code>null</code> or empty.
380      * @return a <code>PGPData</code>
381      * @throws NullPointerException if <code>keyPacket</code> is 
382      *    <code>null</code>
383      * @throws IllegalArgumentException if <code>keyPacket</code> is not in the 
384      *    correct format. For <code>keyPacket</code>, the format of the packet 
385      *    header is checked and the tag is verified that it is of type key 
386      *    material. The contents and format of the packet body are not checked.
387      * @throws ClassCastException if <code>other</code> contains any
388      *    entries that are not of type {@link XMLStructure}
389      */
390     public abstract PGPData newPGPData(byte[] keyPacket, List   other);
391 
392     /**
393      * Creates a <code>RetrievalMethod</code> from the specified URI.
394      *
395      * @param uri the URI that identifies the <code>KeyInfo</code> information 
396      *    to be retrieved
397      * @return a <code>RetrievalMethod</code>
398      * @throws NullPointerException if <code>uri</code> is <code>null</code>
399      * @throws IllegalArgumentException if <code>uri</code> is not RFC 2396
400      *    compliant
401      */
402     public abstract RetrievalMethod newRetrievalMethod(String   uri);
403 
404     /**
405      * Creates a <code>RetrievalMethod</code> from the specified parameters.
406      *
407      * @param uri the URI that identifies the <code>KeyInfo</code> information 
408      *    to be retrieved
409      * @param type a URI that identifies the type of <code>KeyInfo</code> 
410      *    information to be retrieved (may be <code>null</code>)
411      * @param transforms a list of {@link Transform}s. The list is defensively
412      *    copied to protect against subsequent modification. May be 
413      *    <code>null</code> or empty.
414      * @return a <code>RetrievalMethod</code>
415      * @throws NullPointerException if <code>uri</code> is <code>null</code>
416      * @throws IllegalArgumentException if <code>uri</code> is not RFC 2396
417      *    compliant
418      * @throws ClassCastException if <code>transforms</code> contains any
419      *    entries that are not of type {@link Transform}
420      */
421     public abstract RetrievalMethod newRetrievalMethod(String   uri, String   type,
422     List   transforms);
423 
424     /**
425      * Creates a <code>X509Data</code> containing the specified list of
426      * X.509 content.
427      *
428      * @param content a list of one or more X.509 content types. Valid types are
429      *    {@link String} (subject names), <code>byte[]</code> (subject key ids),
430      *    {@link java.security.cert.X509Certificate}, {@link X509CRL},
431      *    or {@link XMLStructure} ({@link X509IssuerSerial}
432      *    objects or elements from an external namespace). Subject names are 
433      *    distinguished names in RFC 2253 String format. Implementations MUST 
434      *    support the attribute type keywords defined in RFC 2253 (CN, L, ST, 
435      *    O, OU, C, STREET, DC and UID). Implementations MAY support additional 
436      *    keywords. The list is defensively copied to protect against 
437      *    subsequent modification.
438      * @return a <code>X509Data</code>
439      * @throws NullPointerException if <code>content</code> is <code>null</code>
440      * @throws IllegalArgumentException if <code>content</code> is empty, or
441      *    if a subject name is not RFC 2253 compliant or one of the attribute 
442      *    type keywords is not recognized.
443      * @throws ClassCastException if <code>content</code> contains any entries
444      *    that are not of one of the valid types mentioned above
445      */
446     public abstract X509Data newX509Data(List   content);
447 
448     /**
449      * Creates an <code>X509IssuerSerial</code> from the specified X.500 issuer
450      * distinguished name and serial number.
451      *
452      * @param issuerName the issuer's distinguished name in RFC 2253 String
453      *    format. Implementations MUST support the attribute type keywords 
454      *    defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC and UID). 
455      *    Implementations MAY support additional keywords.
456      * @param serialNumber the serial number
457      * @return an <code>X509IssuerSerial</code>
458      * @throws NullPointerException if <code>issuerName</code> or 
459      *    <code>serialNumber</code> are <code>null</code>
460      * @throws IllegalArgumentException if the issuer name is not RFC 2253
461      *    compliant or one of the attribute type keywords is not recognized.
462      */
463     public abstract X509IssuerSerial newX509IssuerSerial
464         (String   issuerName, BigInteger   serialNumber);
465 
466     /**
467      * Indicates whether a specified feature is supported.
468      *
469      * @param feature the feature name (as an absolute URI)
470      * @return <code>true</code> if the specified feature is supported,
471      *    <code>false</code> otherwise
472      * @throws NullPointerException if <code>feature</code> is <code>null</code>
473      */
474     public abstract boolean isFeatureSupported(String   feature);
475 
476     /**
477      * Returns a reference to the <code>URIDereferencer</code> that is used by 
478      * default to dereference URIs in {@link RetrievalMethod} objects.
479      *
480      * @return a reference to the default <code>URIDereferencer</code>
481      */
482     public abstract URIDereferencer getURIDereferencer();
483 
484     /**
485      * Unmarshals a new <code>KeyInfo</code> instance from a 
486      * mechanism-specific <code>XMLStructure</code> (ex: {@link DOMStructure}) 
487      * instance.
488      *
489      * @param xmlStructure a mechanism-specific XML structure from which to 
490      *   unmarshal the keyinfo from
491      * @return the <code>KeyInfo</code>
492      * @throws NullPointerException if <code>xmlStructure</code> is 
493      *   <code>null</code>
494      * @throws ClassCastException if the type of <code>xmlStructure</code> is
495      *   inappropriate for this factory
496      * @throws MarshalException if an unrecoverable exception occurs during 
497      *   unmarshalling
498      */
499     public abstract KeyInfo unmarshalKeyInfo(XMLStructure xmlStructure)
500     throws MarshalException;
501 }
502
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags