IKeyCallback interface


package com.kryptel;

public interface IKeyCallback {
    // Allowed key material
    static final int USER_DEFINED_KEY     = 0x00000001; // User-defined raw binary key
    static final int FILE_BASED_KEY       = 0x00000002;
    static final int BINARY_KEY           = 0x00000010; // Key file
    static final int PROTECTED_KEY        = 0x00000020; // Key file + password
    static final int PUBLIC_KEY           = 0x00001000;
    static final int PASSWORD             = 0x00040000;
    static final int LOWERCASE_PASSWORD   = 0x00080000;
    static final int YUBIKEY              = 0x02000000;
    static final int YUBIKEY_PASSWORD     = 0x04000000;

    static final int PASSWORDS            = PASSWORD | LOWERCASE_PASSWORD;
    static final int KEY_FILES            = BINARY_KEY | PROTECTED_KEY;
    static final int YUBIKEYS             = YUBIKEY | YUBIKEY_PASSWORD;
                                              | PUBLIC_KEY | PASSWORDS | YUBIKEYS;

    KeyRecord Callback(Object arg, String prompt, int allowed, UUID expected) throws Exception;


This interface defines a key callback function; high-level Kryptel components such as storage handlers obtain key material by calling this client-provided callback.


KeyRecord Callback(Object arg, String prompt, int allowed, UUID expected) throws Exception;

A component calls this function to get key material in KeyRecord structure. The component's client program may obtain the key material in many possible ways – ask the user, get as a command-line parameter, read from a passwords manager database, and so on.


This argument is supplied by the client during component initialization; the component just passes it to the callback. It usually represents the execution context, or null is the operation is context-independent.
A string to be shown in a password dialog, usually the name of the file to be encrypted or decrypted.
A mask of allowed key material. If several types of key material are allowed, the corresponding bits are combined with bitwise OR.
Key file ID of the key file that we are expecting.


On return KeyRecord.keyMaterial must contain the ID of the key material. Depending on this field the remaining fields must be set as follows:

KeyRecord.password contains the password.
ID of a key file
KeyRecord.keyData contains the binary key and KeyRecord.keyPath is the path to the key file.
KeyRecord.password contains the password, KeyRecord.keyPath is the path to the key file, KeyRecord.keyAssociatedMaterial contains the ID of the key file, and KeyRecord.keyAssociatedData contains the binary key.

If this function returns null, the calling component will throw UserAbortException. Typically, the callback function should return null if the user requested abort, for instance, by pressing Cancel button in the password dialog.

Notes on allowed and expected

On encryption, the allowed argument indicates what types of key material the calling component supports (or allowed by the current capabilities set). The expected argument is always IDENT_NULL.

On decryption, both of these arguments are significant. The allowed argument typically corresponds to the expected argument, which is the ID of the required key material. More precisely, allowed is the result of ExpectedKeyMaterial function:

allowed = ApiHelpers.ExpectedKeyMaterial(expected);

In case of composite keys the dependency is more complex. Specifically, for a protected key allowed value is PROTECTED_KEY, and expected contains the ID of the key file.

Password matching

Kryptel storage offers a useful feature called password matching, i.e. trying the password without leaving the key callback. This way entering a wrong password does not abort the file open sequence.

For instance, when user opens a file in Kryptel Browser, the password is saved in the password cache. On the subsequent open operations the browser tries the passwords in the cache first, and if the matching password is found, the browser does not show the password dialog.

See IEncryptedStorageInfo.TestPassword for a detailed discussion.