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.
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},
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 }
|
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} 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{@literal <} 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.
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} to obtain a
301 * copy of this credential, then call its {@code add} 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} 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},
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} if the two GSSCredentials assert the same
358 * entity; {@code false} 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 }
|