SEFile
Userspace drivers to manage a secure filesystem
 All Data Structures Files Functions Variables Typedefs Macros Groups
Macros | Typedefs | Functions
SEfile.h File Reference

This file includes constants, return values and public functions used for implementing a secure file system. More...

#include "se3/L0.h"
#include "se3/L1.h"
#include "se3/se3c1def.h"
#include <string.h>
#include <ctype.h>

Go to the source code of this file.

Macros

#define MAX_PATHNAME   256
 
Use this values as mode parameter for
#define SEFILE_READ
 
#define SEFILE_WRITE
 
Use this values as access parameter for
#define SEFILE_NEWFILE
 
#define SEFILE_OPEN
 
Use this values as whence parameter for
#define SEFILE_BEGIN
 
#define SEFILE_CURRENT
 
#define SEFILE_END
 
Returned error values

If something goes wrong, one of this values will be returned.

#define SEFILE_ENV_ALREADY_SET   15
 
#define SEFILE_ENV_WRONG_PARAMETER   16
 
#define SEFILE_ENV_MALLOC_ERROR   17
 
#define SEFILE_ENV_NOT_SET   18
 
#define SEFILE_SECTOR_MALLOC_ERR   19
 
#define SEFILE_GET_FILEPOINTER_ERR   20
 
#define SEFILE_HANDLE_MALLOC_ERR   21
 
#define SEFILE_CLOSE_HANDLE_ERR   22
 
#define SEFILE_CREATE_ERROR   23
 
#define SEFILE_OPEN_ERROR   24
 
#define SEFILE_WRITE_ERROR   25
 
#define SEFILE_SEEK_ERROR   26
 
#define SEFILE_READ_ERROR   27
 
#define SEFILE_ILLEGAL_SEEK   28
 
#define SEFILE_FILESIZE_ERROR   29
 
#define SEFILE_BUFFER_MALLOC_ERR   30
 
#define SEFILE_FILENAME_DEC_ERROR   31
 
#define SEFILE_FILENAME_ENC_ERROR   32
 
#define SEFILE_DIRNAME_ENC_ERROR   33
 
#define SEFILE_DIRNAME_DEC_ERROR   34
 
#define SEFILE_DIRNAME_TOO_LONG   35
 
#define SEFILE_MKDIR_ERROR   36
 
#define SEFILE_LS_ERROR   37
 
#define SEFILE_USER_NOT_ALLOWED   38
 
#define SEFILE_ENV_INIT_ERROR   39
 
#define SEFILE_ENV_UPDATE_ERROR   40
 
#define SEFILE_INTEGRITY_ERROR   41
 
#define SEFILE_NAME_NOT_VALID   42
 
#define SEFILE_TRUNCATE_ERROR   43
 
#define SEFILE_DEVICE_SN_MISMATCH   44
 
#define SEFILE_KEYID_NOT_PRESENT   45
 
#define SEFILE_ALGID_NOT_PRESENT   46
 
#define SEFILE_PATH_TOO_LONG   47
 
#define SEFILE_SYNC_ERR   48
 
#define SEFILE_SIGNATURE_MISMATCH   49
 
Constant used to define sector structure.

Do not change this unless you know what you are doing.

#define SEFILE_SECTOR_SIZE   512
 
#define SEFILE_SECTOR_DATA_SIZE   (SEFILE_SECTOR_SIZE-B5_SHA256_DIGEST_SIZE)
 
#define SEFILE_BLOCK_SIZE   B5_AES_BLK_SIZE
 
#define SEFILE_LOGIC_DATA   (SEFILE_SECTOR_DATA_SIZE-2)
 
#define SEFILE_SECTOR_OVERHEAD   (SEFILE_SECTOR_SIZE-SEFILE_LOGIC_DATA)
 

Typedefs

typedef struct SEFILE_HANDLESEFILE_FHANDLE
 

Functions

uint16_t secure_init (se3_session *s, uint32_t keyID, uint16_t crypto)
 This function creates a new secure environment, by allocating statically the parameters needed by the following functions. More...
 
uint16_t secure_update (se3_session *s, int32_t keyID, uint16_t crypto)
 This function can be called only after the secure_init() function and give to the user the possibility to overwrite the Environment variables with new ones. More...
 
uint16_t secure_finit ()
 This function deallocate the structures defined by the secure_init(). Should be called at the end of a session. No parameters are needed;. More...
 
uint16_t crypto_filename (char *path, char *enc_name, uint16_t *encoded_length)
 This function computes the encrypted name of the file specified at position path and its length. More...
 
uint16_t secure_open (char *path, SEFILE_FHANDLE *hFile, int32_t mode, int32_t access)
 This function opens a secure file and create a SEFILE_FHANDLE that can be used in future. More...
 
uint16_t secure_create (char *path, SEFILE_FHANDLE *hFile, int mode)
 This function creates a new secure file and creates a SEFILE_FHANDLE that can be used in future. If the file already exists, it is overwritten with an empty one, all previous data are lost. More...
 
uint16_t secure_write (SEFILE_FHANDLE *hFile, uint8_t *dataIn, uint32_t dataIn_len)
 This function writes the characters given by dataIn to the encrypted file hFile. Before writing them, dataIn is encrypted according to the environmental parameters. More...
 
uint16_t secure_read (SEFILE_FHANDLE *hFile, uint8_t *dataOut, uint32_t dataOut_len, uint32_t *bytesRead)
 This function reads from hFile bytesRead characters out of dataOut_len correctly decrypted ones and stores them in dataOut string. More...
 
uint16_t secure_seek (SEFILE_FHANDLE *hFile, int32_t offset, int32_t *position, uint8_t whence)
 This function is used to move correctly the file pointer. More...
 
uint16_t secure_truncate (SEFILE_FHANDLE *hFile, uint32_t size)
 This function resizes the file pointed by hFile to size. If size is bigger than its current size the gap is filled with 0s. More...
 
uint16_t secure_close (SEFILE_FHANDLE *hFile)
 This function releases resources related to hFile. More...
 
uint16_t secure_ls (char *path, char *list, uint32_t *list_length)
 This function identifies which encrypted files and encrypted directories are present in the directory pointed by path and writes them in list. It only recognizes the ones encrypted with the current environmental parameters. More...
 
uint16_t secure_getfilesize (char *path, uint32_t *position)
 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. More...
 
uint16_t secure_mkdir (char *path)
 This function creates a directory with an encrypted name. More...
 
uint16_t secure_sync (SEFILE_FHANDLE *hFile)
 This function is used in case we want to be sure that the physical file is synced with the OS buffers. More...
 

Detailed Description

This file includes constants, return values and public functions used for implementing a secure file system.

Authors
Francesco Giavatto, Nicolò Maunero, Giulio Scalia
Date
17/09/2016

In this library you will find wrappers to common OS system calls, in order to manage encrypted files using the SECube Board. In this files are also reported the constant used as parameter and all the possible return values.

Macro Definition Documentation

#define MAX_PATHNAME   256

Maximum length for pathname string

Typedef Documentation

typedef struct SEFILE_HANDLE* SEFILE_FHANDLE

Data struct used to access encrypted files

Function Documentation

uint16_t crypto_filename ( char *  path,
char *  enc_name,
uint16_t *  encoded_length 
)

This function computes the encrypted name of the file specified at position path and its length.

Parameters
[in]pathIt can be absolute or relative but it can not be a directory. No encrypted directory are allowed inside the path.
[out]enc_nameAlready allocate string where the encrypted filename should be stored.
[out]encoded_lengthPointer to an allocated uint16_t where the length of the encrypted filename is stored.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_close ( SEFILE_FHANDLE hFile)

This function releases resources related to hFile.

Parameters
[in]hFileThe handle to the file we do not want to manipulate no more.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_create ( char *  path,
SEFILE_FHANDLE hFile,
int  mode 
)

This function creates a new secure file and creates a SEFILE_FHANDLE that can be used in future. If the file already exists, it is overwritten with an empty one, all previous data are lost.

Parameters
[in]pathSpecify the absolute/relative path where to create the file. No encrypted directory are allowed inside the path.
[out]hFileThe pointer in which the file handle to the new opened file is placed after a success, NULL in case of failure.
[in]modeThe mode in which the file should be created. See mode parameter for secure_open.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_finit ( )

This function deallocate the structures defined by the secure_init(). Should be called at the end of a session. No parameters are needed;.

Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_getfilesize ( char *  path,
uint32_t *  position 
)

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.

Parameters
[in]pathAbsolute or relative path the file. No encrypted directory are allowed inside the path.
[out]positionPointer to an allocated uint32_t variable where will be stored the file size.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_init ( se3_session *  s,
uint32_t  keyID,
uint16_t  crypto 
)

This function creates a new secure environment, by allocating statically the parameters needed by the following functions.

Parameters
[in]sContains the pointer to the se3_session structure that must be used during the session.
[in]keyIDContains the ID number of the key that must be used during the session.
[in]cryptoContains the id to specify which algorithm to use. See AlgorithmAvail, it can be SE3_ALGO_MAX + 1 if you don't know which algorithm to choose. See error values for error list.

All the data passed to this function must be allocated and filled with valid data. Once secure_init succeed it is possible to destroy these data, since a copy has been made. N.B. Remember to call the secure_finit function to deallocate these data once you have finished.

uint16_t secure_ls ( char *  path,
char *  list,
uint32_t *  list_length 
)

This function identifies which encrypted files and encrypted directories are present in the directory pointed by path and writes them in list. It only recognizes the ones encrypted with the current environmental parameters.

Parameters
[in]pathAbsolute or relative path to the directory to browse. No encrypted directory are allowed inside the path.
[out]listAlready allocated array where to store filenames and directory names. Each entry is separated by '\0'.
[out]list_lengthPointer to a uint32_t used to stored total number of characters written in list.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_mkdir ( char *  path)

This function creates a directory with an encrypted name.

Parameters
[in]pathAbsolute or relative path of the new directory. No encrypted directory are allowed inside the path.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_open ( char *  path,
SEFILE_FHANDLE hFile,
int32_t  mode,
int32_t  access 
)

This function opens a secure file and create a SEFILE_FHANDLE that can be used in future.

Parameters
[in]pathSpecify the absolute/relative path where to retrieve the file to open. No encrypted directory are allowed inside the path.
[out]hFileThe pointer in which the file handle to the opened file is placed after a success, NULL in case of failure.
[in]modeThe mode in which the file should be opened. See mode parameter for secure_open.
[in]accessDefine if the file should be created or it should already exist. See access parameter for secure_open.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_read ( SEFILE_FHANDLE hFile,
uint8_t *  dataOut,
uint32_t  dataOut_len,
uint32_t *  bytesRead 
)

This function reads from hFile bytesRead characters out of dataOut_len correctly decrypted ones and stores them in dataOut string.

Parameters
[in]hFileThe handle to an already opened file to be read.
[out]dataOutAn already allocated array of characters where to store data read.
[in]dataOut_lenNumber of characters we want to read.
[out]bytesReadNumber of effective characters read, MUST NOT BE NULL.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_seek ( SEFILE_FHANDLE hFile,
int32_t  offset,
int32_t *  position,
uint8_t  whence 
)

This function is used to move correctly the file pointer.

Parameters
[in]hFileThe handle to the file to manipulate.
[in]offsetAmount of character we want to move.
[out]positionPointer to a int32_t variable where the final position is stored, MUST NOT BE NULL.
[in]whenceAccording to this parameter we can choose if we want to move from the file beginning, file ending or current file pointer position. See whence parameter for secure_seek.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_sync ( SEFILE_FHANDLE hFile)

This function is used in case we want to be sure that the physical file is synced with the OS buffers.

Parameters
hFileHandle to the secure file to be synced.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_truncate ( SEFILE_FHANDLE hFile,
uint32_t  size 
)

This function resizes the file pointed by hFile to size. If size is bigger than its current size the gap is filled with 0s.

Parameters
[in]hFileThe handle to the file to manipulate.
[in]sizeNew size of the file.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.
uint16_t secure_update ( se3_session *  s,
int32_t  keyID,
uint16_t  crypto 
)

This function can be called only after the secure_init() function and give to the user the possibility to overwrite the Environment variables with new ones.

Parameters
[in]sContains the pointer to the se3_session structure that must be used during the session. Can be NULL.
[in]keyIDkeyID Contains the ID number of the key that must be used during the session. Can be -1.
[in]cryptoContains the id to specify which algorithm to use.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.

Parameters from 1 to 3 can be a NULL pointer or '-1' value, if all parameters are NULL (or '-1' in case of keyID) the function is a No-Operation one.

uint16_t secure_write ( SEFILE_FHANDLE hFile,
uint8_t *  dataIn,
uint32_t  dataIn_len 
)

This function writes the characters given by dataIn to the encrypted file hFile. Before writing them, dataIn is encrypted according to the environmental parameters.

Parameters
[in]hFileThe handle to an already opened file to be written.
[in]dataInThe string of characters that have to be written.
[in]dataIn_lenThe length, in bytes, of the data that have to be written.
Returns
The function returns a (uint16_t) '0' in case of success. See error values for error list.