KerberosKey (Java Platform SE 8 )
Keywords: javax.security.auth.kerberos.KerberosKey class
Date: 2015-05-24

compact3
javax.security.auth.kerberos

## Class KerberosKey

- java.lang.Object
- - javax.security.auth.kerberos.KerberosKey

- All Implemented Interfaces:
    Serializable, Key, SecretKey, Destroyable

      public class KerberosKey
      extends Object
      implements SecretKey, Destroyable

  This class encapsulates a long term secret key for a Kerberos principal.

  All Kerberos JAAS login modules that obtain a principal's password and generate the secret key from it should use this class. Sometimes, such as when authenticating a server in the absence of user-to-user authentication, the login module will store an instance of this class in the private credential set of a `Subject` during the commit phase of the authentication process.

  A Kerberos service using a keytab to read secret keys should use the `KeyTab` class, where latest keys can be read when needed.

  It might be necessary for the application to be granted a `PrivateCredentialPermission` if it needs to access the KerberosKey instance from a Subject. This permission is not needed when the application depends on the default JGSS Kerberos mechanism to access the KerberosKey. In that case, however, the application will need an appropriate `ServicePermission`.

  Since:
    1.4
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `KerberosKey(KerberosPrincipal principal, byte[] keyBytes, int keyType, int versionNum)` Constructs a KerberosKey from the given bytes when the key type and key version number are known.
    `KerberosKey(KerberosPrincipal principal, char[] password, String algorithm)` Constructs a KerberosKey from a principal's password.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Destroys this key.
    `boolean` | `equals(Object other)` Compares the specified Object with this KerberosKey for equality.
    `String` | `getAlgorithm()` Returns the standard algorithm name for this key.
    `byte[]` | `getEncoded()` Returns the key material of this secret key.
    `String` | `getFormat()` Returns the name of the encoding format for this secret key.
    `int` | `getKeyType()` Returns the key type for this long-term key.
    `KerberosPrincipal` | `getPrincipal()` Returns the principal that this key belongs to.
    `int` | `getVersionNumber()` Returns the key version number.
    `int` | `hashCode()` Returns a hashcode for this KerberosKey.
    `boolean` | `isDestroyed()` Determines if this key has been destroyed.
    `String` | `toString()` Returns a string representation of the object.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### KerberosKey

          public KerberosKey(KerberosPrincipal principal,
                             byte[] keyBytes,
                             int keyType,
                             int versionNum)

      Constructs a KerberosKey from the given bytes when the key type and key version number are known. This can be used when reading the secret key information from a Kerberos "keytab".
      Parameters:
        `principal` - the principal that this secret key belongs to
        `keyBytes` - the raw bytes for the secret key
        `keyType` - the key type for the secret key as defined by the Kerberos protocol specification.
        `versionNum` - the version number of this secret key

    - #### KerberosKey

          public KerberosKey(KerberosPrincipal principal,
                             char[] password,
                             String algorithm)

      Constructs a KerberosKey from a principal's password.
      Parameters:
        `principal` - the principal that this password belongs to
        `password` - the password that should be used to compute the key
        `algorithm` - the name for the algorithm that this key will be used for. This parameter may be null in which case the default algorithm "DES" will be assumed.
      Throws:
        `IllegalArgumentException` - if the name of the algorithm passed is unsupported.

  - ### Method Detail

    - #### getPrincipal

          public final KerberosPrincipal getPrincipal()

      Returns the principal that this key belongs to.
      Returns:
        the principal this key belongs to.

    - #### getVersionNumber

          public final int getVersionNumber()

      Returns the key version number.
      Returns:
        the key version number.

    - #### getKeyType

          public final int getKeyType()

      Returns the key type for this long-term key.
      Returns:
        the key type.

    - #### getAlgorithm

          public final String getAlgorithm()

      Returns the standard algorithm name for this key. For example, "DES" would indicate that this key is a DES key. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
      Specified by:
        `getAlgorithm` in interface `Key`
      Returns:
        the name of the algorithm associated with this key.

    - #### getFormat

          public final String getFormat()

      Returns the name of the encoding format for this secret key.
      Specified by:
        `getFormat` in interface `Key`
      Returns:
        the String "RAW"

    - #### getEncoded

          public final byte[] getEncoded()

      Returns the key material of this secret key.
      Specified by:
        `getEncoded` in interface `Key`
      Returns:
        the key material

    - #### destroy

          public void destroy()
                       throws DestroyFailedException

      Destroys this key. A call to any of its other methods after this will cause an IllegalStateException to be thrown.
      Specified by:
        `destroy` in interface `Destroyable`
      Throws:
        `DestroyFailedException` - if some error occurs while destorying this key.

    - #### isDestroyed

          public boolean isDestroyed()

      Determines if this key has been destroyed.
      Specified by:
        `isDestroyed` in interface `Destroyable`
      Returns:
        true if this `Object` has been destroyed, false otherwise.

    - #### toString

          public String toString()

      Description copied from class: `Object`
      Returns a string representation of the object. In general, the `toString` method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

      The `toString` method for class `Object` returns a string consisting of the name of the class of which the object is an instance, the at-sign character ``@`', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

      >      getClass().getName() + '@' + Integer.toHexString(hashCode())

      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of the object.

    - #### hashCode

          public int hashCode()

      Returns a hashcode for this KerberosKey.
      Overrides:
        `hashCode` in class `Object`
      Returns:
        a hashCode() for the `KerberosKey`
      Since:
        1.6
      See Also:
        `Object.equals(java.lang.Object)`, `System.identityHashCode(java.lang.Object)`

    - #### equals

          public boolean equals(Object other)

      Compares the specified Object with this KerberosKey for equality. Returns true if the given object is also a `KerberosKey` and the two `KerberosKey` instances are equivalent.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `other` - the Object to compare to
      Returns:
        true if the specified object is equal to this KerberosKey, false otherwise. NOTE: Returns false if either of the KerberosKey objects has been destroyed.
      Since:
        1.6
      See Also:
        `Object.hashCode()`, `HashMap`

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.