makwa

Class Makwa

java.lang.Object

makwa.Makwa

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:

• Modulus: a big integer of at least 1273 bits, at most 32768 bits. It is a composite integer, product of two prime integers; the two primes constitute the private key; Makwa can use either the modulus or the private key; processing with the private key is faster, and unlocks some features such as unescrowing.
• Hash function: a hash function is used internally, and is identified by a symbolic constant. The value 0 selects the default function, which is SHA-256.
• Salt: an arbitary sequence of bytes. Salts should strive to achieve worldwide uniqueness. This implementation generates 16-byte salts which are serialized UUID.
• Pre-hashing: a boolean flag. If pre-hashing is applied, then inputs can have an arbitrary length; however, pre-hashing is not compatible with unescrow.
• Post-hashing length: the requested output length. If that length is set to 0, then the Makwa output is the primary output: the encoding of an integer, as long as the modulus. If post-hashing is applied, then the binary output will consist of exactly that many unbiased bytes, suitable for usage as key for a symmetric cryptographic algorithm. Post-hashing allows for a shorter and unbiased output; however, it prevents offline work factor changes and unescrow.
• Work factor: the internal number of iterations (repeated modular squarings). The processing time (without the private key) is proportional to the work factor. The work factor must be a nonnegative integer.

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 post-hashing length must be either 0 (no post hashing) or an integer greater than or equal to 10 bytes.
• The work factor must be equal to 2 or 3 multiplied by a power of 2. The smallest acceptable work factors are 2, 3, 4, 6, 8, 12, 16, 24, 32...

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:

• the modulus;
• optionally, the private key;
• the hash function to use;
• whether pre-hashing should be applied by default;
• whether post-hashing should be applied by default, and, if yes, the default output length (in bytes);
• the default work factor.

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.

Nested Class Summary

Nested Classes

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.

Field Summary

Fields

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 Summary

Constructors

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.

Method Summary

Methods

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.

Methods inherited from class java.lang.Object

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

Field Detail

SHA256

public static final int SHA256

Symbolic constant designating hash function SHA-256.

See Also:

Constant Field Values

SHA512

public static final int SHA512

Symbolic constant designating hash function SHA-512.

See Also:

Constant Field Values

Constructor Detail

Makwa

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.

Parameters:

modulus - the modulus

hashFunction - the underlying hash function

defaultPreHash - whether pre-hashing must be applied

defaultPostHashLength - post-hash length (10 or more), or 0

defaultWorkFactor - default work factor

Throws:

MakwaException - on invalid parameters

Makwa

public 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.

Parameters:

privateKey - the private key

hashFunction - the underlying hash function

defaultPreHash - whether pre-hashing must be applied

defaultPostHashLength - post-hash length (10 or more), or 0

defaultWorkFactor - default work factor

Throws:

MakwaException - on invalid parameters

Makwa

public 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.

Parameters:

param - the modulus or private key

hashFunction - the underlying hash function

defaultPreHash - whether pre-hashing must be applied

defaultPostHashLength - post-hash length (10 or more), or 0

defaultWorkFactor - default work factor

Throws:

MakwaException - on invalid parameters

Method Detail

hashNewPassword

public java.lang.String hashNewPassword(java.lang.String pwd)

Hash a new password. The default parameters (pre-hashing, post-hashing length, work factor) are applied. A new 16-byte salt is internally generated. The returned string contains the parameters and salt.

Parameters:

pwd - the new password

Returns:

the hashed password (encoded

Throws:

MakwaException - on error

verifyPassword

public boolean verifyPassword(java.lang.String pwd,
                     java.lang.String ref)

Verify a password against a string previously produced with 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.

Parameters:

pwd - the password to verify

ref - the reference string (hashed password)

Returns:

true on correct password

Throws:

MakwaException - on format error

setNewWorkFactor

public java.lang.String setNewWorkFactor(java.lang.String ref,
                                int newWorkFactor)

Set the work factor for a given Makwa output string to a new value. The new output string is returned. The new work factor value must be encodable (equal to 2 or 3 times a power of 2). This method can work only if the ref string was produced without post-hashing; moreover, the work factor can be decreased only if this instance was initialized with a private key.

Parameters:

ref - the source Makwa output string

newWorkFactor - the new work factor value

Returns:

the transformed Makwa output string

Throws:

MakwaException - on invalid parameters or format error

createSalt

public static byte[] createSalt()

Create a new salt value. This method returns an encoded UUID, which should ensure worldwide uniqueness with very high probability.

Returns:

a new salt value

doHash

public 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.

Parameters:

input - the encoded input

salt - the salt value

preHash - true to apply pre-hashing

postHashLength - the requested output length (0 for no post-hashing; the output then has the same length as the modulus)

workFactor - the work factor (nonnegative)

Returns:

the Makwa binary output

Throws:

MakwaException - on error

doHashToString

public 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. The output is returned as an encoded string; the work factor must then be "encodable", and the post-hashing length (if non-zero) must be at least 10.

Parameters:

input - the encoded input

salt - the salt value

preHash - true to apply pre-hashing

postHashLength - the requested output length (0 for no post-hashing; the output then has the same length as the modulus)

workFactor - the work factor (nonnegative)

Returns:

the Makwa output (as a string)

Throws:

MakwaException - on error

encodeOutput

public java.lang.String encodeOutput(byte[] salt,
                            boolean preHash,
                            int postHashLength,
                            int workFactor,
                            byte[] output)

Encode a Makwa output (already computed) into a string. The parameters used to compute the output must be specified. The work factor and post-hashing length must comply with the "string encoding" constraints. The binary output must be consistent with the parameters.

Parameters:

salt - the salt value

preHash - true to apply pre-hashing

postHashLength - 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 output

Returns:

the string-encoded output

Throws:

MakwaException - on error

decodeOutput

public 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). The provided string must match the modulus and hash function used by this instance.

Parameters:

str - the output string to parse

Returns:

the decoded output

Throws:

MakwaException - on parse error

changeWorkFactor

public byte[] changeWorkFactor(byte[] prev,
                      int diffWF)

Change the work factor on a given Makwa output. The provided output (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.

Parameters:

prev - the previous Makwa output (binary)

diffWF - the work factor difference

Returns:

the new Makwa output (binary)

Throws:

MakwaException - on format error

unescrow

public byte[] unescrow(java.lang.String ref)

Recover the input (encoded password) from the provided Makwa output string. This method works only if a private key is known, and no pre- or post-hashing was applied.

Parameters:

ref - the Makwa output string

Returns:

the unescrowed input

Throws:

MakwaException - on error

unescrow

public byte[] unescrow(byte[] output,
              byte[] salt,
              int workFactor)

Recover the input (encoded password) from the provided Makwa output (binary). This method works only if a private key is known, and no pre- or post-hashing was applied. The salt and work factor must also be provided explicitly.

Parameters:

output - the Makwa output string

salt - the salt value

workFactor - the work factor

Returns:

the unescrowed input

Throws:

MakwaException - on error

doHashDelegate

public Makwa.DelegationContext doHashDelegate(byte[] input,
                                     byte[] salt,
                                     boolean preHash,
                                     int postHashLength,
                                     MakwaDelegation mdeleg)

Begin delegated application of Makwa on some input value. The returned context contains the values which are to be sent to the delegation server, and can finalize the hash value when that server returns a value.

Parameters:

input - the encoded input

salt - the salt value

preHash - true to apply pre-hashing

postHashLength - the requested output length (0 for no post-hashing; the output then has the same length as the modulus)

mdeleg - the delegation parameters

Returns:

the delegation context

Throws:

MakwaException - on error

hashNewPasswordDelegate

public Makwa.DelegationContext hashNewPasswordDelegate(java.lang.String pwd,
                                              MakwaDelegation mdeleg)

Begin delegated application of Makwa on some input password. This is for a new hash value; a new salt value is internally generated. The returned context contains the values which are to be sent to the delegation server, and can finalize the hash value when that server returns a value. The pre-hashing, post-hashing length and work factors used to initialize this Makwa instance are used.

Parameters:

pwd - the password to hash

mdeleg - the delegation parameters

Returns:

the delegation context

Throws:

MakwaException - on error

verifyPasswordDelegate

public 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.

Parameters:

pwd - the password to hash

ref - the reference hash value to compare with

mdelegs - the sets of delegation parameters

Returns:

the delegation context

Throws:

MakwaException - on error

processDelegationRequest

public static byte[] processDelegationRequest(byte[] req)

Parse a delegation request, and compute the answer. This static method is what a delegation server may use.

Parameters:

req - the delegation request

Returns:

the encoded answer

Throws:

MakwaException - on error

doKDF

public static void doKDF(int hash,
         byte[] inBuf,
         byte[] outBuf)

Compute the Makwa KDF over the provided input. The hash parameter is the symbolic identifier for the underlying hash function.

Parameters:

hash - the underlying hash function

inBuf - the input data buffer

outBuf - the output buffer

doKDF

public static void doKDF(int hash,
         byte[] inBuf,
         byte[] outBuf,
         int outOff,
         int outLen)

Compute the Makwa KDF over the provided input. The hash parameter is the symbolic identifier for the underlying hash function.

Parameters:

hash - the underlying hash function

inBuf - the input data buffer

outBuf - the output buffer

outOff - the output offset

outLen - the output length

doKDF

public static void doKDF(int hash,
         byte[] inBuf,
         int inOff,
         int inLen,
         byte[] outBuf)

Compute the Makwa KDF over the provided input. The hash parameter is the symbolic identifier for the underlying hash function.

Parameters:

hash - the underlying hash function

inBuf - the input data buffer

inOff - the input data offset

inLen - the input data length

outBuf - the output buffer

doKDF

public 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. The hash parameter is the symbolic identifier for the underlying hash function.

Parameters:

hash - the underlying hash function

inBuf - the input data buffer

inOff - the input data offset

inLen - the input data length

outBuf - the output buffer

outOff - the output offset

outLen - the output length