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.