IEncryptedFileStorage interface

Declaration

package com.kryptel.storage;

public interface IEncryptedFileStorage {
  IEncryptedFileStorageInfo GetFileStorageInfo() throws Exception;

  int SetStorageControlFlags(int scFlags) throws Exception;
  CONTAINER_COMPRESSION_STRATEGY SetCompressionStrategy(
                    CONTAINER_COMPRESSION_STRATEGY strategy) throws Exception;

  void SetDescription(String descr) throws Exception;

  String GetEncryptedDescription() throws Exception;
  void SetEncryptedDescription(String descr) throws Exception;

  byte[] GetAssociatedData() throws Exception;
  void SetAssociatedData(byte[] adata) throws Exception;

  int[] GetRoots() throws Exception;
  IEncryptedDirectory GetRootDir(int target) throws Exception;

  void Create(String path,
              IKryptelComponent cipher,
              IKryptelComponent compressor,
              IKryptelComponent hashFunc,
              UUID handler, Object keyArg, IKeyCallback keyFunc) throws Exception;
  void Open(String path, IEncryptedStorage.CONTAINER_ACCESS_MODE mode,
            Object keyArg, IKeyCallback keyFunc) throws Exception;

  void Close() throws Exception;
  void Compress() throws Exception;
  void Discard() throws Exception;
}

Description

This is the top-level File Agent interface representing a file-oriented encrypted container. See Kryptel Storage Model for a discussion of generic Kryptel encrypted storage and how do agents adapt it to specific tasks, in particular, to represent a file system.

GetFileStorageInfo

IEncryptedFileStorageInfo GetFileStorageInfo() throws Exception;

Returns IEncryptedFileStorageInfo interface that provides various information about specific container and storage in general.

SetStorageControlFlags

int SetStorageControlFlags(int scFlags) throws Exception;

Sets storage control flags returning the previous flags. Flags Constants.FSCF_* are used to fine tune the agent's behavior.

SetCompressionStrategy

CONTAINER_COMPRESSION_STRATEGY SetCompressionStrategy(
                CONTAINER_COMPRESSION_STRATEGY strategy) throws Exception;

Sets a new compression strategy for the storage and returns the previous value. The interface instance must not be linked to an open container; this function will throw exception if Create or Open has already been called.

SetDescription

void SetDescription(String descr) throws Exception;

Attaches an unencrypted description to the currently open container. The description is stored in the container's agent data area as zero-terminated plain UTF-16 text.

Specifying null as an argument removes the existing description without adding a new one.

An attached unencrypted description can be read using function IEncryptedFileStorageInfo.GetDescription.

GetEncryptedDescription

String GetEncryptedDescription() throws Exception;

Returns the container's encrypted description or an empty string if there is none. Other implementations may return null so check both the conditions:

String descr = storage.GetEncryptedDescription();
if (descr != null && !descr.isEmpty()) {
  // Encrypted description present
}

SetEncryptedDescription

void SetEncryptedDescription(String descr) throws Exception;

Attaches an encrypted description to the currently open container. Unlike the desciption attached with SetDescription function, this description is stored in the data stream of the container's root object (which automatically makes it encrypted).

Specifying null as an argument removes the existing description without adding a new one.

GetAssociatedData

byte[] GetAssociatedData() throws Exception;

Fetches the container's associated data. For a detailed discussion of associated data see Kryptel Agents, in particular, the note titled File Agent vs. Backup Agent.

void SetAssociatedData(byte[] adata) throws Exception;

Stores the argument as the container's associated data. For a detailed discussion of associated data see Kryptel Agents, in particular, the note titled File Agent vs. Backup Agent.

GetRoots

int[] GetRoots() throws Exception;

Returns an array of targets for which root directories are present in the currently open container.

For a more detailed discussion see Kryptel Agents, the Notes part.

GetRootDir

IEncryptedDirectory GetRootDir(int target) throws Exception;

Get IEncryptedDirectory of the root folder corresponding to the specified target. For File Agent the only supported target is TARGET_DEFAULT, which represents the whole container.

Backup Agent supports the whole set of targets; use GetRoots to get the list of the targets for which root directories are present.

If there is no root for the specified target, a new root directory will be created.

For a more detailed discussion see Kryptel Agents, the Notes part.

Create

void Create(String path,
            IKryptelComponent cipherComp,
            IKryptelComponent compressorComp,
            IKryptelComponent hashFuncComp,
            UUID handler,
            Object arg, IKeyCallback keyFunc) throws Exception;

Creates a new file container.

path

Path to the container file to be created. If the file already exists, the function will throw an exception.

cipherComp

Cipher component to be used for encryption. Set the desired component parameters before passing it to this function. Don't set the cipher key (obtained via IKeyCallback callback) and cipher initialization vector (generated randomly for every item).

compressorComp

Compressor component to be used to compress container directory and data streams. Set the desired component parameters before passing it to this function. Don't set the compression level; encryption jobs will request it for every file via ICompressionLevelCallback callback.

hashFuncComp

Hash function component that will be used for HMAC computation. Set the desired component parameters before passing it to this function.

handler

Component ID of the storage handler to be used for container creation. Typically it is CID_STORAGE.

arg

Context-specific argument for the key callback. The handler passes this argument to keyFunc as is.

keyFunc

IKeyCallback pointer, must not be null.

The handler does not use the passed cipher, compressor, and hash function components but clones them with IComponentState.Clone instead. That is, it is safe to use those components for some other purpose after calling Create.

Open

void Open(String path, IEncryptedStorage.CONTAINER_ACCESS_MODE mode,
          Object keyArg, IKeyCallback keyFunc) throws Exception;

Opens an existing file container.

path

Path to an existing container file.

mode

The required open mode. If it is CONT_READ_WRITE then the container should be open for reading and writing. If it is CONT_READ_ONLY then it should be open in the read-only mode. If it is CONT_ANY then the handler tries to open the container in the read/write mode first; if failed, the handler opens the container in the read-only mode. In order to check what operations are allowed for the container (i.e. in which mode it is open), use IEncryptedFileStorageInfo.GetFileStorageCapabilities.

arg

Context-specific argument for the key callback. The handler passes this argument to keyFunc as is.

keyFunc

IKeyCallback pointer, must not be null.

Close

void Close() throws Exception;

Closes the currently open container, possibly compressing it (depending on the current compression strategy).

Compress

void Compress() throws Exception;

Closes and compresses the currently open container.

Discard

void Discard() throws Exception;

Closes the currently open container discarding all changes made to it. The state of the container is returned to the state before the Open call; in case of a newly created container it simply gets deleted.