aegis::storage Class Reference

A secure file container. More...

#include <aegis_storage.h>

List of all members.

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_filemember (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
class storage_lock


Detailed Description

A secure file container.

This class is used to ensure file integrity by local signing and prevent unauthorized reading by encryption.


Member Enumeration Documentation

The visibility of a store. Defined when a storage is created and cannot be changed afterwards.

Enumerator:
vis_global  Store is globally signed and cannot be modified locally
vis_shared  The caller must have a resource token to modify a signed store or read an encrypted store
vis_private  The store is owned by a single application and can only be modified by it or read by it.

The protection method of a storage. Defined when a storage is created and cannot be changed afterwards.

Enumerator:
prot_signed  Integrity is protected by signatures
prot_encrypted  Confidentiality is protected by encryption

Access status of a store.

Enumerator:
writable  Store can be read and written to
readable  Store is read only
no_access  Access denied, check errno and last_error_str


Constructor & Destructor Documentation

aegis::storage::storage ( const char *  name,
const char *  owner,
visibility_t  visibility,
protection_t  protection 
)

Create a new store or open an existing one.

Parameters:
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.

Parameters:
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.


Member Function Documentation

bool aegis::storage::remove_all_files (  ) 

Erase the storage permanently. If the storage is encrypted, also the member files fill be erase. Use cautiously.

Returns:
true if the command could be completed. If false, errno tells why.
* Caller must have the resource token of the store

size_t aegis::storage::get_files ( stringlist names  ) 

Get a list of the files in the store.

Parameters:
names (out) The names of the files in the store
Returns:
The number of elements in the returned list
* 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.

Parameters:
names (out) The names of the files in the store
Returns:
The number of elements in the returned list or -1 if the caller doesn't have read access.
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.

void aegis::storage::release ( stringlist list  ) 

Release a stringlist after use.

Parameters:
list The list retirned by get_files or get_ufiles

bool aegis::storage::contains_file ( const char *  pathname  ) 

Check if the store contains the given file.

Parameters:
pathname The name of the file to test
Returns:
true, if the file exists in the store
* 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.

Parameters:
pathname The name of a symbolic link
Returns:
true if the link exists in the store
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

bool aegis::storage::hash_of_file ( const char *  pathname,
std::string &  hash 
)

Return the current hash of a file.

Parameters:
pathname The name of the file
hash (out) The current hash as a base64 string
Returns:
true if the file exists in the store
* Caller must have the resource token of the store if the store is encrypted

void aegis::storage::add_file ( const char *  pathname  ) 

Add an existing file into the store.

Parameters:
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::remove_file ( const char *  pathname  ) 

Remove a file from the store.

Parameters:
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::add_link ( const char *  pathname,
const char *  to_file 
)

Add a link to an existing file into the store.

Parameters:
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

void aegis::storage::remove_link ( const char *  pathname  ) 

Remove a link from the store.

Parameters:
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.

Parameters:
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

void aegis::storage::read_link ( const char *  pathname,
std::string &  points_to 
)

Get the name of the file a link points to.

Parameters:
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::verify_file ( const char *  pathname  ) 

Check that a file matches the checksum stored in.

See also:
commit
Parameters:
pathname (in) The name of the file
Returns:
true, if the checksum matches
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

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.

Parameters:
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
Returns:
true, if the contents match
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

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.

Parameters:
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.
Returns:
0 on success, otherwise an error code Use
See also:
release_buffer to release the returned buffer after use.
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

void aegis::storage::release_buffer ( RAWDATA_PTR  buf  ) 

Release a buffer.

Parameters:
buf The buffer to be released, returned by
See also:
get_file

int aegis::storage::put_file ( const char *  pathname,
RAWDATA_PTR  data,
size_t  bytes 
)

Write a file to the filesystem. Encrypt if needed.

Parameters:
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
Returns:
0 on success, otherwise and error code * Caller must have the resource token of the store

bool aegis::storage::commit (  ) 

Seal a store.

Returns:
true on success. If returns false, check errno
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::refresh (  ) 

Check for changes made by other processes.

Returns:
true if the store was changed by some other process after the last commit
* Caller must have the resource token of the store if the store is encrypted

int aegis::storage::nbrof_files (  ) 

How many files the storage contains.

Returns:
The number of files and links in the store. If the function returns -1 it means that the caller does not have read access to the store.
* 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.

Returns:
The number of links in the store.
* Caller must have the resource token of the store if the store is encrypted

const char* aegis::storage::name (  ) 

Logical name of the storage.

Returns:
The name that was used when the store was opened.

const char* aegis::storage::filename (  ) 

Location of the store.

Returns:
The actual pathname of the store index file.
The pathname of the index file is subject to changes and no assumptions should be made about it.

const char* aegis::storage::token (  ) 

Owner token of the store.

Returns:
The token with which the store is protected

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.

Parameters:
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
Returns:
if < 0, 0 - error code if >= 0, the value returned by the callback function

visibility_t aegis::storage::visibility (  )  [inline]

Return the visibility of the store.

Returns:
The value given in the constructor

protection_t aegis::storage::protection (  )  [inline]

Return the protection type of the store.

Returns:
The value given in the constructor

int aegis::storage::stat_file ( const char *  pathname,
struct stat *  stbuf 
)

Get the status of a member file.

Parameters:
pathname (in) The name of the file
stbuf (out) status buffer
Returns:
as with man(2) stat
* Caller must have the resource token of the store if the store is encrypted

p_file* aegis::storage::member ( const char *  pathname  ) 

Create a protected handle to a file in the store.

Parameters:
pathname (in) The name of the file
Returns:
A protected handle of type p_file or NULL if some error occured.
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

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.

Parameters:
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


The documentation for this class was generated from the following file:

Generated on Wed Jul 18 15:51:27 2012 for Aegis Crypto by  doxygen 1.5.6