ANSIX936KDF.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       ANSIX936KDF.h
 *
 *  @brief      ANSIX936KDF driver header
 *
 *  @anchor ti_drivers_ANSIX936KDF_Overview
 *  # Overview #
 *
 *  The ANSI X9.63 Key Derivation Function (KDF) driver utilizes the SHA-256 hash
 *  function to derive a key from a shared secret value and optional shared
 *  info. See ANSI X9.63-2011 or SEC-1 v2.0 standard for more information.
 *
 *  @anchor ti_drivers_ANSIX936KDF_Usage
 *  # Usage #
 *
 *  Before starting a ANSIX936KDF operation, the application must do the following:
 *      - Call #ANSIX936KDF_init() to initialize the driver.
 *      - Call #ANSIX936KDF_Params_init() to initialize the ANSIX936KDF_Params to default values.
 *      - Modify the #ANSIX936KDF_Params as desired.
 *      - Call #ANSIX936KDF_open() to open an instance of the driver.
 *
 *  @anchor ti_drivers_ANSIX936KDF_Synopsis
 *  # Synopsis
 *
 *  @anchor ti_drivers_ANSIX936KDF_Synopsis_Code
 *  @code
 *
 *  // Import ANSIX936KDF Driver definitions
 *  #include <ti/drivers/ANSIX936KDF.h>
 *
 *  // Import driver configuration
 *  #include "ti_drivers_config.h"
 *
 *  // Initialize driver
 *  ANSIX936KDF_init();
 *
 *  // Open driver instance
 *  handle = ANSIX936KDF_open(CONFIG_ANSIX936KDF_0, NULL);
 *
 *  // Perform key derivation
 *  result = ANSIX936KDF_deriveKey(handle, input, sizeof(input), sharedInfo,
 *                                 sizeof(sharedInfo), output, sizeof(output));
 *
 *  // Close driver instance
 *  ANSIX936KDF_close(handle);
 *  @endcode
 *
 *  @anchor ti_drivers_ANSIX936KDF_Example
 *  # Example #
 *
 *  The #ANSIX936KDF_deriveKey() function performs a key derivation operation in
 *  a single call.
 *
 *  After a ANSIX936KDF operation completes, the application may either start
 *  another operation or close the driver by calling #ANSIX936KDF_close().
 *
 *  @code
 *  ANSIX936KDF_Params params;
 *  ANSIX936KDF_Handle handle;
 *  int_fast16_t result;
 *  uint8_t sharedInfo[] = {0x75, 0xee, 0xf8, 0x1a, 0xa3, 0x04, 0x1e, 0x33,
 *                          0xb8, 0x09, 0x71, 0x20, 0x3d, 0x2c, 0x0c, 0x52};
 *  uint8_t input[] = {0x22, 0x51, 0x8b, 0x10, 0xe7, 0x0f, 0x2a, 0x3f, 0x24, 0x38, 0x10, 0xae,
 *                     0x32, 0x54, 0x13, 0x9e, 0xfb, 0xee, 0x04, 0xaa, 0x57, 0xc7, 0xaf, 0x7d};
 *  uint8_t output[32] = {0};
 *
 *  ANSIX936KDF_init();
 *
 *  ANSIX936KDF_Params_init(&params);
 *  params.returnBehavior = ANSIX936KDF_RETURN_BEHAVIOR_POLLING;
 *
 *  handle = ANSIX936KDF_open(CONFIG_ANSIX936KDF_0, &params);
 *  assert(handle != NULL);
 *
 *  result = ANSIX936KDF_deriveKey(handle, input, sizeof(input), sharedInfo,
 *                                 sizeof(sharedInfo), output, sizeof(output));
 *  assert(result == ANSIX936KDF_STATUS_SUCCESS);
 *
 *  ANSIX936KDF_close(handle);
 *  @endcode
 */

#ifndef ti_drivers_ANSIX936KDF__include
#define ti_drivers_ANSIX936KDF__include

#include <stddef.h>
#include <stdint.h>

#include <ti/drivers/SHA2.h>

#ifdef __cplusplus
extern "C" {
#endif

#define ANSIX936KDF_STATUS_RESERVED ((int_fast16_t)-32)

#define ANSIX936KDF_STATUS_SUCCESS ((int_fast16_t)0)

#define ANSIX936KDF_STATUS_ERROR ((int_fast16_t)-1)

#define ANSIX936KDF_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2)

typedef enum
{
    ANSIX936KDF_RETURN_BEHAVIOR_BLOCKING = SHA2_RETURN_BEHAVIOR_BLOCKING,

    ANSIX936KDF_RETURN_BEHAVIOR_POLLING = SHA2_RETURN_BEHAVIOR_POLLING,
} ANSIX936KDF_ReturnBehavior;

typedef struct
{
    void *object;

    void const *hwAttrs;
} ANSIX936KDF_Config;

typedef ANSIX936KDF_Config *ANSIX936KDF_Handle;

typedef struct
{
    ANSIX936KDF_ReturnBehavior returnBehavior; 
    uint32_t timeout;                          
} ANSIX936KDF_Params;

extern const ANSIX936KDF_Config ANSIX936KDF_config[];

extern const uint_least8_t ANSIX936KDF_count;

extern const ANSIX936KDF_Params ANSIX936KDF_defaultParams;

void ANSIX936KDF_init(void);

void ANSIX936KDF_Params_init(ANSIX936KDF_Params *params);

ANSIX936KDF_Handle ANSIX936KDF_open(uint_least8_t index, const ANSIX936KDF_Params *params);

void ANSIX936KDF_close(ANSIX936KDF_Handle handle);

int_fast16_t ANSIX936KDF_deriveKey(ANSIX936KDF_Handle handle,
                                   const void *input,
                                   size_t inputLen,
                                   const void *sharedInfo,
                                   size_t sharedInfoLen,
                                   void *output,
                                   size_t outputLen);

ANSIX936KDF_Handle ANSIX936KDF_construct(ANSIX936KDF_Config *config, const ANSIX936KDF_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_ANSIX936KDF__include */