IEncryptedStorageInfo interface

Declaration

package com.kryptel.storage;

public interface IEncryptedStorageInfo {
  int GetStorageCapabilities() throws Exception;
  StorageStatistics GetStorageStatistics() throws Exception;

  byte[] GetAgentData() throws Exception;

  UUID GetCipherCID() throws Exception;
  CipherParameters GetCipherParameters() throws Exception;
  String GetCipherName() throws Exception;
  String GetCipherScheme() throws Exception;

  UUID GetCompressorCID() throws Exception;
  CompressorParameters GetCompressorParameters() throws Exception;
  String GetCompressorName() throws Exception;
  String GetCompressorScheme() throws Exception;

  UUID GetHashFunctionCID() throws Exception;
  HashFunctionParameters GetHashFunctionParameters() throws Exception;
  String GetHashFunctionName() throws Exception;
  String GetHashFunctionScheme() throws Exception;

  UUID GetKeyID() throws Exception;
  String GetKeyPath() throws Exception;

  boolean TestPassword(String password) throws Exception;
}

Description

As the name implies, this interface returns various information about the currently open Kryptel container. In order to get this interface, call IEncryptedStorage.GetStorageInfo.

GetStorageCapabilities

int GetStorageCapabilities() throws Exception;

This function returns a set of Constants.ESTOR_* flags describing allowed storage operations.

Unlike the other IEncryptedStorageInfo functions, this function may be called even if there is no open container. In this case it returns generic storage capabilites.

GetStorageStatistics

StorageStatistics GetStorageStatistics() throws Exception;

Returns StorageStatistics structure containing a large set of current container's statistical data.

This function returns null if the storage does not support statistics (i.e. ESTOR_STATISTICS flag in the storage capabilites mask is not set).

GetAgentData

byte[] GetAgentData() throws Exception;

Returns container's agent data or null if none present.

Storage handler does not use these data; it just keeps them for the client (an agent in most cases, hence the name agent data). What to store in the container agent area and how to use the stored data is up to the client. For instance, Kryptel file agents use this area to keep unencrypted container description.

GetCipherCID

UUID GetCipherCID() throws Exception;

Returns the container's cipher component ID (see com.kryptel.Guids class).

GetCipherParameters

CipherParameters GetCipherParameters() throws Exception;

Returns the cipher parameters packed into CipherParameters structure.

GetCipherName

String GetCipherName() throws Exception;

Returns the textual cipher name.

GetCipherScheme

String GetCipherScheme() throws Exception;

Returns the user-friendly name of the cipher scheme.

GetCompressorCID

UUID GetCompressorCID() throws Exception;

Returns the container's compressor component ID (see com.kryptel.Guids class).

GetCompressorParameters

CompressorParameters GetCompressorParameters() throws Exception;

Returns the cipher parameters packed into CompressorParameters structure.

GetCompressorName

String GetCompressorName() throws Exception;

Returns the textual compressor name.

GetCompressorScheme

String GetCompressorScheme() throws Exception;

Returns the user-friendly name of the compressor scheme.

GetHashFunctionCID

UUID GetHashFunctionCID() throws Exception;

Returns the container's hash function component ID (see com.kryptel.Guids class).

GetHashFunctionParameters

HashFunctionParameters GetHashFunctionParameters() throws Exception;

Returns the hash function parameters packed into HashFunctionParameters structure.

GetHashFunctionName

String GetHashFunctionName() throws Exception;

Returns the textual hash function name.

GetHashFunctionScheme

String GetHashFunctionScheme() throws Exception;

Returns the user-friendly name of the hash function scheme.

GetKeyID

UUID GetKeyID() throws Exception;

Returns the ID of the used key material. See Kryptel API Commons and com.kryptel.KeyIdent class.

GetKeyPath

String GetKeyPath() throws Exception;

Returns the file path of the currently used binary key. This function may return null or an empty string if the used key material is not a binary key, or if the user did not provide the key path to the key callback function.

See the description of KeyRecord structure, specifically its keyPath field.

TestPassword

public boolean TestPassword(String password) throws Exception

This function was introduced as a support for password caches. It may only be called in the context of a key callback function, when the handler has read the container header already, but has not started decrypting the directory yet. The function tests the argument password string against the container's password verificator and returns true if the password is correct.

Here is a simple example implementation of a password cache:

class KeyCallback implements IKeyCallback {
  private static final String CACHED_PASSWORD_1 = "abc";
  private static final String CACHED_PASSWORD_2 = "qwe";

  // The storage pointer is passed through the callback argument
  
  public KeyRecord Callback(Object arg, String prompt,
                            int allowed, UUID expected) throws Exception {
    assert (expected.equals(KeyIdent.IDENT_PASSWORD));
    IEncryptedStorage stor = (IEncryptedStorage)arg;
    IEncryptedStorageInfo info = stor.GetStorageInfo();

    KeyRecord kr = new KeyRecord();
    kr.keyMaterial = KeyIdent.IDENT_PASSWORD;

    if (info.TestPassword(CACHED_PASSWORD_1))
      kr.password = CACHED_PASSWORD_1;
    else if (info.TestPassword(CACHED_PASSWORD_2))
      kr.password = CACHED_PASSWORD_2;
    else
      throw new Exception("Looks like I forgot the damned thing...");
    return kr;
  }
}