Mbed OS Reference | crys_srp.h Source File

Go to the documentation of this file.
 /**************************************************************************************
 * 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 */
 
 
 
 
 
Important Information for this Arm website
