/*************************************************************************************************/ /*! * \file * * \brief SMP subsystem API. * * Copyright (c) 2010-2018 Arm Ltd. * * Copyright (c) 2019 Packetcraft, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /*************************************************************************************************/ #ifndef SMP_API_H #define SMP_API_H #include "wsf_os.h" #include "smp_defs.h" #include "dm_api.h" #ifdef __cplusplus extern "C" { #endif /*! \addtogroup STACK_SMP_API * \{ */ /************************************************************************************************** Macros **************************************************************************************************/ /** \name SMP Events * Events recognized and handled by the SMP state machine. */ /**@{*/ /*! \brief Event handler messages for SMP state machines */ enum { SMP_MSG_API_PAIR_REQ = 1, /*!< \brief API pairing request */ SMP_MSG_API_PAIR_RSP, /*!< \brief API pairing response */ SMP_MSG_API_CANCEL_REQ, /*!< \brief API cancel request */ SMP_MSG_API_AUTH_RSP, /*!< \brief API pin response */ SMP_MSG_API_SECURITY_REQ, /*!< \brief API security request */ SMP_MSG_CMD_PKT, /*!< \brief SMP command packet received */ SMP_MSG_CMD_PAIRING_FAILED, /*!< \brief SMP pairing failed packet received */ SMP_MSG_DM_ENCRYPT_CMPL, /*!< \brief Link encrypted */ SMP_MSG_DM_ENCRYPT_FAILED, /*!< \brief Link encryption failed */ SMP_MSG_DM_CONN_CLOSE, /*!< \brief Connection closed */ SMP_MSG_WSF_AES_CMPL, /*!< \brief AES calculation complete */ SMP_MSG_INT_SEND_NEXT_KEY, /*!< \brief Send next key to be distributed */ SMP_MSG_INT_MAX_ATTEMPTS, /*!< \brief Maximum pairing attempts reached */ SMP_MSG_INT_PAIRING_CMPL, /*!< \brief Pairing complete */ SMP_MSG_INT_RSP_TIMEOUT, /*!< \brief Pairing protocol response timeout */ SMP_MSG_INT_WI_TIMEOUT, /*!< \brief Pairing protocol wait interval timeout */ SMP_MSG_INT_LESC, /*!< \brief Pair with Secure Connections */ SMP_MSG_INT_LEGACY, /*!< \brief Pair with Legacy Security */ SMP_MSG_INT_JW_NC, /*!< \brief LESC Just-Works/Numeric Comparison pairing */ SMP_MSG_INT_PASSKEY, /*!< \brief LESC Passkey pairing */ SMP_MSG_INT_OOB, /*!< \brief LESC Out-of-Band Pairing */ SMP_MSG_API_USER_CONFIRM, /*!< \brief User confirms valid numeric comparison */ SMP_MSG_API_USER_KEYPRESS, /*!< \brief User keypress in passkey pairing */ SMP_MSG_API_KEYPRESS_CMPL, /*!< \brief User keypress complete in passkey pairing */ SMP_MSG_WSF_ECC_CMPL, /*!< \brief WSF ECC operation complete */ SMP_MSG_INT_PK_NEXT, /*!< \brief Continue to next passkey bit */ SMP_MSG_INT_PK_CMPL, /*!< \brief Passkey operation complete */ SMP_MSG_WSF_CMAC_CMPL, /*!< \brief WSF CMAC operation complete */ SMP_MSG_DH_CHECK_FAILURE, /*!< \brief DHKey check failure */ SMP_MSG_EARLY_CNF, /*!< \brief An early Confirm from the initiator in passkey pairing */ SMP_NUM_MSGS /*!< \brief Number of SMP message types. */ }; /**@}*/ /**@{*/ /*! \brief Additional SMP messages */ enum { SMP_DB_SERVICE_IND = SMP_NUM_MSGS /*!< \brief SMP DB Service timer indication */ }; /**@}*/ /************************************************************************************************** Data Types **************************************************************************************************/ /*! \brief Configurable parameters */ typedef struct { uint32_t attemptTimeout; /*!< \brief 'Repeated attempts' timeout in msec */ uint8_t ioCap; /*!< \brief I/O Capability */ uint8_t minKeyLen; /*!< \brief Minimum encryption key length */ uint8_t maxKeyLen; /*!< \brief Maximum encryption key length */ uint8_t maxAttempts; /*!< \brief Attempts to trigger 'repeated attempts' timeout */ uint8_t auth; /*!< \brief Device authentication requirements */ uint32_t maxAttemptTimeout; /*!< \brief Maximum 'Repeated attempts' timeout in msec */ uint32_t attemptDecTimeout; /*!< \brief Time msec before attemptExp decreases */ uint16_t attemptExp; /*!< \brief Exponent to raise attemptTimeout on maxAttempts */ } smpCfg_t; /*! \brief Data type for SMP_MSG_API_PAIR_REQ and SMP_MSG_API_PAIR_RSP */ typedef struct { wsfMsgHdr_t hdr; /*!< \brief Message header */ uint8_t oob; /*!< \brief Out-of-band data present flag */ uint8_t auth; /*!< \brief authentication flags */ uint8_t iKeyDist; /*!< \brief Initiator key distribution flags */ uint8_t rKeyDist; /*!< \brief Responder key distribution flags */ } smpDmPair_t; /*! \brief Data type for SMP_MSG_API_AUTH_RSP */ typedef struct { wsfMsgHdr_t hdr; /*!< \brief Message header */ uint8_t authData[SMP_OOB_LEN]; /*!< \brief Authentication data to display */ uint8_t authDataLen; /*!< \brief Length of authentication data */ } smpDmAuthRsp_t; /*! \brief Data type for SMP_MSG_API_USER_KEYPRESS */ typedef struct { wsfMsgHdr_t hdr; /*!< \brief Message header */ uint8_t keypress; /*!< \brief Keypress */ } smpDmKeypress_t; /*! \brief Data type for SMP_MSG_API_SECURITY_REQ */ typedef struct { wsfMsgHdr_t hdr; /*!< \brief Message header */ uint8_t auth; /*!< \brief Authentication flags */ } smpDmSecurityReq_t; /*! \brief Union SMP DM message data types */ typedef union { wsfMsgHdr_t hdr; /*!< \brief Message header */ smpDmPair_t pair; /*!< \brief Pairing request/response message */ smpDmAuthRsp_t authRsp; /*!< \brief Authentication message */ smpDmSecurityReq_t securityReq; /*!< \brief Security Request message */ smpDmKeypress_t keypress; /*!< \brief Keypress message */ } smpDmMsg_t; /*! \} */ /* STACK_SMP_API */ /************************************************************************************************** Global Variables; **************************************************************************************************/ /*! \addtogroup STACK_INIT * \{ */ /** \name SMP Configuration Structure * Pointer to structure containing initialization details of the SMP Subsystem. To be configured * by Application. */ /**@{*/ /*! \brief Configuration pointer */ extern smpCfg_t *pSmpCfg; /**@}*/ /*! \} */ /* STACK_INIT */ /************************************************************************************************** Function Declarations **************************************************************************************************/ /*! \addtogroup STACK_SMP_API * \{ */ /** \name SMP Initialization Functions * Legacy and Secure Connections initialization for Initiator and Responder roles. */ /**@{*/ /*************************************************************************************************/ /*! * \brief Initialize SMP initiator role. * * \return None. */ /*************************************************************************************************/ void SmpiInit(void); /*************************************************************************************************/ /*! * \brief Initialize SMP responder role. * * \return None. */ /*************************************************************************************************/ void SmprInit(void); /*************************************************************************************************/ /*! * \brief Initialize SMP initiator role utilizing BTLE Secure Connections. * * \return None. */ /*************************************************************************************************/ void SmpiScInit(void); /*************************************************************************************************/ /*! * \brief Initialize SMP responder role utilizing BTLE Secure Connections. * * \return None. */ /*************************************************************************************************/ void SmprScInit(void); /*************************************************************************************************/ /*! * \brief Use this SMP init function when SMP is not supported. * * \return None. */ /*************************************************************************************************/ void SmpNonInit(void); /**@}*/ /** \name SMP DM Interface Functions * Functions that allow the DM to send messages to SMP. */ /**@{*/ /*************************************************************************************************/ /*! * \brief This function is called by DM to send a message to SMP. * * \param pMsg Pointer to message structure. * * \return None. */ /*************************************************************************************************/ void SmpDmMsgSend(smpDmMsg_t *pMsg); /*************************************************************************************************/ /*! * \brief This function is called by DM to notify SMP of encrypted link status. * * \param pMsg Pointer to HCI message structure. * * \return None. */ /*************************************************************************************************/ void SmpDmEncryptInd(wsfMsgHdr_t *pMsg); /*************************************************************************************************/ /*! * \brief Return the STK for the given connection. * * \param connId Connection identifier. * \param pSecLevel Returns the security level of pairing when STK was created. * * \return Pointer to STK or NULL if not available. */ /*************************************************************************************************/ uint8_t *SmpDmGetStk(dmConnId_t connId, uint8_t *pSecLevel); /*************************************************************************************************/ /*! * \brief Format a cancel message with consideration for the attempts counter * * \param connId Connection Id. * \param pHdr Pointer to header of message to fill. * \param status Status to include. * * \return none. */ /*************************************************************************************************/ void SmpScGetCancelMsgWithReattempt(dmConnId_t connId, wsfMsgHdr_t *pHdr, uint8_t status); /*************************************************************************************************/ /*! * \brief Initialize the SMP Database. * * \return None. */ /*************************************************************************************************/ void SmpDbInit(void); /*************************************************************************************************/ /*! * \brief Called to force the DhKey to zero for qualification test purposes. * * \param enable TRUE - Force DhKey to zero. FALSE - Use calculated key * * \return None. */ /*************************************************************************************************/ void SmpScEnableZeroDhKey(bool_t enable); /**@}*/ /*! \} */ /* STACK_SMP_API */ #ifdef __cplusplus }; #endif #endif /* SMP_API_H */