KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > crypto > KeySelector


1 /*
2  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
3  */
4 /*
5  * $Id: KeySelector.java,v 1.6 2005/05/10 15:47:42 mullan Exp $
6  */
7 package javax.xml.crypto;
8
9 import java.security.Key JavaDoc;
10 import javax.xml.crypto.dsig.keyinfo.KeyInfo;
11 import javax.xml.crypto.dsig.keyinfo.RetrievalMethod;
12
13 /**
14  * A selector that finds and returns a key using the data contained in a
15  * {@link KeyInfo} object. An example of an implementation of
16  * this class is one that searchs a {@link java.security.KeyStore} for
17  * trusted keys that match information contained in a <code>KeyInfo</code>.
18  *
19  * <p>Whether or not the returned key is trusted and the mechanisms
20  * used to determine that is implementation-specific.
21  *
22  * @author Sean Mullan
23  * @author JSR 105 Expert Group
24  * @since 1.6
25  */
26 public abstract class KeySelector {
27
28     /**
29      * The purpose of the key that is to be selected.
30      */
31     public static class Purpose {
32
33     private final String JavaDoc name;
34
35     private Purpose(String JavaDoc name) { this.name = name; }
36
37     /**
38      * Returns a string representation of this purpose ("sign",
39      * "verify", "encrypt", or "decrypt").
40      *
41      * @return a string representation of this purpose
42      */
43     public String JavaDoc toString() { return name; }
44
45     /**
46      * A key for signing.
47      */
48         public static final Purpose SIGN = new Purpose("sign");
49     /**
50      * A key for verifying.
51      */
52         public static final Purpose VERIFY = new Purpose("verify");
53     /**
54      * A key for encrypting.
55      */
56         public static final Purpose ENCRYPT = new Purpose("encrypt");
57     /**
58      * A key for decrypting.
59      */
60         public static final Purpose DECRYPT = new Purpose("decrypt");
61     }
62
63     /**
64      * Default no-args constructor; intended for invocation by subclasses only.
65      */
66     protected KeySelector() {}
67
68     /**
69      * Attempts to find a key that satisfies the specified constraints.
70      *
71      * @param keyInfo a <code>KeyInfo</code> (may be <code>null</code>)
72      * @param purpose the key's purpose ({@link Purpose#SIGN},
73      * {@link Purpose#VERIFY}, {@link Purpose#ENCRYPT}, or
74      * {@link Purpose#DECRYPT})
75      * @param method the algorithm method that this key is to be used for.
76      * Only keys that are compatible with the algorithm and meet the
77      * constraints of the specified algorithm should be returned.
78      * @param context an <code>XMLCryptoContext</code> that may contain
79      * useful information for finding an appropriate key. If this key
80      * selector supports resolving {@link RetrievalMethod} types, the
81      * context's <code>baseURI</code> and <code>dereferencer</code>
82      * parameters (if specified) should be used by the selector to
83      * resolve and dereference the URI.
84      * @return the result of the key selector
85      * @throws KeySelectorException if an exceptional condition occurs while
86      * attempting to find a key. Note that an inability to find a key is not
87      * considered an exception (<code>null</code> should be
88      * returned in that case). However, an error condition (ex: network
89      * communications failure) that prevented the <code>KeySelector</code>
90      * from finding a potential key should be considered an exception.
91      * @throws ClassCastException if the data type of <code>method</code>
92      * is not supported by this key selector
93      */
94     public abstract KeySelectorResult select(KeyInfo keyInfo, Purpose purpose,
95     AlgorithmMethod method, XMLCryptoContext context)
96     throws KeySelectorException;
97
98     /**
99      * Returns a <code>KeySelector</code> that always selects the specified
100      * key, regardless of the <code>KeyInfo</code> passed to it.
101      *
102      * @param key the sole key to be stored in the key selector
103      * @return a key selector that always selects the specified key
104      * @throws NullPointerException if <code>key</code> is <code>null</code>
105      */
106     public static KeySelector singletonKeySelector(Key JavaDoc key) {
107         return new SingletonKeySelector(key);
108     }
109
110     private static class SingletonKeySelector extends KeySelector {
111         private final Key JavaDoc key;
112
113         SingletonKeySelector(Key JavaDoc key) {
114             if (key == null) {
115                 throw new NullPointerException JavaDoc();
116             }
117             this.key = key;
118         }
119
120         public KeySelectorResult select(KeyInfo keyInfo, Purpose purpose,
121         AlgorithmMethod method, XMLCryptoContext context)
122         throws KeySelectorException {
123
124             return new KeySelectorResult() {
125         public Key JavaDoc getKey() {
126             return key;
127         }
128         };
129         }
130     }
131 }
132
Popular Tags