io.jsonwebtoken.security

Interface Password

All Superinterfaces:

Destroyable, Key, SecretKey, Serializable

public interface Password
extends SecretKey, Destroyable

A Key suitable for use with password-based key derivation algorithms.

Usage Warning

Because raw passwords should never be used as direct inputs for cryptographic operations (such as authenticated hashing or encryption) - and only for derivation algorithms (like password-based encryption) - Password instances will throw an exception when used in these invalid contexts. Specifically, calling a Password's getEncoded() method (as would be done automatically by the JCA subsystem during direct cryptographic operations) will throw an UnsupportedOperationException.

Since:

0.12.0

See Also:

toCharArray()

Field Summary

Fields inherited from interface javax.crypto.SecretKey

serialVersionUID

Method Summary

Methods

Modifier and Type	Method and Description
char[]	toCharArray() Returns a new clone of the underlying password character array for use during derivation algorithms.

Methods inherited from interface java.security.Key

getAlgorithm, getEncoded, getFormat

Methods inherited from interface javax.security.auth.Destroyable

destroy, isDestroyed

Method Detail

toCharArray

char[] toCharArray()

Returns a new clone of the underlying password character array for use during derivation algorithms. Like all SecretKey implementations, if you wish to clear the backing password character array for safety/security reasons, call the Destroyable.destroy() method, ensuring that both the character array is cleared and the Password instance can no longer be used.

Usage

Because a new clone is returned from this method each time it is invoked, it is expected that callers will clear the resulting clone from memory as soon as possible to reduce probability of password exposure. For example:

 char[] clonedPassword = aPassword.toCharArray();
 try {
     doSomethingWithPassword(clonedPassword);
 } finally {
     // guarantee clone is cleared regardless of any Exception thrown:
     java.util.Arrays.fill(clonedPassword, '');
 }
 

Returns:

a clone of the underlying password character array.