Module org.cryptomator.cryptolib

Package org.cryptomator.cryptolib.common

Class DestroyableSecretKey

java.lang.Object

org.cryptomator.cryptolib.common.DestroyableSecretKey

All Implemented Interfaces:

Serializable, AutoCloseable, Key, SecretKey, Destroyable

Direct Known Subclasses:

Masterkey

public class DestroyableSecretKey
extends Object
implements SecretKey, AutoCloseable

A SecretKey that (other than JDK's SecretKeySpec) actually implements Destroyable.

Furthermore, this implementation will not create copies when accessing getEncoded(). Instead it implements copy() and AutoCloseable in an exception-free manner. To prevent mutation of the exposed key, you would want to make sure to always work on scoped copies, such as in this example:

     // copy "key" to protect it from unwanted modifications:
     try (DestroyableSecretKey k = key.copy()) {
         // use "k":
         Cipher cipher = Cipher.init(k, ...)
         cipher.doFinal(...)
     } // "k" will get destroyed here
 

See Also:

Serialized Form

Field Summary

Fields inherited from interface javax.crypto.SecretKey

serialVersionUID

Constructor Summary

Constructors

Constructor	Description
DestroyableSecretKey(byte[] key, int offset, int len, String algorithm)	Creates a new destroyable secret key, copying of the provided raw key bytes.
DestroyableSecretKey(byte[] key, String algorithm)	Convenience constructor for DestroyableSecretKey(byte[], int, int, String)

Method Summary

Modifier and Type	Method	Description
void	close()	Same as destroy()
DestroyableSecretKey	copy()	Returns an independent copy of this key
void	destroy()
boolean	equals(Object o)
static DestroyableSecretKey	from(Key secretKey)	Casts or converts a given SecretKey to a DestroyableSecretKey
static DestroyableSecretKey	generate(SecureRandom csprng, String algorithm, int keyLenBytes)	Creates a new key of given length and for use with given algorithm using entropy from the given csprng.
String	getAlgorithm()
byte[]	getEncoded()	Returns the raw key bytes this instance wraps.
String	getFormat()
int	hashCode()
boolean	isDestroyed()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DestroyableSecretKey

public DestroyableSecretKey(byte[] key,
                            String algorithm)

Convenience constructor for DestroyableSecretKey(byte[], int, int, String)

Parameters:

key - The raw key data (will get copied)

algorithm - The algorithm name

DestroyableSecretKey

public DestroyableSecretKey(byte[] key,
                            int offset,
                            int len,
                            String algorithm)

Creates a new destroyable secret key, copying of the provided raw key bytes.

Parameters:

key - A byte[] holding the key material (relevant part will get copied)

offset - The offset within key where the key starts

len - The number of bytes beginning at offset to read from key

algorithm - The algorithm name

Method Detail

from

public static DestroyableSecretKey from(Key secretKey)

Casts or converts a given SecretKey to a DestroyableSecretKey

Parameters:

secretKey - The secret key

Returns:

Either the provided or a new key, depending on whether the provided key is already a DestroyableSecretKey

generate

public static DestroyableSecretKey generate(SecureRandom csprng,
                                            String algorithm,
                                            int keyLenBytes)

Creates a new key of given length and for use with given algorithm using entropy from the given csprng.

Parameters:

csprng - A cryptographically secure random number source

algorithm - The key algorithm

keyLenBytes - The length of the key (in bytes)

Returns:

A new secret key

getAlgorithm

public String getAlgorithm()

Specified by:

getAlgorithm in interface Key

getFormat

public String getFormat()

Specified by:

getFormat in interface Key

getEncoded

public byte[] getEncoded()

Returns the raw key bytes this instance wraps.

Important: Any change to the returned array will reflect in this key. Make sure to make a local copy if you can't rule out mutations.

Specified by:

getEncoded in interface Key

Returns:

A byte array holding the secret key

copy

public DestroyableSecretKey copy()

Returns an independent copy of this key

Returns:

New copy of this

destroy

public void destroy()

Specified by:

destroy in interface Destroyable

isDestroyed

public boolean isDestroyed()

Specified by:

isDestroyed in interface Destroyable

close

public void close()

Same as destroy()

Specified by:

close in interface AutoCloseable

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object