org.ietf.jgss
public interface GSSCredential extends Cloneable
This interface encapsulates the GSS-API credentials for an entity. A credential contains all the necessary cryptographic information to enable the creation of a context on behalf of the entity that it represents. It may contain multiple, distinct, mechanism specific credential elements, each containing information for a specific security mechanism, but all referring to the same entity.
A credential may be used to perform context initiation, acceptance, or both.
GSS-API implementations must impose a local access-control policy on callers to prevent unauthorized callers from acquiring credentials to which they are not entitled. GSS-API credential creation is not intended to provide a "login to the network" function, as such a function would involve the creation of new credentials rather than merely acquiring a handle to existing credentials. Such functions, if required, should be defined in implementation-specific extensions to the API.
If credential acquisition is time-consuming for a mechanism, the mechanism may choose to delay the actual acquisition until the credential is required (e.g. by {@link GSSContext}). Such mechanism- specific implementation decisions should be invisible to the calling application; thus the query methods immediately following the creation of a credential object must return valid credential data, and may therefore incur the overhead of a deferred credential acquisition.
Applications will create a credential object passing the desired parameters. The application can then use the query methods to obtain specific information about the instantiated credential object (equivalent to the gss_inquire routines). When the credential is no longer needed, the application should call the dispose (equivalent to gss_release_cred) method to release any resources held by the credential object and to destroy any cryptographically sensitive information.
Classes implementing this interface also implement the {@link Cloneable} interface. This indicates the the class will support the {@link Cloneable#clone()} method that will allow the creation of duplicate credentials. This is useful when called just before the {@link #add(org.ietf.jgss.GSSName,int,int,org.ietf.jgss.Oid,int)} call to retain a copy of the original credential.
GSSManager mgr = GSSManager.getInstance();
// start by creating a name object for the entity
GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME);
// now acquire credentials for the entity
GSSCredential cred = mgr.createCredential(name,
GSSCredential.ACCEPT_ONLY);
// display credential information - name, remaining lifetime,
// and the mechanisms it has been acquired over
print(cred.getName().toString());
print(cred.getRemainingLifetime());
Oid [] mechs = cred.getMechs();
if (mechs != null)
{
for (int i = 0; i < mechs.length; i++)
print(mechs[i].toString());
}
// release system resources held by the credential
cred.dispose();
| Field Summary | |
|---|---|
| int | ACCEPT_ONLY
Credential usage flag requesting that it be able to be used for
context acceptance only. |
| int | DEFAULT_LIFETIME
A lifetime constant representing the default credential lifetime. |
| int | INDEFINITE_LIFETIME
A lifetime constant representing indefinite credential lifetime. |
| int | INITIATE_AND_ACCEPT
Credential usage flag requesting that it be able to be used for both
context initiation and acceptance. |
| int | INITIATE_ONLY
Credential usage flag requesting that it be able to be used for
context initiation only. |
| Method Summary | |
|---|---|
| void | add(GSSName aName, int initLifetime, int acceptLifetime, Oid mech, int usage) Adds a mechanism specific credential-element to an existing credential. |
| void | dispose()
Releases any sensitive information that the GSSCredential object may
be containing. |
| boolean | equals(Object another)
Tests if this GSSCredential refers to the same entity as the supplied
object. |
| Oid[] | getMechs()
Returns an array of mechanisms supported by this credential.
|
| GSSName | getName()
Retrieves the name of the entity that the credential asserts.
|
| GSSName | getName(Oid mechOID)
Retrieves a mechanism name of the entity that the credential asserts.
|
| int | getRemainingAcceptLifetime(Oid mech)
Returns the remaining lifetime is seconds for the credential to
remain capable of accepting security contexts under the specified
mechanism. |
| int | getRemainingInitLifetime(Oid mech)
Returns the remaining lifetime is seconds for the credential to
remain capable of initiating security contexts under the specified
mechanism. |
| int | getRemainingLifetime()
Returns the remaining lifetime in seconds for a credential. |
| int | getUsage()
Returns the credential usage flag. |
| int | getUsage(Oid mechOID)
Returns the credential usage flag for the specified credential
mechanism. |
| int | hashCode()
Return the hash code of this credential. |
Adds a mechanism specific credential-element to an existing credential. This method allows the construction of credentials one mechanism at a time.
This routine is envisioned to be used mainly by context acceptors during the creation of acceptance credentials which are to be used with a variety of clients using different security mechanisms.
This routine adds the new credential element "in-place". To add the
element in a new credential, first call {@link Cloneable#clone()} to
obtain a copy of this credential, then call its add()
method.
Parameters: aName Name of the principal for whom this credential
is to be acquired. Use null to
specify the default principal. initLifetime The number of seconds that credentials should
remain valid for initiating of security contexts.
Use {@link #INDEFINITE_LIFETIME} to request that
the credentials have the maximum permitted lifetime.
Use {@link GSSCredential#DEFAULT_LIFETIME} to
request the default credential lifetime. acceptLifetime The number of seconds that credentials should
remain valid for accepting of security contexts.
Use {@link GSSCredential#INDEFINITE_LIFETIME} to
request that the credentials have the maximum
permitted lifetime. Use {@link
GSSCredential#DEFAULT_LIFETIME} to request
the default credential lifetime. mech The mechanisms over which the credential is to be
acquired. usage The intended usage for this credential object. The
value of this parameter must be one of:
{@link GSSCredential#ACCEPT_AND_INITIATE},
{@link GSSCredential#ACCEPT_ONLY},
{@link GSSCredential#INITIATE_ONLY}.
Throws: GSSException If this operation fails.
Throws: GSSException If this operation fails.
true
if the two GSSCredentials refer to the same entity; false
otherwise. (Note that the Java language specification requires that two
objects that are equal according to the {@link
Object#equals(java.lang.Object)} method must return the same integer
result when the {@link Object#hashCode()} method is called on them.)
Parameters: another Another GSSCredential object for comparison.
Returns: True if this object equals the other.
Returns: The supported mechanism.
Throws: GSSException If this operation fails.
Returns: The name.
Throws: GSSException If this operation fails.
Parameters: mechOID The mechanism for which information should be returned.
Returns: The name.
Throws: GSSException If this operation fails.
Parameters: mech The mechanism for which information should be returned.
Returns: The remaining lifetime.
Throws: GSSException If this operation fails.
Parameters: mech The mechanism for which information should be returned.
Returns: The remaining lifetime.
Throws: GSSException If this operation fails.
Returns: The remaining lifetime.
Throws: GSSException If this operation fails.
Returns: The credential usage flag.
Throws: GSSException If this operation fails.
Parameters: mechOID The mechanism for which information should be returned.
Returns: The credential usage flag.
Throws: GSSException If this operation fails.
Returns: the hash code that must be the same for two credentials if {@link #equals} returns true.