public class Makwa
extends java.lang.Object
A Makwa
instance implements the Makwa password hashing
function. It is a context structure which contains some useful
parameters.
The Makwa password hashing function uses as input a "password" (actually an arbitrary sequence of bytes) and produces a binary output. The parameters for this processing are the following:
The Makwa output can be optionally encoded as a character string as is described in section A.4 of the Makwa specification. Such a string also contains the salt value, whether pre-hashing and/or post-hashing were applied, the work factor, and a checksum for the modulus and hash function. When the Makwa output is a string, the following restrictions apply:
The modulus can be provided as a BigInteger
, while the
private key can be represented as a MakwaPrivateKey
instance.
Both modulus and private key can be encoded into bytes, using a format
described in the MakwaPrivateKey
class comments.
A Makwa
instance contains the following parameters:
These parameters shall comply to the "character string" restrictions. They are used with the "simple API". That API is what most users of Makwa should use:
hashNewPassword(java.lang.String)
: hash a password into an encoded string.
The password is internally encoded into bytes using UTF-8. A new salt
is generated. The configured modulus, hash function, pre- and
post-hashing parameters, and work factor, are used for this
hashing.verifyPassword(java.lang.String, java.lang.String)
: verify a password with regards to the
provided reference output string.setNewWorkFactor(java.lang.String, int)
: modify an output string to increase
or decrease its work factor. This method is applicable only if no
post-hashing was applied. Decrease is possible only if the context
was initialized with a private key.unescrow(String)
: recover the source password. This is
possible only if no pre- or post-hashing was applied, and the context
was initialized with a private key.Other methods are provided, which use only the modulus (or private key) and hash function, but ignore the other initialization parameters. The pre-hashing, post-hashing length, and work factors are provided explicitly when required:
doHash(byte[], byte[], boolean, int, int)
: compute Makwa with explicit input, salt,
pre-hashing, post-hashing length, and work factor.doHashToString(byte[], byte[], boolean, int, int)
: same as doHash(byte[], byte[], boolean, int, int)
, and the output
is encoded into the character string format used by
hashNewPassword(java.lang.String)
.changeWorkFactor(byte[], int)
: modify the work factor; the work
factor difference is given as parameter. A negative work
factor difference is allowed if the context was initialized with a
private key.unescrow(byte[], byte[], int)
: recover the source
password. The salt and work factor must be provided explicitly.
This recovery works only if a private key is known.The doKDF()
methods give a direct access to the internal
KDF. These are static methods, usable without context initialization.
Each Makwa
instance is thread-safe and immutable.
Modifier and Type | Class and Description |
---|---|
class |
Makwa.DelegationContext
An instance of this class represents a delegated Makwa
computation.
|
class |
Makwa.Output
A
Makwa.Output instance represents a Makwa output,
with its parameters. |
Modifier and Type | Field and Description |
---|---|
static int |
SHA256
Symbolic constant designating hash function SHA-256.
|
static int |
SHA512
Symbolic constant designating hash function SHA-512.
|
Constructor and Description |
---|
Makwa(java.math.BigInteger modulus,
int hashFunction,
boolean defaultPreHash,
int defaultPostHashLength,
int defaultWorkFactor)
Create a new instance, using the provided modulus, underlying
hash function (a symbolic constant, e.g.
|
Makwa(byte[] param,
int hashFunction,
boolean defaultPreHash,
int defaultPostHashLength,
int defaultWorkFactor)
Create a new instance, using the provided parameter,
underlying hash function (a symbolic constant, e.g.
|
Makwa(MakwaPrivateKey privateKey,
int hashFunction,
boolean defaultPreHash,
int defaultPostHashLength,
int defaultWorkFactor)
Create a new instance, using the provided private key,
underlying hash function (a symbolic constant, e.g.
|
Modifier and Type | Method and Description |
---|---|
byte[] |
changeWorkFactor(byte[] prev,
int diffWF)
Change the work factor on a given Makwa output.
|
static byte[] |
createSalt()
Create a new salt value.
|
Makwa.Output |
decodeOutput(java.lang.String str)
Decode a string-encoded Makwa output into its constituent
elements (salt, pre-hashing flag, post-hashing length,
work factor, and binary output).
|
byte[] |
doHash(byte[] input,
byte[] salt,
boolean preHash,
int postHashLength,
int workFactor)
Apply Makwa on the provided parameters: input (already encoded
as bytes), salt, optional pre-hashing, post-hashing length,
and work factor.
|
Makwa.DelegationContext |
doHashDelegate(byte[] input,
byte[] salt,
boolean preHash,
int postHashLength,
MakwaDelegation mdeleg)
Begin delegated application of Makwa on some input value.
|
java.lang.String |
doHashToString(byte[] input,
byte[] salt,
boolean preHash,
int postHashLength,
int workFactor)
Apply Makwa on the provided parameters: input (already encoded
as bytes), salt, optional pre-hashing, post-hashing length,
and work factor.
|
static void |
doKDF(int hash,
byte[] inBuf,
byte[] outBuf)
Compute the Makwa KDF over the provided input.
|
static void |
doKDF(int hash,
byte[] inBuf,
byte[] outBuf,
int outOff,
int outLen)
Compute the Makwa KDF over the provided input.
|
static void |
doKDF(int hash,
byte[] inBuf,
int inOff,
int inLen,
byte[] outBuf)
Compute the Makwa KDF over the provided input.
|
static void |
doKDF(int hash,
byte[] inBuf,
int inOff,
int inLen,
byte[] outBuf,
int outOff,
int outLen)
Compute the Makwa KDF over the provided input.
|
java.lang.String |
encodeOutput(byte[] salt,
boolean preHash,
int postHashLength,
int workFactor,
byte[] output)
Encode a Makwa output (already computed) into a string.
|
java.lang.String |
hashNewPassword(java.lang.String pwd)
Hash a new password.
|
Makwa.DelegationContext |
hashNewPasswordDelegate(java.lang.String pwd,
MakwaDelegation mdeleg)
Begin delegated application of Makwa on some input password.
|
static byte[] |
processDelegationRequest(byte[] req)
Parse a delegation request, and compute the answer.
|
java.lang.String |
setNewWorkFactor(java.lang.String ref,
int newWorkFactor)
Set the work factor for a given Makwa output string to a
new value.
|
byte[] |
unescrow(byte[] output,
byte[] salt,
int workFactor)
Recover the input (encoded password) from the provided Makwa
output (binary).
|
byte[] |
unescrow(java.lang.String ref)
Recover the input (encoded password) from the provided Makwa
output string.
|
boolean |
verifyPassword(java.lang.String pwd,
java.lang.String ref)
Verify a password against a string previously produced with
hashNewPassword . |
Makwa.DelegationContext |
verifyPasswordDelegate(java.lang.String pwd,
java.lang.String ref,
MakwaDelegation... mdelegs)
Begin delegated application of Makwa on some input
password.
|
public static final int SHA256
public static final int SHA512
public Makwa(java.math.BigInteger modulus, int hashFunction, boolean defaultPreHash, int defaultPostHashLength, int defaultWorkFactor)
Create a new instance, using the provided modulus, underlying
hash function (a symbolic constant, e.g. Makwa.SHA256
),
where pre-hashing should be applied, the requested output
length (10 bytes or more; or 0 to apply no post-hashing),
and the default work factor. The default parameters are those
applied by hashNewPassword(java.lang.String)
. The default work factor
must be "encodable" (equal to 2 or 3 times a power of 2).
If hashFunction
is 0, then the default hash function
(SHA-256) is used. If defaultWorkFactor
is used, then
a work factor of value 4096 is used.
modulus
- the modulushashFunction
- the underlying hash functiondefaultPreHash
- whether pre-hashing must be applieddefaultPostHashLength
- post-hash length (10 or more), or 0defaultWorkFactor
- default work factorMakwaException
- on invalid parameterspublic Makwa(MakwaPrivateKey privateKey, int hashFunction, boolean defaultPreHash, int defaultPostHashLength, int defaultWorkFactor)
Create a new instance, using the provided private key,
underlying hash function (a symbolic constant, e.g. Makwa.SHA256
), where pre-hashing should be applied, the
requested output length (10 bytes or more; or 0 to apply no
post-hashing), and the default work factor. The default
parameters are those applied by hashNewPassword(java.lang.String)
.
The default work factor must be "encodable" (equal to 2 or 3
times a power of 2). A context with a known private key
allows for faster computations ("fast path"), unescrow,
and work factor decrease.
If hashFunction
is 0, then the default hash function
(SHA-256) is used. If defaultWorkFactor
is used, then
a work factor of value 4096 is used.
privateKey
- the private keyhashFunction
- the underlying hash functiondefaultPreHash
- whether pre-hashing must be applieddefaultPostHashLength
- post-hash length (10 or more), or 0defaultWorkFactor
- default work factorMakwaException
- on invalid parameterspublic Makwa(byte[] param, int hashFunction, boolean defaultPreHash, int defaultPostHashLength, int defaultWorkFactor)
Create a new instance, using the provided parameter,
underlying hash function (a symbolic constant, e.g. Makwa.SHA256
), where pre-hashing should be applied, the
requested output length (10 bytes or more; or 0 to apply no
post-hashing), and the default work factor. The default
parameters are those applied by hashNewPassword(java.lang.String)
.
The default work factor must be "encodable" (equal to 2 or 3
times a power of 2).
The "parameter" is an encoded modulus, a Makwa private key, or a set of delegation parameters (of which only the modulus part is used); if a private key is used, then the relevant features are unlocked: fast processing ("fast path"), unescrow, and work factor decrease.
If hashFunction
is 0, then the default hash function
(SHA-256) is used. If defaultWorkFactor
is used, then
a work factor of value 4096 is used.
param
- the modulus or private keyhashFunction
- the underlying hash functiondefaultPreHash
- whether pre-hashing must be applieddefaultPostHashLength
- post-hash length (10 or more), or 0defaultWorkFactor
- default work factorMakwaException
- on invalid parameterspublic java.lang.String hashNewPassword(java.lang.String pwd)
pwd
- the new passwordMakwaException
- on errorpublic boolean verifyPassword(java.lang.String pwd, java.lang.String ref)
hashNewPassword
. If the reference string is unsuitable
in some way (e.g. bad encoding, or using a modulus other than
the one used for this context), then an exception is thrown.
If the reference string is proper but the password does not
match, then false
is returned.pwd
- the password to verifyref
- the reference string (hashed password)true
on correct passwordMakwaException
- on format errorpublic java.lang.String setNewWorkFactor(java.lang.String ref, int newWorkFactor)
ref
string was produced without post-hashing; moreover, the
work factor can be decreased only if this instance was
initialized with a private key.ref
- the source Makwa output stringnewWorkFactor
- the new work factor valueMakwaException
- on invalid parameters or format errorpublic static byte[] createSalt()
public byte[] doHash(byte[] input, byte[] salt, boolean preHash, int postHashLength, int workFactor)
input
- the encoded inputsalt
- the salt valuepreHash
- true
to apply pre-hashingpostHashLength
- the requested output length (0 for no
post-hashing; the output then has the
same length as the modulus)workFactor
- the work factor (nonnegative)MakwaException
- on errorpublic java.lang.String doHashToString(byte[] input, byte[] salt, boolean preHash, int postHashLength, int workFactor)
input
- the encoded inputsalt
- the salt valuepreHash
- true
to apply pre-hashingpostHashLength
- the requested output length (0 for no
post-hashing; the output then has the
same length as the modulus)workFactor
- the work factor (nonnegative)MakwaException
- on errorpublic java.lang.String encodeOutput(byte[] salt, boolean preHash, int postHashLength, int workFactor, byte[] output)
salt
- the salt valuepreHash
- true
to apply pre-hashingpostHashLength
- the requested output length (0 for no
post-hashing; the output then has the
same length as the modulus)workFactor
- the work factor (nonnegative)output
- the Makwa binary outputMakwaException
- on errorpublic Makwa.Output decodeOutput(java.lang.String str)
str
- the output string to parseMakwaException
- on parse errorpublic byte[] changeWorkFactor(byte[] prev, int diffWF)
prev
) must have been produced without
post-hashing. The difference between the new work factor and
the previous one is provided as the diffWF
parameter;
if that value is negative then this is a work factor
decrease, which is possible only if this instance was
initialized with a private key.prev
- the previous Makwa output (binary)diffWF
- the work factor differenceMakwaException
- on format errorpublic byte[] unescrow(java.lang.String ref)
ref
- the Makwa output stringMakwaException
- on errorpublic byte[] unescrow(byte[] output, byte[] salt, int workFactor)
output
- the Makwa output stringsalt
- the salt valueworkFactor
- the work factorMakwaException
- on errorpublic Makwa.DelegationContext doHashDelegate(byte[] input, byte[] salt, boolean preHash, int postHashLength, MakwaDelegation mdeleg)
input
- the encoded inputsalt
- the salt valuepreHash
- true
to apply pre-hashingpostHashLength
- the requested output length (0 for no
post-hashing; the output then has the
same length as the modulus)mdeleg
- the delegation parametersMakwaException
- on errorpublic Makwa.DelegationContext hashNewPasswordDelegate(java.lang.String pwd, MakwaDelegation mdeleg)
Makwa
instance are used.pwd
- the password to hashmdeleg
- the delegation parametersMakwaException
- on errorpublic Makwa.DelegationContext verifyPasswordDelegate(java.lang.String pwd, java.lang.String ref, MakwaDelegation... mdelegs)
Begin delegated application of Makwa on some input password. This is for verifying the password; the provided reference string is used to obtain the hash parameters (salt, pre-hashing, post-hashing length, work factor). The returned context contains the values which are to be sent to the delegation server, and can finalize the verification when that server returns a value.
Several sets of delegation parameters can be provided; the first one which matches the reference string will be used. The intended use case is when a system manages hashed passwords with non-homogenous work factors.
pwd
- the password to hashref
- the reference hash value to compare withmdelegs
- the sets of delegation parametersMakwaException
- on errorpublic static byte[] processDelegationRequest(byte[] req)
req
- the delegation requestMakwaException
- on errorpublic static void doKDF(int hash, byte[] inBuf, byte[] outBuf)
hash
parameter is the symbolic identifier for the underlying hash
function.hash
- the underlying hash functioninBuf
- the input data bufferoutBuf
- the output bufferpublic static void doKDF(int hash, byte[] inBuf, byte[] outBuf, int outOff, int outLen)
hash
parameter is the symbolic identifier for the underlying hash
function.hash
- the underlying hash functioninBuf
- the input data bufferoutBuf
- the output bufferoutOff
- the output offsetoutLen
- the output lengthpublic static void doKDF(int hash, byte[] inBuf, int inOff, int inLen, byte[] outBuf)
hash
parameter is the symbolic identifier for the underlying hash
function.hash
- the underlying hash functioninBuf
- the input data bufferinOff
- the input data offsetinLen
- the input data lengthoutBuf
- the output bufferpublic static void doKDF(int hash, byte[] inBuf, int inOff, int inLen, byte[] outBuf, int outOff, int outLen)
hash
parameter is the symbolic identifier for the underlying hash
function.hash
- the underlying hash functioninBuf
- the input data bufferinOff
- the input data offsetinLen
- the input data lengthoutBuf
- the output bufferoutOff
- the output offsetoutLen
- the output length