smp_api.h

00001 /*************************************************************************************************/
00002 /*!
00003  *  \file   smp_api.h
00004  *        
00005  *  \brief  SMP subsystem API.
00006  *
00007  *          $Date: 2011-10-14 21:35:03 -0700 (Fri, 14 Oct 2011) $
00008  *          $Revision: 191 $
00009  *  
00010  *  Copyright (c) 2010-2016 ARM Limited. All rights reserved.
00011  *
00012  *  SPDX-License-Identifier: LicenseRef-PBL
00013  *
00014  *  Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use
00015  *  this file except in compliance with the License.  You may obtain a copy of the License at
00016  *
00017  *  https://www.mbed.com/licenses/PBL-1.0
00018  *
00019  *  See the License for the specific language governing permissions and limitations under the License.
00020  */
00021 /*************************************************************************************************/
00022 #ifndef SMP_API_H
00023 #define SMP_API_H
00024 
00025 #include "wsf_os.h"
00026 #include "smp_defs.h"
00027 #include "dm_api.h"
00028 
00029 #ifdef __cplusplus
00030 extern "C" {
00031 #endif
00032 
00033 /**************************************************************************************************
00034   Macros
00035 **************************************************************************************************/
00036 
00037 /*! Event handler messages for SMP state machines */
00038 enum
00039 {
00040   SMP_MSG_API_PAIR_REQ = 1,               /*! API pairing request */
00041   SMP_MSG_API_PAIR_RSP ,                   /*! API pairing response */
00042   SMP_MSG_API_CANCEL_REQ ,                 /*! API cancel request */
00043   SMP_MSG_API_AUTH_RSP ,                   /*! API pin response */
00044   SMP_MSG_API_SECURITY_REQ ,               /*! API security request */
00045   SMP_MSG_CMD_PKT ,                        /*! SMP command packet received */
00046   SMP_MSG_CMD_PAIRING_FAILED ,             /*! SMP pairing failed packet received */
00047   SMP_MSG_DM_ENCRYPT_CMPL ,                /*! Link encrypted */
00048   SMP_MSG_DM_ENCRYPT_FAILED ,              /*! Link encryption failed */
00049   SMP_MSG_DM_CONN_CLOSE ,                  /*! Connection closed */
00050   SMP_MSG_WSF_AES_CMPL ,                   /*! AES calculation complete */
00051   SMP_MSG_INT_SEND_NEXT_KEY ,              /*! Send next key to be distributed */
00052   SMP_MSG_INT_MAX_ATTEMPTS ,               /*! Maximum pairing attempts reached */
00053   SMP_MSG_INT_PAIRING_CMPL ,               /*! Pairing complete */
00054   SMP_MSG_INT_TIMEOUT ,                    /*! Pairing protocol timeout */
00055   SMP_NUM_MSGS 
00056 };
00057 
00058 /**************************************************************************************************
00059   Data Types
00060 **************************************************************************************************/
00061 
00062 /*! Configurable parameters */
00063 typedef struct
00064 {
00065   uint16_t            attemptTimeout;     /*! 'Repeated attempts' timeout in msec */
00066   uint8_t             ioCap ;              /*! I/O Capability */
00067   uint8_t             minKeyLen ;          /*! Minimum encryption key length */
00068   uint8_t             maxKeyLen ;          /*! Maximum encryption key length */
00069   uint8_t             maxAttempts ;        /*! Attempts to trigger 'repeated attempts' timeout */
00070   uint8_t             auth ;               /*! Device authentication requirements */
00071 } smpCfg_t ;
00072 
00073 /*! Data type for SMP_MSG_API_PAIR_REQ and SMP_MSG_API_PAIR_RSP */
00074 typedef struct
00075 {
00076   wsfMsgHdr_t          hdr;
00077   uint8_t             oob;
00078   uint8_t             auth;
00079   uint8_t             iKeyDist;
00080   uint8_t             rKeyDist;
00081 } smpDmPair_t ;
00082 
00083 /*! Data type for SMP_MSG_API_AUTH_RSP */
00084 typedef struct
00085 {
00086   wsfMsgHdr_t          hdr;
00087   uint8_t             authData[SMP_OOB_LEN];
00088   uint8_t             authDataLen;
00089 } smpDmAuthRsp_t ;
00090 
00091 /*! Data type for SMP_MSG_API_SECURITY_REQ */
00092 typedef struct
00093 {
00094   wsfMsgHdr_t          hdr;
00095   uint8_t             auth;
00096 } smpDmSecurityReq_t ;
00097 
00098 /*! Union SMP DM message data types */
00099 typedef union
00100 {
00101   wsfMsgHdr_t          hdr;
00102   smpDmPair_t          pair;
00103   smpDmAuthRsp_t       authRsp;
00104   smpDmSecurityReq_t   securityReq;
00105 } smpDmMsg_t ;
00106 
00107 /**************************************************************************************************
00108   Global Variables;
00109 **************************************************************************************************/
00110 
00111 /*! Configuration pointer */
00112 extern smpCfg_t  *pSmpCfg ;
00113 
00114 /**************************************************************************************************
00115   Function Declarations
00116 **************************************************************************************************/
00117 
00118 /*************************************************************************************************/
00119 /*!
00120  *  \fn     SmpiInit
00121  *        
00122  *  \brief  Initialize SMP initiator role.
00123  *
00124  *  \return None.
00125  */
00126 /*************************************************************************************************/
00127 void SmpiInit(void);
00128 
00129 /*************************************************************************************************/
00130 /*!
00131  *  \fn     SmprInit
00132  *        
00133  *  \brief  Initialize SMP responder role.
00134  *
00135  *  \return None.
00136  */
00137 /*************************************************************************************************/
00138 void SmprInit(void);
00139 
00140 /*************************************************************************************************/
00141 /*!
00142  *  \fn     SmpNonInit
00143  *        
00144  *  \brief  Use this SMP init function when SMP is not supported.
00145  *
00146  *  \return None.
00147  */
00148 /*************************************************************************************************/
00149 void SmpNonInit(void);
00150 
00151 /*************************************************************************************************/
00152 /*!
00153  *  \fn     SmpDmMsgSend
00154  *        
00155  *  \brief  This function is called by DM to send a message to SMP.
00156  *
00157  *  \param  pMsg      Pointer to message structure.
00158  *
00159  *  \return None.
00160  */
00161 /*************************************************************************************************/
00162 void SmpDmMsgSend(smpDmMsg_t  *pMsg);
00163 
00164 /*************************************************************************************************/
00165 /*!
00166  *  \fn     SmpDmEncryptInd
00167  *        
00168  *  \brief  This function is called by DM to notify SMP of encrypted link status.
00169  *
00170  *  \param  pMsg    Pointer to HCI message structure.
00171  *
00172  *  \return None.
00173  */
00174 /*************************************************************************************************/
00175 void SmpDmEncryptInd(wsfMsgHdr_t  *pMsg);
00176 
00177 /*************************************************************************************************/
00178 /*!
00179  *  \fn     SmpDmGetStk
00180  *        
00181  *  \brief  Return the STK for the given connection.
00182  *
00183  *  \param  connId    Connection identifier.
00184  *  \param  pSecLevel Returns the security level of pairing when STK was created.
00185  *
00186  *  \return Pointer to STK or NULL if not available.
00187  */
00188 /*************************************************************************************************/
00189 uint8_t *SmpDmGetStk(dmConnId_t  connId, uint8_t *pSecLevel);
00190 
00191 #ifdef __cplusplus
00192 };
00193 #endif
00194 
00195 #endif /* SMP_API_H */