SEcube open-source SDK
|
APIs of 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... | |
int sekey_activate_key | ( | std::string & | key_id | ) |
Activate a key. Available only for the administrator.
[in] | key_id | The ID of the key to activate. |
This API activates a key. In case of invalid key ID, invalid transition (i.e. from deactivated to active) or missing key the API will return an error. On activation, also the expiration time of the key is computed (sum of generation time and cryptoperiod). The activation time is not updated if the key is activated multiple times (i.e. activate, suspend, activate again).
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.
[in] | groupID | The ID of the group to be added to SEkey. |
[in] | group_name | The name of the group to be added to SEkey. |
[in] | policy | The policy of the group. See group_policy object for more informations. |
This API adds an empty group to SEkey. The group is not associated to any key by default.
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.
[in] | key_id | ID of the key to be added. |
[in] | key_name | Name of the key to be added. |
[in] | ID | of the group to which the key belongs. |
[in] | cryptoperiod | The time span during which a key will be usable for encryption and decryption. Insert 0 if you want to inherit the cryptoperiod of the group owner of the key, insert any other value for a custom cryptoperiod. |
[in] | keytype | The type of the key. Currently only se_key_type::symmetric_data_encryption is supported. |
API to add a key to SEkey. The key must belong to a group, therefore the caller must provide the ID of the group which owns the key to be added (the key will be added only to that group). All other metadata of the key (i.e. the algorithm, the length, the generation time etc.) are computed automatically (i.e. the algorithm is automatically given by the group policy and the length is automatically given by the algorithm).
int sekey_add_user | ( | std::string & | user_id, |
std::string & | username | ||
) |
Add a new user to SEkey. Available only for the administrator.
[in] | user_id | The ID of the new user. |
[in] | username | The name of the new user. |
When a new user is created, it does not belong to any group. After calling this function, the sekey_init_user_SEcube() should be called to initialize also the SEcube of the user.
int sekey_add_user_group | ( | std::string & | userID, |
std::string & | groupID | ||
) |
Add an existing user to an existing group. Available only for the administrator.
[in] | userID | The ID of the user to be added. Each user ID is unique in SEkey but this API can be called multiple times for the same user ID provided that the group ID is different. In fact the internal table of the users managed by SEkey uses the pair (user ID, group ID) as primary key. |
[in] | groupID | The ID of the group to which the user must be added. This parameter must be an existing group. |
The SEcube of the involved user will receive all informations about the new group, the users of that group and the keys of that group. The other users of that group will receive informations about the new user. Any exception will result in the function returning an error.
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.
[in] | l1 | The L1 object created by the caller. |
[in] | pin | A list of PINs that can be used to login to the SEcube prior to its initialization. |
[in] | userpin | The user PIN to be set on the SEcube. |
[in] | adminpin | The admin PIN to be set on the SEcube. |
This API must be called only once in order to initialize the SEcube of the administrator of SEkey. For the second parameter, in general is enough to pass a vector with only one PIN made of 32 bytes initialized at zero (this is the default PIN of every SEcube prior to initialization). The third and fourth parameters are the new PINs that will be set on the device, notice that they are not saved anywhere so if you forget them you will not be able to recover them.
int sekey_delete_group | ( | std::string & | groupID | ) |
API to delete a group from SEkey. Available only for the administrator.
[in] | groupID | The ID of the group to delete. |
Delete a group from SEkey. This API basically deletes every reference to the group with the specified ID from the system. This means that after calling this function, SEkey will not have any group with that ID and the users who belonged to the group will not belong to it anymore. The keys associated to the delete group will be deactivated and their owner will be set to "zombie". The zombie keys may still be used by the administrator to decrypt old data. If they are not needed anymore, the administrator can delete them changing their status to destroyed.
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.
[in] | userID | The ID of the user to be deleted from SEkey. |
This function will completely delete the user from SEkey. Every information related to that user will be deleted from every SEcube involved in SEkey (i.e. the SEcube of the administrator or the SEcube of another user who was associated to the deleted user by means of a common group). The SEcube of the deleted user will receive a special update that will erase completely its keys and the informations related to SEkey. The ID of the deleted user becomes available again. Any exception will result in the function returning an error.
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.
[in] | user_id | The ID of the user to be deleted from SEkey. |
[in] | group_id | The ID of the group from which the user must be deleted. |
The specified user will simply stop belonging to the specified group. Nothing else will change from the administrator point of view (except for obvious things like the number of users in the group which will be decremented). From the user point of view, if the user to be deleted from the group is the very same user logged in to the SEcube, all the keys of that group will be deleted from SEkey. If the user is not the same, the user will simply be deleted from the list of users known by the current user, if the specified group is the only one in common. Any exception will result in the function returning an error.
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.
[out] | chosen_key | ID of the best key to be used given the specified parameters. |
[in] | source_user_id | User ID of the sender. |
[in] | dest_user_id | User ID of the receiver. |
[in] | keytype | The type of the key. Currently only se_key_type::symmetric_data_encryption is supported. |
The returned key ID is the ID of the best key given these rules: the key is active, the key belongs to the smallest group(s) in common between the users, the key uses the best encryption algorithm. If more than one key with these requirements is found, the most recent key is chosen assuming that data encrypted with that key have been observed for a shorter amount of time than other messages encrypted with a key which is older. If activation times are equal, the key with the lower ID is chosen.
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.
[out] | chosen_key | ID of the best key to be used given the specified group. |
[in] | source_user_id | User ID of the sender. |
[in] | group_id | Group ID of the receiver. |
[in] | keytype | The type of the key. Currently only se_key_type::symmetric_data_encryption is supported. |
This API is intended to be used only when the destination of an operation is an entire group. It searches the most secure key that is active and belongs to the destination group.
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.
[out] | chosen_key | ID of the best key to be used given the users specified. |
[in] | source_user_id | User ID of the sender. |
[in] | dest_user_id | IDs of the recipients. |
[in] | keytype | The type of the key. Currently only se_key_type::symmetric_data_encryption is supported. |
This function works with the same rules of sekey_find_key_v1(). Notice that if there is not a group to which all users involved belong (sender and receivers) an error is returned because is not possible to identify a key that can be used to encrypt data only once for all the recipients. In conclusion, this function behaves as sekey_find_key_v2() but you do not need to provide an entire group as destination, you can provide a subset of his members.
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.
[in] | groupID | The ID of the group to modify. |
[in] | cryptoperiod | The new value for the default cryptoperiod |
API to change the default cryptoperiod of a group. The default cryptoperiod of the group is used for keys owned by the group when their specific cryptoperiod is set to 0 or when it is higher than the default cryptoperiod itself.
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.
[in] | groupID | The group whose maximum number of key should be modified. |
[in] | maxkeys | The maximum number of keys. |
The new value can't be lower than the current number of keys.
int sekey_group_change_name | ( | std::string & | groupID, |
std::string & | newname | ||
) |
Change the name of a group. Available only for the administrator.
[in] | groupID | The ID of the group whose name must be changed. |
[in] | newname | The new name of the group. |
int sekey_group_get_info | ( | std::string & | groupID, |
se_group * | group | ||
) |
Retrieve the details about a single group (keys and users excluded).
[in] | groupID | The ID of the groups we want to search for in the KMS. |
[in] | group | Pointer to a se_group object that will contain the details of the group. |
This function works similarly to the sekey_group_get_info_all() API. The main difference is that, in this case, the caller is supposed to pass the ID of the group he is interested in. Therefore this API is used when the caller wants to find the details about a single group.
int sekey_group_get_info_all | ( | std::vector< se_group > * | groups | ) |
Retrieve the details about all groups of SEkey (keys and users excluded).
[in] | groups | Pointer to a vector of se_group objects. |
This API will fill the vector passed by reference with group objects, each one containing the details about one group of the SEkey KMS. Be careful when using this API because it could potentially use a lot of RAM memory. This API is useful when the higher level application must perform particular analysis filtering the data. Is impossible to write an API for each possible filter that might be needed by the higher level application (e.g. only groups whose algorithm is aes-256) therefore this API is intended as an easy way to provide to the higher level application all the data it needs in order to perform further analysis.
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.
[in] | uid | The ID of the user to initialize. |
[in] | userpin | The PIN to be set on the SEcube of the user to perform the login with user privilege. |
[in] | adminpin | The PIN to be set on the SEcube of the user to perform the login with admin privilege. |
[in] | pin | The list of PINs that can be used to login as admin on the SEcube of the user before it gets initialized (usually a single PIN with 32 bytes at zero is enough). |
int sekey_key_change_name | ( | std::string & | key_id, |
std::string & | key_name | ||
) |
Change the name of a key. Available only for the administrator.
[in] | key_id | The ID of the key whose name should be changed. |
[in] | key_name | The new name of the key. |
int sekey_key_change_status | ( | std::string & | key_id, |
se_key_status | status | ||
) |
Change the status of a key. Available only for the administrator.
[in] | key_id | The ID of the key whose status should be changed. |
[in] | status | The new status of the key. |
This API changes the status of a key but it must not be used to activate a key (which means changing the status to active) because the transition to the active status implies additional constraints and is handled by the sekey_activate_key() API. If the new status of the key is not compatible with the current status, an error is returned.
int sekey_key_get_info | ( | std::string & | key_id, |
se_key * | key | ||
) |
Retrieve the details about a single key.
[in] | key_id | The ID of the key to search for. |
[out] | key | Pointer to a se_key object that will contain the details of the key. |
This function works similarly to the sekey_key_get_info_all() API. The main difference is that, in this case, the caller is supposed to pass the ID of the key he is interested in. Therefore this API is used when the caller wants to find the details about a single key.
int sekey_key_get_info_all | ( | std::vector< se_key > * | keys | ) |
Retrieve the details about all keys of SEkey.
[out] | keys | Pointer to a vector of se_key objects. |
This API will fill the vector passed by reference with key objects, each one containing the details about one key of the SEkey KMS. Be careful when using this API because it could potentially use a lot of RAM memory. This API is useful when the higher level application must perform particular analysis filtering the data. Is impossible to write an API for each possible filter that might be needed by the higher level application (e.g. only keys whose expiration time is in a specific interval and whose algorithm is aes-256) therefore this API is intended as an easy way to provide to the higher level application all the data it needs in order to perform further analysis.
void sekey_readlog | ( | std::string * | sn, |
std::string & | output | ||
) |
Retrieve the content of the logfile associated to a specific SEcube.
[in] | sn | The serial number of the SEcube whose logfile must be retrieved. If NULL the current SEcube is considered. |
[out] | output | A string containing the content of the logfile. |
int sekey_start | ( | L0 & | l0, |
L1 * | l1ptr | ||
) |
API to start the SEkey KMS.
[in] | l0 | L0 object created by the caller. |
[in] | l1ptr | The pointer to the L1 object created iby the caller. |
This API must be called before any other API of SEkey. It is used to initialize SEkey, in particular it will search for an existing database dedicated to SEkey and it will create the database in case it can't be found on the SEcube's SD card. Any pending SEkey database transaction left on disk by previous crashes of the application, power loss or unexpected event will be rolled back. When opening the database, an integrity check of the database will be performed. Upon completion, the function will force a SEcube flash maintenance routine (to clear any data inside the device flash which is not needed by SEkey) and it will also force the SEkey update when in user mode. Any exception will result in the function returning an error, when this API does not return SEKEY_OK there is no need to call sekey_stop().
int sekey_stop | ( | ) |
API to stop the SEkey KMS.
Notice that, after executing this API, all other APIs based on SEkey will stop working because SEkey itself has been shut down. Must be called before closing the main application.
int sekey_user_change_name | ( | std::string & | userID, |
std::string & | newname | ||
) |
Change the name of a user. Available only for the administrator.
[in] | userID | The ID of the user whose name should be changed. |
[in] | newname | The new name of the user. |
int sekey_user_get_info | ( | std::string & | userid, |
se_user * | user | ||
) |
Retrieve the details about a single user.
[in] | userid | The ID of the users we want to search for in the KMS. |
[in] | user | Pointer to a se_user object that will contain the details of the user. |
This function works similarly to the sekey_user_get_info_all() API. The main difference is that, in this case, the caller is supposed to pass the ID of the user he is interested in. Therefore this API is used when the caller wants to find the details about a single user.
int sekey_user_get_info_all | ( | std::vector< se_user > * | users | ) |
Retrieve the details about all users of SEkey.
[in] | users | Pointer to a vector of se_user objects. |
This API will fill the vector passed by reference with user objects, each one containing the details about one user of SEkey. Be careful when using this API because it could potentialy use a lot of RAM memory. This API is useful when the higher level application must perform particular analysis filtering the data. Is impossible to write an API for each possible filter that might be needed by the higher level application (e.g. only users whose name is "Paul") therefore this API is intended as an easy way to provide to the higher level application all the data it needs in order to perform further analysis.