#ifndef _QSEE_SFS_H_ #define _QSEE_SFS_H_ /** @file qsee_sfs.h @brief Secure File System with Encryption and Integrity Protection. This file contains the definitions of the constants, data structures, and interfaces that provide methods to encrypt/integrity-protect and decrypt/verify content to the EFS. */ /*============================================================================= Copyright (c) 2000-2019 QUALCOMM Technologies Incorporated. All Rights Reserved. Qualcomm Confidential and Proprietary =============================================================================*/ /*============================================================================= EDIT HISTORY FOR MODULE when who what, where, why -------- --- ---------------------------------------------------------- 07/23/14 mr Added new SFS for file enumeration 03/12/14 yh Add qsee_sfs_error() 02/12/12 chm Added support for SFS remove directory. 10/06/11 cz corrected the checking of theqsee_sfs_open return 08/06/10 sd {TechPubs] Edited Doxygen markup and comments. 08/28/09 ejt removed #include "customer.h" and FEATURE flags for CMI compliance 12/17/08 ejt removedqsee_sfs_SYSTEM_INTERFACE from SFS files 04/04/07 df adding MINIMAL_DUAL_PD featurization 03/03/07 df new functionqsee_sfs_ixfile_rm() 03/01/07 df support for seek 01/09/06 df local support for GetInfo 12/22/06 df support for usfs 12/08/06 df added cpp support 07/25/05 df changedqsee_sfs_init prototype 07/22/05 df added FEATURE_SEC_SFS =============================================================================*/ /*=========================================================================== INCLUDE FILES FOR MODULE ===========================================================================*/ #ifdef __cplusplus extern "C" { #endif #include #include /** @cond */ typedef enum { SFS_NO_ERROR = 0, /**< No error. */ SFS_ERROR_GENERIC = 1, /**< Generic failure error code. */ SFS_NO_MEMORY = 2, /**< Malloc failed. */ SFS_FS_ERROR = 3, /**< REE file system operation failed. */ SFS_NO_FILE = 4, /**< No such file. */ SFS_VERI_HMAC_ERROR = 5, /**< SFS segment sanity check failed, data is tampered. */ }sfs_errno_enum_type; /* Maximum file name size allowed by Secure File System */ #define SFS_MAX_FILENAME_SIZE 64 /* File entry which makes up the file list returned by qsee_sfs_get_file_list() */ typedef struct { char file_name[SFS_MAX_FILENAME_SIZE + 1]; /* Name of file in app's file list */ uint32_t file_size; /* Size of the file with file_name is app's file list */ } sfs_file_entry; /** @endcond */ /*---------------------------------------------------------------------------- * Function Declarations and Documentation * -------------------------------------------------------------------------*/ /** @addtogroup qtee_sfs @{ */ /** Retrieves open SFS file size. @param[in] fd File descriptor. @param[out] size Pointer to open file size. @return E_SUCCESS - File size stored in size parameter. \n E_FAILURE - Error occurred while getting file size. */ int qsee_sfs_getSize(int fd, uint32_t* size); /** This is a deprecated function because SFS does not support folder hierarchy. Calls to this function result in a NOP. @param[in] path Pointer to a fully qualified path. @return Always returns E_SUCCESS. */ int qsee_sfs_mkdir(const char* path); /** This is a deprecated function because SFS does not support folder hierarchy. Calls to this function result in a NOP. @param[in] path Pointer to a fully qualified path @return Always returns E_SUCCESS. */ int qsee_sfs_rmdir(const char* path); /** Opens an SFS file. The options are specified by File mode in the flag parameter. @detdesc In the SFS, opening a file does not actually do anything in the file system. If the file (along with the associated file segments) already exists and the file is created with O_TRUNC mode, the associated subfiles are deleted. \n The first segment is created only when new bytes to be written begin arriving. @note1hang The base directory must exist; otherwise, returns NULL. @param[in] path Pointer to a fully qualified path of filename to be opened. @param[in] flags Bitmask field used to specify file modes: - O_RDONLY - Open for read-only access. - O_READWRITE - Open for read-write access. - O_CREAT - Creates file if it does not exist. - O_TRUNC - Truncates file to zero size after opening. - O_APPEND - Write operations occur at the end of the file. @return Non-zero -- A valid file descriptor. \n Zero - Error occurred while opening file. */ int qsee_sfs_open(const char* path, int flags); /** Closes an open SFS file. Releases all resources used by the file. @param[in] fd File descriptor. @return E_SUCCESS - Closed file successfully. \n E_FAILURE - Error occurred while closing file. */ int qsee_sfs_close(int fd); /** Reads bytes from an encrypted SFS file previously opened via call to qsee_sfs_open(). @detdesc nbytes are read from the current file position, and the file position advances by the number of read bytes. SFS performs the necessary cipher and verification operations as bytes are read from the file. @param[in] fd File descriptor. @param[in] buf Pointer to buffer to hold read bytes. @param[in] nbytes Number of bytes to read from the file. @return Returns the number of bytes read from an SFS file. \n Returns -1 for the error case. */ int qsee_sfs_read(int fd, char *buf, int nbytes); /** Writes bytes to a previously opened encrypted SFS file via call to qsee_sfs_open. @detdesc nbytes are written to the current file position. \n If O_APPEND flag was set in qsee_sfs_open(), bytes are written at the end of the file unless qsee_sfs_seek() was issued before qsee_sfs_write(). In this case, data is written to the file position that qsee_sfs_seek() set. The file position advances by the number of bytes written. @param[in] fd File descriptor. @param[in] buf Pointer to buffer to be written. @param[in] nbytes Number of bytes to write to the file. @return Returns the number of bytes written to an SFS file. \n Returns -1 for the error case. */ int qsee_sfs_write(int fd, const char *buf, int nbytes); /** Removes an SFS file that was previously created through qsee_sfs_open(). @param[in] path Pointer to a fully qualified path of the file to be deleted. @return E_SUCCESS - File removal successful. \n E_FAILURE - Error occurred while removing the file. */ int qsee_sfs_rm(const char *path); /** Moves the read location to point to n bytes from the start, current, or end of the file. @detdesc Opens, verifies, and decrypts the subfile that corresponds to the current position. The segment position advances to the current position. @param[in] fd File descriptor. @param[in] offset File offset to seek in bytes. @param[in] whence Indicates start, end, or current position. - SEEK_SET - Start of file. - SEEK_CUR - Current file position. - SEEK_END - End of file. @return If successful, the current location. \n If an error occurred, -1. */ int qsee_sfs_seek(int fd, int32_t offset, int whence); /** Checks error indicator. @detdesc Checks if the error indicator associated with fd is set; returns a value different from zero if it is. @note1hang The indicator is set by a previous operation on the SFS fd that failed. @param[in] fd File descriptor. When qsee_sfs_open() returns zero, it will try to return the failure reason of the last open file. @return Returns a non-zero value if the error indicator associated with fd is set. \n Otherwise, returns zero. */ int qsee_sfs_error(int fd); /** Returns a list of files created by the calling application. @detdesc Returns an array of sfs_file_entry structs through the output parameter file_list, which contains the file name and file size for each file created by the calling applicaiton through qsee_sfs_open using the O_CREAT flag. The returned file_list size is returned through the output parameter file_list_len. @par If file_list_len > 0, the caller must call qsee_sfs_clean_file_list to recollect resources allocated by this function. @par If file_list_len == 0, there are currently no files belonging to the calling application and the caller should not call qsee_sfs_clean_file_list because the list will be set to NULL. \n After editing the files, it is recommended to obtain a new file list by calling qsee_sfs_clean_file_list on the current file list and calling this function once more. @param[out] file_list Double pointer to sfs_file_entry list represents files created by the calling application. @param[out] file_list_len Pointer to file list length. @return 0 -- Created the application file list successfully. \n Non-zero -- An error occured while creating the application file list. Use qsee_sfs_error() to get a more detailed error code. */ int qsee_sfs_get_file_list(sfs_file_entry** file_list, uint32_t* file_list_len); /** Reclaims allocated resources to create the application's file list. @detdesc The memory resources allocated in qsee_sfs_get_file_list() are reclaimed and can be used for future memory allocation. @param[in] file_list Pointer to file list returned by a successful call to qsee_sfs_get_file_list(). */ void qsee_sfs_clean_file_list(sfs_file_entry* file_list); /** Reports if SFS supports hardware-backed rollback protection. @param[out] b Pointer to boolean rollback protection supported status. @return E_SUCCESS -- On success. \n E_FAILURE -- On failure. */ int qsee_sfs_is_anti_rollback_enabled(bool* b); /** @} */ /* end_addtogroup qtee_sfs*/ #ifdef __cplusplus } #endif #endif //_qsee_sfs_API_H_