Skip navigation links

oracle.security.crypto.core
Class SymmetricKey

java.lang.Object
oracle.security.crypto.core.SymmetricKey

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, java.security.Key, javax.crypto.SecretKey

Direct Known Subclasses:

DESKey

public class SymmetricKey

extends java.lang.Object

implements Key, javax.crypto.SecretKey

An encryption/decryption key used by a symmetric cipher.

See Also:

Serialized Form

Field Summary

Fields inherited from interface javax.crypto.SecretKey

serialVersionUID

Constructor Summary

SymmetricKey()
Creates a new symmetric key.

SymmetricKey(byte[] key)
Creates a new symmetric key with the given key material.

SymmetricKey(byte[] key, AlgorithmIdentifier algID)
Creates a new symmetric key with the given key material and algorithm identifier.

Method Summary

protected void	assertAllowExport() If either this key's export flag or the global export flag is set to false, this method throws a KeyExportException.
java.lang.Object	clone() Creates a deep copy of this SymmetricKey instance.
boolean	equals(java.lang.Object o) A shallow equals method that simply compares the key material of two SymmetricKey instances for equality.
void	erase() Erases the sensitive key material of a private or symmetric key, making the key un-usable.
void	finalize() Erases this object prior to being reclaimed by the garbage collector.
AlgorithmIdentifier	getAlgID() Returns the algorithm identifier of this symmetric key.
java.lang.String	getAlgorithm() Returns a description of this symmetric key.
boolean	getAllowExport() Returns false if plaintext export of this SymmetricKey's key material is not allowed; returns true if plaintext export is allowed.
int	getBitLength() Returns the number of bits required to represent the byte array wrapped by the SymmetricKey instance.
byte[]	getBytes() Returns a copy of the key bytes.
byte[]	getEncoded() Returns a copy of the key bytes.
java.lang.String	getFormat() Returns the format used in this key's encoding.
int	keySize() Returns the length of the key in bytes.
void	readExternal(java.io.ObjectInput is) Reads the input stream and initializes the symmetric key.
void	setAlgID(AlgorithmIdentifier algID) Sets the algorithm identifier of this symmetric key.
void	setAllowExport(boolean value) Set to false to disallow plaintext export of this SymmetricKey's key material; set to true to allow plaintext export if the global value in FIPS_140_2 is also set to true.
void	setBytes(byte[] keyBytes) Sets the actual bytes of the key.
java.lang.String	toString()
void	writeExternal(java.io.ObjectOutput os) Writes to the output stream the DER encoding of this object.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SymmetricKey

public SymmetricKey()

Creates a new symmetric key. Call setBytes to define the key material.

SymmetricKey

public SymmetricKey(byte[] key)

Creates a new symmetric key with the given key material.

Parameters:

key - The bytes of the symmetric key.

SymmetricKey

public SymmetricKey(byte[] key,
                    AlgorithmIdentifier algID)

Creates a new symmetric key with the given key material and algorithm identifier.

Parameters:

key - The bytes of the symmetric key.

algID - The algorithm identifier for this symmetric key.

Method Detail

getAlgID

public AlgorithmIdentifier getAlgID()

Returns the algorithm identifier of this symmetric key.

setAlgID

public void setAlgID(AlgorithmIdentifier algID)

Sets the algorithm identifier of this symmetric key.

getAlgorithm

public java.lang.String getAlgorithm()

Returns a description of this symmetric key.

Specified by:

getAlgorithm in interface java.security.Key

keySize

public int keySize()

Returns the length of the key in bytes.

setBytes

public void setBytes(byte[] keyBytes)

Sets the actual bytes of the key.

getBytes

public byte[] getBytes()

Returns a copy of the key bytes.

Returns:

The plaintext bytes of this key's material.

Throws:

KeyExportException - If plaintext key export is not allowed for this key or globally.

See Also:

setAllowExport(boolean), getAllowExport(), FIPS_140_2.setAllowKeyExport(boolean), FIPS_140_2.getAllowKeyExport(), Cipher.wrapKey(SymmetricKey key)

getEncoded

public byte[] getEncoded()

Returns a copy of the key bytes.

Specified by:

getEncoded in interface java.security.Key

Returns:

The plaintext bytes of this key's material.

Throws:

KeyExportException - If plaintext key export is not allowed for this key or globally.

See Also:

setAllowExport(boolean), getAllowExport(), FIPS_140_2.setAllowKeyExport(boolean), FIPS_140_2.getAllowKeyExport(), Cipher.wrapKey(SymmetricKey key)

getBitLength

public int getBitLength()

Returns the number of bits required to represent the byte array wrapped by the SymmetricKey instance.

This will always be 8 * the number of bytes in the key array or 0 if the array is null.

getFormat

public java.lang.String getFormat()

Returns the format used in this key's encoding.

Specified by:

getFormat in interface java.security.Key

Returns:

"RAW"

equals

public boolean equals(java.lang.Object o)

A shallow equals method that simply compares the key material of two SymmetricKey instances for equality.

Overrides:

equals in class java.lang.Object

erase

public void erase()

Description copied from interface: Key

Erases the sensitive key material of a private or symmetric key, making the key un-usable. Keys may be erased multiple times with no consequences.

Note: After erase() has been invoked, no other methods of the Key object are guaranteed to function correctly. In particular, invoking another method after erase() may result in a NullPointerException being thrown.

finalize

public void finalize()

Erases this object prior to being reclaimed by the garbage collector.

Note: There is no guarantee of when, if ever, finalize will be invoked by the Java runtime.

Overrides:

finalize in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

clone

public java.lang.Object clone()

Creates a deep copy of this SymmetricKey instance.

Overrides:

clone in class java.lang.Object

Returns:

A deep clone of the Key instance.

setAllowExport

public void setAllowExport(boolean value)

Set to false to disallow plaintext export of this SymmetricKey's key material; set to true to allow plaintext export if the global value in FIPS_140_2 is also set to true.

If either this value or the global value is false, the getBytes() and getEncoded() methods will throw a KeyExportException.

Parameters:

value - false to disallow plaintext key material export, true to allow.

Since:

3.0

See Also:

FIPS_140_2.setAllowKeyExport(boolean), Cipher.wrapKey(SymmetricKey key)

getAllowExport

public boolean getAllowExport()

Returns false if plaintext export of this SymmetricKey's key material is not allowed; returns true if plaintext export is allowed.

If either this value or the global value is false, the getBytes() and getEncoded() methods will throw a KeyExportException.

Returns:

false if plaintext key material export is not allowed, true if allowed.

Since:

3.0

See Also:

FIPS_140_2.getAllowKeyExport(), Cipher.wrapKey(SymmetricKey key)

assertAllowExport

protected void assertAllowExport()

If either this key's export flag or the global export flag is set to false, this method throws a KeyExportException.

Since:

3.0

See Also:

FIPS_140_2.getAllowKeyExport()

writeExternal

public void writeExternal(java.io.ObjectOutput os)
                   throws java.io.IOException

Writes to the output stream the DER encoding of this object.

Specified by:

writeExternal in interface java.io.Externalizable

Parameters:

os - The output stream to write the encoding to.

Throws:

java.io.IOException

readExternal

public void readExternal(java.io.ObjectInput is)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException

Reads the input stream and initializes the symmetric key.

Specified by:

readExternal in interface java.io.Externalizable

Parameters:

is - The stream to read from.

Throws:

java.io.IOException

java.lang.ClassNotFoundException

Skip navigation links