GitBucket
Newer
/*************************************************************************************************/
/*!
* \file
*
* \brief SMP subsystem API.
*
* Copyright (c) 2010-2019 Arm Ltd. All Rights Reserved.
*
* Copyright (c) 2019-2020 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_MSG_INT_CLEANUP, /*!< \brief Cleanup control information and return to IDLE state */
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 Check if LE Secure Connections is enabled on the connection.
*
* \param connId Connection identifier.
*
* \return TRUE is Secure Connections is enabled, else FALSE
*/
/*************************************************************************************************/
bool_t SmpDmLescEnabled(dmConnId_t connId);
/*************************************************************************************************/
/*!
* \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 */