/**
 * @file       five_api.h
 * @brief      FIVE API for Android native applications.
 *
 * Main purpose of this module is providing interface FIVE
 * authentication functions. API is allowed for high-privileged applications.
 * @author     Oleksandr Fadieiev (o.fadieiev@samsung.com)
 * @version    1.0
 * @date       Created Nov 1, 2016
 * @copyright  In Samsung Ukraine R&D Center (SURC) under a contract between
 * @copyright  LLC "Samsung Electronics Ukraine Company" (Kiev, Ukraine) and
 * @copyright  "Samsung Electronics Co", Ltd (Seoul, Republic of Korea)
 * @copyright   Copyright: (c) Samsung Electronics Co, Ltd 2016. All rights reserved.
**/

#ifndef __FIVE_API_H__
#define __FIVE_API_H__

#include <stddef.h>
#include <stdbool.h>
#include "five_codes.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef struct {
  uint16_t length;
  uint8_t data[0];
} __attribute__((packed)) FiveIntegrityLabel;

/**
 * @brief Verifies fd in asynchronous mode
 * @details FIVE populates signature field to file struct of this fd after this command
 * @warning This checking affects process integrity flag.
 * @param [in] fd File descriptor
 * @return ::FIVE_SUCCESS code in case of success and error code otherwise
 */
FiveResult FiveVerifyFd(int fd);

/**
 * @brief Verifies fd in synchronize mode
 * @details FIVE populates signature field to file struct of this fd after this command
 * @warning This checking affects process integrity flag.
 * @param [in] fd File descriptor
 * @return ::FIVE_SUCCESS code in case of success and error code otherwise
 */
FiveResult FiveVerifyFdSync(int fd);

/**
 * @brief Signs fd
 * @warning The API can be called only from specific applications
 * @param [in] fd File descriptor
 * @param [in] label Label for FIVE signature (used to union files of an application)
 * @return ::FIVE_SUCCESS code in case of success and error code otherwise
 */
FiveResult FiveSignFd(int fd, const FiveIntegrityLabel *label);

/**
 * @brief Allocates integrity label
 * @param [in] data Data which must be used to create new label
 * @param [in] dataLen Length of data
 * @param [out] label Pointer on allocated label
 * @return ::FIVE_SUCCESS code in case of success and error code otherwise
 */
FiveResult FiveLabelAlloc(const char *data, uint16_t dataLen, FiveIntegrityLabel **label);

/**
 * @brief Frees allocated integrity label
 * @param [in] label Pointer on label to free
 */
void FiveLabelFree(FiveIntegrityLabel *label);

/**
 * @brief Gets integrity of task
 * @param [in] pid Process ID of task to read integrity. 0 means "current task"
 * @return Integrity of task (>= 0, except 100) in case of success and negative value if error occurs
 */
int FiveTaskGetIntegrity(pid_t pid);

/**
 * @brief Reads integrity of task or current state of integrity verification process
 * @param [in] pid Process ID of task to read integrity. 0 means "current task"
 * @param [in] blocked_read Attempt to read synchronously and wait for verification process completion
 * @return Integrity of task (>= 0) including verification in progress (= 100) in case of success and negative value
 *         if error occurs
 */
int FiveTaskReadIntegrity(pid_t pid, bool blocked_read);

/**
 * @brief Reads and allocates integrity label of task
 * @param [in] pid Process ID of task to read label (0 means current task)
 * @param [out] label Pointer on allocated label
 * @return ::FIVE_SUCCESS code in case of success and error code otherwise.
 * NOTES:
 * - Task doesn't have integrity label if label has been set as NULL
 * - Task has "system label" if label->length == 0
 */
FiveResult FiveTaskGetIntegrityLabel(pid_t pid, FiveIntegrityLabel **label);

#ifdef __cplusplus
}
#endif

#endif // __FIVE_API_H__