summaryrefslogtreecommitdiff
path: root/digital/zigbit/bitcloud/stack/Components/APS/include/apsmeEstablishKey.h
blob: 2065dc72337c3a2419b0dcd8ec2599ab756fb238 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
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 */