GSSCredential JDK 1.6)

Description

public interface GSSCredential

This interface encapsulates the GSS-API credentials for an entity.

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.

Credentials are instantiated using one of the createCredential methods in the GSSManager class. 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. The section on credential acquisition in the package level description describes how existing credentials are acquired in the Java platform. 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.

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. When the credential is no longer needed, the application should call the dispose method to release any resources held by the credential object and to destroy any cryptographically sensitive information.

This example code demonstrates the creation of a GSSCredential implementation for a specific entity, querying of its fields, and its release when it is no longer needed:

    GSSManager manager = GSSManager.getInstance();

    // start by creating a name object for the entity
    GSSName name = manager.createName("myusername", GSSName.NT_USER_NAME);

    // now acquire credentials for the entity
    GSSCredential cred = manager.createCredential(name,
                    GSSCredential.ACCEPT_ONLY);

    // display credential information - name, remaining lifetime,
    // and the mechanisms it has been acquired over
    System.out.println(cred.getName().toString());
    System.out.println(cred.getRemainingLifetime());

    Oid [] mechs = cred.getMechs();
    if (mechs != null) {
            for (int i = 0; i < mechs.length; i++)
                    System.out.println(mechs[i].toString());
    }

    // release system resources held by the credential
    cred.dispose();

See also: GSSManager.createCredential(int) GSSManager.createCredential(GSSName, int, Oid, int) GSSManager.createCredential(GSSName, int, Oid[], int) GSSCredential.dispose()

Methods

Hide/Show inherited methods

public void add (GSSName name, int initLifetime, int acceptLifetime, Oid mech, int usage) throws GSSException

Adds a mechanism specific credential-element to an existing 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 acceptor 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 clone to obtain a copy of this credential, then call its add method.

As always, 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. Non-default values for initLifetime and acceptLifetime cannot always be honored by the underlying mechanisms, thus callers should be prepared to call getRemainingInitLifetime and getRemainingAcceptLifetime on the credential.
Parameters:
- name - the 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 the credential element should remain valid for initiating of security contexts. Use {@link GSSCredential#INDEFINITE_LIFETIME GSSCredential.INDEFINITE_LIFETIME} to request that the credentials have the maximum permitted lifetime for this. Use {@link GSSCredential#DEFAULT_LIFETIME GSSCredential.DEFAULT_LIFETIME} to request default credential lifetime for this.
- acceptLifetime - the number of seconds that the credential element should remain valid for accepting security contexts. Use {@link GSSCredential#INDEFINITE_LIFETIME GSSCredential.INDEFINITE_LIFETIME} to request that the credentials have the maximum permitted lifetime for this. Use {@link GSSCredential#DEFAULT_LIFETIME GSSCredential.DEFAULT_LIFETIME} to request default credential lifetime for this.
- mech - the mechanism over which the credential is to be acquired.
- usage - the usage mode that this credential element should add to the credential. The value of this parameter must be one of: {@link #INITIATE_AND_ACCEPT INITIATE_AND_ACCEPT}, {@link #ACCEPT_ONLY ACCEPT_ONLY}, and {@link #INITIATE_ONLY INITIATE_ONLY}.
Throws:
- GSSException - containing the following major error codes: {@link GSSException#DUPLICATE_ELEMENT GSSException.DUPLICATE_ELEMENT}, {@link GSSException#BAD_MECH GSSException.BAD_MECH}, {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE}, {@link GSSException#NO_CRED GSSException.NO_CRED}, {@link GSSException#CREDENTIALS_EXPIRED GSSException.CREDENTIALS_EXPIRED}, {@link GSSException#FAILURE GSSException.FAILURE}

public void dispose () throws GSSException

Releases any sensitive information that the GSSCredential object may be containing.

public boolean equals (Object another)

Tests if this GSSCredential asserts the same entity as the supplied object.

Tests if this GSSCredential asserts the same entity as the supplied
object. The two credentials must be acquired over the same
mechanisms and must refer to the same principal.
Returns: true if the two GSSCredentials assert the same entity; false otherwise.
Parameters:
- another - another GSSCredential for comparison to this one

public Oid getMechs () throws GSSException

Returns a list of mechanisms supported by this credential.

public GSSName getName () throws GSSException

Retrieves the name of the entity that the credential asserts.

public GSSName getName (Oid mech) throws GSSException

Retrieves a Mechanism Name of the entity that the credential asserts.

public int getRemainingAcceptLifetime (Oid mech) throws GSSException

Returns the lifetime in seconds for the credential to remain capable of accepting security contexts using the specified mechanism.

public int getRemainingInitLifetime (Oid mech) throws GSSException

Returns the lifetime in seconds for the credential to remain capable of initiating security contexts using the specified mechanism.

public int getRemainingLifetime () throws GSSException

Returns the remaining lifetime in seconds for a credential.

public int getUsage () throws GSSException

Returns the credential usage mode.

public int getUsage (Oid mech) throws GSSException

Returns the credential usage mode for a specific mechanism.

public int hashCode ()

Returns a hashcode value for this GSSCredential.