summaryrefslogtreecommitdiff
path: root/digital/zigbit/bitcloud/stack/Components/APS/include/apsmeEstablishKey.h
diff options
context:
space:
mode:
Diffstat (limited to 'digital/zigbit/bitcloud/stack/Components/APS/include/apsmeEstablishKey.h')
-rw-r--r--digital/zigbit/bitcloud/stack/Components/APS/include/apsmeEstablishKey.h317
1 files changed, 317 insertions, 0 deletions
diff --git a/digital/zigbit/bitcloud/stack/Components/APS/include/apsmeEstablishKey.h b/digital/zigbit/bitcloud/stack/Components/APS/include/apsmeEstablishKey.h
new file mode 100644
index 00000000..2065dc72
--- /dev/null
+++ b/digital/zigbit/bitcloud/stack/Components/APS/include/apsmeEstablishKey.h
@@ -0,0 +1,317 @@
+/**************************************************************************//**
+ \file apsmeEstablishKey.h
+
+ \brief Interface of APS Key-Establishment Services.
+
+ \author
+ Atmel Corporation: http://www.atmel.com \n
+ Support email: avr@atmel.com
+
+ Copyright (c) 2008-2011, Atmel Corporation. All rights reserved.
+ Licensed under Atmel's Limited License Agreement (BitCloudTM).
+
+ \internal
+ History:
+ 2010-11-24 Max Gekk - Created.
+ Last change:
+ $Id: apsmeEstablishKey.h 18914 2011-10-18 09:13:36Z mgekk $
+ ******************************************************************************/
+#if !defined _APSME_ESTABLISH_KEY_H
+#define _APSME_ESTABLISH_KEY_H
+/**//**
+ *
+ * The APS layer provides services that allow two devices to establish
+ * a mutual link key. Initial trust information (for example, a master key) must be
+ * installed on each device prior to running the key establishment procedure.
+ * See ZigBee Specification r19, 4.4.2, page 441.
+ *
+ **/
+
+/******************************************************************************
+ Includes section
+ ******************************************************************************/
+#include <apsCommon.h>
+#if defined _SECURITY_ && defined _LINK_SECURITY_
+#include <sspSkke.h>
+
+/******************************************************************************
+ Types section
+ ******************************************************************************/
+/**//**
+ * \brief Status values as a result of the SKKE protocol.
+ * See ZigBee Specification r19, Table 4.10, page 448.
+ **/
+typedef enum
+{
+ /** No errors occured .*/
+ APS_SKKE_SUCCESS_STATUS = 0x00,
+ /** An invalid parameter was input to one of the key establishment
+ * primitives. */
+ APS_SKKE_INVALID_PARAMETER_STATUS = 0x01,
+ /** No master key is available. */
+ APS_SKKE_NO_MASTER_KEY_STATUS = 0x02,
+ /** Challenge is invalid:
+ * \li Initiator during action step 3 (sub-clause B.7.1),
+ * \li Responder during action step 3 (sub-clause B.7.2).
+ **/
+ APS_SKKE_INVALID_CHALLENGE_STATUS = 0x03,
+ /** SKG outputs invalid:
+ * \li Initiator during action step 4 (sub-clause B.7.1),
+ * \li Responder during action step 3 (sub-clause B.7.2).
+ **/
+ APS_SKKE_INVALID_SKG_STATUS = 0x04,
+ /** MAC transformation outputs invalid:
+ * \li Initiator during action step 8 (sub-clause B.7.1),
+ * \li Responder during action step 10 (sub-clause B.7.2).
+ **/
+ APS_SKKE_INVALID_MAC_STATUS = 0x05,
+ /** Tag checking transformation outputs invalid:
+ * \li Initiator during action step 12 (sub-clause B.7.1),
+ * \li Responder during action step 8 (sub-clause B.7.2).
+ **/
+ APS_SKKE_INVALID_KEY_STATUS = 0x06,
+ /** Either the initiator or responder waits for the next expected incoming
+ * message for time greater than the apsSecurityTimeOutPeriod attribute
+ * of the AIB. */
+ APS_SKKE_TIMEOUT_STATUS = 0x07,
+ /** Either the initiator or responder receives an SKKE frame out of order. */
+ APS_SKKE_BAD_FRAME_STATUS = 0x08,
+ /** Invalid global state of APS layer. */
+ APS_SKKE_NOT_PERMITTED_STATUS = 0x09,
+ /** Transmission of SKKE-1 command frame is failure. */
+ APS_SKKE_1_TX_ERROR_STATUS = 0x0A,
+ /** Transmission of SKKE-2 command frame is failure. */
+ APS_SKKE_2_TX_ERROR_STATUS = 0x0B,
+ /** Transmission of SKKE-3 command frame is failure. */
+ APS_SKKE_3_TX_ERROR_STATUS = 0x0C,
+ /** Transmission of SKKE-4 command frame is failure. */
+ APS_SKKE_4_TX_ERROR_STATUS = 0x0D,
+ /** Error saving new link key. */
+ APS_SKKE_SET_LINK_KEY_ERROR_STATUS = 0x0E,
+ /** Short address of key establish partner is not found. */
+ APS_SKKE_NO_SHORT_ADDR_STATUS = 0x0F
+} APS_SkkeStatus_t;
+
+/**//**
+ * \brief The requested key-establishment method.
+ **/
+typedef enum
+{
+ APS_SKKE_KEY_ESTABLISHMENT_METHOD = 0x00
+} APS_KeyEstablishmentMethod_t;
+
+/**//**
+ * \struct APS_EstablishKeyConf_t apsmeEstablishKey.h "aps.h"
+ *
+ * \brief Parameters of a callback for the APS_EstablishKeyReq() function.
+ *
+ * The structure conforms to APSME-KEY-ESTABLISH.confirm primitive defined in
+ * ZigBee Specification r19, Table 4.6, page 443.
+ **/
+typedef struct
+{
+ /** \ref Endian "[LE]" The extended 64-bit address of the device with
+ * which the key-establishment protocol was executed. */
+ ExtAddr_t address;
+ /** This parameter indicates the final status of the key-establishment
+ * protocol. */
+ APS_SkkeStatus_t status;
+} APS_EstablishKeyConf_t;
+
+/** Type of time-to-live of Establish Key request or response. */
+typedef uint16_t ApsSkkeTTL_t;
+
+typedef struct _ApsSkkeElem_t
+{
+ QueueElement_t qelem; /*!< Used for queue support. */
+ uint8_t state; /*!< Internal state of Establish Key request (response). */
+ ApsSkkeTTL_t ttl; /*!< Time to live of appropriate SKKE request. */
+ /** Pointer to confirmation function of SKKE operations. */
+ void (* apsSkkeConf)(struct _ApsSkkeElem_t *elem, APS_SkkeStatus_t skkeStatus);
+} ApsSkkeElem_t;
+
+/**//**
+ * \struct APS_EstablishKeyReq_t apsmeEstablishKey.h "aps.h"
+ *
+ * \brief Parameters of the APS_EstablishKeyReq() function
+ *
+ * The structure conforms to APSME-KEY-ESTABLISH.request primitive
+ * defined in ZigBee Specification r19, Table 4.5, page 441.
+ **/
+typedef struct
+{
+ /** \cond SERVICE_FIELDS */
+ struct
+ {
+ ApsSkkeElem_t elem; /*!< Common substructure of SKKE request. */
+ ShortAddr_t dstShortAddr; /*!< Short address of SKKE responder. */
+ /** Saved pointer to NWK_DataReq_t structure for SKKE-1 command frame. */
+ NWK_DataReq_t *skke1NwkDataReq;
+ /** Saved pointer to NWK_DataReq_t structure for SKKE-3 command frame. */
+ NWK_DataReq_t *skke3NwkDataReq;
+ /** Request to allocate memory for SKKE command in NWK layer. */
+ NWK_AllocDataReq_t allocNwkDataReq;
+ /** Parameters of request for calculation of link key by master key. */
+ SSP_CalculateSkkeParamsReq_t sspReq;
+ } service;
+ /** \endcond */
+
+ /** \ref Endian "[LE]" The extended 64-bit address of the responder device. */
+ ExtAddr_t responderAddress;
+ /** This parameter indicates if the responder's parent shall be used to
+ * forward messages between the initiator and responder devices:
+ * \li TRUE - Use parent,
+ * \li FALSE - Do not use parent.
+ **/
+ bool useParent;
+ /** \ref Endian "[LE]"
+ * If \c useParent is TRUE, then the \c responderParentAddress parameter shall
+ * contain the extended 64-bit address of the responder’s parent device.
+ * Otherwise, this parameter is not used and need not to be set. */
+ ExtAddr_t responderParentAddress;
+ /** Requested key-establishment method. The valid value is SKKE. */
+ APS_KeyEstablishmentMethod_t keyEstablishmentMethod;
+ /** Parameters that will be passed to the confirmation callback in the argument */
+ APS_EstablishKeyConf_t confirm;
+ /** Confirmation callback function */
+ void (*APS_EstablishKeyConf)(APS_EstablishKeyConf_t *conf);
+} APS_EstablishKeyReq_t;
+
+/**//**
+ * \struct APS_EstablishKeyInd_t apsmeEstablishKey.h "aps.h"
+ *
+ * \brief Parameters of APSME-KEY-ESTABLISH.indication.
+ * See ZigBee Specification r19, Table 4.7, page 444.
+ **/
+typedef struct
+{
+ /** \ref Endian "[LE]" The extended 64-bit address of the initiator device. */
+ ExtAddr_t initiatorAddress;
+ /** The requested key-establishment method shall be SKKE. */
+ APS_KeyEstablishmentMethod_t keyEstablishmentMethod;
+ /** Data field from received SKKE-1 command frame. */
+ uint8_t qeu[CHALLENGE_SEQUENCE_SIZE];
+ /** An initial Establish Key command is received from parent or not. */
+ bool fromParent;
+} APS_EstablishKeyInd_t;
+
+/**//**
+ * \struct APS_EstablishKeyResp_t apsmeEstablishKey.h "aps.h"
+ *
+ * \brief Parameters of APSME-KEY-ESTABLISH.response.
+ * See ZigBee Specification r19, Table 4.8, page 445.
+ **/
+typedef struct
+{
+ /** \cond SERVICE_FIELDS */
+ struct
+ {
+ ApsSkkeElem_t elem; /*!< Common substructure of SKKE request. */
+ ShortAddr_t dstShortAddr; /*!< Short address of SKKE initiator. */
+ /** Parameters of request for calculation of link key by master key. */
+ SSP_CalculateSkkeParamsReq_t sspReq;
+ /** Request to allocate memory for SKKE command in NWK layer. */
+ NWK_AllocDataReq_t allocNwkDataReq;
+ /** Saved pointer to NWK_DataReq_t structure for SKKE-2 command frame. */
+ NWK_DataReq_t *skke2NwkDataReq;
+ /** Saved pointer to NWK_DataReq_t structure for SKKE-4 command frame. */
+ NWK_DataReq_t *skke4NwkDataReq;
+ } service;
+ /** \endcond */
+
+ /** \ref Endian "[LE]" The extended 64-bit address of the device
+ * that initiated key establishment. */
+ ExtAddr_t initiatorAddress;
+ /** This parameter indicates the response to an initiator's request to
+ * execute a keyestablishment protocol. The response shall be either:
+ * \li TRUE = Accept,
+ * \li FALSE = Reject.
+ **/
+ bool accept;
+ /** This parameter indicates if the responder's parent shall be used to
+ * forward messages between the initiator and responder devices:
+ * \li TRUE - Use parent,
+ * \li FALSE - Do not use parent.
+ **/
+ bool useParent;
+ /** Data field from received SKKE-1 command frame. */
+ uint8_t qeu[CHALLENGE_SEQUENCE_SIZE];
+ /** Confirm primitive as a parameter of the callback function. */
+ APS_EstablishKeyConf_t confirm;
+ /** Callback function pointer as a handler of corresponding
+ * confirm primitive. */
+ void (*APS_EstablishKeyConf)(APS_EstablishKeyConf_t *conf);
+} APS_EstablishKeyResp_t;
+
+/******************************************************************************
+ Prototypes section
+ ******************************************************************************/
+#if defined _HI_SECURITY_
+/**************************************************************************//**
+ \brief Initiates the key establishment procedure
+
+ The function is used in high security to initiate a link key
+ establishment procedure (currently, SKKE) between two device. The procedure requires
+ the master key, which must be known on both devices (set via the APS_SetMasterKey()
+ function). The stack uses this procedure during device authentication on the
+ trust center, while the application may use it to establish application link
+ keys between two common devices.
+
+ If the function is used to establish an application link key, set the
+ \c useParent field to \c false and do not specify \c responderParentAddress.
+
+ Currently only SKKE protocol is supported, and so set \c keyEstablishmentMethod
+ to ::APS_SKKE_KEY_ESTABLISHMENT_METHOD.
+
+ The function conforms to APSME-ESTABLISH-KEY.request primitive.
+ See ZigBee Specification r19, 4.4.2.1, page 441.
+
+ \param[in] req - pointer to request parameters of the APS_EstablishKeyReq_t type
+
+ \return None
+ ******************************************************************************/
+void APS_EstablishKeyReq(APS_EstablishKeyReq_t *const req);
+
+/**************************************************************************//**
+ \brief Informs the upper layer when APS receives an initial
+ key-establishment message
+
+ The APS layer on the responder device calls this function informing the ZDO layer
+ when a request to start the key-establishment procedure (for example, an SKKE-1
+ frame) is received from the initiator device and the master key associated with
+ the initiator is present in the APS Key-pair set.
+
+ The function conforms to APSME-ESTABLISH-KEY.indication primitive.
+ See ZigBee Specification r19, 4.4.2.3, page 444.
+
+ \param[in] ind - pointer to parameters of the APS_EstablishKeyInd_t type
+
+ \return None
+ ******************************************************************************/
+void APS_EstablishKeyInd(APS_EstablishKeyInd_t *ind);
+
+/**************************************************************************//**
+ \brief The responder device calls this function to respond
+ to an APSME-ESTABLISH-KEY.indication primitive.
+
+ The ZDO layer calls this function to inform APS following a request from the
+ initiator device to start the key-establishment procedure. The function provides
+ the responder's ZDO with an opportunity to determine whether to accept or reject
+ the request to establish the key with a given initiator.
+
+ The function conforms to APSME-ESTABLISH-KEY.response primitive.
+ See ZigBee Specification r19, 4.4.2.4, page 444.
+
+ \param[in] resp - pointer to parameters of the APS_EstablishKeyResp_t type
+
+ \return None
+ ******************************************************************************/
+void APS_EstablishKeyResp(APS_EstablishKeyResp_t *const resp);
+
+#endif /* _HI_SECURITY_ */
+
+#endif /* _SECURITY_ and _LINK_SECURITY_ */
+
+#endif /* _APSME_ESTABLISH_KEY_H */
+/** eof apsmeEstablishKey.h */
+