summaryrefslogtreecommitdiffhomepage
path: root/digital/beacon/src/Bitcloud_stack/Components/APS/include/apsmeTransportKey.h
blob: 2c50ab5f41dde240fbc7c2567a092f122f474ee6 (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
/**************************************************************************//**
  \file apsmeTransportKey.h

  \brief Interface of APS Transport-Key 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: apsmeTransportKey.h 17946 2011-07-13 09:26:59Z mgekk $
 ******************************************************************************/
#if !defined _APSME_TRANSPORT_KEY_H
#define _APSME_TRANSPORT_KEY_H
/**//**
 *
 *  The APS-layer provides this services that allow an initiator to transport
 * keying material to a responder. The different types of keying material that
 * can be transported are shown in Tables 4.12 to 4.15 of ZigBee Spec. r19.
 *
 **/

/******************************************************************************
                               Includes section
 ******************************************************************************/
#include <apsCommon.h>
#if defined _SECURITY_
#include <sspCommon.h>

/******************************************************************************
                                Types section
 ******************************************************************************/
/**//**
 * \brief KeyType Parameter of the Transport-Key Primitive.
 *  See ZigBee Specification r19, Table 4.12, page 452.
 **/
typedef enum
{
  /** Indicates the key is a master key used to set up link keys between
   * the Trust Center and another device. */
  APS_TRUST_CENTER_MASTER_KEY_TYPE   = 0x00,
  /** Indicates that the key is a network key to be used in standard security
   * mode and may be distributed using key-transport or a standard network key.
   **/
  APS_STANDARD_NETWORK_KEY_TYPE      = 0x01,
  /** Indicates the key is a master key used to set up link keys between
   * two devices. */
  APS_APP_MASTER_KEY_TYPE            = 0x02,
  /** Indicates the key is a link key used as a basis of security between
   * two devices. */
  APS_APP_LINK_KEY_TYPE              = 0x03,
  /** Indicates that the key is a link key used as a basis for security
   * between the Trust Center and another device. */
  APS_TRUST_CENTER_LINK_KEY_TYPE     = 0x04,
  /** Indicates that the key is a network key to be used in high security
   * mode and may be distributed using key-transport only. */
  APS_HIGH_SECURITY_NETWORK_KEY_TYPE = 0x05
} APS_TransportKeyType_t;

/**//**
 * \brief TransportKeyData Parameter for a Trust Center Master Key or Link Key
 *  See ZigBee Specification r19, Table 4.13, page 453.
 **/
typedef struct
{
  /** \ref Endian "[LE]" The extended 64-bit address of the parent of
   * the destination device given by the DestAddress parameter. */
  ExtAddr_t parentAddress;
  /** The Trust Center master or link key. */
  uint8_t key[SECURITY_KEY_SIZE];
} APS_ReqTrustCenterMasterOrLinkKeyTransportData_t;

/**//**
 * \brief TransportKeyData Parameter for a Network Key.
 *  See ZigBee Specification r19, Table 4.14, page 453.
 **/
typedef struct
{
  /** A sequence number assigned to a network key by the Trust Center and used
   * to distinguish network keys for purposes of key updates and incoming
   * frame security operations. */
  uint8_t keySeqNumber;
  uint8_t networkKey[SECURITY_KEY_SIZE];
  /** This parameter indicates if the destination device's parent shall be
   * used to forward the key to the destination device:
   * \li TRUE = Use parent,
   * \li FALSE = Do not use parent. */
  bool useParent;
  /** \ref Endian "[LE]" If the UseParent is TRUE, then ParentAddress parameter
   * shall contain the extended 64-bit address of the destination device’s
   * parent device; otherwise, this parameter is not used and need not be set.*/
  ExtAddr_t parentAddress;
  /** Use tunneling for transport NWK key. */
  bool tunneling;
} APS_ReqNetworkKeyTransportData_t;

/**//**
 * \brief TransportKeyData Parameter for an Application Master or Link Key.
 *  See ZigBee Specification r19, Table 4.15, page 454.
 **/
typedef struct
{
  /** \ref Endian "[LE]" The extended 64-bit address of the device that was also
   * sent this master key. */
  ExtAddr_t partnerAddress;
  /** This parameter indicates if the destination device of this master
   * key requested it:
   * \li TRUE = If the destination requested the key,
   * \li FALSE = Otherwise. */
  bool initiator;
  /** The master or link key (as indicated by the KeyType parameter). */
  uint8_t key[SECURITY_KEY_SIZE];
} APS_ReqApplicationMasterOrLinkKeyTransportData_t;

typedef union
{
  APS_ReqTrustCenterMasterOrLinkKeyTransportData_t trustCenterKey;
  APS_ReqNetworkKeyTransportData_t networkKey;
  APS_ReqApplicationMasterOrLinkKeyTransportData_t applicationKey;
} APS_ReqTransportKeyData_t;

/** Status of creating and sending a transport key command frame. */
typedef enum
{
  APS_TRANSPORT_KEY_SUCCESS_STATUS = 0x00,
  APS_TRANSPORT_KEY_NO_SHORT_ADDRESS_STATUS = 0x01,
  APS_TRANSPORT_KEY_SECURITY_FAIL_STATUS = 0x02,
  APS_TRANSPORT_KEY_NOT_SENT_STATUS = 0x03,
  APS_TRANSPORT_KEY_INVALID_PARAMETER_STATUS = 0x04,
  /* These names are deprecated and will be removed. */
  APS_TKR_SUCCESS_STATUS          = APS_TRANSPORT_KEY_SUCCESS_STATUS,
  APS_TKR_NO_SHORT_ADDRESS_STATUS = APS_TRANSPORT_KEY_NO_SHORT_ADDRESS_STATUS,
  APS_TKR_SECURITY_FAIL_STATUS    = APS_TRANSPORT_KEY_SECURITY_FAIL_STATUS,
  APS_TKR_NOT_SENT_STATUS         = APS_TRANSPORT_KEY_NOT_SENT_STATUS
} APS_TkrStatus_t;

/**//**
 * \struct APS_TransportKeyConf_t apsmeTransportKey.h "aps.h"
 *
 * \brief Confirmation parameters of APSME-TRANSPORT-KEY.request.
 **/
typedef struct
{
  APS_TkrStatus_t status;
} APS_TransportKeyConf_t;

/**//**
 * \struct APS_TransportKeyReq_t apsmeTransportKey.h "aps.h"
 *
 * \brief Parameters of APSME-TRANSPORT-KEY.request primitive.
 *  See ZigBee Specification r19, 4.4.3.1, page 451.
 **/
typedef struct
{
  /** \cond SERVICE_FIELDS **/
  struct
  {
    ApsCommandReq_t commandReq;
    /** Global internal state of APS Transport Key component. */
    enum
    {
      APS_TRANSPORT_KEY_BEGIN_STATE,
      APS_TRANSPORT_KEY_CONFIRM_STATE,
      APS_TRANSPORT_KEY_PROCESS_STATE
    } state;
  } service;
  /** \endcond **/

  /** \ref Endian "[LE]"
   * The extended 64-bit address of the destination device.*/
  ExtAddr_t destAddress;
  /** Identifies the type of key material that should be transported;
   * See ZigBee Specification r19, Table 4.12, page 452. */
  APS_TransportKeyType_t keyType;
  /** The key being transported along with identification
   * and usage parameters. */
  APS_ReqTransportKeyData_t transportKeyData;
  /** Confirm primitive as a parameter of the callback function. */
  APS_TransportKeyConf_t confirm;
  /** Callback function pointer as a handler of corresponding
   * confirm primitive. */
  void (*APS_TransportKeyConf)(APS_TransportKeyConf_t *conf);
} APS_TransportKeyReq_t;

/**//**
 * \brief TransportKeyData Parameter for a Trust Center Master or Link Key.
 *  See ZigBee Specification r19, Table 4.17, page 457.
 **/
typedef struct
{
  uint8_t trustCenterMasterKey[SECURITY_KEY_SIZE];
} APS_IndTrustCenterMasterOrLinkKeyTransportData_t;

/**//**
 * \brief TransportKeyData Parameter for a Network Key.
 *  See ZigBee Specification r19, Table 4.18, page 457.
 **/
typedef struct
{
  /** A sequence number assigned to a network key by the Trust Center and
   * used to distinguish. */
  uint8_t keySeqNumber;
  uint8_t networkKey[SECURITY_KEY_SIZE];
} APS_IndNetworkKeyTransportData_t;

/**//**
 * \brief TransportKeyData Parameter for an Application Master or Link Key.
 *  See ZigBee Specification r19, Table 4.19, page 457.
 **/
typedef struct
{
  /** This parameter indicates this device was initiator or not. */
  bool initiatorFlag;
  /** \ref Endian "[LE]" The extended 64-bit address of the device that was also
   * sent this master key. */
  ExtAddr_t partnerAddress;
  /** The master or link key (as indicated by the KeyType
   * parameter). \sa APS_TransportKeyInd_t */
  uint8_t key[SECURITY_KEY_SIZE];
} APS_IndApplicationMasterOrLinkKeyTransportData_t;

typedef union
{
  APS_IndTrustCenterMasterOrLinkKeyTransportData_t trustCenterKey;
  APS_IndNetworkKeyTransportData_t networkKey;
  APS_IndApplicationMasterOrLinkKeyTransportData_t applicationKey;
} APS_IndTransportKeyData_t;

//\cond internal
/**//**
 * \struct APS_TransportKeyInd_t apsmeTransportKey.h "aps.h"
 *
 * \brief Parameters of APSME-TRANSPORT-KEY.indication primitive.
 *  See ZigBee Specification r19, 4.4.3.2, page 455.
 **/
typedef struct
{
  /** \ref Endian "[LE]" The extended 64-bit address of the device
   * that is the original source of the transported key. */
  ExtAddr_t srcAddress;
  /** Identifies the type of key material that was be transported;
   * See Table 4.12 of ZigBee Specification r19. */
  APS_TransportKeyType_t keyType;
  /** The key that was transported along with identification and usage
   * parameters. The type of this parameter depends on the KeyType
   * parameter. */
  APS_IndTransportKeyData_t transportKeyData;
  /* Type of key with the transport key command was secured. */
  APS_Status_t securedWith;
} APS_TransportKeyInd_t;
//\endcond

/******************************************************************************
                              Prototypes section
 ******************************************************************************/
/**************************************************************************//**
  \brief Transfers a security key to a specified node

    The function is used by the stack on the trust center to transfer security
  keys during authentication procedures and upon receiving requests for a link
  key. The application can also use it, for example, to distribute a new network
  key. The function conforms to ZigBee Specification r19, 4.4.3.1, page 451.

  \param[in] req - a pointer to request parameters of type APS_TransportKeyReq_t

  \return None.
 ******************************************************************************/
void APS_TransportKeyReq(APS_TransportKeyReq_t *const req);

/**************************************************************************//**
  \cond internal
  \brief Informs ZDO of security key reception

    See ZigBee Specification r19, 4.4.3.2, page 455.

  \param[in] ind - pointer to APSME-TRANSPORT-KEY.indication's parameters.

  \return None
  \endcond
 ******************************************************************************/
void APS_TransportKeyInd(APS_TransportKeyInd_t *ind);

#endif /* _SECURITY_ */
#endif /* _APSME_TRANSPORT_KEY_H */
/** eof apsmeTransportKey.h */