SEcube open-source SDK
Sefile_apis

APIs of SEfile

These APIs are the most useful to exploit the SEfile library.

uint16_t SEfile::secure_open (char *path, int32_t mode, int32_t creation)
 This function opens or creates a secure file managed with SEfile. More...
 
uint16_t SEfile::secure_close ()
 This function releases the resources related to the underlying SEfile object (i.e. closes the file descriptor). More...
 
uint16_t SEfile::secure_read (uint8_t *dataOut, uint32_t dataOut_len, uint32_t *bytesRead)
 This function reads dataOut_len bytes into dataOut from the file descriptor managed by the underlying SEfile object. More...
 
uint16_t SEfile::secure_write (uint8_t *dataIn, uint32_t dataIn_len)
 This function writes the bytes stored at dataIn to the encrypted file managed by the SEfile object on which this method is called. More...
 
uint16_t SEfile::secure_seek (int32_t offset, int32_t *position, uint8_t whence)
 This function is used to move the file pointer of a file managed by a SEfile object. More...
 
uint16_t SEfile::secure_truncate (uint32_t size)
 This function resizes the file managed by the underlying SEfile object to size bytes. If size is bigger than its current size the gap is filled with 0s. More...
 
uint16_t SEfile::secure_sync ()
 This function is used in case we want to be sure that the physical file is synced with the OS buffers. More...
 

Detailed Description

Function Documentation

◆ secure_close()

uint16_t SEfile::secure_close ( )

This function releases the resources related to the underlying SEfile object (i.e. closes the file descriptor).

Returns
The function returns 0 in case of success. See error values for error list.

◆ secure_open()

uint16_t SEfile::secure_open ( char *  path,
int32_t  mode,
int32_t  creation 
)

This function opens or creates a secure file managed with SEfile.

Parameters
[in]pathThe absolute/relative path (plaintext, i.e. myfile.txt) where to open or create the file.
[in]modeThe mode in which the file should be opened. See mode parameter for secure_open.
[in]creationDefine if the file should be created or it should already exist. See creation parameter for secure_open.
Returns
The function returns 0 in case of success. See error values for error list.

Notice that you must specify if you want to open the file or if you want to create it. There is not the possibility of "create if the file does not exist", therefore if you need such behaviour you must check in advance if the file exists or not (i.e. computing the encrypted name of the file with crypto_filename() and then checking with OS system calls if the file exists).

◆ secure_read()

uint16_t SEfile::secure_read ( uint8_t *  dataOut,
uint32_t  dataOut_len,
uint32_t *  bytesRead 
)

This function reads dataOut_len bytes into dataOut from the file descriptor managed by the underlying SEfile object.

Parameters
[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, it cannot be NULL.
Returns
The function returns 0 in case of success. See error values for error list.

◆ secure_seek()

uint16_t SEfile::secure_seek ( int32_t  offset,
int32_t *  position,
uint8_t  whence 
)

This function is used to move the file pointer of a file managed by a SEfile object.

Parameters
[in]offsetAmount of bytes we want to move.
[out]positionPointer to a int32_t variable where the final position is stored, it cannot 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 0 in case of success. See error values for error list.

◆ secure_sync()

uint16_t SEfile::secure_sync ( )

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

Returns
The function returns 0 in case of success. See error values for error list.

◆ secure_truncate()

uint16_t SEfile::secure_truncate ( uint32_t  size)

This function resizes the file managed by the underlying SEfile object to size bytes. If size is bigger than its current size the gap is filled with 0s.

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

◆ secure_write()

uint16_t SEfile::secure_write ( uint8_t *  dataIn,
uint32_t  dataIn_len 
)

This function writes the bytes stored at dataIn to the encrypted file managed by the SEfile object on which this method is called.

Parameters
[in]dataInThe array of bytes that have to be written.
[in]dataIn_lenThe length, in bytes, of the data that have to be written.
Returns
The function returns a 0 in case of success. See error values for error list.