SEcube open-source SDK
Classes | Macros | Functions | Variables
SEfile.h File Reference

This is the SEfile header that contains most of the methods, constants and structures used by SEfile. More...

#include "../sources/L1/L1.h"
#include "SEfile_C_interface.h"

Go to the source code of this file.

Classes

struct  SEFILE_HANDLE
 The SEFILE_HANDLE struct This abstract data type is used to hide from higher level of abstraction its implementation. The data stored in here are the current physical file pointer position and the file descriptor OS-dependent data type. More...
 
struct  SEKEY_HEADER
 The header of each file encrypted with SEfile. This is the header that contains info for the SEkey system. It is stored as cleartext and it is not authenticated. The dimension is always SEKEY_HDR_LEN. More...
 
struct  SEFILE_HEADER
 The SEFILE_HEADER struct This data struct is used to define a 31 bytes field inside a sector while taking care of its inner composition. More...
 
struct  SEFILE_SECTOR
 The SEFILE_SECTOR struct This data struct is the actual sector organization. The total size should ALWAYS be equal to SEFILE_SECTOR_SIZE. The first sector is used to hold ONLY the header. Thanks to the union data type, the developer can simply declare a sector and then choose if it is the header sector or not. More...
 
class  SEfile
 A SEfile object is used to manage a file encrypted with SEfile. More...
 

Macros

#define KEY_CHECK_INTERVAL   1
 Time interval (in seconds) used to check for the validity of the key used to encrypt the file.
 
#define SEFILE_NONCE_LEN   32
 
#define SEKEY_HDR_LEN   16
 Length of header sector reserved to SEkey informations. More...
 

Functions

uint16_t get_secure_context (std::string &filename, std::string *keyid, uint16_t *algo)
 This function retrieves the key ID and the algorithm used to encrypt the file specified by filename. More...
 
uint16_t secure_mkdir (std::string &path, L1 *SEcubeptr, uint32_t key)
 This function creates a directory with an encrypted name. More...
 
uint16_t secure_ls (std::string &path, std::vector< std::pair< std::string, std::string >> &list, L1 *SEcubeptr)
 This function identifies which encrypted files and encrypted directories are present in the directory pointed by path and writes them in list. More...
 
uint16_t secure_getfilesize (char *path, uint32_t *position, L1 *SEcubeptr)
 This function is used to get the total logic size of an encrypted file pointed by path. Logic size will always be smaller than physical size because it takes into account the overhead introduced by SEfile. More...
 
uint16_t secure_recrypt (std::string path, uint32_t key, L1 *SEcubeptr)
 This function re-encrypts an encrypted file pointed by path with the new key specified as parameter. More...
 
uint16_t decrypt_filename (std::string &path, char *filename, L1 *SEcubeptr)
 This function is used to compute the plaintext of an encrypted filename stored in path. More...
 
uint16_t crypt_dirname (std::string &path, char *encDirname, uint32_t *enc_len, L1 *SEcubeptr, uint32_t key)
 This function is used to compute the ciphertext of a directory name stored in dirname. More...
 
uint16_t decrypt_dirname (std::string &path, char *decDirname, L1 *SEcubeptr)
 This function is used to compute the plaintext of am encrypted directory name stored in dirname. More...
 
uint16_t encrypt_name (void *buff1, void *buff2, size_t size, uint16_t direction, L1 *SEcubeptr, uint32_t key)
 Internally used by crypt_dirname and decrypt_dirname().
 
uint16_t valid_directory_name (std::string &name)
 This function checks if the given name can be a valid SEfile directory name. More...
 
uint16_t valid_file_name (std::string &name)
 This function checks if the given name can be a valid SEfile file name. More...
 
size_t pos_to_cipher_block (size_t current_position)
 Internally used by SEfile functions.
 
void compute_blk_offset (size_t current_offset, uint8_t *nonce)
 Internally used by SEfile functions.
 
void get_filename (char *path, char *file_name)
 Extract the name of a file from its path.
 
void get_path (char *full_path, char *path)
 Extract the path of a file removing the file name.
 

Variables

bool override_key_check
 Global flag that is used to bypass the validity check of a key to read or write encrypted data. It is used only to re-encrypt data belonging to a compromised file.
 

Detailed Description

This is the SEfile header that contains most of the methods, constants and structures used by SEfile.

Author
Fornero Matteo
Date
25/11/2019

Macro Definition Documentation

◆ SEKEY_HDR_LEN

#define SEKEY_HDR_LEN   16

Length of header sector reserved to SEkey informations.

This is the length of the header required by SEkey. it is embedded in the SEfile header; the length of the SEkey header must be a multiple of the block size used by the cipher (16 bytes for AES256 at the moment) because the size of the data to cipher inside the first sector is 512 - SEFILE_NONCE_LEN - SEKEY_HDR_LEN and it must be a multiple of 16.

Function Documentation

◆ crypt_dirname()

uint16_t crypt_dirname ( std::string &  path,
char *  encDirname,
uint32_t *  enc_len,
L1 *  SEcubeptr,
uint32_t  key 
)

This function is used to compute the ciphertext of a directory name stored in dirname.

Parameters
[in]pathPath to the directory whose name has to be encrypted.
[out]encDirnameA preallocated string where to store the encrypted directory name.
[out]enc_lenWhere to store how many bytes the encrypted directory name is long. Can be NULL.
[in]SEcubeptrPointer to the L1 object used to communicate with the SEcube.
[in]keyID of the key to be used to encrypt the name of the new directory.
Returns
The function returns 0 in case of success. See error values for error list.

◆ decrypt_dirname()

uint16_t decrypt_dirname ( std::string &  path,
char *  decDirname,
L1 *  SEcubeptr 
)

This function is used to compute the plaintext of am encrypted directory name stored in dirname.

Parameters
[in]dirpathPath to the directory whose name has to be decrypted.
[out]decDirnameA preallocated char array where to store the decrypted directory name.
[in]SEcubeptrPointer to the L1 object used to communicate with the SEcube.
Returns
The function returns 0 in case of success. See error values for error list.

◆ decrypt_filename()

uint16_t decrypt_filename ( std::string &  path,
char *  filename,
L1 *  SEcubeptr 
)

This function is used to compute the plaintext of an encrypted filename stored in path.

Parameters
[in]pathWhere the encrypted file is stored, it can be an absolute or relative path. No encrypted directory names are allowed.
[out]filenameA preallocated string where to store the plaintext filename.
[in]SEcubeptrPointer to the L1 object used to communicate with the SEcube.
Returns
The function returns 0 in case of success. See error values for error list.

◆ get_secure_context()

uint16_t get_secure_context ( std::string &  filename,
std::string *  keyid,
uint16_t *  algo 
)

This function retrieves the key ID and the algorithm used to encrypt the file specified by filename.

Parameters
[in]filenameAbsolute or relative path of the file.
[out]keyidThe ID of the key used to encrypt the file.
[out]algoThe algorithm used to encrypt the file.
Returns
The function returns 0 in case of success. See error values for error list.

◆ secure_getfilesize()

uint16_t secure_getfilesize ( char *  path,
uint32_t *  position,
L1 *  SEcubeptr 
)

This function is used to get the total logic size of an encrypted file pointed by path. Logic size will always be smaller than physical size because it takes into account the overhead introduced by SEfile.

Parameters
[in]pathAbsolute or relative path the file.
[out]positionWhere the size of the file is stored.
[in]SEcubeptrPointer to the L1 object used to communicate with the SEcube.
Returns
The function returns 0 in case of success. See error values for error list.

◆ secure_ls()

uint16_t secure_ls ( std::string &  path,
std::vector< std::pair< std::string, std::string >> &  list,
L1 *  SEcubeptr 
)

This function identifies which encrypted files and encrypted directories are present in the directory pointed by path and writes them in list.

Parameters
[in]pathAbsolute or relative path to the directory to browse.
[out]listList of pairs containing the encrypted name and the decrypted name.
[in]SEcubeptrPointer to the L1 object used to communicate with the SEcube.
Returns
The function returns a 0 in case of success. See error values for error list.

Notice that, if the name of a file or of a directory belonging to the path is not associated to SEfile, then it is copied as it is in the list. This function is not recursive.

◆ secure_mkdir()

uint16_t secure_mkdir ( std::string &  path,
L1 *  SEcubeptr,
uint32_t  key 
)

This function creates a directory with an encrypted name.

Parameters
[in]pathAbsolute or relative path of the new directory.
[in]SEcubeptrPointer to the L1 object used to communicate with the SEcube.
[in]keyID of the key to be used to encrypt the name of the new directory.
Returns
The function returns 0 in case of success. See error values for error list.

◆ secure_recrypt()

uint16_t secure_recrypt ( std::string  path,
uint32_t  key,
L1 *  SEcubeptr 
)

This function re-encrypts an encrypted file pointed by path with the new key specified as parameter.

Parameters
[in]pathAbsolute or relative path of the file.
[in]keyThe ID of the key used to encrypt the file.
[in]SEcubeptrPointer to the L1 object used to communicate with the SEcube.
Returns
The function returns 0 in case of success. See error values for error list.

This function should be used to re-encrypt a file that was encrypted with a key that is not trusted anymore (i.e. a compromised key).

◆ valid_directory_name()

uint16_t valid_directory_name ( std::string &  name)

This function checks if the given name can be a valid SEfile directory name.

Parameters
[in]nameName of the directory.
Returns
The function returns 0 in case of success. See error values for error list.

This function takes as input the name of a directory and checks if it matches the requirements of an encrypted directory name create with secure_mkdir() (i.e. alphanumeric characters, minimum number of characters, etc.).

◆ valid_file_name()

uint16_t valid_file_name ( std::string &  name)

This function checks if the given name can be a valid SEfile file name.

Parameters
[in]nameName of the file.
Returns
The function returns 0 in case of success. See error values for error list.

This function takes as input the name of a file and checks if it matches the requirements of an encrypted file name created with crypto_filename() (i.e. alphanumeric characters, minimum number of characters, etc.).