ApiHelpers class

Declaration

package com.kryptel;

public final class ApiHelpers {

    public static String NormalizePassword(String password)

    public static KeyRecord PasswordToKeyRecord(String password,
                                                UUID hashCID) throws Exception

    public static KeyRecord PasswordToKeyRecord(String password,
                                                IKryptelComponent hashComp) throws Exception

    public static void ConvertPassword(KeyRecord keyRecord,
                                       UUID hashCID) throws Exception

    public static void ConvertPassword(KeyRecord keyRecord,
                                       IKryptelComponent hashComp) throws Exception

    public static int ExpectedKeyMaterial(UUID keyMaterial) throws Exception

    public static byte[] ComputeAreaHash(
                    RandomAccessFile dataFile, long start, long size,
                    IHashFunction hashFunc,
                    Object arg, IProgressCallback progressFunc,
                    Message.Code progressMessageCode) throws Exception
}

Description

This class contains a number of various helper functions. They are intended mostly for component developers, but some of them may be useful outside this library (specifically NormalizePassword and ComputeAreaHash).

NormalizePassword

public static String NormalizePassword(String password)

This function removes all excessive whitespace character from the password string. First, the function removes all whaitespce characters from the beginning and from the end of the string. On the second step, all sequences of whitespaces (including single ones) are replaced with single space characters.

Space is a character with hex code 0x20. Whitespace is a character for which Java Character.isWhitespace function returns true.

PasswordToKeyRecord

public static KeyRecord PasswordToKeyRecord(String password,
                                            UUID hashCID) throws Exception

public static KeyRecord PasswordToKeyRecord(String password,
                                            IKryptelComponent hashComp) throws Exception

Normalizes the password, hashes it, and returns a filled KeyRecord structure. On return, the structure will have three valid field: keyMaterial (IDENT_PASSWORD), password (normalized password), and keyData (hash value).

The first form creates the specified hash function and discards it on return. The second form uses the provided hash function and does not discard it.

The hashComp argument may be HMAC or, in general, any component that exports IMemoryBlockHash interface. PasswordToKeyRecord uses the supplied hash function 'as is', so you can tune it first with IHashFunctionParams interface (or IMacSetup interface if HMAC is used). The second form of the function (IKryptelComponent) does not discard the component.

public static void ConvertPassword(KeyRecord keyRecord,
                                   UUID hashCID) throws Exception

public static void ConvertPassword(KeyRecord keyRecord,
                                   IKryptelComponent hashComp) throws Exception

These functions work exactly as PasswordToKeyRecord family. The only difference is that the client provides the password in keyRecord. The keyMaterial field must contain either IDENT_PASSWORD or IDENT_LOWERCASE_PASSWORD. The function converts the password to lower case if necessary, normalizes and hashes it. On return the password field contains the normalized password, and the keyData field contains the hash value.

See PasswordToKeyRecord description for the discussion of hash function usage.

ExpectedKeyMaterial

public static int ExpectedKeyMaterial(UUID keyMaterial) throws Exception

This function translates key ID values (see KeyIdent class) to the corresponding key material mask (see IKeyCallback interface). Typically this function is used by key callbacks to check if the provided key material matches the allowed key material mask.

ComputeAreaHash

public static byte[] ComputeAreaHash(
                RandomAccessFile dataFile, long start, long size,
                IHashFunction hashFunc,
                Object arg, IProgressCallback progressFunc,
                Message.Code progressMessageCode) throws Exception

This function computes hash or HMAC of the specified byte range in a file.

Parameters

dataFile

Opened random access file.

start

Start of the range. This value must be between 0 and (filesize - 1).

size

Size of the range, must be>0. The whole range must lie within the file, i.e. start + size must not exceed the file size.

hashFunc

Hash function interface to be used for hash computing. The function uses this interface 'as is' and does not discard the hash function object on return.

arg

An argument for progressFunc callback. The function does not use it, just passes it to the callback.

progressFunc

Progress callback interface, may be null.

progressMessageCode

A code of the message displayed in the progress window, something like Computing file checksum.... If progressFunc is null, just specify any code, for example Message.Code.UnsupportedCap.