1 /*
2 * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package org.ietf.jgss;
27
28 /**
29 * This interface encapsulates the GSS-API credentials for an entity. A
30 * credential contains all the necessary cryptographic information to
31 * enable the creation of a context on behalf of the entity that it
32 * represents. It may contain multiple, distinct, mechanism specific
33 * credential elements, each containing information for a specific
34 * security mechanism, but all referring to the same entity. A credential
35 * may be used to perform context initiation, acceptance, or both.<p>
36 *
37 * Credentials are instantiated using one of the
38 * <code>createCredential</code> methods in the {@link GSSManager
39 * GSSManager} class. GSS-API credential creation is not
40 * intended to provide a "login to the network" function, as such a
41 * function would involve the creation of new credentials rather than
42 * merely acquiring a handle to existing credentials. The
43 * <a href=package-summary.html#useSubjectCredsOnly>section on credential
44 * acquisition</a> in the package level description describes
45 * how existing credentials are acquired in the Java platform. GSS-API
46 * implementations must impose a local access-control policy on callers to
47 * prevent unauthorized callers from acquiring credentials to which they
48 * are not entitled. <p>
49 *
50 * Applications will create a credential object passing the desired
51 * parameters. The application can then use the query methods to obtain
52 * specific information about the instantiated credential object.
53 * When the credential is no longer needed, the application should call
54 * the {@link #dispose() dispose} method to release any resources held by
55 * the credential object and to destroy any cryptographically sensitive
56 * information.<p>
57 *
58 * This example code demonstrates the creation of a GSSCredential
59 * implementation for a specific entity, querying of its fields, and its
60 * release when it is no longer needed:
61 * <pre>
62 * GSSManager manager = GSSManager.getInstance();
63 *
64 * // start by creating a name object for the entity
65 * GSSName name = manager.createName("myusername", GSSName.NT_USER_NAME);
66 *
67 * // now acquire credentials for the entity
68 * GSSCredential cred = manager.createCredential(name,
69 * GSSCredential.ACCEPT_ONLY);
70 *
71 * // display credential information - name, remaining lifetime,
72 * // and the mechanisms it has been acquired over
73 * System.out.println(cred.getName().toString());
74 * System.out.println(cred.getRemainingLifetime());
75 *
76 * Oid [] mechs = cred.getMechs();
77 * if (mechs != null) {
78 * for (int i = 0; i < mechs.length; i++)
79 * System.out.println(mechs[i].toString());
80 * }
81 *
82 * // release system resources held by the credential
83 * cred.dispose();
84 * </pre>
85 *
86 * @see GSSManager#createCredential(int)
87 * @see GSSManager#createCredential(GSSName, int, Oid, int)
88 * @see GSSManager#createCredential(GSSName, int, Oid[], int)
89 * @see #dispose()
90 *
91 * @author Mayank Upadhyay
92 * @since 1.4
93 */
94 public interface GSSCredential extends Cloneable{
95
96 /**
97 * Credential usage flag requesting that it be usable
98 * for both context initiation and acceptance.
99 *
100 */
101 public static final int INITIATE_AND_ACCEPT = 0;
102
103
104 /**
105 * Credential usage flag requesting that it be usable
106 * for context initiation only.
107 *
108 */
109 public static final int INITIATE_ONLY = 1;
110
111
112 /**
113 * Credential usage flag requesting that it be usable
114 * for context acceptance only.
115 *
116 */
117 public static final int ACCEPT_ONLY = 2;
118
119
120 /**
121 * A lifetime constant representing the default credential lifetime. This
122 * value it set to 0.
123 */
124 public static final int DEFAULT_LIFETIME = 0;
125
126 /**
127 * A lifetime constant representing indefinite credential lifetime.
128 * This value must is set to the maximum integer value in Java -
129 * {@link java.lang.Integer#MAX_VALUE Integer.MAX_VALUE}.
130 */
131 public static final int INDEFINITE_LIFETIME = Integer.MAX_VALUE;
132
133 /**
134 * Releases any sensitive information that the GSSCredential object may
135 * be containing. Applications should call this method as soon as the
136 * credential is no longer needed to minimize the time any sensitive
137 * information is maintained.
138 *
139 * @throws GSSException containing the following
140 * major error codes:
141 * {@link GSSException#FAILURE GSSException.FAILURE}
142 */
143 public void dispose() throws GSSException;
144
145 /**
146 * Retrieves the name of the entity that the credential asserts.
147 *
148 * @return a GSSName representing the entity
149 *
150 * @throws GSSException containing the following
151 * major error codes:
152 * {@link GSSException#FAILURE GSSException.FAILURE}
153 */
154 public GSSName getName() throws GSSException;
155
156 /**
157 * Retrieves a Mechanism Name of the entity that the credential
158 * asserts. This is equivalent to calling {@link
159 * GSSName#canonicalize(Oid) canonicalize} on the value returned by
160 * the other form of {@link #getName() getName}.
161 *
162 * @param mech the Oid of the mechanism for which the Mechanism Name
163 * should be returned.
164 * @return a GSSName representing the entity canonicalized for the
165 * desired mechanism
166 *
167 * @throws GSSException containing the following
168 * major error codes:
169 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
170 * {@link GSSException#FAILURE GSSException.FAILURE}
171 */
172 public GSSName getName(Oid mech) throws GSSException;
173
174 /**
175 * Returns the remaining lifetime in seconds for a credential. The
176 * remaining lifetime is the minimum lifetime amongst all of the underlying
177 * mechanism specific credential elements.
178 *
179 * @return the minimum remaining lifetime in seconds for this
180 * credential. A return value of {@link #INDEFINITE_LIFETIME
181 * INDEFINITE_LIFETIME} indicates that the credential does
182 * not expire. A return value of 0 indicates that the credential is
183 * already expired.
184 *
185 * @see #getRemainingInitLifetime(Oid)
186 * @see #getRemainingAcceptLifetime(Oid)
187 *
188 * @throws GSSException containing the following
189 * major error codes:
190 * {@link GSSException#FAILURE GSSException.FAILURE}
191 */
192 public int getRemainingLifetime() throws GSSException;
193
194 /**
195 * Returns the lifetime in seconds for the credential to remain capable
196 * of initiating security contexts using the specified mechanism. This
197 * method queries the initiator credential element that belongs to the
198 * specified mechanism.
199 *
200 * @return the number of seconds remaining in the life of this credential
201 * element. A return value of {@link #INDEFINITE_LIFETIME
202 * INDEFINITE_LIFETIME} indicates that the credential element does not
203 * expire. A return value of 0 indicates that the credential element is
204 * already expired.
205 *
206 * @param mech the Oid of the mechanism whose initiator credential element
207 * should be queried.
208 *
209 * @throws GSSException containing the following
210 * major error codes:
211 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
212 * {@link GSSException#FAILURE GSSException.FAILURE}
213 */
214 public int getRemainingInitLifetime(Oid mech) throws GSSException;
215
216 /**
217 * Returns the lifetime in seconds for the credential to remain capable
218 * of accepting security contexts using the specified mechanism. This
219 * method queries the acceptor credential element that belongs to the
220 * specified mechanism.
221 *
222 * @return the number of seconds remaining in the life of this credential
223 * element. A return value of {@link #INDEFINITE_LIFETIME
224 * INDEFINITE_LIFETIME} indicates that the credential element does not
225 * expire. A return value of 0 indicates that the credential element is
226 * already expired.
227 *
228 * @param mech the Oid of the mechanism whose acceptor credential element
229 * should be queried.
230 *
231 * @throws GSSException containing the following
232 * major error codes:
233 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
234 * {@link GSSException#FAILURE GSSException.FAILURE}
235 */
236 public int getRemainingAcceptLifetime(Oid mech) throws GSSException;
237
238 /**
239 * Returns the credential usage mode. In other words, it
240 * tells us if this credential can be used for initiating or accepting
241 * security contexts. It does not tell us which mechanism(s) has to be
242 * used in order to do so. It is expected that an application will allow
243 * the GSS-API to pick a default mechanism after calling this method.
244 *
245 * @return The return value will be one of {@link #INITIATE_ONLY
246 * INITIATE_ONLY}, {@link #ACCEPT_ONLY ACCEPT_ONLY}, and {@link
247 * #INITIATE_AND_ACCEPT INITIATE_AND_ACCEPT}.
248 *
249 * @throws GSSException containing the following
250 * major error codes:
251 * {@link GSSException#FAILURE GSSException.FAILURE}
252 */
253 public int getUsage() throws GSSException;
254
255 /**
256 * Returns the credential usage mode for a specific mechanism. In other
257 * words, it tells us if this credential can be used
258 * for initiating or accepting security contexts with a given underlying
259 * mechanism.
260 *
261 * @return The return value will be one of {@link #INITIATE_ONLY
262 * INITIATE_ONLY}, {@link #ACCEPT_ONLY ACCEPT_ONLY}, and {@link
263 * #INITIATE_AND_ACCEPT INITIATE_AND_ACCEPT}.
264 * @param mech the Oid of the mechanism whose credentials usage mode is
265 * to be determined.
266 *
267 * @throws GSSException containing the following
268 * major error codes:
269 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
270 * {@link GSSException#FAILURE GSSException.FAILURE}
271 */
272 public int getUsage(Oid mech) throws GSSException;
273
274 /**
275 * Returns a list of mechanisms supported by this credential. It does
276 * not tell us which ones can be used to initiate
277 * contexts and which ones can be used to accept contexts. The
278 * application must call the {@link #getUsage(Oid) getUsage} method with
279 * each of the returned Oid's to determine the possible modes of
280 * usage.
281 *
282 * @return an array of Oid's corresponding to the supported mechanisms.
283 *
284 * @throws GSSException containing the following
285 * major error codes:
286 * {@link GSSException#FAILURE GSSException.FAILURE}
287 */
288 public Oid[] getMechs() throws GSSException;
289
290 /**
291 * Adds a mechanism specific credential-element to an existing
292 * credential. This method allows the construction of credentials, one
293 * mechanism at a time.<p>
294 *
295 * This routine is envisioned to be used mainly by context acceptors
296 * during the creation of acceptor credentials which are to be used
297 * with a variety of clients using different security mechanisms.<p>
298 *
299 * This routine adds the new credential element "in-place". To add the
300 * element in a new credential, first call <code>clone</code> to obtain a
301 * copy of this credential, then call its <code>add</code> method.<p>
302 *
303 * As always, GSS-API implementations must impose a local access-control
304 * policy on callers to prevent unauthorized callers from acquiring
305 * credentials to which they are not entitled.
306 *
307 * Non-default values for initLifetime and acceptLifetime cannot always
308 * be honored by the underlying mechanisms, thus callers should be
309 * prepared to call {@link #getRemainingInitLifetime(Oid)
310 * getRemainingInitLifetime} and {@link #getRemainingAcceptLifetime(Oid)
311 * getRemainingAcceptLifetime} on the credential.
312 *
313 * @param name the name of the principal for whom this credential is to
314 * be acquired. Use <code>null</code> to specify the default
315 * principal.
316 * @param initLifetime the number of seconds that the credential element
317 * should remain valid for initiating of security contexts. Use {@link
318 * GSSCredential#INDEFINITE_LIFETIME GSSCredential.INDEFINITE_LIFETIME}
319 * to request that the credentials have the maximum permitted lifetime
320 * for this. Use {@link GSSCredential#DEFAULT_LIFETIME
321 * GSSCredential.DEFAULT_LIFETIME} to request default credential lifetime
322 * for this.
323 * @param acceptLifetime the number of seconds that the credential
324 * element should remain valid for accepting security contexts. Use {@link
325 * GSSCredential#INDEFINITE_LIFETIME GSSCredential.INDEFINITE_LIFETIME}
326 * to request that the credentials have the maximum permitted lifetime
327 * for this. Use {@link GSSCredential#DEFAULT_LIFETIME
328 * GSSCredential.DEFAULT_LIFETIME} to request default credential lifetime
329 * for this.
330 * @param mech the mechanism over which the credential is to be acquired.
331 * @param usage the usage mode that this credential
332 * element should add to the credential. The value
333 * of this parameter must be one of:
334 * {@link #INITIATE_AND_ACCEPT INITIATE_AND_ACCEPT},
335 * {@link #ACCEPT_ONLY ACCEPT_ONLY}, and
336 * {@link #INITIATE_ONLY INITIATE_ONLY}.
337 *
338 * @throws GSSException containing the following
339 * major error codes:
340 * {@link GSSException#DUPLICATE_ELEMENT
341 * GSSException.DUPLICATE_ELEMENT},
342 * {@link GSSException#BAD_MECH GSSException.BAD_MECH},
343 * {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
344 * {@link GSSException#NO_CRED GSSException.NO_CRED},
345 * {@link GSSException#CREDENTIALS_EXPIRED
346 * GSSException.CREDENTIALS_EXPIRED},
347 * {@link GSSException#FAILURE GSSException.FAILURE}
348 */
349 public void add(GSSName name, int initLifetime, int acceptLifetime,
350 Oid mech, int usage) throws GSSException;
351
352 /**
353 * Tests if this GSSCredential asserts the same entity as the supplied
354 * object. The two credentials must be acquired over the same
355 * mechanisms and must refer to the same principal.
356 *
357 * @return <code>true</code> if the two GSSCredentials assert the same
358 * entity; <code>false</code> otherwise.
359 * @param another another GSSCredential for comparison to this one
360 */
361 public boolean equals(Object another);
362
363 /**
364 * Returns a hashcode value for this GSSCredential.
365 *
366 * @return a hashCode value
367 */
368 public int hashCode();
369
370 }