| /************************************************************************************** |
| * 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 */ |
| |
| |
| |
| |
| |
