KeyProvider


1   /*
2    * Copyright 2006 Schlichtherle IT Services
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package de.schlichtherle.key;
18  
19  /**
20   * A general purpose interface used by client applications to retrieve a
21   * key which is required to create or open a protected resource.
22   * Both the key and the protected resources may be virtually anything:
23   * The minimum requirement for a key is just that it's an {@link Object}.
24   * Protected resources are not even explicitly modelled in this interface.
25   * So in order to use it, an instance must be associated with a protected
26   * resource by a third party - this is the job of the {@link KeyManager} class.
27   * Because the protected resource is not modelled within this interface,
28   * it is at the discretion of the provider implementation whether its
29   * instances may or may not be shared among protected resources.
30   * If they do, then all associated protected resources share the same key.
31   * <p>
32   * For the following examples, it helps if you think of the protected
33   * resource being an encrypted file and the key being a password.
34   * Of course, this interface also works with certificate based encryption.
35   * <p>
36   * Once an instance has been associated to a protected resource, the client
37   * application is assumed to use the key for two basic operations:
38   * <ol>
39   * <li>A key is required in order to create a new protected resource or
40   *     entirely replace its contents.
41   *     This implies that the key does not need to be authenticated.
42   *     For this purpose, client applications call the method {@link #getCreateKey}.
43   * <li>A key is required in order to open an already existing protected
44   *     resource for access to its contents.
45   *     This implies that the key needs to be authenticated by the client
46   *     application.
47   *     For this purpose, client applications call the method {@link #getOpenKey},
48   *     followed by a call to {@link #invalidOpenKey} if the authentication of
49   *     the returned key failed for some reason.
50   * </ol>
51   * If the same resource is accessed multiple times, these basic operations
52   * are guaranteed to return a key which compares {@link Object#equals equal},
53   * but is not necessarily the same.
54   * In fact, the standard implementations in this package try to return a
55   * clone of the key wherever possible for maximum security.
56   * Failing that, the same key is returned.
57   * <p>
58   * From a client application's perspective, the two basic operations may be
59   * executed in no particular order. Following are some typical use cases:
60   * <ol>
61   * <li>A new protected resource needs to be created.
62   *     In this case, just the first basic operation is applied.
63   * <li>The contents of an already existing protected resource need to be
64   *     completely replaced.
65   *     Hence there is no need to retrieve and authenticate the existing key.
66   *     In this case, just the first basic operation is applied.
67   * <li>The contents of an already existing protected resource need to be
68   *     read, but not changed.
69   *     This implies that the existing key needs to be retrieved and
70   *     authenticated.
71   *     In this case, just the second basic operation is applied.
72   * <li>The contents of an already existing protected resource need to be
73   *     read and then only partially updated with new contents.
74   *     This implies that the existing key needs to be retrieved and
75   *     authenticated.
76   *     Because the contents are only partially updated, changing the key
77   *     is not possible.
78   *     In this case, just the second basic operation is applied.
79   * <li>The contents of an already existing protected resource need to be
80   *     read and then entirely replaced with new contents.
81   *     This implies that the existing key needs to be retrieved and
82   *     authenticated before it is probably (at the provider's discretion)
83   *     replaced with a new key.
84   *     In this case, the second and then the first operation is applied.
85   * </ol>
86   * As you can see in the last example, it is at the discretion of the key
87   * provider whether or not {@link #getCreateKey} returns a key which compares
88   * equal to the key returned by {@link #getOpenKey} or returns a completely
89   * different (new) key.
90   * Ideally, a brave provider implementation would allow the user to control this.
91   * In fact, this is the behaviour of the {@link PromptingKeyProvider} in
92   * this package and its user interface class(es).
93   * <p>
94   * Note that provider implementations must be thread safe.
95   * This allows clients to use the same provider by multiple threads
96   * concurrently.
97   *
98   * @see KeyManager
99   *
100  * @author Christian Schlichtherle
101  * @since TrueZIP 6.0
102  * @version @version@
103  */
104 public interface KeyProvider {
105 
106     /**
107      * The minimum delay between subsequent attempts to authenticate a key
108      * in milliseconds.
109      * More specifically, this is the minimum delay between the call to
110      * {@link #invalidOpenKey} and a subsequent {@link #getOpenKey} by the
111      * same thread.
112      */
113     int MIN_KEY_RETRY_DELAY = 3 * 1000;
114     
115     /**
116      * Returns the key which may be used to create a new protected resource or
117      * entirely replace the contents of an already existing protected resource.
118      * Hence, the key does not need to be authenticated.
119      * <p>
120      * For each call to this method an object is returned which compares
121      * {@link Object#equals equal} to the previously returned object, but is
122      * not necessarily the same.
123      * 
124      * @return A clone of the key object.
125      *         If the key does not support cloning or cloning fails for some
126      *         reason, the key object itself is returned.
127      *         <code>null</code> is never returned.
128      *
129      * @throws UnknownKeyException If the required key is unknown.
130      *         At the provider implementation's discretion, this may mean that
131      *         prompting for the key has been disabled or cancelled by the user.
132      */
133     Object   getCreateKey() throws UnknownKeyException;
134 
135     /**
136      * Returns the key which may be used to open an existing protected resource
137      * in order to access its contents.
138      * Hence, the key needs to be authenticated.
139      * If the authentication fails, {@link #invalidOpenKey} must be called
140      * immediately to indicate this situation.
141      * <p>
142      * Unless {@link #invalidOpenKey} is called, on each call to this method
143      * an object is returned which compares {@link Object#equals equal} to
144      * the previously returned object, but is not necessarily the same.
145      * <p>
146      * <b>Important:</b> From a client application's perspective, a
147      * <code>KeyProvider</code> is not trustworthy!
148      * Hence, the key returned by this method must not only get authenticated,
149      * but the client application should also throttle the pace for the
150      * return from a subsequent call to this method if the key is invalid
151      * in order to protect the client application from an exhaustive search
152      * for the correct key.
153      * As a rule of thumb, at least three seconds should pass between the
154      * immediate call to {@link #invalidOpenKey} and the return from the
155      * subsequent call to this method.
156      * "Friendly" implementations of this interface should duplicate this
157      * behaviour in order to protect client applications which do not obeye
158      * these considerations against abuses of the key provider implementation.
159      * Note that <code>invalidOpenKey()</code> must still be called
160      * immediately by the client application, so that other threads are not
161      * negatively affected by the suspension penalty.
162      * For the same reason, "friendly" implementations should enforce the
163      * suspension penalty for the local thread only.
164      * 
165      * @return A clone of the key object.
166      *         If the key does not support cloning or cloning fails for some
167      *         reason, the key object itself is returned.
168      *         <code>null</code> is never returned.
169      * @throws UnknownKeyException If the required key is unknown.
170      *         At the provider implementation's discretion, this may mean that
171      *         prompting for the key has been disabled or cancelled by the user.
172      * @see #MIN_KEY_RETRY_DELAY
173      */
174     Object   getOpenKey() throws UnknownKeyException;
175 
176     /**
177      * Called to indicate that authentication of the key returned by
178      * {@link #getOpenKey()} has failed and to request an entirely different
179      * key.
180      * Whether or not an entirely different key is provided on the next call
181      * to {@link #getOpenKey} is at the discretion of the provider's
182      * implementation and its instance's state.
183      */
184     void invalidOpenKey();
185 }
186
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags