SEcube open-source SDK
|
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... | |
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.
[in] | algorithm | The algorithm to be checked. |
bool check_input | ( | std::string & | in, |
uint8_t | sel | ||
) |
Checks if an ID matches the corresponding regular expression.
[in] | in | String containing the ID to check. |
[in] | sel | Integer identifying which kind of ID (user, group, or key). |
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.
[in] | current_status | The current key status. |
[in] | new_status | The new key status. |
A key status transition is allowed only in very specific circumstances. For example a key can change its status to active only if its previous status was preactive or suspended. On the other hand a key status can always be changed to destroyed but a key whose status is destroyed can't be activated anymore. Therefore this function checks for these (and more) constraints.
int commit_transaction | ( | ) |
Commit a SQLite transaction.
Try (up to 3 times) to commit a transaction. If commit is successful no problem, otherwise try to revert back the changes. If even rollback is not feasible, ask to restart the application. This function never throws exceptions.
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.
[in] | users | The array of user IDs on which the req_delete_group() function must be invoked. |
[in] | group_id | The ID of the group to be deleted. |
[in] | erase | A flag to request also the deletion of the user from the recovery list in case the update generation succeeds. |
Used internally by SEkey (admin mode only) in order to implement the complex update logic. Do not use otherwise.
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.
[in] | users | The array of user IDs on which the req_delete_user_from_group() function must be invoked. |
[in] | user_id | The ID of the user to be deleted. |
[in] | group_id | The ID of the group from which the user must be deleted. |
[in] | erase | A flag to request also the deletion of the user from the recovery list in case the update generation succeeds. |
Used internally by SEkey (admin mode only) in order to implement the complex update logic. Do not use otherwise.
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.
[in] | users | The array of user IDs on which the req_delete_user() function must be invoked. |
[in] | user_id | The ID of the user to be deleted. |
[in] | erase | A flag to request also the deletion of the user from the recovery list in case the update generation succeeds. |
Used internally by SEkey (admin mode only) in order to implement the complex update logic. Do not use otherwise.
bool deletefile | ( | SEfile * | fileptr, |
std::string & | filepath | ||
) |
Delete a file encrypted with SEfile. This embeds plaintext filepath translation to encrypted filepath used by SEfile.
[in] | The | SEfile object related to the file, if any. Used to close the file before deleting it. |
[in] | The | path of the file. |
int execute_update | ( | std::string & | filepath | ) |
Read an update file (of any type) and process its content.
[in] | filepath | The path of the file to process. |
Used internally by SEkey, should not be used by higher levels.
int file_exists | ( | std::string & | filename | ) |
Check if a SEfile file exists. Automatically translate the plaintext filename to the encrypted filename used by SEfile.
[in] | The | name of the file expressed as plaintext. |
int fill_recovery | ( | std::vector< std::string > & | users | ) |
Add one or more users of SEkey to the list of users who need recovery.
[in] | users | The list (even with only one element) of users to be added to the recovery. |
Used only in admin mode. Do not use otherwise.
int generate_serial_number | ( | char * | sn | ) |
Generate a 32 byte serial number for a SEcube device.
[out] | sn | The 32 byte long buffer which will contain the serial number. |
uint32_t get_u32 | ( | sqlite3_stmt * | stmt, |
int | index | ||
) |
Wrapper around sqlite3_column_int64() to retrieve the corresponding 32 bit unsigned value.
This is necessary because all the integers stored in the database are set to 64 bit signed value. This is done in order to have all integers of the same type inside the db, instead of letting SQLite to choose automatically what kind of integer to use (16,32,64 bits). Each function internally will manage these values according to the real needs of SEkey, for example a key ID is always 4 bytes while the key algorithm is stored on 2 bytes.
int is_user_present | ( | std::string & | user_id | ) |
Check if a user is already stored in the SEkey KMS.
[in] | user_id | The id of the user to search. |
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.
[in] | users | The array of user IDs on which the send_key_update() function must be invoked. |
[in] | kid | The ID of the key to be sent. |
[in] | key_len | The length of the key to be sent. |
[in] | erase | A flag to request also the deletion of the user from the recovery list in case the update generation succeeds. |
Used internally by SEkey (admin mode only) in order to implement the complex update logic. Do not use otherwise.
int open_update_file | ( | SEfile & | updatefile, |
std::string & | sn, | ||
bool | overwrite, | ||
bool | create, | ||
int | mode | ||
) |
Open an update file of a specific user.
[in] | updatefile | The SEfile object related to the file to open. |
[in] | sn | The serial number of the user. |
[in] | overwrite | Flag to force the override of the current file (if any). |
[in] | create | Flag to enable the creation of the file, if not present. |
[in] | mode | Specifies if init file, recovery file or normal file. |
This is basically a wrapper for the SEfile::secure_open() function of SEfile. The parameters are simply used to take decisions before calling the SEfile::secure_open() on the updatefile parameter.
int process_update_file | ( | ) |
Process updates for the current user.
This function is executed only by the user application and is used to check if there are updates for the SEkey database of the user. There are 3 types of updates, following a specific hierarchy: init, recovery and normal. The init update file is generated only once when the SEcube of the user is initialized. The recovery update file is generated every time that the admin issues a recovery for the user or every time that the user asks specifically to the admin to do a recovery. The normal update file is the file generated by the administrator of SEkey when everything works normally. These three updates must be executed strictly in order, i.e. the user cannot execute the normal update file if there is a recovery update file pending. This is fundamental to implement correctly the database update mechanism and to grant that the SEkey database of the user is consistent in time. This function may throw; it is called automatically by the other API called sekey_update_userdata().
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.
[in] | user_id | The ID of the user who needs the update. |
[in] | gid | The ID of the group to be deleted. |
[in] | erase | A flag to request also the deletion of the user from the recovery list in case the update generation succeeds. |
Used internally by SEkey (admin mode only) in order to implement the complex update logic. Do not use otherwise.
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.
[in] | user_id | The ID of the user who needs the update. |
[in] | uid | The ID of the user to be deleted. |
[in] | erase | A flag to request also the deletion of the user from the recovery list in case the update generation succeeds. |
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.
[in] | user_id | The ID of the user who needs the update (who is also the user to be deleted). |
[in] | algo | The algorithm to be used to write the update file. |
[in] | key_id | The key to be used to encrypt the update file. |
[in] | sn | The serial number of the user to be deleted. |
[in] | erase | A flag to request also the deletion of the user from the recovery list in case the update generation succeeds. |
[in] | mode | The mode to open the update file to be written (i.e. init, recovery, normal). |
Used internally by SEkey (admin mode only) in order to implement the complex update logic. Do not use otherwise.
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.
[in] | user_id | The ID of the user who needs the update. |
[in] | uid | The ID of the user to be deleted (may or may not be the same as user_id). |
[in] | group_id | The ID of the group from which the user must be deleted. |
[in] | erase | A flag to request also the deletion of the user from the recovery list in case the update generation succeeds (see reset_user_recovery()). |
Used internally by SEkey, do not use otherwise. No throw.
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.
[in] | user_id | The ID of the user to be deleted from the recovery list. |
[in] | sn | The serial number of the user's SEcube. |
Used internally by SEkey, should not be used by higher levels.
int rollback_transaction | ( | ) |
Rollback a SQLite transaction.
This function attempts to rollback the database following an unexpected error. In case of failure of the first rollback query, the function will wait a limited amount of time (configured to 1 second by default) before attempting the rollback again. If the rollback fails multiple times (set to 3 by default) the function will return SEKEY_RESTART in order to signal to the caller that the application should be restarted. When the application will be relaunched, the rollback will be issued automatically by SQLite thanks to the journaling file left on disk. In case of correct rollback the function will return SEKEY_UNCHANGED in order to inform the caller that the database is not changed with respect to the last successfull operation. Notice that a rollback may leave unnecessary data in the flash of the SEcube but these data will be deleted by the garbage collector. This function does not throw any exception.
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.
int sekey_recovery | ( | ) |
Iterate over the recovery table of SEkey processing all the recovery requests. Available only for the administrator.
Generate the recovery file for all users who need it. Return error if the generation of the recovery file is not completed correctly for all users inside the recovery table. The policy of SEkey APIs is to prevent the execution of the API if the recovery table is not empty. May throw exceptions. This function will call the sekey_write_recovery().
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.
[in] | user_id | The ID of the user to add. |
[in] | username | The name of the user to add. |
[in] | sn | The serial number assigned to the SEcube of the new user. |
This function must never be called explicitly because it is used internally by the sekey_add_user() function. It will add the user to SEkey and it will also compute the update keys specific for the new user (both keys will be stored in the flash of the admin SEcube). May throw exceptions.
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.
[in] | user_id | The ID of the user who needs a SEkey data recovery. |
[in] | serial_number | The serial number of the SEcube of the user. |
This function generates the recovery file for a user, given its ID and serial number. If the couple (user, serial number) is not found, this function will simply generate an update encrypted with a universal key (known as wildcard, known by all present and past users of SEkey) in order to force the user to delete its SEkey content (if any). If the user is found in SEkey, the recovery file is generated inserting all the informations that the user needs to rebuild its SEkey database from scratch. If the recovery file is generated correctly, the user is removed from the list of users (Recovery table) who need recovery, otherwise the user stays in the list.
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.
[in] | user_id | The ID of the user who needs the update. |
[in] | kid | The ID of the key to be sent. |
[in] | key_len | The length of the key to be sent. |
[in] | erase | A flag to request also the deletion of the user from the recovery list (see reset_user_recovery()) in case the update generation succeeds. |
Used internally by SEkey, do not use otherwise. May throw exceptions.
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.
[in] | user_id | ID of the user who is the destination of the update file. |
[in] | query | SQL query to be written to the file and executed by the user. |
[in] | erase | If true delete user from recovery table upon success, if false do not. |
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.
[in] | user_id | The ID of the user who needs the init update. |
[in] | query | The SQL query to be run in order to update the SEkey user database. |
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.
[in] | query | The parameter to bind inside the query. |
[in] | query | The query to be executed. |
[out] | The | vector of strings that will be filled by this function. |
This is a handy wrapper that executes a query and stores the results in an array of strings. Notice that it is intended to be used only to fill a container with strings that have the same meaning. Therefore this function is normally used with a query that selects only one attribute for each row that matches the query itself. For example it is used to fill a vector of user IDs with the ID of each user of SEkey who belongs to a specific group. Internally used by SEkey, do not use otherwise.
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.
[in] | users | The users involved by this update. |
[in] | query | The query to be written to the update files. |
[in] | erase | Tells to send_sql_update() if the user should also be removed from recovery upon success. |
This function is a wrapper that allows to execute the send_sql_update() function for all users listed inside the array of user IDs passed to the wrapper itself. This means that the query will be written to several update files, one for each user included in the array.
int sqlite3_expanded_sql_wrapper | ( | sqlite3_stmt * | stmt, |
std::string & | s | ||
) |
Wrapper around the sqlite3_expanded_sql() function from SQLite.
[in] | stmt | The statement to retrieve. |
[out] | s | The string that will contain the statement. |
This is simply a wrapper around the sqlite3_expanded_sql() used to retrieve the SQL query after the prepared statement and binding procedure. A wrapper is required in order to ensure that the memory allocated by the original SQLite API is always freed.
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().
[in] | buffer | The buffer to be deserialized with all the info about the operations to be done. |
This function is used internally by SEkey in order to manage the complex update logic. It should not be used directly by the higher level application. The function will delete the specified group from SEkey, modifying the user's SEkey database.
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().
[in] | buffer | The buffer to be deserialized with all the info about the operations to be done. |
This function will delete the specified user from SEkey, modifying the user's SEkey database. If the user to be deleted is the same user executing the update, then all SEkey informations (both in the database and in the SEcube flash) will be deleted. Used internally by SEkey, do not use otherwise.
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().
[in] | buffer | The buffer to be deserialized with all the info about the operations to be done. |
Used by SEkey to apply a specific update request, do not use otherwise. The function will delete the requested user from the specified group.
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.
[in] | buffer | The buffer to be deserialized with all the info about the operations to be done. |
[in] | bufsize | The length of the SQL query to be executed. |
int usr_store_key | ( | char * | buffer | ) |
Function executed only when SEkey is running in user mode. Execute operations requested by send_key_update().
[in] | buffer | The buffer to be deserialized with all the info about the operations to be done. |