SEcube open-source SDK
Classes | Macros | Typedefs | Enumerations
SEkey.h File Reference

This file includes everything about SEkey. More...

#include "../sefile/SEfile.h"
#include "../sqlite/sqlite3.h"

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

Detailed Description

This file includes everything about SEkey.

Author
Fornero Matteo
Date
22/11/2019

Enumeration Type Documentation

◆ filetype

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.

◆ se_key_status

enum se_key_status
strong

Possible status assumed by a key. There are specific rules for status transition, see check_key_transition_validity() for more informations.

Enumerator
statusmin 

Lower boundary. This status is not valid, it is used only to check if the actual status value is within the boundaries.

preactive 

Default key status (automatically set on key generation).

active 

The key can be used for encryption and decryption.

suspended 

The key may be used for decryption, it may also be reactivated in future.

deactivated 

The key can be used only for decryption.

compromised 

The key must not be used for encryption. Files encrypted with this key must be decrypted and re-encrypted as soon as possible with a new key.

destroyed 

The key is not stored anymore in the KMS. Only the metadata are kept.

statusmax 

Upper boundary. This status is not valid, it is used only to check if the actual status value is within the boundaries.

◆ sekey_error

Error codes returned by functions of SEkey.

Enumerator
SEKEY_OK 

Function completed correctly.

SEKEY_ERR 

Generic error. SEkey database unchanged.

SEKEY_FILE_FOUND 

File found.

SEKEY_FILE_NOT_FOUND 

File not found.

SEKEY_ERR_AUTH 

Requested operation not allowed with current SEkey mode (admin or user).

SEKEY_USER_GROUP_DUP 

User already belonging to the group.

SEKEY_KEY_DUP 

Key already stored in SEkey.

SEKEY_GROUP_NOT_FOUND 

No such group inside SEkey.

SEKEY_GROUP_DUP 

Group already stored in SEkey.

SEKEY_USER_DUP 

User already stored in SEkey.

SEKEY_USER_NOT_FOUND 

No such user inside SEkey.

SEKEY_KEY_NOT_FOUND 

No such key inside SEkey.

SEKEY_ERR_PARAMS 

Invalid input parameters.

SEKEY_UNCHANGED 

Error. SEkey database unchanged.

SEKEY_RESTART 

Error while executing commit or rollback on the database. Restart the application to go back to coherent database content.

SEKEY_CORRUPTED 

SEkey database corrupted.

SEKEY_REPROG 

Error while initializing a SEcube. Device erase needed.

SEKEY_RESTART_REPROG 

Error while initializing a SEcube. Device erase needed and SEkey host application restart required.

SEKEY_BLOCKED 

Impossible to update SEkey. SEkey blocked until update is completed.

SEKEY_COMMON_GROUP_NOT_FOUND 

Returned when the application asks to SEkey to return the key to encrypt data for a set of users but there is no common groups among those users. The application must check for this error and, in case this error is returned, proceed to request a key to encrypt data in a unicast manner (1 to 1) instead of multicast (1 to many).

SEKEY_UNSUPPORTED 

Returned when a certain feature is not yet supported by the system (i.e. requesting a key with a type different from symmetric data encryption).

SEKEY_INVALID_KEY 

The key is not valid (i.e. does not exist or has invalid attributes).

SEKEY_INACTIVE_KEY 

The key is not active, so can't be used for encryption.

SEKEY_COMPROMISED_KEY 

The key is in compromised status.

SEKEY_DESTROYED_KEY 

The key is in destroyed status.

SEKEY_DEACTIVATED_KEY 

The key is in deactivated status.

SEKEY_PREACTIVE_KEY 

The key is in preactive status.

SEKEY_SUSPENDED_KEY 

The key is in suspended status.

◆ update_record_type

Record type identifiers for SEkey update files.

Enumerator
DELETE_USER_FROM_GROUP 

Request to delete a user from a group.

DELETE_USER 

Request to delete a user from SEkey.

KEY_DATA 

Request to store a new key inside the SEcube flash memory.

SQL_QUERY 

Request to execute a SQL query on the database.

DELETE_GROUP 

Request to delete a group from SEkey.