Kryptel Agents

Kryptel agents (namely, File Agent and Backup Agent) work as intermediaries between client software (such as Kryptel Browser) and the storage handler. It ‘maps’ file system objects to (rather abstract) encrypted storage objects. The storage object's attribute block contains all required information about the filesystem object being represented. If the filesystem object has associated data (for instance, it is a non-empty file), the data are stored in the object's data stream.

Kryptel Agent's Objects

Although we often refer to agent's objects as filesystem objects, not all of them are really filesystem ones. Some are used internally and are not accessible directly through the agent's interfaces (alternate streams), and some are not filesystem objects (thumbnails).

Target

Target represents either a drive root (for example, ‘Drive C’), or a folder that has no fixed filesystem path (for example, ‘My Documents’).

Size	Description
4	ID_TARGET
4	Target (a value from bslx::TARGETS enumeration)

Directory

Size	Description
4	ID_DIRECTORY
1	System code for system-dependent attributes
3	Size of system-dependent attributes (0 if not present)
8	System-independent time stamp (number of seconds since Jan 1, 1970)
STR	Directory name
STR	Directory description
. . .	System-dependent attributes

STR represents a UTF-16 string; first word (2 bytes) contains the string length in characters. The string does not contain trailing zero. Each UNICODE character occupies 2 bytes.

File

File object can have children objects representing alternate streams and/or thumbnails.

Size	Description
4	ID_FILE
1	System code for system-dependent attributes
3	Size of system-dependent attributes (0 if not present)
8	System-independent time stamp (number of seconds since Jan 1, 1970)
4	Number of records in allocation table (-1 if not sparse)
8	Total size (not present if not sparse)
. . .	Allocation table (not present if not sparse); each record consists of two 64-bit values – range start and range size.
STR	File name
STR	File description
STR	File keywords (string of comma-separated keywords / keyphrases)
. . .	System-dependent attributes

STR represents a UTF-16 string; first word (2 bytes) contains the string length in characters. The string does not contain trailing zero. Each UNICODE character occupies 2 bytes.

If the file has non-zero length, the file contents is stored in the object's data stream.

Alternate Stream

Alternate stream is represented as a child object of the file's storage object. An alternate stream object is invalid outside of a file object.

Size	Description
4	ID_STREAM
4	Number of records in allocation table (-1 if not sparse)
8	Total size (not present if not sparse)
. . .	Allocation table (not present if not sparse); each record consists of two 64-bit values – range start and range size.
STR	Stream name

STR represents a UTF-16 string; first word (2 bytes) contains the string length in characters. The string does not contain trailing zero. Each UNICODE character occupies 2 bytes.

If the alternate stream has non-zero length, the stream contents is stored in the object's data stream.

Thumbnails

Thumbnail set is represented as a child object of the corresponding file's storage object. A thumbnail object is invalid outside of a file object.

Size	Description
4	ID_THUMBNAILS
4	Size of 64x64 jpeg thumbnail
4	Size of 128x128 jpeg thumbnail
4	Size of 256x256 jpeg thumbnail

Thumbnails are stored sequentally in the object's data stream.

System-dependent attributes

Different implementations stores different sets of system-specific attributes. If the decrypting application does not support the specific set of attrinutes, it should ignore them completely.

Windows implementations

Windows Directory Attributes

Size	Description
8	Creation time (FILETIME)
4	Directory attributes (set of FILE_ATTRIBUTE_* values)

Windows File Attributes

Size	Description
8	Creation time (FILETIME)
8	Last access time (FILETIME)
8	Last write time (FILETIME)
4	File attributes (set of FILE_ATTRIBUTE_* values)

Other Structures

Agent-owned Recovery Data

Size	Description
4	Number of records in allocation table (-1 if not sparse)
6	Total size (not present if not sparse)
. . .	Allocation table (not present if not sparse); each record consists of two 48-bit values – range start and range size.
. . .	Relative path (zero-terminated UTF-16 string)

Constants

System codes

SYSTEM_NEUTRAL          0
SYSTEM_WINDOWS          1
SYSTEM_WINDOWS_MOBILE   5
SYSTEM_LINUX            10
SYSTEM_MAC              20

SYSTEM_NEUTRAL means that no system-specific attributes provided.

Identifiers

ID_TARGET               0x3E050B22
ID_DIRECTORY            0x3E050B25
ID_FILE                 0x3E050B2B
ID_STREAM               0x3E050BCB
ID_THUMBNAILS           0x3E050BEB

Notes

File Agent vs. Backup Agent

Both Backup Agent and File Agent organize storage in similar manner and, in fact, share most code. The most important difference is targets.

File Agent does not support targets; the storage root object represents the root directory (for the sake of common approach it is assumed to be TARGET_DEFAULT).

In case of Backup Agent, the container root object is not mapped to anything; it just contain a collection of objects representing targets' root directories. Empty root object (no target roots) is allowed; in this case the container will be of course empty.

File Agent can't have associated data; any attempt to call the GetAssociatedData and SetAssociatedData methods will result the 'unsupported operation' exception.

Backup Agent stores associated data in the root object's attribute block. In case of Backup Agent associated data is the associated fileset definition. If there is no associated data, then the container is a backup; otherwise it is a fileset, and the associated data contains the definition (.fs) text file.

Both the agents use the agent data area to store the unencrypted container description, and the root object's stream to store the encrypted one. Descriptions are UTF-16 zero-delimited strings.

TARGET_DEFAULT

As was mentioned above, TARGET_DEFAULT is the only target that File Agent has; all other targets belong exclusively to Backup Agent. Backup Agent also supports TARGET_DEFAULT, but for Backup Agent that target has a very special meaning. It does not correspond to any real target, but rather to the whole container, like with File Agent. However, unlike File Agent, Backup Agent does not resolve TARGET_DEFAULT to fully functional IEncryptedDirectory; it supports only a few methods: the batch encryption functions, which perform group backup, and the Decrypt method, which restores the whole container contents (the wzsTargetDir argument can be used for restoring to an alternate location).

The reason for introducing this backup pseudo-target is the need to maintain integral progress bar. While per-target operations are sufficient from the datacentric point of view, they cannot maintain a persistent progress bar required for a script-driven backup, or for whole container restore operation.

Other Features

Alternate streams are represented as children objects of the file object. They are not directly accessible through the agent interfaces, however IEncryptedDirectory::Store and IEncryptedDirectory::Extract are stream-aware and process files with alternate streams correctly.

The same is true for sparse files. Although the Store/Extract functions retain sparseness, the application directly accessing the contents through the IEncryptedStream interface has no way of knowing if the file being read is sparse or not. Nor there is a way to create an allocation table for a sparse file without directly calling the underlying storage handler's interfaces.