A secure file container. More...
#include <aegis_storage.h>
Public Types | |
enum | visibility_t { vis_global, vis_shared, vis_private } |
The visibility of a store. Defined when a storage is created and cannot be changed afterwards. More... | |
enum | protection_t { prot_signed, prot_encrypted } |
The protection method of a storage. Defined when a storage is created and cannot be changed afterwards. More... | |
enum | status_t { writable, readable, no_access } |
Access status of a store. More... | |
typedef std::vector< const char * > | stringlist |
A list of strings. | |
Public Member Functions | |
storage (const char *name, const char *owner, visibility_t visibility, protection_t protection) | |
Create a new store or open an existing one. | |
storage (const char *name, visibility_t visibility, protection_t protection) | |
Create a new store or open an existing one with the application id. | |
~storage () | |
Destructor. Release memory allocations. | |
bool | remove_all_files () |
Erase the storage permanently. If the storage is encrypted, also the member files fill be erase. Use cautiously. | |
size_t | get_files (stringlist &names) |
Get a list of the files in the store. | |
ssize_t | get_ufiles (stringlist &names) |
Get a list of the actual files that contain the content in the store, including the index file. | |
void | release (stringlist &list) |
Release a stringlist after use. | |
bool | contains_file (const char *pathname) |
Check if the store contains the given file. | |
bool | contains_link (const char *pathname) |
Check if the store contains the given link. | |
bool | hash_of_file (const char *pathname, std::string &hash) |
Return the current hash of a file. | |
void | add_file (const char *pathname) |
Add an existing file into the store. | |
void | remove_file (const char *pathname) |
Remove a file from the store. | |
void | add_link (const char *pathname, const char *to_file) |
Add a link to an existing file into the store. | |
void | remove_link (const char *pathname) |
Remove a link from the store. | |
void | rename (const char *pathname, const char *to_this) |
Rename a file or link to something else. | |
void | read_link (const char *pathname, std::string &points_to) |
Get the name of the file a link points to. | |
bool | verify_file (const char *pathname) |
Check that a file matches the checksum stored in. | |
bool | verify_content (const char *pathname, unsigned char *data, size_t of_len) |
Check if the content in a buffer matches the hash recorded for a file. | |
int | get_file (const char *pathname, RAWDATA_RPTR to_buf, size_t *bytes) |
Read an entire file into memory. Verification and decryption are performed automatically. | |
void | release_buffer (RAWDATA_PTR buf) |
Release a buffer. | |
int | put_file (const char *pathname, RAWDATA_PTR data, size_t bytes) |
Write a file to the filesystem. Encrypt if needed. | |
bool | commit () |
Seal a store. | |
bool | refresh () |
Check for changes made by other processes. | |
int | nbrof_files () |
How many files the storage contains. | |
int | nbrof_links () |
How many links the storage contains. | |
const char * | name () |
Logical name of the storage. | |
const char * | filename () |
Location of the store. | |
const char * | token () |
Owner token of the store. | |
visibility_t | visibility () |
Return the visibility of the store. | |
protection_t | protection () |
Return the protection type of the store. | |
status_t | status () |
Return the status of the store, can it be written to or just read or is there access at all. Use this function after constructor to check the status of the created or opened store. | |
int | stat_file (const char *pathname, struct stat *stbuf) |
Get the status of a member file. | |
p_file * | member (const char *pathname) |
Create a protected handle to a file in the store. | |
bool | test_xts_aes (bool do_encrypt, int8_t key[32], int8_t ivec[16], size_t block_nr, int8_t idata[16], int8_t odata[16]) |
Test the encryption algorithm with reference data. | |
Static Public Member Functions | |
static int | iterate_storage_names (storage::visibility_t of_visibility, storage::protection_t of_protection, const char *matching_names, aegis_callback *cb_func, void *ctx) |
List stores of the given visibility and protection. | |
Friends | |
class | p_file |
class | pe_file |
A secure file container.
This class is used to ensure file integrity by local signing and prevent unauthorized reading by encryption.
The visibility of a store. Defined when a storage is created and cannot be changed afterwards.
aegis::storage::storage | ( | const char * | name, | |
const char * | owner, | |||
visibility_t | visibility, | |||
protection_t | protection | |||
) |
Create a new store or open an existing one.
name | (in) The logical name of the store | |
owner | (in) The resource token to protect the store or NULL for the application id | |
visibility | (in) The visibility of the store | |
protection | (in) The protection level of the store * Caller must have the given owner token to create a store, to open an existing signed store for writing or to open an existing encrypted store for any purpose |
aegis::storage::storage | ( | const char * | name, | |
visibility_t | visibility, | |||
protection_t | protection | |||
) |
Create a new store or open an existing one with the application id.
name | (in) The logical name of the store | |
visibility | (in) The visibility of the store | |
protection | (in) The protection level of the store |
This function is retained by compatibility, and it cannot be used to create new shared stores which do not yet exist.
AID::* Caller must have an application id to create a store. Only stores created by the same application can be modified if they are signed or read if they are encrypted.
void aegis::storage::add_file | ( | const char * | pathname | ) |
Add an existing file into the store.
pathname | (in) The name of the file. Relative pathnames are automatically converted to absolute. |
Existing files can only be added to signed stores. New files are added to encrypted stores by put_file
* Caller must have the resource token of the store
void aegis::storage::add_link | ( | const char * | pathname, | |
const char * | to_file | |||
) |
Add a link to an existing file into the store.
pathname | (in) The name of the link. | |
to_file | (in) The file where the link points to. |
The file identified by to_file must already be a member in the store, otherwise no link is added.
* Caller must have the resource token of the store
bool aegis::storage::commit | ( | ) |
Seal a store.
Save a new copy of the store index file. Unless this call is made the changes will not be recorded.
* Caller must have the resource token of the store
bool aegis::storage::contains_file | ( | const char * | pathname | ) |
Check if the store contains the given file.
pathname | The name of the file to test |
* Caller must have the resource token of the store if the store is encrypted
bool aegis::storage::contains_link | ( | const char * | pathname | ) |
Check if the store contains the given link.
pathname | The name of a symbolic link |
Links are an internal feature of a store and do not map into actual symbolic links in the filesystem. A link can be added into a store with add_link, adding a file that is a symbolic link will result into a regular file member.
* Caller must have the resource token of the store if the store is encrypted
const char* aegis::storage::filename | ( | ) |
Location of the store.
The pathname of the index file is subject to changes and no assumptions should be made about it.
int aegis::storage::get_file | ( | const char * | pathname, | |
RAWDATA_RPTR | to_buf, | |||
size_t * | bytes | |||
) |
Read an entire file into memory. Verification and decryption are performed automatically.
pathname | (in) The name of the file | |
to_buf | (out) The buffer where the file contents are copied. Decryption is done automatically if needed. The parameter needs not to have any value at entry. | |
bytes | (out) The number of bytes read, should equal the file size. |
This function is safe to use but requires the while file to be in memory at once. Use the member function and p_file::p_read to read data in smaller pieces if necessary.
* Caller must have the resource token of the store if the store is encrypted
size_t aegis::storage::get_files | ( | stringlist & | names | ) |
Get a list of the files in the store.
names | (out) The names of the files in the store |
* Caller must have the resource token of the store if the store is encrypted
ssize_t aegis::storage::get_ufiles | ( | stringlist & | names | ) |
Get a list of the actual files that contain the content in the store, including the index file.
names | (out) The names of the files in the store |
CAP::dac_override Caller must either have the resource token of the store or CAP::dac_override in order to call this function of the store is encrypted. If the store is signed, no credentials are needed.
bool aegis::storage::hash_of_file | ( | const char * | pathname, | |
std::string & | hash | |||
) |
Return the current hash of a file.
pathname | The name of the file | |
hash | (out) The current hash as a base64 string |
* Caller must have the resource token of the store if the store is encrypted
static int aegis::storage::iterate_storage_names | ( | storage::visibility_t | of_visibility, | |
storage::protection_t | of_protection, | |||
const char * | matching_names, | |||
aegis_callback * | cb_func, | |||
void * | ctx | |||
) | [static] |
List stores of the given visibility and protection.
of_visibility | (in) vis_shared or vis_private | |
of_protection | (in) prot_signed or prot_encrypted | |
matching_names | (in) a regular expression for the storage name | |
cb_func | (in) an aegis_callback function, the logical store name as the payload parameter. | |
ctx | (in) the context pointer for the callback |
p_file* aegis::storage::member | ( | const char * | pathname | ) |
Create a protected handle to a file in the store.
pathname | (in) The name of the file |
With the protected handle the file can be read from and written to in pieces like a regular file, with no race conditions.
If the file didn't exist, it is created automatically, so this function cannot be used to test the existence of a file, use the contains_file or contains_link functions for that in stead.
* Caller must have the resource token of the store if the store is encrypted
const char* aegis::storage::name | ( | ) |
Logical name of the storage.
int aegis::storage::nbrof_files | ( | ) |
How many files the storage contains.
* Caller must have the resource token of the store if the store is encrypted
int aegis::storage::nbrof_links | ( | ) |
How many links the storage contains.
* Caller must have the resource token of the store if the store is encrypted
protection_t aegis::storage::protection | ( | ) | [inline] |
Return the protection type of the store.
int aegis::storage::put_file | ( | const char * | pathname, | |
RAWDATA_PTR | data, | |||
size_t | bytes | |||
) |
Write a file to the filesystem. Encrypt if needed.
pathname | (in) The name of the file to write. If the file does not yet exist in the store, it's added. | |
data | (in) The data to be written and optionally encrypted | |
bytes | (in) The number of bytes to be written |
void aegis::storage::read_link | ( | const char * | pathname, | |
std::string & | points_to | |||
) |
Get the name of the file a link points to.
pathname | (in) The name of the link | |
points_to | (out) The full pathname of the file |
If no such link exists, the content of the points_to variable remains unchanged.
* Caller must have the resource token of the store if the store is encrypted
bool aegis::storage::refresh | ( | ) |
Check for changes made by other processes.
* Caller must have the resource token of the store if the store is encrypted
void aegis::storage::release | ( | stringlist & | list | ) |
Release a stringlist after use.
list | The list retirned by get_files or get_ufiles |
void aegis::storage::release_buffer | ( | RAWDATA_PTR | buf | ) |
bool aegis::storage::remove_all_files | ( | ) |
Erase the storage permanently. If the storage is encrypted, also the member files fill be erase. Use cautiously.
* Caller must have the resource token of the store
void aegis::storage::remove_file | ( | const char * | pathname | ) |
Remove a file from the store.
pathname | The name of the file |
In a signed store this does not affect the actual file, which will remain where it is. Only its hash is removed from the store.
NOP if the file does not exist in the store.
* Caller must have the resource token of the store
void aegis::storage::remove_link | ( | const char * | pathname | ) |
Remove a link from the store.
pathname | The name of the link |
NOP if the link doesn't exist in the store.
* Caller must have the resource token of the store
void aegis::storage::rename | ( | const char * | pathname, | |
const char * | to_this | |||
) |
Rename a file or link to something else.
pathname | (in) the name of the file or link | |
to_this | (in) the new name |
NOP if the given file or link doesn't exist
* Caller must have the resource token of the store
int aegis::storage::stat_file | ( | const char * | pathname, | |
struct stat * | stbuf | |||
) |
Get the status of a member file.
pathname | (in) The name of the file | |
stbuf | (out) status buffer |
* Caller must have the resource token of the store if the store is encrypted
bool aegis::storage::test_xts_aes | ( | bool | do_encrypt, | |
int8_t | key[32], | |||
int8_t | ivec[16], | |||
size_t | block_nr, | |||
int8_t | idata[16], | |||
int8_t | odata[16] | |||
) |
Test the encryption algorithm with reference data.
do_encrypt | if true encrypt, else decrypt | |
key | A 256 bits long AES-key | |
ivec | A 16 bytes long initialization vector | |
block_nr | Ordering number of the 16 byte block | |
idata | 16 bytes of input data | |
odata | 16 bytes of output data |
const char* aegis::storage::token | ( | ) |
Owner token of the store.
bool aegis::storage::verify_content | ( | const char * | pathname, | |
unsigned char * | data, | |||
size_t | of_len | |||
) |
Check if the content in a buffer matches the hash recorded for a file.
data | (in) The data to verify. If the store is encrypted this should be the plaintext data. | |
of_len | (in) Length of data in bytes | |
pathname | (in) The name of the file |
It is also possible to verify a piece of data at the start of the file that is smaller than the real file contents.
* Caller must have the resource token of the store if the store is encrypted
bool aegis::storage::verify_file | ( | const char * | pathname | ) |
Check that a file matches the checksum stored in.
pathname | (in) The name of the file |
Using this function will easily result in a race condition, if the file is opened and read later. It is safer to use get_file or the member function to return a p_open instance which allows reading the file contents without a race.
* Caller must have the resource token of the store if the store is encrypted
visibility_t aegis::storage::visibility | ( | ) | [inline] |
Return the visibility of the store.