/**
 * @file       pa_api.h
 * @brief      Process authenticator API for Android native applications.
 *
 * @author     Ivan Vorobiov (i.vorobiov@samsung.com)
 * @version    1.0
 * @date       Created Feb 11, 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.
**/

/**
 * @defgroup nwd_api (Deprecated) Authentication handler API for NWd applications
 *
 * Main purpose of this module is providing interface to create
 * process authentication handler that be used
 * inside SWd to authenticate this process. The authentication handler
 * should be transfer to SWd counterpart in 3rd-application based manner.
 */

#ifndef __PA_API_H__
#define __PA_API_H__

#include "pa_handler.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Describe Process Authenticator return codes
 * @ingroup nwd_api
 */
typedef enum {
  PA_SUCCESS              = 0x00000000,   //!< The operation is completed successfully
  PA_GENERAL_ERROR        = 0x00010000,   //!< The operation is completed with error
  PA_INVALID_ARGUMENTS    = 0x00010001,   //!< The invalid arguments are passed to the function
  PA_MALLOC_ERROR         = 0x00010002,   //!< The function can not allocate enough memory
  PA_FIVE_ERROR           = 0x00010003,   //!< The file does not have FIVE signature
  PA_ALREADY_PROVISIONED  = 0x00010004,   //!< The file already has PA signature
} PaResult;

/**
 * @brief Create new authentication handler and pass current process information to it.
 * @details The function allocate memory for authentication blob and
 * add next information to it:
 * 1. Current process (thread) id.
 * 2. Process name (same with /proc/self/status).
 * 3. Application certificate which is provisioned by PROCA.
 * The application should pass this handler to SWd in custom manner.
 * @ingroup nwd_api
 *
 * Example of usage:
 * @code
 * void main() {
 *     PaHandler handler;
 *     PaHandlerCreate(&handler);
 *     
 *     // Call Trusted application and send the handler in custom manner
 *     call_trustlet(&handler);
 *     // Destroy PA handler
 *     PaHandlerDestroy(&handler);
 * }
 * @endcode
 *
 * @warning If PaHandlerCreate() returned PA_SUCCESS then application should free
 *          memory using PaHandlerDestroy(). Otherwise you don't need to call it
 *          because output data was not changed.
 *
 * @param [out] handler pointer on Process authentication handler
 * @return ::PA_SUCCESS code in case of success and error code otherwise
 */
PaResult PaHandlerCreate(PaHandler *handler);

/**
 * @brief Destroy the authentication handler and assigned information
 * @details Do cleanup and free all allocated memory. Should never fail.
 * @ingroup nwd_api
 * @param [in] handler pointer on Process authentication handler
 */
void PaHandlerDestroy(PaHandler *handler);

#ifdef __cplusplus
}
#endif

#endif // __PA_API_H__