sss/inc/fsl_sss_api.h

/*
 *
 * Copyright 2018-2020 NXP
 * SPDX-License-Identifier: Apache-2.0
 */
/** @file */
#ifndef _FSL_SSS_H_
#define _FSL_SSS_H_

#if !defined(SSS_CONFIG_FILE)
#include "fsl_sss_config.h"
#else
#include SSS_CONFIG_FILE
#endif

#include <fsl_sss_policy.h>

#include "fsl_sss_types.h"

/** Version of the SSS API */
#define SSS_API_VERSION (0x00000001u)

/** Size of an AES Block, in bytes */
#define SSS_AES_BLOCK_SIZE (16u)
/** Size of a DES Block, in bytes */
#define SSS_DES_BLOCK_SIZE (8u)
/** Size of a DES Key, in bytes */
#define SSS_DES_KEY_SIZE (8u)
/** Size of a DES IV, in bytes */
#define SSS_DES_IV_SIZE (8u)

/** Status of the SSS APIs */
typedef enum
{
    /** Operation was successful */
    kStatus_SSS_Success = 0x5a5a5a5au,
    /** Operation failed */
    kStatus_SSS_Fail = 0x3c3c0000u,
    /** Operation not performed because some of the passed parameters
     * were found inappropriate */
    kStatus_SSS_InvalidArgument = 0x3c3c0001u,
    /** Where the underlying sub-system *supports* multi-threading,
     * Internal status to handle simultaneous access.
     *
     * This status is not expected to be returned to higher layers.
     * */
    kStatus_SSS_ResourceBusy = 0x3c3c0002u,
} sss_status_t;

/** Helper macro to set enum value */

#define SSS_ENUM(GROUP, INDEX) ((GROUP) | (INDEX))

/** Cryptographic sub system */
typedef enum
{
    kType_SSS_SubSystem_NONE,
    /** Software based */
    kType_SSS_Software = SSS_ENUM(0x01 << 8, 0x00),
    kType_SSS_mbedTLS  = SSS_ENUM(kType_SSS_Software, 0x01),
    kType_SSS_OpenSSL  = SSS_ENUM(kType_SSS_Software, 0x02),
    /** HOST HW Based */
    kType_SSS_HW   = SSS_ENUM(0x02 << 8, 0x00),
    kType_SSS_SECO = SSS_ENUM(kType_SSS_HW, 0x01),
    /** Isolated HW */
    kType_SSS_Isolated_HW = SSS_ENUM(0x04 << 8, 0x00),
    kType_SSS_Sentinel    = SSS_ENUM(kType_SSS_Isolated_HW, 0x01),
    kType_SSS_Sentinel200 = SSS_ENUM(kType_SSS_Isolated_HW, 0x02),
    kType_SSS_Sentinel300 = SSS_ENUM(kType_SSS_Isolated_HW, 0x03),
    kType_SSS_Sentinel400 = SSS_ENUM(kType_SSS_Isolated_HW, 0x04),
    kType_SSS_Sentinel500 = SSS_ENUM(kType_SSS_Isolated_HW, 0x05),
    /** Secure Element */
    kType_SSS_SecureElement = SSS_ENUM(0x08 << 8, 0x00),
    /** To connect to https://www.nxp.com/products/:A71CH */
    kType_SSS_SE_A71CH = SSS_ENUM(kType_SSS_SecureElement, 0x01),
    kType_SSS_SE_A71CL = SSS_ENUM(kType_SSS_SecureElement, 0x02),
    /** To connect to https://www.nxp.com/products/:SE050 */
    kType_SSS_SE_SE05x = SSS_ENUM(kType_SSS_SecureElement, 0x03),
    kType_SSS_SubSystem_LAST
} sss_type_t;

/** Destintion connection type */
typedef enum
{
    /* Plain => Lowest level of security requested.
     *       => Probably a system with no mechanism to *identify* who
     *          has opened the session from host
     *       => Probably a system with Easy for man in the middle attack.
     *
     */
    kSSS_ConnectionType_Plain,
    /* Password:
     *       => Some level of user authentication/identification requested
     *       => Probably a system with "static" authentication/identification.
     *       => Probably same Password us always.
     *       => "Password" mostly gets sent in plain over the communication layer
     *       => Probably a system with replay attack possible
     */
    kSSS_ConnectionType_Password,
    /* Encrypted:
     *    Communication is guaranteed to be Encrypted.
     *    For SE => This would mean highest level of authentication
     *    For other system => channel would be encrypted
     *
     *    In general, almost a level of security that is definitely higher than
     *    Plain/Password/PIN.
     *
     *    Using *Dynamic* Sessions Keys for authenticated communication.
     */
    kSSS_ConnectionType_Encrypted
} sss_connection_type_t;

#ifndef __DOXYGEN__

#define SSS_ALGORITHM_START_AES (0x00)
#define SSS_ALGORITHM_START_CHACHA (0x01)
#define SSS_ALGORITHM_START_DES (0x02)
#define SSS_ALGORITHM_START_SHA (0x03)
#define SSS_ALGORITHM_START_MAC (0x04)
#define SSS_ALGORITHM_START_DH (0x05)
#define SSS_ALGORITHM_START_DSA (0x06)
#define SSS_ALGORITHM_START_RSASSA_PKCS1_V1_5 (0x07)
#define SSS_ALGORITHM_START_RSASSA_PKCS1_PSS_MGF1 (0x08)
#define SSS_ALGORITHM_START_RSAES_PKCS1_OAEP (0x09)
#define SSS_ALGORITHM_START_RSAES_PKCS1_V1_5 (0x0A)
#define SSS_ALGORITHM_START_RSASSA_NO_PADDING (0x0B)
#define SSS_ALGORITHM_START_ECDSA (0x0C)
#define SSS_ALGORITHM_START_ECDAA (0x0D)

/* Not available outside this file */
#define SSS_ENUM_ALGORITHM(GROUP, INDEX) (((SSS_ALGORITHM_START_##GROUP) << 8) | (INDEX))

#endif

/** Cryptographic algorithm to be applied */
typedef enum /* _sss_algorithm */
{
    kAlgorithm_None,
    /* AES */
    kAlgorithm_SSS_AES_ECB        = SSS_ENUM_ALGORITHM(AES, 0x01),
    kAlgorithm_SSS_AES_CBC        = SSS_ENUM_ALGORITHM(AES, 0x02),
    kAlgorithm_SSS_AES_CTR        = SSS_ENUM_ALGORITHM(AES, 0x03),
    kAlgorithm_SSS_AES_GCM        = SSS_ENUM_ALGORITHM(AES, 0x04),
    kAlgorithm_SSS_AES_CCM        = SSS_ENUM_ALGORITHM(AES, 0x05),
    kAlgorithm_SSS_AES_GCM_INT_IV = SSS_ENUM_ALGORITHM(AES, 0x06),
    /* CHACHA_POLY */
    kAlgorithm_SSS_CHACHA_POLY = SSS_ENUM_ALGORITHM(CHACHA, 0x01),
    /* DES */
    kAlgorithm_SSS_DES_ECB = SSS_ENUM_ALGORITHM(DES, 0x01),
    kAlgorithm_SSS_DES_CBC = SSS_ENUM_ALGORITHM(DES, 0x02),
    /* DES3 */
    kAlgorithm_SSS_DES3_ECB = SSS_ENUM_ALGORITHM(DES, 0x03),
    kAlgorithm_SSS_DES3_CBC = SSS_ENUM_ALGORITHM(DES, 0x04),
    /* digest */
    /* doc:start hash_algo */
    kAlgorithm_SSS_SHA1   = SSS_ENUM_ALGORITHM(SHA, 0x01),
    kAlgorithm_SSS_SHA224 = SSS_ENUM_ALGORITHM(SHA, 0x02),
    kAlgorithm_SSS_SHA256 = SSS_ENUM_ALGORITHM(SHA, 0x03),
    kAlgorithm_SSS_SHA384 = SSS_ENUM_ALGORITHM(SHA, 0x04),
    kAlgorithm_SSS_SHA512 = SSS_ENUM_ALGORITHM(SHA, 0x05),
    /* doc:end hash_algo */
    /* MAC */
    kAlgorithm_SSS_CMAC_AES    = SSS_ENUM_ALGORITHM(MAC, 0x01),
    kAlgorithm_SSS_HMAC_SHA1   = SSS_ENUM_ALGORITHM(MAC, 0x02),
    kAlgorithm_SSS_HMAC_SHA224 = SSS_ENUM_ALGORITHM(MAC, 0x03),
    kAlgorithm_SSS_HMAC_SHA256 = SSS_ENUM_ALGORITHM(MAC, 0x04),
    kAlgorithm_SSS_HMAC_SHA384 = SSS_ENUM_ALGORITHM(MAC, 0x05),
    kAlgorithm_SSS_HMAC_SHA512 = SSS_ENUM_ALGORITHM(MAC, 0x06),
    /* See above:
     * kAlgorithm_SSS_HMAC_SHA224 = SSS_ENUM_ALGORITHM(CHACHA, 0x01) */

    /* Diffie-Helmann */
    kAlgorithm_SSS_DH   = SSS_ENUM_ALGORITHM(DH, 0x01),
    kAlgorithm_SSS_ECDH = SSS_ENUM_ALGORITHM(DH, 0x02),
    /* DSA */
    kAlgorithm_SSS_DSA_SHA1   = SSS_ENUM_ALGORITHM(DSA, 0x01),
    kAlgorithm_SSS_DSA_SHA224 = SSS_ENUM_ALGORITHM(DSA, 0x02),
    kAlgorithm_SSS_DSA_SHA256 = SSS_ENUM_ALGORITHM(DSA, 0x03),

    /* RSA */
    /* doc:start rsa_sign_algo */
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_NO_HASH    = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x01),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA1       = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x02),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA224     = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x03),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA256     = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x04),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA384     = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x05),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA512     = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x06),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA1   = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x01),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA224 = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x02),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA256 = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x03),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA384 = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x04),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA512 = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x05),
    /* doc:end rsa_sign_algo */

    /* doc:start rsa_enc_algo */
    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA1   = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x01),
    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA224 = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x02),
    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA256 = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x03),
    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA384 = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x04),
    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA512 = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x05),
    kAlgorithm_SSS_RSAES_PKCS1_V1_5        = SSS_ENUM_ALGORITHM(RSAES_PKCS1_V1_5, 0x01),
    /* doc:end rsa_enc_algo */

    /* doc:start rsa_sign_algo_no_padding */
    kAlgorithm_SSS_RSASSA_NO_PADDING = SSS_ENUM_ALGORITHM(RSASSA_NO_PADDING, 0x01),
    /* doc:end rsa_sign_algo_no_padding */

    /* ECDSA */
    /* doc:start ecc_sign_algo */
    kAlgorithm_SSS_ECDSA_SHA1   = SSS_ENUM_ALGORITHM(ECDSA, 0x01),
    kAlgorithm_SSS_ECDSA_SHA224 = SSS_ENUM_ALGORITHM(ECDSA, 0x02),
    kAlgorithm_SSS_ECDSA_SHA256 = SSS_ENUM_ALGORITHM(ECDSA, 0x03),
    kAlgorithm_SSS_ECDSA_SHA384 = SSS_ENUM_ALGORITHM(ECDSA, 0x04),
    kAlgorithm_SSS_ECDSA_SHA512 = SSS_ENUM_ALGORITHM(ECDSA, 0x05),
    /* doc:end ecc_sign_algo */

    /* ECDAA */
    /* doc:start ecc_bn_sign_algo */
    kAlgorithm_SSS_ECDAA = SSS_ENUM_ALGORITHM(ECDAA, 0x01),
    /* doc:end ecc_bn_sign_algo */
} sss_algorithm_t;

#undef SSS_ENUM_ALGORITHM

#ifndef __DOXYGEN__

// Deprecated names for RSAES_PKCS1_OAEP algorithms
#define kAlgorithm_SSS_RSASSA_PKCS1_OEAP_SHA1 kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA1
#define kAlgorithm_SSS_RSASSA_PKCS1_OEAP_SHA224 kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA224
#define kAlgorithm_SSS_RSASSA_PKCS1_OEAP_SHA256 kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA256
#define kAlgorithm_SSS_RSASSA_PKCS1_OEAP_SHA384 kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA384
#define kAlgorithm_SSS_RSASSA_PKCS1_OEAP_SHA512 kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA512

// Deprecated names for RSAES_PKCS1_V1_5 algorithms
#define kAlgorithm_SSS_RSAES_PKCS1_V1_5_SHA1 kAlgorithm_SSS_RSAES_PKCS1_V1_5
#define kAlgorithm_SSS_RSAES_PKCS1_V1_5_SHA224 kAlgorithm_SSS_RSAES_PKCS1_V1_5
#define kAlgorithm_SSS_RSAES_PKCS1_V1_5_SHA256 kAlgorithm_SSS_RSAES_PKCS1_V1_5
#define kAlgorithm_SSS_RSAES_PKCS1_V1_5_SHA384 kAlgorithm_SSS_RSAES_PKCS1_V1_5
#define kAlgorithm_SSS_RSAES_PKCS1_V1_5_SHA512 kAlgorithm_SSS_RSAES_PKCS1_V1_5

#endif /* __DOXYGEN__ */

/** High level algorihtmic operations.
 *
 * Augmented by @ref sss_algorithm_t
 */
typedef enum
{
    kMode_SSS_Encrypt = 1, //!< Encrypt
    kMode_SSS_Decrypt = 2, //!< Decrypt
    kMode_SSS_Sign    = 3, //!< Sign
    kMode_SSS_Verify  = 4, //!< Verify
    /* Compute Shared Secret. e.g. Diffie-Hellman */
    kMode_SSS_ComputeSharedSecret = 5,
    kMode_SSS_Digest              = 6, //!< Message Digest
    kMode_SSS_Mac                 = 7, //!< Message Authentication Code

    // For now, use kMode_SSS_ComputeSharedSecret for HKDF Extract and Expand
    // kMode_SSS_HKDF = 8,   //!< HKDF Extract and Expand (RFC 5869)
    kMode_SSS_HKDF_ExpandOnly = 9 //!< HKDF Expand Only (RFC 5869)
} sss_mode_t;

/**
 * Permissions of an object
 */
typedef enum
{
    /** Can read (applicable) contents of the key.
     *
     *  @note This is not same as @ref kAccessPermission_SSS_Use.
     *
     *  Without reading, the object, the key can be used.
     */
    kAccessPermission_SSS_Read = (1u << 0),
    /** Can change the value of an object */
    kAccessPermission_SSS_Write = (1u << 1),
    /** Can use an object */
    kAccessPermission_SSS_Use = (1u << 2),
    /** Can delete an object */
    kAccessPermission_SSS_Delete = (1u << 3),
    /** Can change permissions applicable to an object */
    kAccessPermission_SSS_ChangeAttributes = (1u << 4),
} sss_access_permission_t;

/**
 * Persistent / Non persistent mode of a key
 */
typedef enum
{
    kKeyObject_Mode_None = 0, //!< kKeyObject_Mode_None
    /** Key object will be persisted in memory
     * and will retain it's value after a closed session
     */
    kKeyObject_Mode_Persistent = 1,
    /** Key Object will be stored in RAM.
     * It will lose it's contents after a session is closed
     */
    kKeyObject_Mode_Transient = 2,
} sss_key_object_mode_t;

/** Part of a key */
typedef enum
{
    kSSS_KeyPart_NONE,
    /** Applicable where we have UserID, PIN, Binary Files,
     * Certificates, Symmetric Keys, PCR */
    kSSS_KeyPart_Default = 1,
    /** Public part of asymmetric key */
    kSSS_KeyPart_Public = 2,
    /** Private only part of asymmetric key */
    kSSS_KeyPart_Private = 3,
    /** Both, public and private part of asymmetric key */
    kSSS_KeyPart_Pair = 4,
} sss_key_part_t;

/** For all cipher types, key bit length is provides at the time key is inserted/generated */
typedef enum
{
    kSSS_CipherType_NONE,
    kSSS_CipherType_AES = 10,
    kSSS_CipherType_DES = 12,

    kSSS_CipherType_CMAC = 20,
    kSSS_CipherType_HMAC = 21,

    kSSS_CipherType_MAC     = 30,
    kSSS_CipherType_RSA     = 31, /*! RSA RAW format      */
    kSSS_CipherType_RSA_CRT = 32, /*! RSA CRT format      */

    /* The following keys can be identified
     * solely by the *Family* and bit length
     */
    kSSS_CipherType_EC_NIST_P = 40, /*! Keys Part of NIST-P Family */
    kSSS_CipherType_EC_NIST_K = 41, /*! Keys Part of NIST-K Family */

    /* The following keys need their full curve parameters (p,a,b,x,y,n,h)
     */
    /** Montgomery Key,   */
    kSSS_CipherType_EC_MONTGOMERY = 50,
    /** twisted Edwards form elliptic curve public key */
    kSSS_CipherType_EC_TWISTED_ED = 51,
    /** Brainpool form elliptic curve public key */
    kSSS_CipherType_EC_BRAINPOOL = 52,
    /** Barreto Naehrig curve */
    kSSS_CipherType_EC_BARRETO_NAEHRIG = 53,

    kSSS_CipherType_UserID      = 70,
    kSSS_CipherType_Certificate = 71,
    kSSS_CipherType_Binary      = 72,
    kSSS_CipherType_Count       = 73,
    kSSS_CipherType_PCR         = 74,
    kSSS_CipherType_ReservedPin = 75,
} sss_cipher_type_t;

/** XY Co-ordinates for ECC Curves */
typedef struct
{
    /** X Point */
    uint8_t *X;
    /** Y Point */
    uint8_t *Y;
} sss_ecc_point_t;

/** ECC Curve Parameter */
typedef struct
{
    uint8_t *p;         /**< ECC parameter P */
    uint8_t *a;         /**< ECC parameter a */
    uint8_t *b;         /**< ECC parameter b */
    sss_ecc_point_t *G; /**< ECC parameter G */
    uint8_t *n;         /**< ECC parameter n */
    uint8_t *h;         /**< ECC parameter h */
} sss_eccgfp_group_t;

/**
 * @addtogroup sss_session
 * @{
 */

/** Properties of session that are U32
 *
 * From 0 to kSSS_SessionProp_Optional_Prop_Start,
 * around 2^24 = 16777215 Properties are
 * possible.
 *
 * From 0 to kSSS_SessionProp_Optional_Prop_Start,
 * around 2^24 = 16777215 Properties are
 * possible.
 *
 */
typedef enum
{
    /** Invalid */
    kSSS_SessionProp_u32_NA = 0,
    /** Major version */
    kSSS_SessionProp_VerMaj,
    /** Minor Version */
    kSSS_SessionProp_VerMin,
    /** Development Version */
    kSSS_SessionProp_VerDev,

    /* Lenght of UID */
    kSSS_SessionProp_UIDLen,

    /** Optional Properties Start */
    kSSS_SessionProp_u32_Optional_Start = 0x00FFFFFFu,

    /** How much persistent memory is free */
    kSSS_KeyStoreProp_FreeMem_Persistant,

    /** How much transient memory is free */
    kSSS_KeyStoreProp_FreeMem_Transient,

    /** Proprietary Properties Start */
    kSSS_SessionProp_u32_Proprietary_Start = 0x01FFFFFFu,

} sss_session_prop_u32_t;

/** Properties of session that are S32
 *
 * From 0 to kSSS_SessionProp_Optional_Prop_Start,
 * around 2^24 = 16777215 Properties are
 * possible.
 *
 * From 0 to kSSS_SessionProp_Optional_Prop_Start,
 * around 2^24 = 16777215 Properties are
 * possible.
 *
 */
typedef enum
{
    /** Invalid */
    kSSS_SessionProp_au8_NA = 0,
    /** Name of the product, string */
    kSSS_SessionProp_szName,
    /** Unique Identifier */
    kSSS_SessionProp_UID,

    /** Optional Properties Start */
    kSSS_SessionProp_au8_Optional_Start = 0x00FFFFFFu,

    /** Proprietary Properties Start */
    kSSS_SessionProp_au8_Proprietary_Start = 0x01FFFFFFu,

} sss_session_prop_au8_t;

/** @} */

/**
 * @addtogroup sss_session
 * @{
 */

/** @brief Root session
 *
 * This is a *singleton* for each connection (physical/logical)
 * to individual cryptographic system.
 */
typedef struct
{
    /** Indicates which security subsystem is selected.
     *
     *  This is set when @ref sss_session_open is successful */
    sss_type_t subsystem;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_SESSION_MAX_CONTEXT_SIZE];
    } extension;
} sss_session_t;
/** @} */

/**
 * @addtogroup sss_key_store
 * @{
 */

/** @brief Store for secure and non secure key objects within a cryptographic system.
 *
 * - A cryptographic system may have more than partitions to store such keys.
 *
 */
typedef struct
{
    /** Virtual connection between application (user context) and specific
     * security subsystem and function thereof. */
    sss_session_t *session;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_KEY_STORE_MAX_CONTEXT_SIZE];
    } extension;
} sss_key_store_t;

/** properties of a Key Store that return array */
typedef enum
{
    /** Optional Properties Start */
    kSSS_KeyStoreProp_au8_Optional_Start = 0x00FFFFFFu,

} sss_key_store_prop_au8_t;

/** Entity on the other side of the tunnel */
typedef enum
{
    /** Default value */
    kSSS_TunnelDest_None = 0,

    /** SE05X IoT Applet */
    kSSS_TunnelType_Se05x_Iot_applet,
} sss_tunnel_dest_t;

/** @} */

/**
 * @addtogroup sss_key_object
 * @{
 */

/** @brief An object (secure / non-secure) within a Key Store.
 *
 */
typedef struct
{
    /** key store holding the data and other properties */
    sss_key_store_t *keyStore;
    /** The type/part of object is referneced from @ref sss_key_part_t */
    uint32_t objectType;
    /** cipherType type from @ref sss_cipher_type_t */
    uint32_t cipherType;
    /** Application specific key identifier. The keyId is kept in the key  store
     * along with the key data and other properties. */
    uint32_t keyId;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_KEY_OBJECT_MAX_CONTEXT_SIZE];
    } extension;
} sss_object_t;

/** @} */

/**
 * @addtogroup sss_crypto_symmetric
 * @{
 */

/** @brief Typedef for the symmetric crypto context */
typedef struct
{
    /** Virtual connection between application (user context) and specific
     * security subsystem and function thereof. */
    sss_session_t *session;
    /** Key to be used for the symmetric operation */
    sss_object_t *keyObject;
    /** Algorithm to be applied, e.g AES_ECB / CBC */
    sss_algorithm_t algorithm;
    /** Mode of operation, e.g Encryption/Decryption */
    sss_mode_t mode;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_SYMMETRIC_MAX_CONTEXT_SIZE];
    } extension;
} sss_symmetric_t;
/** @} */

/** @brief Authenticated Encryption with Additional Data
 *
 */
typedef struct
{
    /** Virtual connection between application (user context) and specific
     * security subsystem and function thereof. */
    sss_session_t *session;
    /** Key to be used for asymmetric */
    sss_object_t *keyObject;
    /** TODO : Algorithm to be applied */
    sss_algorithm_t algorithm;
    /** TODO : High level operation */
    sss_mode_t mode;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_AEAD_MAX_CONTEXT_SIZE];
    } extension;
} sss_aead_t;

/** Message Digest operations */
typedef struct
{
    /** Virtual connection between application (user context) and specific
     * security subsystem and function thereof. */
    sss_session_t *session;
    /** Algorithm to be applied, e.g SHA1, SHA256 */
    sss_algorithm_t algorithm;
    /** Mode of operation, e.g Sign/Verify */
    sss_mode_t mode;
    /** Full digest length per algorithm definition. This field is initialized along with algorithm. */
    size_t digestFullLen;
    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_DIGEST_MAX_CONTEXT_SIZE];
    } extension;
} sss_digest_t;

/** @brief Message Authentication Code
 *
 */
typedef struct
{
    /** Virtual connection between application (user context) and specific
     * security subsystem and function thereof. */
    sss_session_t *session;
    /** Key to be used for ... */
    sss_object_t *keyObject;
    /** Algorithm to be applied, e.g. MAC/CMAC */
    sss_algorithm_t algorithm;
    /** Mode of operation for MAC e.g. ...
     * @todo : May be we don ot this mode here. */
    sss_mode_t mode;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_MAC_MAX_CONTEXT_SIZE];
    } extension;
} sss_mac_t;

/** @brief Asymmetric Cryptographic operations
 *
 * e.g. RSA/ECC.
 */

typedef struct
{
    /** Pointer to root session */
    sss_session_t *session;
    /** KeyObject used for Asymmetric operation */
    sss_object_t *keyObject;
    /** Algorithm to be applied, e.g. ECDSA */
    sss_algorithm_t algorithm;
    /** Mode of operation for the Asymmetric operation.
     *  e.g. Sign/Verify/Encrypt/Decrypt */
    sss_mode_t mode;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_ASYMMETRIC_MAX_CONTEXT_SIZE];
    } extension;
} sss_asymmetric_t;

/** Header for a IS716 APDU */

typedef struct
{
    /** ISO 7816 APDU Header */
    uint8_t hdr[0   /* For Indentation */
                + 1 /* CLA */
                + 1 /* INS */
                + 1 /* P1 */
                + 1 /* P2 */
    ];
} tlvHeader_t;

/** Tunneling
 *
 * Used for communication via another system.
 */
typedef struct
{
    /** Pointer to the session */
    sss_session_t *session;
    /** TODO: More documentation */
    uint32_t tunnelType;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_TUNNEL_MAX_CONTEXT_SIZE];
    } extension;
} sss_tunnel_t;

/**
 * @addtogroup sss_crypto_derive_key
 * @{
 */

/** Key derivation */
typedef struct
{
    /** Pointer to the session */
    sss_session_t *session;
    /** KeyObject used to derive key s*/
    sss_object_t *keyObject;
    /** Algorithm to be applied, e.g. ... */
    sss_algorithm_t algorithm;
    /** Mode of operation for .... e.g. ... */
    sss_mode_t mode;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_DERIVE_KEY_MAX_CONTEXT_SIZE];
    } extension;
} sss_derive_key_t;
/** @} */

/** Random number generator context */
typedef struct
{
    /** Pointer to the session */
    sss_session_t *session;

    /** Reserved memory for implementation specific extension */
    struct
    {
        uint8_t data[SSS_RNG_MAX_CONTEXT_SIZE];
    } context;

} sss_rng_context_t;

/*******************************************************************************
 * API
 ******************************************************************************/
#if defined(__cplusplus)
extern "C" {
#endif

/**
 * @addtogroup sss_session
 * @{
 */

/**
 * Same as @ref sss_session_open but to support sub systems
 * that explictily need a create before opening.
 *
 * For the sake of portabilty across various sub systems,
 * the applicaiton has to call @ref sss_session_create
 * before calling @ref sss_session_open.
 *
 *
 * @param[in,out] session Pointer to session context
 * @param[in] subsystem See @ref sss_session_open
 * @param[in] application_id See @ref sss_session_open
 * @param[in] connection_type See @ref sss_session_open
 * @param[in] connectionData See @ref sss_session_open
 */
sss_status_t sss_session_create(sss_session_t *session,
    sss_type_t subsystem,
    uint32_t application_id,
    sss_connection_type_t connection_type,
    void *connectionData);

/**
 * @brief         Open session between application and a security subsystem.
 *
 *                Open virtual session between application (user context) and a
 *                security subsystem and function thereof. Pointer to session
 *                shall be supplied to all SSS APIs as argument. Low level SSS
 *                functions can provide implementation specific behaviour based
 *                on the session argument.
 *
 * @param[in,out] session          Session context.
 * @param[in]     subsystem        Indicates which security subsystem is
 *                                 selected to be used.
 * @param[in]     application_id   ObjectId/AuthenticationID Connecting to:
 *          - ``application_id`` == 0 => Super use / Plaform user
 *          - Anything else => Authenticated user
 * @param[in]     connection_type  How are we connecting to the system.
 * @param[in,out] connectionData   subsystem specific connection parameters.
 *
 * @return        status
 */
sss_status_t sss_session_open(sss_session_t *session,
    sss_type_t subsystem,
    uint32_t application_id,
    sss_connection_type_t connection_type,
    void *connectionData);

/**
 * @brief Get an underlying property of the crypto sub system
 *
 * This API is used to get values that are
 * numeric in nature.
 *
 * Property can be either fixed value that is
 * calculated at compile time and returned
 * directly, or it may involve some access to the
 * underlying system.
 *
 * For applicable properties see @ref sss_session_prop_u32_t
 *
 * @param[in] session Session context
 * @param[in] property Value that is part of @ref sss_session_prop_u32_t
 * @param[out] pValue
 *
 * @return
 */
sss_status_t sss_session_prop_get_u32(sss_session_t *session, uint32_t property, uint32_t *pValue);

/**
 * @brief Get an underlying property of the crypto sub system
 *
 * This API is used to get values that are
 * numeric in nature.
 *
 * Property can be either fixed value that is
 * calculated at compile time and returned
 * directly, or it may involve some access to the
 * underlying system.
 *
 * @param[in] session Session context
 * @param[in] property Value that is part of @ref sss_session_prop_au8_t
 * @param[out] pValue Output buffer array
 * @param[in,out] pValueLen Count of values thare are/must br read
 * @return
 */
sss_status_t sss_session_prop_get_au8(sss_session_t *session, uint32_t property, uint8_t *pValue, size_t *pValueLen);

/**
 * @brief Close session between application and security subsystem.
 *
 * This function closes a session which has been opened with a security subsystem.
 * All commands within the session must have completed before this function can be called.
 * The implementation must do nothing if the input ``session`` parameter is NULL.
 *
 *
 * @param   session Session context.
 */
void sss_session_close(sss_session_t *session);

/** Counterpart to @ref sss_session_create
 *
 * Similar to contraint on @ref sss_session_create, application
 * may call @ref sss_session_delete to explicitly release all
 * underlying/used session specific resoures of that implementation.
 */
void sss_session_delete(sss_session_t *session);

/**
 *@}
 */ /* end of sss_session */

/**
 * @addtogroup sss_key_store
 * @{
 */

/** @brief Constructor for the key store context data structure.
 *
 * @param[out] keyStore Pointer to key store context. Key store context is updated on function return.
 * @param session Session context.
 */
sss_status_t sss_key_store_context_init(sss_key_store_t *keyStore, sss_session_t *session);

/** @brief Get handle to key store.
 *  If the key store already exists, nothing is allocated.
 *  If the key store does not exists, new empty key store is created and initialized.
 *  Key store context structure is updated with actual information.
 *
 * @param[out] keyStore Pointer to key store context. Key store context is updated on function return.
 * @param keyStoreId Implementation specific ID, can be used in case security subsystem manages multiple different
 * key stores.
 */
sss_status_t sss_key_store_allocate(sss_key_store_t *keyStore, uint32_t keyStoreId);

/** @brief Save all cached persistent objects to persistent memory.
 */
sss_status_t sss_key_store_save(sss_key_store_t *keyStore);

/** @brief Load from persistent memory to cached objects.
 */
sss_status_t sss_key_store_load(sss_key_store_t *keyStore);

/** @brief This function moves data[] from memory to the destination key store.
 *
 * @param keyStore Key store context
 * @param keyObject Reference to a key and it's properties
 * @param data Data to be stored in Key. When setting ecc private key only, do not include key header.
 * @param dataLen Length of the data
 * @param keyBitLen Crypto algorithm key bit length
 * @param options Pointer to implementation specific options
 * @param optionsLen Length of the options in bytes
 *
 * @return
 */
sss_status_t sss_key_store_set_key(sss_key_store_t *keyStore,
    sss_object_t *keyObject,
    const uint8_t *data,
    size_t dataLen,
    size_t keyBitLen,
    void *options,
    size_t optionsLen);

/** @brief This function generates key[] in the destination key store. */
sss_status_t sss_key_store_generate_key(
    sss_key_store_t *keyStore, sss_object_t *keyObject, size_t keyBitLen, void *options);

/** @brief This function exports plain key[] from key store (if constraints and user id allows reading) */
sss_status_t sss_key_store_get_key(
    sss_key_store_t *keyStore, sss_object_t *keyObject, uint8_t *data, size_t *dataLen, size_t *pKeyBitLen);

/**
 * @brief      Access key store using one more level of encryption
 *
 * e.g. Access keys / encryption key during storage
 *
 * @param      keyStore   The key store
 * @param      keyObject  The key object that is to be used as a KEK (Key Encryption Key)
 *
 * @return     The sss status.
 */
sss_status_t sss_key_store_open_key(sss_key_store_t *keyStore, sss_object_t *keyObject);

/**
 * @brief      The referenced key cannot be updated any more.
 *
 * @param      keyStore   The key store
 * @param      keyObject  The key object to be locked / frozen.
 *
 * @return     The sss status.
 */
sss_status_t sss_key_store_freeze_key(sss_key_store_t *keyStore, sss_object_t *keyObject);

/**
 * @brief      Delete / destroy allocated keyObect .
 *
 * @param      keyStore   The key store
 * @param      keyObject  The key object to be deleted
 *
 * @return     The sss status.
 */
sss_status_t sss_key_store_erase_key(sss_key_store_t *keyStore, sss_object_t *keyObject);

// sss_status_t sss_key_store_clear_all(sss_key_store_t *keyStore);

/** @brief Destructor for the key store context. */
void sss_key_store_context_free(sss_key_store_t *keyStore);

/**
 *@}
 */ /* end of sss_key_store */

/**
 * @addtogroup sss_key_object
 * @{
 */

/** @brief Constructor for a key object data structure
 *  The function initializes keyObject data structure and associates it with a key store
 *  in which the plain key and other attributes are stored.
 *
 * @param keyObject
 * @param keyStore
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_key_object_init(sss_object_t *keyObject, sss_key_store_t *keyStore);

/**
 * @brief         Allocate / pre-provision memory for new key
 *
 *                This API allows underlying cryptographic subsystems to perform
 *                preconditions of before creating any cryptographic key object.
 *
 * @param[in,out] keyObject      The object If required, update implementation
 *                               defined values inside the keyObject
 * @param         keyId          External Key ID.  Later on this may be used by
 *                               @ref sss_key_object_get_handle
 * @param         keyPart        See @ref sss_key_part_t
 * @param         cipherType     See @ref sss_cipher_type_t
 * @param         keyByteLenMax  Maximum storage this type of key may need. For
 *                               systems that have their own internal allocation
 *                               table this would help
 * @param         options        0 = Persistant Key (Default) or Transient Key.
 *                               See sss_key_object_mode_t
 *
 * @return        Status of object allocation.
 */
sss_status_t sss_key_object_allocate_handle(sss_object_t *keyObject,
    uint32_t keyId,
    sss_key_part_t keyPart,
    sss_cipher_type_t cipherType,
    size_t keyByteLenMax,
    uint32_t options); /* Check if this can be made sss_key_object_mode_t */

/**
 * @brief      Get handle to an existing allocated/provisioned/created Object
 *
 *             See @ref sss_key_object_allocate_handle.
 *
 *             After calling this API, Ideally keyObject should become equivlant
 *             to as set after the calling of @ref
 *             sss_key_object_allocate_handle api.
 *
 * @param      keyObject  The key object
 * @param[in]  keyId      The key identifier
 *
 * @return     The sss status.
 */
sss_status_t sss_key_object_get_handle(sss_object_t *keyObject, uint32_t keyId);

/** @brief Assign user to a key object.
 *
 * @param keyObject the object where permission restrictions are applied
 *
 * @param user Assign User id for a key object. The user is kept in the key
 *        store along with the key data and other properties.
 * @param options Transient or persistent update. Allows for transient update
 * of persistent attributes.
 */
sss_status_t sss_key_object_set_user(sss_object_t *keyObject, uint32_t user, uint32_t options);

/** @brief Assign purpose to a key object.
 *
 *  @param keyObject the object where permission restrictions are applied
 *  @param purpose Usage of the key.
 *  @param options Transient or persistent update. Allows for transient update of persistent attributes.
 */
sss_status_t sss_key_object_set_purpose(sss_object_t *keyObject, sss_mode_t purpose, uint32_t options);

/** @brief Assign access permissions to a key object.
 *
 *  @param keyObject the object where permission restrictions are applied
 *  @param access Logical OR of read, write, delete, use, change attributes defined by enum _sss_access_permission.
 *  @param options Transient or persistent update. Allows for transient update of persistent attributes.
 */
sss_status_t sss_key_object_set_access(sss_object_t *keyObject, uint32_t access, uint32_t options);

/** @brief Set elliptic curve domain parameters over Fp for a key object
 *
 *  When the key object is a reference to one of ECC Private, ECC Public or ECC Pair key types,
 *  this function shall be used to specify the exact domain parameters prior to using the key object
 *  for ECDSA or ECDH algorithms.
 *
 *  @param keyObject The destination key object
 *  @param group Pointer to elliptic curve domain parameters over Fp (sextuple p,a,b,G,n,h)
 */
sss_status_t sss_key_object_set_eccgfp_group(sss_object_t *keyObject, sss_eccgfp_group_t *group);

/** @brief get attributes */
sss_status_t sss_key_object_get_user(sss_object_t *keyObject, uint32_t *user);

/** Check what is purpose restrictions on an object
 *
 * @param keyObject Object to be checked
 * @param purpose Know what is permitted.
 * @return
 */
sss_status_t sss_key_object_get_purpose(sss_object_t *keyObject, sss_mode_t *purpose);

/** Check what are access restrictions on an object
 *
 * @param keyObject Object
 * @param access What is permitted
 * @return
 */
sss_status_t sss_key_object_get_access(sss_object_t *keyObject, uint32_t *access);

/** @brief Destructor for the key object.
 *  The function frees key object context.
 *
 * @param keyObject Pointer to key object context.
 */
void sss_key_object_free(sss_object_t *keyObject);

/**
 *@}
 */ /* end of sss_key_object */

/**
 * @addtogroup sss_crypto_symmetric
 * @{
 */

/** @brief Symmetric context init.
 *  The function initializes symmetric context with initial values.
 *
 * @param context Pointer to symmetric crypto context.
 * @param session Associate SSS session with symmetric context.
 * @param keyObject Associate SSS key object with symmetric context.
 * @param algorithm One of the symmetric algorithms defined by @ref sss_algorithm_t.
 * @param mode One of the modes defined by @ref sss_mode_t.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_symmetric_context_init(sss_symmetric_t *context,
    sss_session_t *session,
    sss_object_t *keyObject,
    sss_algorithm_t algorithm,
    sss_mode_t mode);

/** @brief Symmetric cipher in one blocking function call.
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to symmetric crypto context.
 * @param iv Buffer containing the symmetric operation Initialization Vector.
 * @param ivLen Length of the Initialization Vector in bytes.
 * @param srcData Buffer containing the input data.
 * @param destData Buffer containing the output data.
 * @param dataLen Size of input and output data buffer in bytes.
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_cipher_one_go(
    sss_symmetric_t *context, uint8_t *iv, size_t ivLen, const uint8_t *srcData, uint8_t *destData, size_t dataLen);

/** @brief Symmetric cipher init.
 *  The function starts the symmetric cipher operation.
 *
 * @param context Pointer to symmetric crypto context.
 * @param iv Buffer containing the symmetric operation Initialization Vector.
 * @param ivLen Length of the Initialization Vector in bytes.
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_cipher_init(sss_symmetric_t *context, uint8_t *iv, size_t ivLen);

/** @brief Symmetric cipher update.
 * Input data does not have to be a multiple of block size. Subsequent calls to this function are possible.
 * Unless one or more calls of this function have supplied sufficient input data, no output is generated.
 * The cipher operation is finalized with a call to @ref sss_cipher_finish().
 *
 * @param context Pointer to symmetric crypto context.
 * @param srcData Buffer containing the input data.
 * @param srcLen Length of the input data in bytes.
 * @param destData Buffer containing the output data.
 * @param[in,out] destLen Length of the output data in bytes. Buffer length on entry, reflects actual output size on
 * return.
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_cipher_update(
    sss_symmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen);

/** @brief Symmetric cipher finalize.
 *
 * @param context Pointer to symmetric crypto context.
 * @param srcData Buffer containing final chunk of input data.
 * @param srcLen Length of final chunk of input data in bytes.
 * @param destData Buffer containing output data.
 * @param[in,out] destLen Length of output data in bytes. Buffer length on entry, reflects actual output size on
 * return.
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_cipher_finish(
    sss_symmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen);

/** @brief Symmetric AES in Counter mode in one blocking function call.
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to symmetric crypto context.
 * @param srcData Buffer containing the input data.
 * @param destData Buffer containing the output data.
 * @param size Size of source and destination data buffers in bytes.
 * @param[in,out] initialCounter Input counter (updates on return)
 * @param[out] lastEncryptedCounter Output cipher of last counter, for chained CTR calls. NULL can be passed if
 * chained calls are not used.
 * @param[out] szLeft Output number of bytes in left unused in lastEncryptedCounter block. NULL can be passed if
 * chained calls are not used.
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_cipher_crypt_ctr(sss_symmetric_t *context,
    const uint8_t *srcData,
    uint8_t *destData,
    size_t size,
    uint8_t *initialCounter,
    uint8_t *lastEncryptedCounter,
    size_t *szLeft);

/** @brief Symmetric context release.
 *  The function frees symmetric context.
 *
 * @param context Pointer to symmetric crypto context.
 */
void sss_symmetric_context_free(sss_symmetric_t *context);
/**
 *@}
 */ /* end of sss_crypto_symmetric */

/**
 * @addtogroup sss_crypto_aead
 * @{
 */

/** @brief AEAD context init.
 *  The function initializes aead context with initial values.
 *
 * @param context Pointer to aead crypto context.
 * @param session Associate SSS session with aead context.
 * @param keyObject Associate SSS key object with aead context.
 * @param algorithm One of the aead algorithms defined by @ref sss_algorithm_t.
 * @param mode One of the modes defined by @ref sss_mode_t.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_aead_context_init(
    sss_aead_t *context, sss_session_t *session, sss_object_t *keyObject, sss_algorithm_t algorithm, sss_mode_t mode);

/** @brief AEAD in one blocking function call.
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to aead crypto context.
 * @param srcData Buffer containing the input data.
 * @param destData Buffer containing the output data.
 * @param size Size of input and output data buffer in bytes.
 * @param nonce The operation nonce or IV.
 * @param nonceLen The length of nonce in bytes. For AES-GCM it must be >= 1. For AES-CCM it must be 7, 8, 9, 10,
 * 11, 12, or 13.
 * @param aad Input additional authentication data AAD
 * @param aadLen Input size in bytes of AAD
 * @param tag Encryption: Output buffer filled with computed tag
 *            Decryption: Input buffer filled with received tag
 * @param tagLen Length of the tag in bytes.
 *               For AES-GCM it must be 4,8,12,13,14,15 or 16.
 *               For AES-CCM it must be 4,6,8,10,12,14 or 16.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_aead_one_go(sss_aead_t *context,
    const uint8_t *srcData,
    uint8_t *destData,
    size_t size,
    uint8_t *nonce,
    size_t nonceLen,
    const uint8_t *aad,
    size_t aadLen,
    uint8_t *tag,
    size_t *tagLen);

/** @brief AEAD init.
 *  The function starts the aead operation.
 *
 * @param context Pointer to aead crypto context.
 * @param nonce The operation nonce or IV.
 * @param nonceLen The length of nonce in bytes. For AES-GCM it must be >= 1. For AES-CCM it must be 7, 8, 9, 10,
 * 11, 12, or 13.
 * @param tagLen Length of the computed or received tag in bytes.
 *               For AES-GCM it must be 4,8,12,13,14,15 or 16.
 *               For AES-CCM it must be 4,6,8,10,12,14 or 16.
 * @param aadLen Input size in bytes of AAD. Used only for AES-CCM. Ignored for AES-GCM.
 * @param payloadLen Length in bytes of the payload. Used only for AES-CCM. Ignored for AES-GCM.
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_aead_init(
    sss_aead_t *context, uint8_t *nonce, size_t nonceLen, size_t tagLen, size_t aadLen, size_t payloadLen);

/** @brief Feeds a new chunk of the AAD.
 *  Subsequent calls of this function are possible.
 *
 * @param context Pointer to aead crypto context
 * @param aadData Input buffer containing the chunk of AAD
 * @param aadDataLen Length of the AAD data in bytes.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_aead_update_aad(sss_aead_t *context, const uint8_t *aadData, size_t aadDataLen);

/** @brief AEAD data update.
 * Feeds a new chunk of the data payload.
 * Input data does not have to be a multiple of block size. Subsequent calls to this function are possible.
 * Unless one or more calls of this function have supplied sufficient input data, no output is generated.
 * The integration check is done by @ref sss_aead_finish(). Until then it is not sure if the decrypt data is
 * authentic.
 *
 * @param context Pointer to aead crypto context.
 * @param srcData Buffer containing the input data.
 * @param srcLen Length of the input data in bytes.
 * @param destData Buffer containing the output data.
 * @param[in,out] destLen Length of the output data in bytes. Buffer length on entry, reflects actual output size on
 * return.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_aead_update(
    sss_aead_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen);

/** @brief Finalize AEAD.
 * The functions processes data that has not been processed by previous calls to sss_aead_update() as well as
 * srcData. It finalizes the AEAD operations and computes the tag (encryption) or compares the computed tag with the
 * tag supplied in the parameter (decryption).
 *
 * @param context Pointer to aead crypto context.
 * @param srcData Buffer containing final chunk of input data.
 * @param srcLen Length of final chunk of input data in bytes.
 * @param destData Buffer containing output data.
 * @param[in,out] destLen Length of output data in bytes. Buffer length on entry, reflects actual output size on
 * return.
 * @param tag Encryption: Output buffer filled with computed tag
 *            Decryption: Input buffer filled with received tag
 * @param tagLen Length of the computed or received tag in bytes.
 *               For AES-GCM it must be 4,8,12,13,14,15 or 16.
 *               For AES-CCM it must be 4,6,8,10,12,14 or 16.
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_aead_finish(sss_aead_t *context,
    const uint8_t *srcData,
    size_t srcLen,
    uint8_t *destData,
    size_t *destLen,
    uint8_t *tag,
    size_t *tagLen);

/** @brief AEAD context release.
 *  The function frees aead context.
 *
 * @param context Pointer to aead context.
 */
void sss_aead_context_free(sss_aead_t *context);
/**
 *@}
 */ /* end of sss_crypto_aead */

/**
 * @addtogroup sss_crypto_digest
 * @{
 */

/** @brief Digest context init.
 *  The function initializes digest context with initial values.
 *
 * @param context Pointer to digest context.
 * @param session Associate SSS session with digest context.
 * @param algorithm One of the digest algorithms defined by @ref sss_algorithm_t.
 * @param mode One of the modes defined by @ref sss_mode_t.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_digest_context_init(
    sss_digest_t *context, sss_session_t *session, sss_algorithm_t algorithm, sss_mode_t mode);

/** @brief Message digest in one blocking function call.
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to digest context.
 * @param message Input message
 * @param messageLen Length of the input message in bytes
 * @param digest Output message digest
 * @param digestLen Message digest byte length
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_digest_one_go(
    sss_digest_t *context, const uint8_t *message, size_t messageLen, uint8_t *digest, size_t *digestLen);

/** @brief Init digest for a message.
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to digest context.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_digest_init(sss_digest_t *context);

/** @brief Update digest for a message.
 *
 * The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to digest context.
 * @param message Buffer with a message chunk.
 * @param messageLen Length of the input buffer in bytes.
 * @returns Status of the operation
 *
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_digest_update(sss_digest_t *context, const uint8_t *message, size_t messageLen);

/** @brief Finish digest for a message.
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to digest context.
 * @param digest Output message digest
 * @param digestLen Message digest byte length
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_digest_finish(sss_digest_t *context, uint8_t *digest, size_t *digestLen);

/** @brief Digest context release.
 *  The function frees digest context.
 *
 * @param context Pointer to digest context.
 */
void sss_digest_context_free(sss_digest_t *context);

/**
 *@}
 */ /* end of sss_crypto_digest */

/**
 * @addtogroup sss_crypto_mac
 * @{
 */

/** @brief MAC context init.
 *  The function initializes mac context with initial values.
 *
 * @param context Pointer to mac context.
 * @param session Associate SSS session with mac context.
 * @param keyObject Associate SSS key object with mac context.
 * @param algorithm One of the mac algorithms defined by @ref sss_algorithm_t.
 * @param mode One of the modes defined by @ref sss_mode_t.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_mac_context_init(
    sss_mac_t *context, sss_session_t *session, sss_object_t *keyObject, sss_algorithm_t algorithm, sss_mode_t mode);

/** @brief Message MAC in one blocking function call.
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to mac context.
 * @param message Input message
 * @param messageLen Length of the input message in bytes
 * @param mac Output message MAC
 * @param macLen Computed MAC byte length
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_mac_one_go(
    sss_mac_t *context, const uint8_t *message, size_t messageLen, uint8_t *mac, size_t *macLen);

/** @brief Init mac for a message.
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to mac context.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_mac_init(sss_mac_t *context);

/** @brief Update mac for a message.
 *
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to mac context.
 * @param message Buffer with a message chunk.
 * @param messageLen Length of the input buffer in bytes.
 * @returns Status of the operation
 *
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_mac_update(sss_mac_t *context, const uint8_t *message, size_t messageLen);

/** @brief Finish mac for a message.
 *  The function blocks current thread until the operation completes or an error occurs.
 *
 * @param context Pointer to mac context.
 * @param mac Output message MAC
 * @param macLen Computed MAC byte length
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 */
sss_status_t sss_mac_finish(sss_mac_t *context, uint8_t *mac, size_t *macLen);

/** @brief MAC context release.
 *  The function frees mac context.
 *
 * @param context Pointer to mac context.
 */
void sss_mac_context_free(sss_mac_t *context);
/**
 *@}
 */ /* end of sss_crypto_mac */

/**
 * @addtogroup sss_crypto_asymmetric
 * @{
 */

/** @brief Asymmetric context init.
 *  The function initializes asymmetric context with initial values.
 *
 * @param context Pointer to asymmetric crypto context.
 * @param session Associate SSS session with asymmetric context.
 * @param keyObject Associate SSS key object with asymmetric context.
 * @param algorithm One of the asymmetric algorithms defined by @ref sss_algorithm_t.
 * @param mode One of the modes defined by @ref sss_mode_t.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_asymmetric_context_init(sss_asymmetric_t *context,
    sss_session_t *session,
    sss_object_t *keyObject,
    sss_algorithm_t algorithm,
    sss_mode_t mode);

/** @brief Asymmetric encryption
 *  The function uses asymmetric algorithm to encrypt data. Public key portion of a key pair is used for encryption.
 *
 * @param context Pointer to asymmetric context.
 * @param srcData Input buffer
 * @param srcLen Length of the input in bytes
 * @param destData Output buffer
 * @param destLen Length of the output in bytes
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_asymmetric_encrypt(
    sss_asymmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen);

/** @brief Asymmetric decryption
 *  The function uses asymmetric algorithm to decrypt data. Private key portion of a key pair is used for
 * decryption.
 *
 * @param context Pointer to asymmetric context.
 * @param srcData Input buffer
 * @param srcLen Length of the input in bytes
 * @param destData Output buffer
 * @param destLen Length of the output in bytes
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_asymmetric_decrypt(
    sss_asymmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen);

/** @brief Asymmetric signature of a message digest
 *  The function signs a message digest.
 *
 * @param context Pointer to asymmetric context.
 * @param digest Input buffer containing the input message digest
 * @param digestLen Length of the digest in bytes
 * @param signature Output buffer written with the signature of the digest
 * @param signatureLen Length of the signature in bytes
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_asymmetric_sign_digest(
    sss_asymmetric_t *context, uint8_t *digest, size_t digestLen, uint8_t *signature, size_t *signatureLen);

/** @brief Asymmetric verify of a message digest
 *  The function verifies a message digest.
 *
 * @param context Pointer to asymmetric context.
 * @param digest Input buffer containing the input message digest
 * @param digestLen Length of the digest in bytes
 * @param signature Input buffer containing the signature to verify
 * @param signatureLen Length of the signature in bytes
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_asymmetric_verify_digest(
    sss_asymmetric_t *context, uint8_t *digest, size_t digestLen, uint8_t *signature, size_t signatureLen);

/** @brief Asymmetric context release.
 *  The function frees asymmetric context.
 *
 * @param context Pointer to asymmetric context.
 */
void sss_asymmetric_context_free(sss_asymmetric_t *context);
/**
 *@}
 */ /* end of sss_crypto_asymmetric */

/**
 * @addtogroup sss_crypto_derive_key
 * @{
 */

/** @brief Derive key context init.
 *  The function initializes derive key context with initial values.
 *
 * @param context Pointer to derive key context.
 * @param session Associate SSS session with the derive key context.
 * @param keyObject Associate SSS key object with the derive key context.
 * @param algorithm One of the derive key algorithms defined by @ref sss_algorithm_t.
 * @param mode One of the modes defined by @ref sss_mode_t.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_derive_key_context_init(sss_derive_key_t *context,
    sss_session_t *session,
    sss_object_t *keyObject,
    sss_algorithm_t algorithm,
    sss_mode_t mode);

/** @brief Symmetric key derivation
 *  The function cryptographically derives a key from another key.
 *  For example MIFARE key derivation, PRF, HKDF-Extract.
 *
 * @deprecated Please use ::sss_derive_key_one_go instead
 *
 * @param context Pointer to derive key context.
 * @param saltData Input data buffer, typically with some random data.
 * @param saltLen Length of saltData buffer in bytes.
 * @param info Input data buffer, typically with some fixed info.
 * @param infoLen Length of info buffer in bytes.
 * @param[in,out] derivedKeyObject Reference to a derived key
 * @param deriveDataLen <b>TODO</b> Document this
 * @param hkdfOutput <b>TODO</b> Document this
 * @param hkdfOutputLen <b>TODO</b> Document this
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_derive_key_go(sss_derive_key_t *context,
    const uint8_t *saltData,
    size_t saltLen,
    const uint8_t *info,
    size_t infoLen,
    sss_object_t *derivedKeyObject,
    uint16_t deriveDataLen,
    uint8_t *hkdfOutput,
    size_t *hkdfOutputLen);

/** @brief Symmetric key derivation (replaces the deprecated function ::sss_derive_key_go)
 *  The function cryptographically derives a key from another key.
 *  For example MIFARE key derivation, PRF, HKDF-Extract-Expand, HKDF-Expand.
 *  Refer to ::sss_derive_key_sobj_one_go in case the Salt is available as a key object.
 *
 * @param context Pointer to derive key context.
 * @param saltData Input data buffer, typically with some random data.
 * @param saltLen Length of saltData buffer in bytes.
 * @param info Input data buffer, typically with some fixed info.
 * @param infoLen Length of info buffer in bytes.
 * @param[in,out] derivedKeyObject Reference to a derived key
 * @param[in] deriveDataLen Expected length of derived key.
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_derive_key_one_go(sss_derive_key_t *context,
    const uint8_t *saltData,
    size_t saltLen,
    const uint8_t *info,
    size_t infoLen,
    sss_object_t *derivedKeyObject,
    uint16_t deriveDataLen);

/**
 * @brief      Symmetric key derivation (salt in key object)
 * Refer to ::sss_derive_key_one_go in case the salt is not available as a key object.
 *
 * @param      context           Pointer to derive key context
 * @param      saltKeyObject     Reference to salt. The salt key object must reside in the same keystore as the derive key context.
 * @param[in]  info              Input data buffer, typically with some fixed info.
 * @param[in]  infoLen           Length of info buffer in bytes.
 * @param      derivedKeyObject  Reference to a derived key
 * @param[in]  deriveDataLen     The derive data length
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_derive_key_sobj_one_go(sss_derive_key_t *context,
    sss_object_t *saltKeyObject,
    const uint8_t *info,
    size_t infoLen,
    sss_object_t *derivedKeyObject,
    uint16_t deriveDataLen);

/** @brief Asymmetric key derivation Diffie-Helmann
 *  The function cryptographically derives a key from another key.
 *  For example Diffie-Helmann.
 *
 * @param context Pointer to derive key context.
 * @param otherPartyKeyObject Public key of the other party in the Diffie-Helmann algorithm
 * @param[in,out] derivedKeyObject Reference to a derived key
 *
 * @returns Status of the operation
 * @retval #kStatus_SSS_Success The operation has completed successfully.
 * @retval #kStatus_SSS_Fail The operation has failed.
 * @retval #kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
 */
sss_status_t sss_derive_key_dh(
    sss_derive_key_t *context, sss_object_t *otherPartyKeyObject, sss_object_t *derivedKeyObject);

/** @brief Derive key context release.
 *  The function frees derive key context.
 *
 * @param context Pointer to derive key context.
 */
void sss_derive_key_context_free(sss_derive_key_t *context);
/**
 *@}
 */ /* end of sss_crypto_derive_key */

/**
 * @addtogroup sss_rng
 * @{
 */

/**
 * @brief Initialise random generator context between application and a security subsystem.
 *
 *
 * @warning API Changed
 *
 *      Earlier:
 *          sss_status_t sss_rng_context_init(
 *              sss_session_t *session, sss_rng_context_t *context);
 *
 *      Now: Parameters are swapped
 *       sss_status_t sss_rng_context_init(
 *           sss_rng_context_t *context, sss_session_t *session);
 *
 * @param   session Session context.
 * @param   context random generator context.
 * @return  status
 */
sss_status_t sss_rng_context_init(sss_rng_context_t *context, sss_session_t *session);

/**
 * @brief Generate random number.
 *
 * @param   context random generator context.
 * @param   random_data buffer to hold random data.
 * @param   dataLen required random number length
 * @return  status
 */
sss_status_t sss_rng_get_random(sss_rng_context_t *context, uint8_t *random_data, size_t dataLen);

/**
 * @brief free random genertor context.
 *
 * @param   context generator context.
 * @return  status
 */
sss_status_t sss_rng_context_free(sss_rng_context_t *context);

/**
 *@}
 */ /* end of sss_rng */

/**
 * @addtogroup sss_crypto_tunnel
 * @{
 */

/** @brief Constructor for the tunnelling service context.
 *
 *      Earlier:
 *          sss_status_t sss_tunnel_context_init(
 *              sss_session_t *session, sss_tunnel_t *context);
 *
 *      Now: Parameters are swapped
 *          sss_status_t sss_tunnel_context_init(
 *              sss_tunnel_t *context, sss_session_t *session);
 *
 * @param[out] context Pointer to tunnel context. Tunnel context is updated on function return.
 * @param session Pointer to session this tunnelling service belongs to.
 */
sss_status_t sss_tunnel_context_init(sss_tunnel_t *context, sss_session_t *session);

/** @brief Tunnelling service.
 *
 * @param[in,out] context Pointer to tunnel context.
 * @param data Pointer to data to be send to subsystem.
 * @param dataLen Length of the data in bytes.
 * @param keyObjects Objects references used by the service.
 * @param keyObjectCount Number of key references at ``keyObjects``.
 * @param tunnelType Implementation specific id of the service.
 */
sss_status_t sss_tunnel(sss_tunnel_t *context,
    uint8_t *data,
    size_t dataLen,
    sss_object_t *keyObjects,
    uint32_t keyObjectCount,
    uint32_t tunnelType);

/** @brief Destructor for the tunnelling service context.
 *
 * @param[out] context Pointer to tunnel context. */
void sss_tunnel_context_free(sss_tunnel_t *context);

/**
 *@}
 */ /* end of sss_crypto_channel */

/**
 * @addtogroup sss_str_log
 * @{
 */

/**
 * @brief      Returns string error code for @ref sss_status_t
 *
 * @param[in]  status  See @ref sss_status_t
 *
 * @return     String conversion of ``status`` to String.
 */

const char *sss_status_sz(sss_status_t status);

/**
* @brief      Returns string error code for @ref sss_cipher_type_t
*
* @param[in]  status  See @ref sss_cipher_type_t
*
* @return     String conversion of ``cipher_type`` to String.
*/

const char *sss_cipher_type_sz(sss_cipher_type_t cipher_type);

/**
 *@}
 */ /* end of sss_str_log */

#if defined(__cplusplus)
}
#endif

#endif /* _FSL_SSS_H_ */