APIdia Launch Partner
Top Description Fields Constructors Methods
javax.security.auth.kerberos

public Class KerberosKey

extends Object
implements SecretKey
Class Inheritance
All Implemented Interfaces
javax.crypto.SecretKey, javax.security.auth.Destroyable, java.security.Key, java.io.Serializable
Imports
java.io.Serial, java.util.Arrays, .Objects, javax.crypto.SecretKey, javax.security.auth.DestroyFailedException
This class encapsulates a long term secret key for a Kerberos principal.

A KerberosKey object includes an EncryptionKey, a KerberosPrincipal as its owner, and the version number of the key.

An EncryptionKey is defined in Section 4.2.9 of the Kerberos Protocol Specification (RFC 4120) as: 

    EncryptionKey   ::= SEQUENCE {
            keytype         [0] Int32 -- actually encryption type --,
            keyvalue        [1] OCTET STRING
    }
The key material of a KerberosKey is defined as the value of the keyValue above.

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.

When creating a KerberosKey using the KerberosKey(KerberosPrincipal, char[], String) constructor, an implementation may accept non-IANA algorithm names (For example, "ArcFourMac" for "rc4-hmac"), but the getAlgorithm method must always return the IANA algorithm name.

Implementation Note

Old algorithm names used before JDK 9 are supported in the KerberosKey(KerberosPrincipal, char[], String) constructor in this implementation for compatibility reasons, which are "DES" (and null) for "des-cbc-md5", "DESede" for "des3-cbc-sha1-kd", "ArcFourHmac" for "rc4-hmac", "AES128" for "aes128-cts-hmac-sha1-96", and "AES256" for "aes256-cts-hmac-sha1-96".

Author
Mayank Upadhyay
Since
1.4

Field Summary

Modifier and TypeField and Description
private transient boolean
destroyed

private final KeyImpl
key

KeyImpl is serialized by writing out the ASN.1 encoded bytes of the encryption key.

private KerberosPrincipal
principal

The principal that this secret key belongs to.

private static final long
serialVersionUID

Hides javax.crypto.SecretKey.serialVersionUID.

private final int
versionNum

the version number of this secret key

Constructor Summary

AccessConstructor and Description
public
KerberosKey(KerberosPrincipal
the principal that this secret key belongs to
principal, byte[]
the key material for the secret key
keyBytes, int
the key type for the secret key as defined by the Kerberos protocol specification.
keyType, int
the version number of this secret key
versionNum)

Constructs a KerberosKey from the given bytes when the key type and key version number are known.

public
KerberosKey(KerberosPrincipal
the principal that this password belongs to
principal, char[]
the password that should be used to compute the key
password, String
the name for the algorithm that this key will be used for
algorithm)

Constructs a KerberosKey from a principal's password using the specified algorithm name.

Method Summary

Modifier and TypeMethod and Description
public void
destroy()

Overrides default javax.security.auth.Destroyable.destroy.

Destroys this key by clearing out the key material of this secret key.

public boolean

Returns:

true if the specified object is equal to this KerberosKey, false otherwise.
equals(Object
the object to compare to
other)

Overrides java.lang.Object.equals.

Compares the specified object with this KerberosKey for equality.

public final String

Returns:

the name of the algorithm associated with this key.
getAlgorithm()

Implements java.security.Key.getAlgorithm.

Returns the standard algorithm name for this key.

public final byte[]

Returns:

the key material
getEncoded()

Implements java.security.Key.getEncoded.

Returns the key material of this secret key.

public final String

Returns:

the String "RAW"
getFormat()

Implements java.security.Key.getFormat.

Returns the name of the encoding format for this secret key.

public final int

Returns:

the key type.
getKeyType()

Returns the key type for this long-term key.

public final KerberosPrincipal

Returns:

the principal this key belongs to.
getPrincipal()

Returns the principal that this key belongs to.

public final int

Returns:

the key version number.
getVersionNumber()

Returns the key version number.

public int

Returns:

a hash code for this KerberosKey
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code for this KerberosKey.

public boolean
isDestroyed()

Overrides default javax.security.auth.Destroyable.isDestroyed.

Determines if this key has been destroyed.

public String

Returns:

an informative textual representation of this KerberosKey.
toString()

Overrides java.lang.Object.toString.

Returns an informative textual representation of this KerberosKey.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

destroyedback to summary
private transient boolean destroyed
keyback to summary
private final KeyImpl key

KeyImpl is serialized by writing out the ASN.1 encoded bytes of the encryption key.

principalback to summary
private KerberosPrincipal principal

The principal that this secret key belongs to.

serialVersionUIDback to summary
private static final long serialVersionUID

Hides javax.crypto.SecretKey.serialVersionUID.

Annotations
@Serial
versionNumback to summary
private final int versionNum

the version number of this secret key

Constructor Detail

KerberosKeyback to summary
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:KerberosPrincipal

the principal that this secret key belongs to

keyBytes:byte[]

the key material for the secret key

keyType:int

the key type for the secret key as defined by the Kerberos protocol specification.

versionNum:int

the version number of this secret key

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

Constructs a KerberosKey from a principal's password using the specified algorithm name. The algorithm name (case insensitive) should be provided as the encryption type string defined on the IANA Kerberos Encryption Type Numbers page. The version number of the key generated will be 0.

Parameters
principal:KerberosPrincipal

the principal that this password belongs to

password:char[]

the password that should be used to compute the key

algorithm:String

the name for the algorithm that this key will be used for

Exceptions
IllegalArgumentException:
if the name of the algorithm passed is unsupported.

Method Detail

destroyback to summary
public void destroy() throws DestroyFailedException

Overrides default javax.security.auth.Destroyable.destroy.

Destroys this key by clearing out the key material of this secret key.

Exceptions
DestroyFailedException:
if some error occurs while destroying this key.
equalsback to summary
public boolean equals(Object other)

Overrides java.lang.Object.equals.

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. A destroyed KerberosKey object is only equal to itself.

Parameters
other:Object

the object to compare to

Returns:boolean

true if the specified object is equal to this KerberosKey, false otherwise.

Annotations
@Override
Since
1.6
getAlgorithmback to summary
public final String getAlgorithm()

Implements java.security.Key.getAlgorithm.

Returns the standard algorithm name for this key. The algorithm names are the encryption type string defined on the IANA Kerberos Encryption Type Numbers page.

This method can return the following value not defined on the IANA page:

  1. none: for etype equal to 0
  2. unknown: for etype greater than 0 but unsupported by the implementation
  3. private: for etype smaller than 0
Returns:String

the name of the algorithm associated with this key.

Exceptions
IllegalStateException:
if the key is destroyed
getEncodedback to summary
public final byte[] getEncoded()

Implements java.security.Key.getEncoded.

Returns the key material of this secret key.

Returns:byte[]

the key material

Exceptions
IllegalStateException:
if the key is destroyed
getFormatback to summary
public final String getFormat()

Implements java.security.Key.getFormat.

Returns the name of the encoding format for this secret key.

Returns:String

the String "RAW"

Exceptions
IllegalStateException:
if the key is destroyed
getKeyTypeback to summary
public final int getKeyType()

Returns the key type for this long-term key.

Returns:int

the key type.

Exceptions
IllegalStateException:
if the key is destroyed
getPrincipalback to summary
public final KerberosPrincipal getPrincipal()

Returns the principal that this key belongs to.

Returns:KerberosPrincipal

the principal this key belongs to.

Exceptions
IllegalStateException:
if the key is destroyed
getVersionNumberback to summary
public final int getVersionNumber()

Returns the key version number.

Returns:int

the key version number.

Exceptions
IllegalStateException:
if the key is destroyed
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code for this KerberosKey.

Returns:int

a hash code for this KerberosKey

Annotations
@Override
Since
1.6
isDestroyedback to summary
public boolean isDestroyed()

Overrides default javax.security.auth.Destroyable.isDestroyed.

Determines if this key has been destroyed.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns an informative textual representation of this KerberosKey.

Returns:String

an informative textual representation of this KerberosKey.