SEcube open-source SDK
Sekey_apis

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

Detailed Description

Function Documentation

◆ sekey_activate_key()

int sekey_activate_key ( std::string &  key_id)

Activate a key. Available only for the administrator.

Parameters
[in]key_idThe ID of the key to activate.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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).

◆ sekey_add_group()

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.

Parameters
[in]groupIDThe ID of the group to be added to SEkey.
[in]group_nameThe name of the group to be added to SEkey.
[in]policyThe policy of the group. See group_policy object for more informations.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

This API adds an empty group to SEkey. The group is not associated to any key by default.

◆ sekey_add_key()

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.

Parameters
[in]key_idID of the key to be added.
[in]key_nameName of the key to be added.
[in]IDof the group to which the key belongs.
[in]cryptoperiodThe 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]keytypeThe type of the key. Currently only se_key_type::symmetric_data_encryption is supported.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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).

◆ sekey_add_user()

int sekey_add_user ( std::string &  user_id,
std::string &  username 
)

Add a new user to SEkey. Available only for the administrator.

Parameters
[in]user_idThe ID of the new user.
[in]usernameThe name of the new user.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_add_user_group()

int sekey_add_user_group ( std::string &  userID,
std::string &  groupID 
)

Add an existing user to an existing group. Available only for the administrator.

Parameters
[in]userIDThe 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]groupIDThe ID of the group to which the user must be added. This parameter must be an existing group.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_admin_init()

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.

Parameters
[in]l1The L1 object created by the caller.
[in]pinA list of PINs that can be used to login to the SEcube prior to its initialization.
[in]userpinThe user PIN to be set on the SEcube.
[in]adminpinThe admin PIN to be set on the SEcube.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_delete_group()

int sekey_delete_group ( std::string &  groupID)

API to delete a group from SEkey. Available only for the administrator.

Parameters
[in]groupIDThe ID of the group to delete.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_delete_user()

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.

Parameters
[in]userIDThe ID of the user to be deleted from SEkey.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_delete_user_group()

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.

Parameters
[in]user_idThe ID of the user to be deleted from SEkey.
[in]group_idThe ID of the group from which the user must be deleted.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_find_key_v1()

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.

Parameters
[out]chosen_keyID of the best key to be used given the specified parameters.
[in]source_user_idUser ID of the sender.
[in]dest_user_idUser ID of the receiver.
[in]keytypeThe type of the key. Currently only se_key_type::symmetric_data_encryption is supported.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_find_key_v2()

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.

Parameters
[out]chosen_keyID of the best key to be used given the specified group.
[in]source_user_idUser ID of the sender.
[in]group_idGroup ID of the receiver.
[in]keytypeThe type of the key. Currently only se_key_type::symmetric_data_encryption is supported.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_find_key_v3()

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.

Parameters
[out]chosen_keyID of the best key to be used given the users specified.
[in]source_user_idUser ID of the sender.
[in]dest_user_idIDs of the recipients.
[in]keytypeThe type of the key. Currently only se_key_type::symmetric_data_encryption is supported.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_group_change_default_cryptoperiod()

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.

Parameters
[in]groupIDThe ID of the group to modify.
[in]cryptoperiodThe new value for the default cryptoperiod
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_group_change_max_keys()

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.

Parameters
[in]groupIDThe group whose maximum number of key should be modified.
[in]maxkeysThe maximum number of keys.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

The new value can't be lower than the current number of keys.

◆ sekey_group_change_name()

int sekey_group_change_name ( std::string &  groupID,
std::string &  newname 
)

Change the name of a group. Available only for the administrator.

Parameters
[in]groupIDThe ID of the group whose name must be changed.
[in]newnameThe new name of the group.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

◆ sekey_group_get_info()

int sekey_group_get_info ( std::string &  groupID,
se_group group 
)

Retrieve the details about a single group (keys and users excluded).

Parameters
[in]groupIDThe ID of the groups we want to search for in the KMS.
[in]groupPointer to a se_group object that will contain the details of the group.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_group_get_info_all()

int sekey_group_get_info_all ( std::vector< se_group > *  groups)

Retrieve the details about all groups of SEkey (keys and users excluded).

Parameters
[in]groupsPointer to a vector of se_group objects.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_init_user_SEcube()

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.

Parameters
[in]uidThe ID of the user to initialize.
[in]userpinThe PIN to be set on the SEcube of the user to perform the login with user privilege.
[in]adminpinThe PIN to be set on the SEcube of the user to perform the login with admin privilege.
[in]pinThe 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).
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise. This API must be called after the sekey_add_user() function. It does not matter how much time after you call it, as long as you do it before physically handing the SEcube to the SEkey user. For Linux users: when you connect the SEcube of the user to the host computer, remember to mount the SEcube otherwise this API might fail.

◆ sekey_key_change_name()

int sekey_key_change_name ( std::string &  key_id,
std::string &  key_name 
)

Change the name of a key. Available only for the administrator.

Parameters
[in]key_idThe ID of the key whose name should be changed.
[in]key_nameThe new name of the key.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

◆ sekey_key_change_status()

int sekey_key_change_status ( std::string &  key_id,
se_key_status  status 
)

Change the status of a key. Available only for the administrator.

Parameters
[in]key_idThe ID of the key whose status should be changed.
[in]statusThe new status of the key.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_key_get_info()

int sekey_key_get_info ( std::string &  key_id,
se_key key 
)

Retrieve the details about a single key.

Parameters
[in]key_idThe ID of the key to search for.
[out]keyPointer to a se_key object that will contain the details of the key.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_key_get_info_all()

int sekey_key_get_info_all ( std::vector< se_key > *  keys)

Retrieve the details about all keys of SEkey.

Parameters
[out]keysPointer to a vector of se_key objects.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_readlog()

void sekey_readlog ( std::string *  sn,
std::string &  output 
)

Retrieve the content of the logfile associated to a specific SEcube.

Parameters
[in]snThe serial number of the SEcube whose logfile must be retrieved. If NULL the current SEcube is considered.
[out]outputA string containing the content of the logfile.

◆ sekey_start()

int sekey_start ( L0 &  l0,
L1 *  l1ptr 
)

API to start the SEkey KMS.

Parameters
[in]l0L0 object created by the caller.
[in]l1ptrThe pointer to the L1 object created iby the caller.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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().

◆ sekey_stop()

int sekey_stop ( )

API to stop the SEkey KMS.

Returns
This API always returns SEKEY_OK, errors are ignored, no throw.

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.

◆ sekey_user_change_name()

int sekey_user_change_name ( std::string &  userID,
std::string &  newname 
)

Change the name of a user. Available only for the administrator.

Parameters
[in]userIDThe ID of the user whose name should be changed.
[in]newnameThe new name of the user.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

◆ sekey_user_get_info()

int sekey_user_get_info ( std::string &  userid,
se_user user 
)

Retrieve the details about a single user.

Parameters
[in]useridThe ID of the users we want to search for in the KMS.
[in]userPointer to a se_user object that will contain the details of the user.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.

◆ sekey_user_get_info_all()

int sekey_user_get_info_all ( std::vector< se_user > *  users)

Retrieve the details about all users of SEkey.

Parameters
[in]usersPointer to a vector of se_user objects.
Returns
Returns SEKEY_OK upon success, a value from sekey_error otherwise.

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.