mirror of https://github.com/ARMmbed/mbed-os.git
376 lines
16 KiB
C
376 lines
16 KiB
C
/**************************************************************************************
|
|
* Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved *
|
|
* *
|
|
* This file and the related binary are licensed under the following license: *
|
|
* *
|
|
* ARM Object Code and Header Files License, v1.0 Redistribution. *
|
|
* *
|
|
* Redistribution and use of object code, header files, and documentation, without *
|
|
* modification, are permitted provided that the following conditions are met: *
|
|
* *
|
|
* 1) Redistributions must reproduce the above copyright notice and the *
|
|
* following disclaimer in the documentation and/or other materials *
|
|
* provided with the distribution. *
|
|
* *
|
|
* 2) Unless to the extent explicitly permitted by law, no reverse *
|
|
* engineering, decompilation, or disassembly of is permitted. *
|
|
* *
|
|
* 3) Redistribution and use is permitted solely for the purpose of *
|
|
* developing or executing applications that are targeted for use *
|
|
* on an ARM-based product. *
|
|
* *
|
|
* DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
|
|
* CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT *
|
|
* NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, *
|
|
* AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE *
|
|
* COPYRIGHT HOLDERS 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
|
|
@brief This file contains all of the enums and definitions that are used for the
|
|
CRYS SRP APIs, as well as the APIs themselves.
|
|
@defgroup crys_srp CryptoCell SRP APIs
|
|
@{
|
|
@ingroup cryptocell_api
|
|
|
|
*/
|
|
#ifndef CRYS_SRP_H
|
|
#define CRYS_SRP_H
|
|
|
|
|
|
#include "ssi_pal_types.h"
|
|
#include "crys_error.h"
|
|
#include "crys_pka_defs_hw.h"
|
|
#include "crys_hash.h"
|
|
#include "crys_rnd.h"
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
/*!\internal The following describes the SRP APIs usage for the Device and the Accessory :*
|
|
|
|
Device (User) Accessory (Host)
|
|
* -------------- -----------------
|
|
|
|
1. CRYS_SRP_HK_INIT(CRYS_SRP_USER, .......) CRYS_SRP_HK_INIT(CRYS_SRP_HOST, .....)
|
|
|
|
2. CRYS_SRP_PwdVerCreate(..)
|
|
|
|
3. CRYS_SRP_UserPubKeyCreate(..) CRYS_SRP_HostPubKeyCreate(..)
|
|
|
|
4. CRYS_SRP_UserProofCalc(..)
|
|
|
|
5. CRYS_SRP_HostProofVerifyAndCalc(..)
|
|
|
|
6. CRYS_SRP_UserProofVerify(..)
|
|
|
|
7. CRYS_SRP_Clear(..) CRYS_SRP_Clear(..)
|
|
|
|
*/
|
|
|
|
/************************ Defines ******************************/
|
|
/*! The SRP modulus sizes. */
|
|
/*! 1024 bits modulus size. */
|
|
#define CRYS_SRP_MODULUS_SIZE_1024_BITS 1024
|
|
/*! 1536 bits modulus size. */
|
|
#define CRYS_SRP_MODULUS_SIZE_1536_BITS 1536
|
|
/*! 2048 bits modulus size. */
|
|
#define CRYS_SRP_MODULUS_SIZE_2048_BITS 2048
|
|
/*! 3072 bits modulus size. */
|
|
#define CRYS_SRP_MODULUS_SIZE_3072_BITS 3072
|
|
|
|
/*! Maximal modulus size in bits. */
|
|
#define CRYS_SRP_MAX_MODULUS_IN_BITS CRYS_SRP_MODULUS_SIZE_3072_BITS
|
|
/*! Maximal modulus size in bytes. */
|
|
#define CRYS_SRP_MAX_MODULUS (CRYS_SRP_MAX_MODULUS_IN_BITS/SASI_BITS_IN_BYTE)
|
|
/*! Maximal modulus size in words. */
|
|
#define CRYS_SRP_MAX_MODULUS_IN_WORDS (CRYS_SRP_MAX_MODULUS_IN_BITS/SASI_BITS_IN_32BIT_WORD)
|
|
|
|
/*! The SRP private number size range. */
|
|
/*! Minimal private number size in bits. */
|
|
#define CRYS_SRP_PRIV_NUM_MIN_SIZE_IN_BITS (256)
|
|
/*! Minimal private number size in bytes. */
|
|
#define CRYS_SRP_PRIV_NUM_MIN_SIZE (CRYS_SRP_PRIV_NUM_MIN_SIZE_IN_BITS/SASI_BITS_IN_BYTE)
|
|
/*! Minimal private number size in words. */
|
|
#define CRYS_SRP_PRIV_NUM_MIN_SIZE_IN_WORDS (CRYS_SRP_PRIV_NUM_MIN_SIZE_IN_BITS/SASI_BITS_IN_32BIT_WORD)
|
|
/*! Maximal private number size in bits. */
|
|
#define CRYS_SRP_PRIV_NUM_MAX_SIZE_IN_BITS (CRYS_SRP_MAX_MODULUS_IN_BITS)
|
|
/*! Maximal private number size in bytes. */
|
|
#define CRYS_SRP_PRIV_NUM_MAX_SIZE (CRYS_SRP_PRIV_NUM_MAX_SIZE_IN_BITS/SASI_BITS_IN_BYTE)
|
|
/*! Maximal private number size in words. */
|
|
#define CRYS_SRP_PRIV_NUM_MAX_SIZE_IN_WORDS (CRYS_SRP_PRIV_NUM_MAX_SIZE_IN_BITS/SASI_BITS_IN_32BIT_WORD)
|
|
|
|
/*! Maximal SRP HASH digest size in words. */
|
|
#define CRYS_SRP_MAX_DIGEST_IN_WORDS CRYS_HASH_RESULT_SIZE_IN_WORDS
|
|
/*! Maximal SRP HASH digest size in bytes. */
|
|
#define CRYS_SRP_MAX_DIGEST (CRYS_SRP_MAX_DIGEST_IN_WORDS*SASI_32BIT_WORD_SIZE)
|
|
|
|
/*! Minimal salt size in bytes. */
|
|
#define CRYS_SRP_MIN_SALT_SIZE (8)
|
|
/*! Minimal salt size in words. */
|
|
#define CRYS_SRP_MIN_SALT_SIZE_IN_WORDS (CRYS_SRP_MIN_SALT_SIZE/SASI_32BIT_WORD_SIZE)
|
|
/*! Maximal salt size in bytes. */
|
|
#define CRYS_SRP_MAX_SALT_SIZE (64)
|
|
/*! Maximal salt size in words. */
|
|
#define CRYS_SRP_MAX_SALT_SIZE_IN_WORDS (CRYS_SRP_MAX_SALT_SIZE/SASI_32BIT_WORD_SIZE)
|
|
|
|
/************************ Typedefs ****************************/
|
|
/*! SRP modulus buffer definition. */
|
|
typedef uint8_t CRYS_SRP_Modulus_t[CRYS_SRP_MAX_MODULUS];
|
|
|
|
/*! SRP digest buffer definition. */
|
|
typedef uint8_t CRYS_SRP_Digest_t[CRYS_SRP_MAX_DIGEST];
|
|
|
|
/*! SRP secret buffer definition. */
|
|
typedef uint8_t CRYS_SRP_Secret_t[2*CRYS_SRP_MAX_DIGEST];
|
|
|
|
/************************ Enums ********************************/
|
|
|
|
/*!
|
|
SRP supported versions
|
|
*/
|
|
typedef enum {
|
|
CRYS_SRP_VER_3 = 0, /*!< VER 3. */
|
|
CRYS_SRP_VER_6 = 1, /*!< VER 6. */
|
|
CRYS_SRP_VER_6A = 2, /*!< VER 6A. */
|
|
CRYS_SRP_VER_HK = 3, /*!< VER 6A. */
|
|
/*! Maximal number of supported versions.*/
|
|
CRYS_SRP_NumOfVersions,
|
|
/*! Reserved.*/
|
|
CRYS_SRP_VersionLast= 0x7FFFFFFF,
|
|
|
|
}CRYS_SRP_Version_t;
|
|
|
|
/*!
|
|
SRP entity type
|
|
*/
|
|
typedef enum {
|
|
CRYS_SRP_HOST = 1, /*!< Host entity, called also server, verifier, or Accessory in Home-Kit */
|
|
CRYS_SRP_USER = 2, /*!< User entity, called also client, or Device in Home-Kit */
|
|
/*! Maximal number of entities types.*/
|
|
CRYS_SRP_NumOfEntityType,
|
|
/*! Reserved.*/
|
|
CRYS_SRP_EntityLast= 0x7FFFFFFF,
|
|
|
|
}CRYS_SRP_Entity_t;
|
|
|
|
/************************ Structs ******************************/
|
|
|
|
/*! Group parameters for the SRP - defines the modulus and the generator used */
|
|
typedef struct CRYS_SRP_GroupParam_t {
|
|
/*! SRP modulus.*/
|
|
CRYS_SRP_Modulus_t modulus;
|
|
/*! SRP generator.*/
|
|
uint8_t gen;
|
|
/*! SRP modulus size in bits .*/
|
|
size_t modSizeInBits;
|
|
/*! SRP valid Np.*/
|
|
uint32_t validNp;
|
|
/*! SRP Np buffer.*/
|
|
uint32_t Np[CRYS_PKA_BARRETT_MOD_TAG_BUFF_SIZE_IN_WORDS];
|
|
}CRYS_SRP_GroupParam_t;
|
|
|
|
/************************ context Structs ******************************/
|
|
/*! The SRP context prototype */
|
|
typedef struct CRYS_SRP_Context_t {
|
|
/*! SRP entitiy type.*/
|
|
CRYS_SRP_Entity_t srpType;
|
|
/*! SRP version.*/
|
|
CRYS_SRP_Version_t srpVer;
|
|
/*! Group parameter including the modulus information.*/
|
|
CRYS_SRP_GroupParam_t groupParam; // N, g, Np
|
|
/*! Hash mode.*/
|
|
CRYS_HASH_OperationMode_t hashMode;
|
|
/*! Hash digest size.*/
|
|
size_t hashDigestSize;
|
|
/*! Pointer to RND state.*/
|
|
CRYS_RND_State_t *pRndState;
|
|
/*! Pointer to random vector generation function.*/
|
|
SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc;
|
|
/*! Modulus.*/
|
|
CRYS_SRP_Modulus_t ephemPriv; // a or b
|
|
/*! Modulus size.*/
|
|
size_t ephemPrivSize;
|
|
/*! User name digest.*/
|
|
CRYS_SRP_Digest_t userNameDigest; // M
|
|
/*! Cred digest.*/
|
|
CRYS_SRP_Digest_t credDigest; // p
|
|
/*! SRP K multiplier. */ //
|
|
CRYS_SRP_Digest_t kMult; // k multiplier
|
|
}CRYS_SRP_Context_t;
|
|
|
|
|
|
/************************ SRP common Functions **********************/
|
|
/****************************************************************************************************/
|
|
/*!
|
|
@brief This function initiates the SRP context.
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_srp_error.h or crys_hash_error.h.
|
|
*/
|
|
CIMPORT_C CRYSError_t CRYS_SRP_Init(
|
|
CRYS_SRP_Entity_t srpType, /*!< [in] SRP entity type. */
|
|
CRYS_SRP_Version_t srpVer, /*!< [in] SRP version. */
|
|
CRYS_SRP_Modulus_t srpModulus, /*!< [in] A pointer to the SRP modulus, BE byte buffer. */
|
|
uint8_t srpGen, /*!< [in] The SRP generator param. */
|
|
size_t modSizeInBits, /*!< [in] The SRP modulus size in bits:1024, 1536, 2048 & 3072 */
|
|
CRYS_HASH_OperationMode_t hashMode, /*!< [in] Enumerator defining the HASH mode. */
|
|
uint8_t *pUserName, /*!< [in] A Pointer to user name. */
|
|
size_t userNameSize, /*!< [in] The user name buffer size > 0. */
|
|
uint8_t *pPwd, /*!< [in] A Pointer to user password. */
|
|
size_t pwdSize, /*!< [in] The user password buffer size > 0 if pPwd is valid. */
|
|
void *pRndState, /*!< [in] A Pointer to RND context.*/
|
|
SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, /*!< [in] Pointer to random vector generation function.*/
|
|
CRYS_SRP_Context_t *pCtx /*!< [out] A Pointer to the SRP host context.*/
|
|
);
|
|
|
|
/*! MACRO definition for a specific SRP initialization function.*/
|
|
#define CRYS_SRP_HK_INIT(srpType, srpModulus, srpGen, modSizeInBits, pUserName, userNameSize, pPwd, pwdSize, pRndState, rndGenerateVectFunc, pCtx) \
|
|
CRYS_SRP_Init(srpType, CRYS_SRP_VER_HK, srpModulus, srpGen, modSizeInBits, CRYS_HASH_SHA512_mode, pUserName, userNameSize, pPwd, pwdSize, pRndState, rndGenerateVectFunc, pCtx)
|
|
|
|
|
|
/****************************************************************************************************/
|
|
/*!
|
|
@brief This function calculates pSalt & password verifier
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_srp_error.h, crys_rnd_error.h or crys_hash_error.h.
|
|
*/
|
|
CIMPORT_C CRYSError_t CRYS_SRP_PwdVerCreate(
|
|
size_t saltSize, /*!< [in] The size of the random salt to generate,
|
|
The range is between CRYS_SRP_MIN_SALT_SIZE
|
|
to CRYS_SRP_MAX_SALT_SIZE. */
|
|
uint8_t *pSalt, /*!< [out] A Pointer to the pSalt number (s).*/
|
|
CRYS_SRP_Modulus_t pwdVerifier, /*!< [out] A Pointer to the password verifier (v). */
|
|
CRYS_SRP_Context_t *pCtx /*!< [out] A Pointer to the SRP context.*/
|
|
);
|
|
|
|
|
|
/****************************************************************************************************/
|
|
/*!
|
|
@brief Clears the SRP context.
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_srp_error.h.
|
|
*/
|
|
CIMPORT_C CRYSError_t CRYS_SRP_Clear(
|
|
CRYS_SRP_Context_t *pCtx /*!< [in/out] A Pointer to the SRP context.*/
|
|
);
|
|
|
|
|
|
/************************ SRP Host Functions **********************/
|
|
/****************************************************************************************************/
|
|
/*!
|
|
@brief This function generates host public & private ephemeral key, known as B & b in RFC
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_srp_error.h or crys_rnd_error.h.
|
|
*/
|
|
CIMPORT_C CRYSError_t CRYS_SRP_HostPubKeyCreate(
|
|
size_t ephemPrivSize, /*!< [in] The size of the generated ephemeral private key (b).
|
|
The range is between CRYS_SRP_PRIV_NUM_MIN_SIZE to
|
|
CRYS_SRP_PRIV_NUM_MAX_SIZE */
|
|
CRYS_SRP_Modulus_t pwdVerifier, /*!< [in] A Pointer to the verifier (v). */
|
|
CRYS_SRP_Modulus_t hostPubKeyB, /*!< [out] A Pointer to the host ephemeral public key (B). */
|
|
CRYS_SRP_Context_t *pCtx /*!< [in/out] A Pointer to the SRP context.*/
|
|
);
|
|
|
|
|
|
/*!
|
|
@brief Verifies the user Proof and calculates the Host message proof.
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_srp_error.h or crys_hash_error.h.
|
|
*/
|
|
CIMPORT_C CRYSError_t CRYS_SRP_HostProofVerifyAndCalc(
|
|
size_t saltSize, /*!< [in] The size of the random salt,
|
|
The range is between CRYS_SRP_MIN_SALT_SIZE
|
|
to CRYS_SRP_MAX_SALT_SIZE. */
|
|
uint8_t *pSalt, /*!< [in] A Pointer to the pSalt number.*/
|
|
CRYS_SRP_Modulus_t pwdVerifier, /*!< [in] A Pointer to the password verifier (v). */
|
|
CRYS_SRP_Modulus_t userPubKeyA, /*!< [in] A Pointer to the user ephemeral public key (A). */
|
|
CRYS_SRP_Modulus_t hostPubKeyB, /*!< [in] A Pointer to the host ephemeral public key (B). */
|
|
CRYS_SRP_Digest_t userProof, /*!< [in] A Pointer to the SRP user proof buffer (M1).*/
|
|
CRYS_SRP_Digest_t hostProof, /*!< [out] A Pointer to the SRP host proof buffer (M2).*/
|
|
CRYS_SRP_Secret_t sharedSecret, /*!< [out] A Pointer to the SRP shared secret (K).*/
|
|
CRYS_SRP_Context_t *pCtx /*!< [in] A Pointer to the SRP context.*/
|
|
);
|
|
|
|
|
|
|
|
/************************ SRP User Functions **********************/
|
|
/****************************************************************************************************/
|
|
/*!
|
|
@brief This function generates user public & private ephemeral key, known as A & a in RFC
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_srp_error.h or crys_rnd_error.h.
|
|
*/
|
|
CIMPORT_C CRYSError_t CRYS_SRP_UserPubKeyCreate(
|
|
size_t ephemPrivSize, /*!< [in] The size of the generated ephemeral private key (a).
|
|
The range is between CRYS_SRP_PRIV_NUM_MIN_SIZE to
|
|
CRYS_SRP_PRIV_NUM_MAX_SIZE */
|
|
CRYS_SRP_Modulus_t userPubKeyA, /*!< [out] A Pointer to the user ephemeral public key (A). */
|
|
CRYS_SRP_Context_t *pCtx /*!< [in/out] A Pointer to the SRP context.*/
|
|
);
|
|
|
|
|
|
/****************************************************************************************************/
|
|
/*!
|
|
@brief This function calculates the user proof.
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_srp_error.h or crys_hash_error.h.
|
|
*/
|
|
CIMPORT_C CRYSError_t CRYS_SRP_UserProofCalc(
|
|
size_t saltSize, /*!< [in] The size of the random salt,
|
|
The range is between CRYS_SRP_MIN_SALT_SIZE
|
|
to CRYS_SRP_MAX_SALT_SIZE. */
|
|
uint8_t *pSalt, /*!< [in] A Pointer to the pSalt number.*/
|
|
CRYS_SRP_Modulus_t userPubKeyA, /*!< [in] A Pointer to the user public ephmeral key (A).*/
|
|
CRYS_SRP_Modulus_t hostPubKeyB, /*!< [in] A Pointer to the host public ephmeral key (B).*/
|
|
CRYS_SRP_Digest_t userProof, /*!< [out] A Pointer to the SRP user proof buffer (M1).*/
|
|
CRYS_SRP_Secret_t sharedSecret, /*!< [out] A Pointer to the SRP shared secret (K).*/
|
|
CRYS_SRP_Context_t *pCtx /*!< [out] A Pointer to the SRP context.*/
|
|
);
|
|
|
|
/****************************************************************************************************/
|
|
/*!
|
|
@brief This function verifies the host proof
|
|
|
|
@return CRYS_OK on success.
|
|
@return A non-zero value on failure as defined crys_srp_error.h or crys_hash_error.h.
|
|
*/
|
|
CIMPORT_C CRYSError_t CRYS_SRP_UserProofVerify(
|
|
CRYS_SRP_Secret_t sharedSecret, /*!< [in] A Pointer to the SRP shared secret (K).*/
|
|
CRYS_SRP_Modulus_t userPubKeyA, /*!< [in] A Pointer to the user public ephmeral key (A).*/
|
|
CRYS_SRP_Digest_t userProof, /*!< [in] A Pointer to the SRP user proof buffer (M1).*/
|
|
CRYS_SRP_Digest_t hostProof, /*!< [in] A Pointer to the SRP host proof buffer (M2).*/
|
|
CRYS_SRP_Context_t *pCtx /*!< [out] A Pointer to the SRP user context.*/
|
|
);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
/**
|
|
@}
|
|
*/
|
|
#endif /* #ifndef CRYS_SRP_H */
|
|
|
|
|
|
|
|
|
|
|