Standard implementation of the StringDigester interface.
This class lets the user specify the algorithm to be used for
creating digests, the size of the salt to be applied,
the number of times the hash function will be applied (iterations) and
the salt generator to be used.

This class avoids byte-conversion problems related to the fact of
different platforms having different default charsets, and returns
digests in the form of BASE64-encoded ASCII Strings.

This class is thread-safe.

Configuration

The algorithm, salt size, iterations and salt generator can take values
in any of these ways:

The result of the concatenation is encoded in BASE64
and returned as an ASCII String.

Put schematically in bytes:

DIGEST = |S|..(ssb)..|S|X|X|X|...|X|

S: salt bytes (plain, not digested). (OPTIONAL).

ssb: salt size in bytes.

X: bytes resulting from hashing (see below).

|X|X|X|...|X| =
H(H(H(..(it)..H(Z|Z|Z|...|Z|))))

H: Hash function (algorithm).

it: Number of iterations.

Z: Input for hashing (see below).

|Z|Z|Z|...|Z| =
|S|..(ssb)..|S|M|M|M...|M|

S: salt bytes (plain, not digested).

ssb: salt size in bytes.

M: message bytes.

If a random salt generator is used, two digests created for the same
message will always be different
(except in the case of random salt coincidence).
Because of this, in this case the result of the digest method
will contain both the undigested salt and the digest of the
(salt + message), so that another digest operation can be performed
with the same salt on a different message to check if both messages
match (all of which will be managed automatically by the
matches method).

To learn more about the mechanisms involved in digest creation, read
PKCS #5: Password-Based Cryptography Standard.

Charset to be used to obtain "digestable" byte arrays from input Strings.
Set to UTF-8.

This charset has to be fixed to some value so that we avoid problems
with different platforms having different "default" charsets.

It is set to UTF-8 because it covers the whole spectrum of characters
representable in Java (which internally uses UTF-16), and avoids the
size penalty of UTF-16 (which will always use two bytes for representing
each character, even if it is an ASCII one).

Setting this value to UTF-8 does not mean that Strings that originally
come for, for example, an ISO-8859-1 input, will not be correcly
digested. It simply provides a way of "fixing" the way a String will
be converted into bytes for digesting.

Charset to be used for encoding the resulting digests.
Set to US-ASCII.

The result of digesting some bytes can be any other bytes, and so
the result of digesting, for example, some LATIN-1 valid String bytes,
can be bytes that may not conform a "valid" LATIN-1 String.

Because of this, digests are always encoded in BASE64 after
being created, and this ensures that the
digests will make perfectly representable, safe ASCII Strings. Because
of this, the charset used to convert the digest bytes to the returned
String is set to US-ASCII.

The result of the concatenation is encoded in BASE64
and returned as an ASCII String.

Put schematically in bytes:

DIGEST = |S|..(ssb)..|S|X|X|X|...|X|

S: salt bytes (plain, not digested). (OPTIONAL).

ssb: salt size in bytes.

X: bytes resulting from hashing (see below).

|X|X|X|...|X| =
H(H(H(..(it)..H(Z|Z|Z|...|Z|))))

H: Hash function (algorithm).

it: Number of iterations.

Z: Input for hashing (see below).

|Z|Z|Z|...|Z| =
|S|..(ssb)..|S|M|M|M...|M|

S: salt bytes (plain, not digested).

ssb: salt size in bytes.

M: message bytes.

If a random salt generator is used, two digests created for the same
message will always be different
(except in the case of random salt coincidence).
Because of this, in this case the result of the digest method
will contain both the undigested salt and the digest of the
(salt + message), so that another digest operation can be performed
with the same salt on a different message to check if both messages
match (all of which will be managed automatically by the
matches method).

This method tells whether a message corresponds to a specific digest
or not by getting the salt with which the digest was created and
applying it to a digest operation performed on the message. If
new and existing digest match, the message is said to match the digest.

This method will be used, for instance, for password checking in
authentication processes.