ECIES.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       ECIES.h
 *
 *  @brief      ECIES driver header
 *
 *  @anchor ti_drivers_ECIES_Overview
 *  # Overview #
 *
 *  The Elliptic Curve Integrated Encryption Scheme (ECIES) driver provides a
 *  public-key encryption scheme based on Elliptic Curve Cryptography. This
 *  driver supports the ECIES implementation defined in the SEC-1 v2.0 standard
 *  https://www.secg.org/sec1-v2.pdf except the cipher and MAC functions were
 *  changed to use AES-128-GCM:
 *
 *  | Function       | Implementation  |
 *  |----------------|-----------------|
 *  | Key Agreement  | ECDH NIST P-256 |
 *  | KDF            | ANSI X9.63      |
 *  | Hash           | SHA-256         |
 *  | Cipher         | AES-128-GCM     |
 *  | MAC            | AES-128-GCM     |
 *
 *  @anchor ti_drivers_ECIES_Usage
 *  # Usage #
 *
 *  Before starting a ECIES operation, the application must do the following:
 *      - Call #ECIES_init() to initialize the driver.
 *      - Call #ECIES_Params_init() to initialize the ECIES_Params to default values.
 *      - Modify the #ECIES_Params as desired.
 *      - Call #ECIES_open() to open an instance of the driver.
 *
 *  @anchor ti_drivers_ECIES_Synopsis
 *  # Synopsis
 *
 *  @anchor ti_drivers_ECIES_Synopsis_Code
 *  @code
 *
 *  // Import ECIES Driver definitions
 *  #include <ti/drivers/ECIES.h>
 *
 *  // Import driver configuration
 *  #include "ti_drivers_config.h"
 *
 *  // Initialize driver
 *  ECIES_init();
 *
 *  // Open driver instance
 *  handle = ECIES_open(CONFIG_ECIES_0, NULL);
 *
 *  // Perform ECIES encryption
 *  result = ECIES_encrypt(handle, &publicKey, input, sizeof(input), output, sizeof(output));
 *
 *  // Close driver instance
 *  ECIES_close(handle);
 *  @endcode
 *
 *  @anchor ti_drivers_ECIES_Example
 *  # Example #
 *
 *  The #ECIES_encrypt() function performs an ECIES encryption operation in
 *  a single call.
 *
 *  After an ECIES operation completes, the application may either start
 *  another operation or close the driver by calling #ECIES_close().
 *
 *  @code
 *  #define INPUT_SIZE 24
 *
 *  CryptoKey publicKey;
 *  ECIES_Params params;
 *  ECIES_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[INPUT_SIZE] = {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[ECIES_PADDING_BYTES + ECIES_PUBLIC_KEY_SIZE + INPUT_SIZE + ECIES_TAG_SIZE];
 *  uint8_t publicKeyMaterial[] = {0x04,
 *                                 // X coordinate
 *                                 0x33,0x91,0x50,0x84,0x4E,0xC1,0x52,0x34,
 *                                 0x80,0x7F,0xE8,0x62,0xA8,0x6B,0xE7,0x79,
 *                                 0x77,0xDB,0xFB,0x3A,0xE3,0xD9,0x6F,0x4C,
 *                                 0x22,0x79,0x55,0x13,0xAE,0xAA,0xB8,0x2F,
 *                                 // Y coordinate
 *                                 0xB1,0xC1,0x4D,0xDF,0xDC,0x8E,0xC1,0xB2,
 *                                 0x58,0x3F,0x51,0xE8,0x5A,0x5E,0xB3,0xA1,
 *                                 0x55,0x84,0x0F,0x20,0x34,0x73,0x0E,0x9B,
 *                                 0x5A,0xDA,0x38,0xB6,0x74,0x33,0x6A,0x21};
 *
 *  // RNG initialization should be handled by the application after the RNG
 *  // driver is seeded with the noise input from Radio Control Layer.
 *
 *  ECIES_init();
 *
 *  ECIES_Params_init(&params);
 *  params.returnBehavior = ECIES_RETURN_BEHAVIOR_POLLING;
 *
 *  handle = ECIES_open(CONFIG_ECIES_0, &params);
 *  assert(handle != NULL);
 *
 *  CryptoKeyPlaintext_initKey(&publicKey, publicKeyMaterial, sizeof(publicKeyMaterial));
 *
 *  result = ECIES_encrypt(handle, &publicKey, input, sizeof(input), output, sizeof(output));
 *  assert(result == ECIES_STATUS_SUCCESS);
 *
 *  ECIES_close(handle);
 *  @endcode
 */

#ifndef ti_drivers_ECIES__include
#define ti_drivers_ECIES__include

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

#include <ti/drivers/ANSIX936KDF.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>

#ifdef __cplusplus
extern "C" {
#endif

#define ECIES_STATUS_RESERVED ((int_fast16_t)-32)

#define ECIES_STATUS_SUCCESS ((int_fast16_t)0)

#define ECIES_STATUS_ERROR ((int_fast16_t)-1)

#define ECIES_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2)

#define ECIES_STATUS_INSUFFICIENT_OUTPUT_LENGTH ((int_fast16_t)-3)

#define ECIES_STATUS_MAC_INVALID ((int_fast16_t)-4)

#define ECIES_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED

typedef enum
{
    ECIES_RETURN_BEHAVIOR_BLOCKING = 2,

    ECIES_RETURN_BEHAVIOR_POLLING = 4,
} ECIES_ReturnBehavior;

#define ECIES_TAG_SIZE 16U

#ifndef ECCParams_NISTP256_LENGTH

    #define ECCParams_NISTP256_LENGTH 32U
#endif

#define ECIES_PUBLIC_KEY_SIZE (1U + (2U * ECCParams_NISTP256_LENGTH))

#define ECIES_PADDING_BYTES 3U

typedef struct
{
    void *object;

    void const *hwAttrs;
} ECIES_Config;

typedef ECIES_Config *ECIES_Handle;

typedef struct
{
    ECIES_ReturnBehavior returnBehavior; 
    uint32_t timeout;                    
} ECIES_Params;

extern const ECIES_Config ECIES_config[];

extern const uint_least8_t ECIES_count;

extern const ECIES_Params ECIES_defaultParams;

void ECIES_init(void);

void ECIES_Params_init(ECIES_Params *params);

ECIES_Handle ECIES_open(uint_least8_t index, const ECIES_Params *params);

void ECIES_close(ECIES_Handle handle);

int_fast16_t ECIES_encrypt(ECIES_Handle handle,
                           const CryptoKey *publicKey,
                           const void *input,
                           size_t inputLen,
                           void *paddedOutput,
                           size_t paddedOutputLen);

int_fast16_t ECIES_decrypt(ECIES_Handle handle,
                           const CryptoKey *privateKey,
                           const void *paddedInput,
                           size_t paddedInputLen,
                           void *output,
                           size_t outputLen);

ECIES_Handle ECIES_construct(ECIES_Config *config, const ECIES_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_ECIES__include */