SEcube open-source SDK
|
This file includes everything about SEkey. More...
Go to the source code of this file.
Classes | |
struct | userdata_ |
Structure used to enclose all elements required by the APIs to initialize a user device inside SEkey. More... | |
struct | userinfo_ |
Simlpe struct used to store the details about the SEkey user which is using the application. ID and name are not really user when SEkey is in admin mode, they are used when SEkey is in user mode. The device serial number instead is always used and is crucial for the correct execution of the SEkey KMS. More... | |
class | se_user |
The user class is used to model a user object. User's attributes are private but methods are available to retrieve them. More... | |
class | group_policy |
The policy class is used to model a security policy adopted by a group. A policy for a group has 3 features: a maximum number of keys for the group, a common algorithm for all keys belonging to the group, a default cryptoperiod common to all keys belonging to the group. More... | |
class | se_key |
The key class is used to model a key object. A key has several properties which are kept private (id, name, owner, status, algorithm, length, generation time, activation time, expiration time). Public methods are available to retrieve the values of private properties. More... | |
class | se_group |
Implement the concept of group inside SEkey. Class members are kept private and suitable getter/setter methods are provided. More... | |
class | statement |
Handy RAII wrapper for sqlite3_stmt which requires call to sqlite3_finalize to avoid resource leakage. See the SQLite documentation for more informations about sqlite3_stmt. More... | |
Macros | |
#define | PINLEN 32 |
Length (bytes) of the PIN used to login as user or admin to the SEcube. | |
#define | AES256KEYLEN 32 |
Length of an AES-256 key expressed in bytes. | |
#define | IDLEN 11 |
Maximum length expected (in bytes) for a generic ID (could be a key, a user or a group). The value is 11 because each ID must have 1 literal at the beginning followed by up to 10 numbers. | |
#define | NAMELEN 100 |
This is the maximum length accepted for a name or label (i.e. the username, the label of a group or the label of a key). | |
#define | TRY_LIMIT 5 |
Maximum number of attempts updating SEkey in user mode. If the limit is reached and the update failed, recovery will be needed. | |
#define | UPDATE_RECORD_HEADER_LEN 11 |
Length of header of each update record in the update, init or recovery file. 1 byte for the type, 8 bytes for the counter, 2 bytes for the length. | |
#define | NUMBER_RESERVED_KEY_IDS 100 |
Batch of reserved key identifiers. These can be used without SEkey (i.e. IDs 1 and 2 are used to implement SEkey) and are not managed in any way (key life cycle, etc. not supported). | |
#define | NUMBER_MASTER_SLAVE_KEY_IDS 100000 |
Batch of key identifiers reserved to master-slave (admin-user) keys of the SEkey KMS. | |
#define | KEY_ID_RESERVED_RANGE_BEGIN 1 |
Minimum value of reserved key identifiers (notice that 1 and 2 are already used by SEkey). | |
#define | KEY_ID_RESERVED_RANGE_END NUMBER_RESERVED_KEY_IDS |
Maximum range value of reserved key identifiers (100). | |
#define | KEY_ID_SEKEY_BEGIN (KEY_ID_RESERVED_RANGE_END + 1) |
Minimum range value of standard SEkey key identifiers (101). | |
#define | KEY_ID_SEKEY_END (UINT32_MAX - NUMBER_MASTER_SLAVE_KEY_IDS) |
Maximum range value of standard SEkey key identifiers (2^32 -1 -100000). | |
#define | KEY_ID_MASTER_SLAVE_BEGIN (KEY_ID_SEKEY_END + 1) |
Minimum range value of master-slave key identifiers. | |
#define | KEY_ID_MASTER_SLAVE_END UINT32_MAX |
Maximum range value of master-slave key identifiers. | |
#define | SEkey_ID 1 |
The key ID 1 is reserved for the database internally used by SEkey. | |
#define | wildcard_key_ID 2 |
The key ID 2 is reserved for internal purposes of SEkey. | |
Typedefs | |
typedef struct userdata_ | userdata |
Structure used to enclose all elements required by the APIs to initialize a user device inside SEkey. | |
typedef struct userinfo_ | userinfo |
Simlpe struct used to store the details about the SEkey user which is using the application. ID and name are not really user when SEkey is in admin mode, they are used when SEkey is in user mode. The device serial number instead is always used and is crucial for the correct execution of the SEkey KMS. | |
Enumerations | |
enum | update_record_type { DELETE_USER_FROM_GROUP, DELETE_USER, KEY_DATA, SQL_QUERY, DELETE_GROUP } |
Record type identifiers for SEkey update files. More... | |
enum | sekey_error { SEKEY_OK = 0, SEKEY_ERR = 1, SEKEY_FILE_FOUND = 2, SEKEY_FILE_NOT_FOUND = 3, SEKEY_ERR_AUTH = 4, SEKEY_USER_GROUP_DUP = 5, SEKEY_KEY_DUP = 6, SEKEY_GROUP_NOT_FOUND = 7, SEKEY_GROUP_DUP = 8, SEKEY_USER_DUP = 9, SEKEY_USER_NOT_FOUND = 10, SEKEY_KEY_NOT_FOUND = 11, SEKEY_ERR_PARAMS = 12, SEKEY_UNCHANGED = 13, SEKEY_RESTART = 14, SEKEY_CORRUPTED = 15, SEKEY_REPROG = 16, SEKEY_RESTART_REPROG = 17, SEKEY_BLOCKED = 18, SEKEY_COMMON_GROUP_NOT_FOUND = 19, SEKEY_UNSUPPORTED = 20, SEKEY_INVALID_KEY = 21, SEKEY_INACTIVE_KEY = 22, SEKEY_COMPROMISED_KEY = 23, SEKEY_DESTROYED_KEY = 24, SEKEY_DEACTIVATED_KEY = 25, SEKEY_PREACTIVE_KEY = 26, SEKEY_SUSPENDED_KEY = 27 } |
Error codes returned by functions of SEkey. More... | |
enum | se_key_status { se_key_status::statusmin = 0, se_key_status::preactive = 1, se_key_status::active = 2, se_key_status::suspended = 3, se_key_status::deactivated = 4, se_key_status::compromised = 5, se_key_status::destroyed = 6, se_key_status::statusmax = 7 } |
Possible status assumed by a key. There are specific rules for status transition, see check_key_transition_validity() for more informations. More... | |
enum | se_key_type { typemin = 100, private_signature = 101, public_signature_verification = 102, symmetric_authentication = 103, private_authentication = 104, public_authentication = 105, symmetric_data_encryption = 106, symmetric_key_wrapping = 107, symmetric_RGB = 108, symmetric_key_derivation = 109, private_key_transport = 110, public_key_transport = 111, symmetric_key_agreement = 112, private_static_key_agreement = 113, public_static_key_agreement = 114, private_ephemeral_key_agreement = 115, public_ephemeral_key_agreement = 116, symmetric_authorization = 117, private_authorization = 118, public_authorization = 119, typemax = 120 } |
Possible key types. Notice that only symmetric_data_encryption is supported, other types are listed here in case someone wanted to expand the features of the system. | |
enum | filetype { INIT = 1, RECOVERY = 2, NORMAL = 3 } |
Used to identify the different types of files used by the update mechanism of SEkey. The hierarchy is the same, where the init file is the most important update file (the first to be processed), then there is the recovery file and finally the standard update file (used when SEkey is operating normally without errors). More... | |
Functions | |
APIs of SEkey | |
These are the APIs available to use SEkey. | |
int | sekey_start (L0 &l0, L1 *l1ptr) |
API to start the SEkey KMS. More... | |
int | sekey_stop () |
API to stop the SEkey KMS. More... | |
int | sekey_admin_init (L1 &l1, std::vector< std::string > &pin, std::string &userpin, std::string &adminpin) |
Initialize the SEcube of the administrator of SEkey. More... | |
int | sekey_init_user_SEcube (std::string &uid, std::string &userpin, std::string &adminpin, std::vector< std::string > &pin) |
API to initialize the SEcube device of a SEkey user. Admin only. More... | |
int | sekey_add_user (std::string &user_id, std::string &username) |
Add a new user to SEkey. Available only for the administrator. More... | |
int | sekey_delete_user (std::string &userID) |
Delete a user from SEkey; the user will not be able to use the key management system anymore. Available only for the administrator. More... | |
int | sekey_add_user_group (std::string &userID, std::string &groupID) |
Add an existing user to an existing group. Available only for the administrator. More... | |
int | sekey_delete_user_group (std::string &user_id, std::string &group_id) |
Delete a user from a group. All keys of that group will be deleted from the SEcube of the user. Available only for the administrator. More... | |
int | sekey_user_change_name (std::string &userID, std::string &newname) |
Change the name of a user. Available only for the administrator. More... | |
int | sekey_user_get_info_all (std::vector< se_user > *users) |
Retrieve the details about all users of SEkey. More... | |
int | sekey_user_get_info (std::string &userid, se_user *user) |
Retrieve the details about a single user. More... | |
int | sekey_add_group (std::string &groupID, std::string &group_name, group_policy policy) |
API to add a group to SEkey. Available only for the administrator. More... | |
int | sekey_delete_group (std::string &groupID) |
API to delete a group from SEkey. Available only for the administrator. More... | |
int | sekey_group_change_name (std::string &groupID, std::string &newname) |
Change the name of a group. Available only for the administrator. More... | |
int | sekey_group_change_max_keys (std::string &groupID, uint32_t maxkeys) |
Change the maximum number of keys that a group can be associated to. Available only for the administrator. More... | |
int | sekey_group_change_default_cryptoperiod (std::string &groupID, uint32_t cryptoperiod) |
Change the default cryptoperiod of a specific group. Available only for the administrator. More... | |
int | sekey_group_get_info (std::string &groupID, se_group *group) |
Retrieve the details about a single group (keys and users excluded). More... | |
int | sekey_group_get_info_all (std::vector< se_group > *groups) |
Retrieve the details about all groups of SEkey (keys and users excluded). More... | |
int | sekey_add_key (std::string &key_id, std::string &key_name, std::string &key_owner, uint32_t cryptoperiod, se_key_type keytype) |
Add a key to SEkey. Available only for the administrator. More... | |
int | sekey_activate_key (std::string &key_id) |
Activate a key. Available only for the administrator. More... | |
int | sekey_key_change_status (std::string &key_id, se_key_status status) |
Change the status of a key. Available only for the administrator. More... | |
int | sekey_key_change_name (std::string &key_id, std::string &key_name) |
Change the name of a key. Available only for the administrator. More... | |
int | sekey_key_get_info (std::string &key_id, se_key *key) |
Retrieve the details about a single key. More... | |
int | sekey_key_get_info_all (std::vector< se_key > *keys) |
Retrieve the details about all keys of SEkey. More... | |
int | sekey_find_key_v1 (std::string &chosen_key, std::string &source_user_id, std::string &dest_user_id, se_key_type keytype) |
Find a suitable key to encrypt data given a couple of users source-destination. More... | |
int | sekey_find_key_v2 (std::string &chosen_key, std::string &source_user_id, std::string &group_id, se_key_type keytype) |
Find a suitable key to encrypt data to be delivered from a single user to an entire group. More... | |
int | sekey_find_key_v3 (std::string &chosen_key, std::string &source_user_id, std::vector< std::string > &dest_user_id, se_key_type keytype) |
Find a suitable key to encrypt data given a sender and multiple recipients. More... | |
int | sekey_readlog (std::string *sn, std::string &output) |
Retrieve the content of the logfile associated to a specific SEcube. More... | |
Other functions of SEkey | |
These functions are used by SEkey for internal purposes but they can also be used by higher levels if needed. Always check the documentation and the source code before using them. | |
time_t | sekey_gettime () |
SEkey interface to retrieve the timestamp to be set for any KMS need. This API should be customized in order to meet the security requirements of the environment integrating the SEcube. The basic version simply retrieves the current system time, a customized version may require to get the time from an authoritative time server. | |
int | sekey_update_userdata () |
Synchronize the data of SEkey stored on the SEcube of the user with the data stored on the SEcube of the administrator. Available only for the users. More... | |
int | sekey_check_expired_keys () |
Check for expired keys inside SEkey. Expired keys which are still flagged as active will be deactivated. More... | |
int | sekey_recovery_request (std::string &user_id, std::string &serial_number) |
Explicitly request to SEkey to execute the recovery procedure for a specific user, given his serial number. Available only for the administrator. More... | |
std::string | epoch_to_localtime (time_t t) |
Convert an integer (epoch time) to the local time as readable string. More... | |
std::string | cryptoperiod_to_days (uint32_t n) |
Convert an integer to number of days, hours, minutes and seconds into a readable string. More... | |
uint32_t | stoul_wrap (std::string &s) |
Wrapper around stoul() function. More... | |
std::string | statusmap (se_key_status s) |
Convert a key status to the corresponding string. May throw exceptions. | |
std::string | keytypemap (se_key_type t) |
Convert a key type to the corresponding string. | |
std::string | algomap (uint32_t algorithm) |
Map an algorithm (expressed as integer) to the corresponding algorithm expressed as string. More... | |
uint32_t | algolen (uint32_t algorithm) |
Return the length (in byte) of the key, given the algorithm. Return 0 if algorithm is unknown. | |
Internal functions of SEkey | |
These functions are used by SEkey for internal purposes so they should not be called expliticly. | |
void | sekey_printlog (std::string &msg) |
Insert the string passed as parameter in the SEkey logfile of the current user or of the administrator. | |
int | sekey_user_init (std::string &user_id, std::string &username, std::string &sn) |
Function to add a user to SEkey, embedded by sekey_add_user(). Must not be called explicitly, available only for the administrator. More... | |
int | sekey_recovery () |
Iterate over the recovery table of SEkey processing all the recovery requests. Available only for the administrator. More... | |
int | sekey_write_recovery (std::string &user_id, std::string &serial_number) |
Generate the recovery file for a specific user. Available only for the administrator. More... | |
int | reset_user_recovery (std::string &user_id, std::string &sn) |
Remove a user from list of users who need a complete recovery of the SEkey database. Available only for the administrator. More... | |
void | req_delete_user (std::string &user_id, std::string &uid, bool erase) |
Function to write in the update file of a user the request to delete entirely another user from SEkey. More... | |
void | req_delete_user (std::string &user_id, uint32_t algo, uint32_t key_id, std::string &sn, bool erase, int mode) |
Function to write in the update file of a user the request to delete the very same user from SEkey. More... | |
void | req_delete_group (std::string &user_id, std::string &gid, bool erase) |
Function to write in the update file of a user the request to delete a group from SEkey. More... | |
void | req_delete_user_from_group (std::string &user_id, std::string &uid, std::string &group_id, bool erase) |
Function to write in the update file of a user the request to delete a user from a group. Available only for the administrator. More... | |
int | usr_delete_user_from_group (char *buffer) |
Function executed only when SEkey is running in user mode. This performs the actions requested by req_delete_user_from_group(). More... | |
int | usr_delete_user (char *buffer) |
Function executed only when SEkey is running in user mode. This performs the actions requested by req_delete_user(). More... | |
void | send_key_update (std::string &user_id, uint32_t kid, uint32_t key_len, bool erase) |
Function to write in a secure way a key of SEkey to the update file of a user. Available only for the administrator. More... | |
int | usr_delete_group (char *buffer) |
Function executed only when SEkey is running in user mode. This performs the actions requested by req_delete_group(). More... | |
int | usr_store_key (char *buffer) |
Function executed only when SEkey is running in user mode. Execute operations requested by send_key_update(). More... | |
int | send_user_init_update (std::string &user_id, std::string &query) |
Send to a new SEkey user the update containing basic info to initialize his SEkey database. More... | |
void | se3_flash_maintenance_routine () |
Retrieves the ID of all the keys stored inside the flash of the SEcube. If the ID is not found inside SEkey and the ID is not reserved (meaning that the key is a normal key of SEkey) then that key should not be in the flash and it is deleted. This is a simple garbage collector that will keep the flash of the SEcube clean from everything that should not be there. More... | |
int | usr_sql_exec (char *buffer, uint32_t bufsize) |
Function executed only when SEkey is running in user mode. This function will execute a SQL query written in the update file of the user. More... | |
int | execute_update (std::string &filepath) |
Read an update file (of any type) and process its content. More... | |
void | send_sql_update (std::string &user_id, std::string &query, bool erase) |
Write a SQL query to the update file of a specific user. More... | |
int | open_update_file (SEfile &updatefile, std::string &sn, bool overwrite, bool create, int mode) |
Open an update file of a specific user. More... | |
int | check_key_transition_validity (se_key_status current_status, se_key_status new_status) |
Check if a key status transition is allowed or not. More... | |
int | process_update_file () |
Process updates for the current user. More... | |
void | delete_user_iterator (std::vector< std::string > &users, std::string &user_id, bool erase) |
Wrapper around req_delete_user() to invoke the function for each user in the users vector passed as argument. More... | |
void | delete_group_iterator (std::vector< std::string > &users, std::string &group_id, bool erase) |
Wrapper around req_delete_group() to invoke the function for each user in the users vector passed as argument. More... | |
void | sql_update_iterator (std::vector< std::string > &users, std::string &query, bool erase) |
Wrapper to execute send_sql_update() for all users inside a list. More... | |
void | delete_user_from_group_iterator (std::vector< std::string > &users, std::string &user_id, std::string &group_id, bool erase) |
Wrapper around req_delete_user_from_group() to invoke the function for each user in the users vector passed as argument. More... | |
void | key_update_iterator (std::vector< std::string > &users, uint32_t kid, uint32_t key_len, bool erase) |
Wrapper around send_key_update() to invoke the function for each user in the users vector passed as argument. More... | |
int | rollback_transaction () |
Rollback a SQLite transaction. More... | |
int | commit_transaction () |
Commit a SQLite transaction. More... | |
int | fill_recovery (std::vector< std::string > &users) |
Add one or more users of SEkey to the list of users who need recovery. More... | |
int | sql_fill_vector (std::string *bind, std::string &query, std::vector< std::string > *container) |
Executes a SQLite query (with one parameter to bind) and stores the results in a vector of strings. More... | |
uint32_t | get_u32 (sqlite3_stmt *stmt, int index) |
Wrapper around sqlite3_column_int64() to retrieve the corresponding 32 bit unsigned value. More... | |
bool | algovalid (uint32_t algorithm) |
Check if the algorithm is valid. In order to be valid, the algorithm should be included in L1Algorithms::Algorithm. Check L1_enumerations.h for more info. More... | |
int | is_user_present (std::string &user_id) |
Check if a user is already stored in the SEkey KMS. More... | |
int | is_group_present (std::string &group_id) |
Same as is_user_present(), simply written for groups. May throw. | |
int | is_key_present (std::string &key_id) |
Same as is_user_present(), simply written for keys. May throw. | |
bool | deletefile (SEfile *fileptr, std::string &filepath) |
Delete a file encrypted with SEfile. This embeds plaintext filepath translation to encrypted filepath used by SEfile. More... | |
int | file_exists (std::string &filename) |
Check if a SEfile file exists. Automatically translate the plaintext filename to the encrypted filename used by SEfile. More... | |
int | generate_serial_number (char *sn) |
Generate a 32 byte serial number for a SEcube device. More... | |
bool | user_allowed () |
Check if SEkey in user mode is updated to latest version. If not block every operation. | |
int | algocmp (uint32_t algo1, uint32_t algo2) |
Check if algo1 is stronger than algo2. Return 1 if stronger, return -1 if weaker, 0 if equal. | |
int | sqlite3_expanded_sql_wrapper (sqlite3_stmt *stmt, std::string &s) |
Wrapper around the sqlite3_expanded_sql() function from SQLite. More... | |
std::string | sqlite3_column_text_wrapper (sqlite3_stmt *stmt, int col) |
Safe wrapper around the sqlite3_column_text() API of SQLite. | |
bool | check_input (std::string &in, uint8_t sel) |
Checks if an ID matches the corresponding regular expression. More... | |
This file includes everything about SEkey.
enum filetype |
Used to identify the different types of files used by the update mechanism of SEkey. The hierarchy is the same, where the init file is the most important update file (the first to be processed), then there is the recovery file and finally the standard update file (used when SEkey is operating normally without errors).
Enumerator | |
---|---|
INIT | Used to specify mode = init file in the open_update_file() function. |
RECOVERY | Used to specify mode = recovery file in the open_update_file() function. |
NORMAL | Used to specify mode = normal update file in the open_update_file() function. |
|
strong |
Possible status assumed by a key. There are specific rules for status transition, see check_key_transition_validity() for more informations.
enum sekey_error |
Error codes returned by functions of SEkey.
enum update_record_type |
Record type identifiers for SEkey update files.