IEncryptedStorage interface
Contents
- Introduction to the Library
- Basic support package (com.kryptel.bslx)
- Kryptel API Commons package (com.kryptel)
- Cipher package (com.kryptel.cipher)
- Compressor package (com.kryptel.compressor)
- Exceptions package (com.kryptel.exceptions)
- Hash function package (com.kryptel.hash_function)
- MAC function package (com.kryptel.mac)
- Key-related functions (com.kryptel.key)
- Silver Key engine (com.kryptel.silver_key)
- Kryptel encrypted storage (com.kryptel.storage)
- Handlers and Agents
- Names and Unique Names
- Kryptel class
- FileStorageStatistics structure
- StorageStatistics structure
- IEncryptedStorage interface
- IEncryptedStorageInfo interface
- IEncryptedObject interface
- IEncryptedStream interface
- IEncryptedFileStorage interface
- IEncryptedFileStorageInfo interface
- IFileSystemAttributes interface
- IEncryptedDirectory interface
- IEncryptedFile interface
- Example: Password storage
- File encryption examples
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.