182 lines
6.8 KiB
C
182 lines
6.8 KiB
C
/*
|
||
* Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved.
|
||
*
|
||
* SPDX-License-Identifier: BSD-3-Clause
|
||
*/
|
||
|
||
/*!
|
||
@addtogroup cc_ecies
|
||
@{
|
||
*/
|
||
|
||
/*!
|
||
@file mbedtls_cc_ecies.h
|
||
|
||
@brief This file contains the CryptoCell Elliptic Curve Integrated Encryption Scheme (ECIES) APIs.
|
||
*/
|
||
|
||
#ifndef _MBEDTLS_CC_ECIES_H
|
||
#define _MBEDTLS_CC_ECIES_H
|
||
|
||
|
||
#include "cc_ecpki_types.h"
|
||
#include "cc_pal_types_plat.h"
|
||
#include "cc_kdf.h"
|
||
#include "mbedtls_cc_hkdf.h"
|
||
#include "mbedtls/ecp.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C"
|
||
{
|
||
#endif
|
||
/*! The maximal length of the ECIES cipher in bytes. */
|
||
#define MBEDTLS_ECIES_MAX_CIPHER_LEN_BYTES ((2*CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS + 1) * sizeof(int))
|
||
/*! The minimal length of the ECIES buffer in bytes. */
|
||
#define MBEDTLS_ECIES_MIN_BUFF_LEN_BYTES (sizeof(CCEciesTempData_t))
|
||
|
||
/*!
|
||
@brief A macro for creating and encrypting a secret key.
|
||
|
||
For a description of the parameters see ::mbedtls_ecies_kem_encrypt_full.
|
||
*/
|
||
#define mbedtls_ecies_kem_encrypt(pGrp, pRecipPublKey, kdfDerivMode, kdfHashMode, \
|
||
isSingleHashMode, pSecrKey, secrKeySize, \
|
||
pCipherData, pCipherDataSize, pBuff, buffLen, \
|
||
f_rng, p_rng) \
|
||
mbedtls_ecies_kem_encrypt_full((pGrp), (pRecipPublKey), (kdfDerivMode), (kdfHashMode), \
|
||
(isSingleHashMode), NULL, NULL, (pSecrKey), (secrKeySize), \
|
||
(pCipherData), (pCipherDataSize), (pBuff), (buffLen), \
|
||
f_rng, p_rng)
|
||
|
||
/*!
|
||
@brief This function creates and encrypts (encapsulates) the secret key of
|
||
required size, according to <em>ISO/IEC 18033-2:2006: Information technology
|
||
-- Security techniques -- Encryption algorithms -- Part 2: Asymmetric
|
||
ciphers</em>, ECIES-KEM Encryption.
|
||
|
||
To call this function in applications, the ::mbedtls_ecies_kem_encrypt macro
|
||
definition must be used. The function itself has the additional input of the
|
||
external ephemeral key pair, used only for testing purposes.
|
||
|
||
@note Use KDF2 function mode for compliance with <em>X9.63-2011: Public Key
|
||
Cryptography for the Financial Services Industry – Key Agreement and Key
|
||
Transport Using Elliptic Curve Cryptography</em>. \par
|
||
|
||
@note The term "sender" indicates an entity that creates and
|
||
encapsulates the secret key using this function. The term "recipient"
|
||
indicates another entity which receives and decrypts the secret key. \par
|
||
|
||
@note All public and private keys that are used must relate to the same EC
|
||
Domain. \par
|
||
|
||
@note The user must verify that the public key of the recipient is
|
||
on the elliptic curve before it is used in this function.
|
||
|
||
@return CCError_t \c 0 on success.
|
||
*/
|
||
CCError_t mbedtls_ecies_kem_encrypt_full(
|
||
/*! [in] The ECP group to use. */
|
||
mbedtls_ecp_group *pGrp,
|
||
/*! [in] A pointer to the public key of the recipient. */
|
||
mbedtls_ecp_point *pRecipUzPublKey,
|
||
/*! [in] The KDF function mode to use: KDF1 or KDF2. For more
|
||
information, see CCKdfDerivFuncMode_t() in cc_kdf.h. */
|
||
CCKdfDerivFuncMode_t kdfDerivMode,
|
||
/*! [in] The used hash function. */
|
||
mbedtls_hkdf_hashmode_t kdfHashMode,
|
||
/*! [in] The specific ECIES mode, according to <em>ISO/IEC 18033-2:2006:
|
||
Information technology -- Security techniques -- Encryption algorithms
|
||
-- Part 2: Asymmetric ciphers</em> - section 10.2: 0: Not-single hash,
|
||
or 1: Single hash. */
|
||
uint32_t isSingleHashMode,
|
||
/*! [in] A pointer to the ephemeral public key related to the private
|
||
key. Must be set to NULL if \p pExtEphUzPrivateKey = NULL. */
|
||
mbedtls_ecp_point *pExtEphUzPublicKey,
|
||
/*! [in] The pointer to the external ephemeral private key. This key
|
||
is used only for testing the function. In regular use, the pointer
|
||
should be set to NULL and then the random key-pair should be generated
|
||
internally. */
|
||
mbedtls_mpi *pExtEphUzPrivateKey,
|
||
/*! [in] A pointer to the buffer for the secret-key data to be
|
||
generated. */
|
||
uint8_t *pSecrKey,
|
||
/*! [in] The size of the secret-key data in bytes. */
|
||
size_t secrKeySize,
|
||
/*! [in] A pointer to the encrypted cipher text. */
|
||
uint8_t *pCipherData,
|
||
/*! [in/out] In: A pointer to the size of the buffer for CipherData
|
||
output, or Out: The size of the buffer for CipherData output in
|
||
bytes. */
|
||
size_t *pCipherDataSize,
|
||
/*! [in] A pointer to the temporary buffer. */
|
||
void *pBuff,
|
||
/*! [in] The size of the buffer pointed by \p pBuff. Must not be less
|
||
than #MBEDTLS_ECIES_MIN_BUFF_LEN_BYTES. */
|
||
size_t buffLen,
|
||
/*! [in] The RNG function required for generating a key pair when
|
||
\p pExtEphUzPublicKey and \p pExtEphUzPrivateKey are NULL */
|
||
int (*f_rng)(void *, unsigned char *, size_t),
|
||
/*! [in] The RNG parameter. */
|
||
void *p_rng
|
||
);
|
||
|
||
/*!
|
||
@brief This function decrypts the encapsulated secret key passed by the
|
||
sender, according to <em>ISO/IEC 18033-2:2006: Information technology --
|
||
Security techniques -- Encryption algorithms -- Part 2: Asymmetric
|
||
ciphers</em>, sec. 10.2.4 - ECIES-KEM Decryption.
|
||
|
||
@note The KDF2 function mode must be used for compliance with <em>X9.63-2011:
|
||
Public Key Cryptography for the Financial Services Industry – Key Agreement
|
||
and Key Transport Using Elliptic Curve Cryptograph</em>. \par
|
||
|
||
@note The term "sender" indicates an entity that creates and
|
||
encapsulates the secret key using this function. The term "recipient"
|
||
indicates another entity which receives and decrypts the secret key. \par
|
||
|
||
@note All public and private keys that are used must relate to the same EC
|
||
Domain. \par
|
||
|
||
@return CCError_t \c 0 on success.
|
||
*/
|
||
CCError_t mbedtls_ecies_kem_decrypt(
|
||
/*! [in] The ECP group to use. */
|
||
mbedtls_ecp_group *pGrp,
|
||
/*! [in] A pointer to the private key of the recipient. */
|
||
mbedtls_mpi *pRecipUzPrivKey,
|
||
/*! [in] The KDF function mode to use: KDF1 or KDF2. For more
|
||
information, see CCKdfDerivFuncMode_t() in cc_kdf.h. */
|
||
CCKdfDerivFuncMode_t kdfDerivMode,
|
||
/*! [in] The used hash function. */
|
||
mbedtls_hkdf_hashmode_t kdfHashMode,
|
||
/*! [in] The specific ECIES mode definition: 0,1, according to
|
||
<em>ISO/IEC 18033-2:2006: Information technology -- Security techniques
|
||
-- Encryption algorithms -- Part 2: Asymmetric ciphers</em> -
|
||
section 10.2. */
|
||
uint32_t isSingleHashMode,
|
||
/*! [in] A pointer to the received encrypted cipher data. */
|
||
uint8_t *pCipherData,
|
||
/*! [in] The size of the cipher data in bytes. */
|
||
size_t cipherDataSize,
|
||
/*! [in] A pointer to the buffer for the secret-key data to be
|
||
generated. */
|
||
uint8_t *pSecrKey,
|
||
/*! [in] The size of the secret-key data in bytes. */
|
||
size_t secrKeySize,
|
||
/*! [in] A pointer to the temporary buffer. */
|
||
void *pBuff,
|
||
/*! [in] The size of the buffer pointed by \p pBuff. Must not be
|
||
less than #MBEDTLS_ECIES_MIN_BUFF_LEN_BYTES. */
|
||
size_t buffLen
|
||
);
|
||
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
/*!
|
||
@}
|
||
*/
|
||
#endif
|