IEncryptedStorage interface

Declaration

package com.kryptel.storage;

public interface IEncryptedStorage {
  enum CONTAINER_COMPRESSION_STRATEGY { KRCONT_COMPRESS_NEVER,
                                        KRCONT_COMPRESS_ALWAYS,
                                        KRCONT_COMPRESS_SMART };
  enum CONTAINER_ACCESS_MODE { CONT_READ_WRITE, CONT_READ_ONLY, CONT_ANY };


  IEncryptedStorageInfo GetStorageInfo() throws Exception;

  CONTAINER_COMPRESSION_STRATEGY SetCompressionStrategy(
                    CONTAINER_COMPRESSION_STRATEGY strategy) throws Exception;

  void SetAgentData(byte[] data, int start, int size) throws Exception;

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

  IEncryptedObject Open(String path, CONTAINER_ACCESS_MODE mode,
                        Object arg, IKeyCallback keyFunc) throws Exception;

  IEncryptedObject GetRootObject() throws Exception;

  boolean IsModified() throws Exception;

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

Description

IEncryptedStorage interface represents Kryptel container.

GetStorageInfo

IEncryptedStorageInfo GetStorageInfo() throws Exception;

Returns IEncryptedStorageInfo interface, which provides full information about the container.

This function may also be called with no container open.

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.

KRCONT_COMPRESS_NEVER

Container never gets compressed. Deleted and replaced files remain accessible and may be undeleted. Container operations are very fast, but the size of the container may grow uncontrollable if the user replaces many large files. This mode is best on slow USB devices, where compressing a large container may take a lot of time.

KRCONT_COMPRESS_ALWAYS

The storage handler initiates compression as soon as a gap appears, no matter how small. Deleting a small file in a large container is the worst scenario for this mode. On a slow USB flash drive closing such a container (when most compression work occurs) may take literally forever. The best scenario this strategy is a container with a single large file inside – compression will not take noticeable additional work in this case.

KRCONT_COMPRESS_SMART

This is the default mode fitting most usage scenarios. Compression does not occur until gap size exceeds some threshold.

SetAgentData

void SetAgentData(byte[] data, int start, int size) throws Exception;

Stores size of data starting at position start.

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.

In order to read the container agent data use IEncryptedStorageInfo.GetAgentData.

Create

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

Creates a new Kryptel 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; it will be set by the storage handler. It is always CT_MAX_COMPRESSION for directory area; for data streams it is specified as an argument of IEncryptedStream.CreateStream on data stream creation.

hashFuncComp

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

agent

Component ID of the associated agent. The handler does not use this ID, just stores it in the container header. For a non-file container not using any agent this may be NULL_GUID or any custom UUID. For example, Yubikey manager uses CID_YUBIKEY_STORAGE, which does not correspond to any agent and simply marks the container as a Yubikey storage (see Yubikey Implementation Notes). If the function is called by an agent, the agent must specify its Component ID here to ensure that opening this container via Kryptel.GetContainerHandlers will work properly.

arg

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

keyFunc

IKeyCallback pointer, must not be null.

If the container has been created successfully, the function returns IEncryptedObject of the container's root object, which always exists and is created automatically.

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

IEncryptedObject Open(String path, CONTAINER_ACCESS_MODE mode,
                      Object arg, IKeyCallback keyFunc) throws Exception;

Opens an existing 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 IEncryptedStorageInfo.GetStorageCapabilities.

arg

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

keyFunc

IKeyCallback pointer, must not be null.

If the container has been opened successfully, the function returns IEncryptedObject of the container's root object.

GetRootObject

IEncryptedObject GetRootObject() throws Exception;

Returns IEncryptedObject of the container's root object.

IsModified

boolean IsModified() throws Exception;

Returns true if the container has been modified.

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.