summaryrefslogtreecommitdiff
path: root/digital/zigbit/bitcloud/stack/Components/APS/include/apsmeRequestKey.h
blob: fbb55e1c5582aa9e630090723780d210ee3f3db6 (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
/**************************************************************************//**
  \file apsmeRequestKey.h

  \brief Interface of APS Request Key Service.

  \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: apsmeRequestKey.h 18914 2011-10-18 09:13:36Z mgekk $
 ******************************************************************************/
#if !defined _APSME_REQUEST_KEY_H
#define _APSME_REQUEST_KEY_H
/**//**
 *
 *  The APSME provides services that allow a device to request the active
 * network key or a master key from another device (for example, its Trust
 * Center). See ZigBee Specification r19, 4.4.6, page 465.
 *
 **/

/******************************************************************************
                               Includes section
 ******************************************************************************/
#include <apsCommon.h>

#if defined _SECURITY_ && defined _LINK_SECURITY_
/******************************************************************************
                                Types section
 ******************************************************************************/
/**//**
 * The type of key being requested:
 *  \li Network (0x01) and Application (0x02) key,
 *  \li Trust Center Link Key (0x04 - it's not supported),
 *  \li 0x00 and 0x03-0xFF = Reserved.
 **/
typedef enum
{
  APS_NETWORK_KEY_TYPE = 0x01,
  APS_APP_KEY_TYPE     = 0x02,
  APS_TC_LINK_KEY_TYPE = 0x04
} APS_RequestKeyType_t;

/** Status of creating and sending a request key command frame. */
typedef enum
{
  APS_REQUEST_KEY_SUCCESS_STATUS  = 0x00,
  APS_REQUEST_KEY_NO_SHORT_ADDRESS_STATUS = 0x01,
  APS_REQUEST_KEY_SECURITY_FAIL_STATUS = 0x02,
  APS_REQUEST_KEY_NOT_SENT_STATUS = 0x03,
  APS_REQUEST_KEY_TIMEOUT_STATUS  = 0x04,
  /* These names are deprecated and will be removed. */
  APS_RKR_SUCCESS_STATUS          = APS_REQUEST_KEY_SUCCESS_STATUS,
  APS_RKR_NO_SHORT_ADDRESS_STATUS = APS_REQUEST_KEY_NO_SHORT_ADDRESS_STATUS,
  APS_RKR_SECURITY_FAIL_STATUS    = APS_REQUEST_KEY_SECURITY_FAIL_STATUS,
  APS_RKR_NOT_SENT_STATUS         = APS_REQUEST_KEY_NOT_SENT_STATUS,
  APS_RKR_TIMEOUT                 = APS_REQUEST_KEY_TIMEOUT_STATUS
} APS_RequestKeyStatus_t;

/** This type is deprecated and will be removed. */
typedef APS_RequestKeyStatus_t APS_RkrStatus_t;

/**//**
 * \struct APS_RequestKeyConf_t apsmeRequestKey.h "aps.h"
 *
 * \brief Parameters of APSME-REQUEST-KEY.confirm primitive.
 **/
typedef struct
{
  APS_RequestKeyStatus_t status; /*!< \sa APS_RequestKeyStatus_t */
} APS_RequestKeyConf_t;

/**//**
 * \struct APS_RequestKeyReq_t apsmeRequestKey.h "aps.h"
 *
 * \brief Parameters of APSME-REQUEST-KEY.request primitive.
 *
 *  See ZigBee Specification r19, Table 4.24, page 465.
 **/
typedef struct
{
  /** \cond SERVICE_FIELDS **/
  struct
  {
    /** Service field, used for queue support */
    QueueElement_t qelem;
    /** Request to send APS Update Device command. */
    ApsCommandReq_t commandReq;
    uint32_t ttl;
    bool transportKeyReceived;
    bool requestKeySent;
  } service;
  /** \endcond **/

  /** \ref Endian "[LE]" The extended 64-bit address of the device to which
   * the request-key command should be sent. */
  ExtAddr_t destAddress;
  /** The type of key being requested:
   * \li 0x01 = Network key,
   * \li 0x02 = Application key,
   * \li 0x04 = Trust Center Link Key. */
  APS_RequestKeyType_t keyType;
  /** \ref Endian "[LE]" If the KeyType parameter indicates an application key,
   * this parameter shall indicate an extended 64-bit address of a device that
   * shall receive the same key as the device requesting the key. */
  ExtAddr_t partnerAddress;
  /** Canfirmation parameters. \sa APS_RequestKeyConf_t */
  APS_RequestKeyConf_t confirm;
  /** Callback function pointer as a handler of corresponding
   * confirm primitive. */
  void (*APS_RequestKeyConf)(APS_RequestKeyConf_t *conf);
} APS_RequestKeyReq_t;

/**//**
 * \struct APS_RequestKeyInd_t apsmeRequestKey.h "aps.h"
 *
 * \brief Parameters of APSME-REQUEST-KEY.indication primitive.
 *
 *  See ZigBee Specification r19, Table 4.25, page 466.
 **/
typedef struct
{
  /** \ref Endian "[LE]" The extended 64-bit address of the device that sent
   * the request-key command. */
  ExtAddr_t srcAddress;
  /** The type of key being requested. Valid values:
   * \li APS_NETWORK_KEY_TYPE
   * \li APS_APP_KEY_TYPE
   **/
  APS_RequestKeyType_t keyType;
  /** \ref Endian "[LE]" If the KeyType parameter indicates an application key,
   * this parameter shall indicate an extended 64-bit address of a device that
   * shall receive the same key as the device requesting the key. */
  ExtAddr_t partnerAddress;
} APS_RequestKeyInd_t;

/******************************************************************************
                              Prototypes section
 ******************************************************************************/
/**************************************************************************//**
  \brief Request either the active network key or a new application link key

     See ZigBee Specification r19, 4.4.6.1, page 465.

  \param[in] req - pointer to APSME-REQUEST-KEY.request's parameters.
                   \sa APS_RequestKeyReq_t
  \return None.
 ******************************************************************************/
void APS_RequestKeyReq(APS_RequestKeyReq_t *req);

/**************************************************************************//**
  \brief Generate this primitive when APS receives a request-key command frame

  Upon receipt of the APSME-REQUEST-KEY.indication primitive, the ZDO shall
  be informed that the device referenced by the SrcAddress parameter is
  requesting a key. See ZigBee Specification r19, 4.4.6.2, page 466.

  \param[in] indParams - pointer to APSME-REQUEST-KEY.indication's parameters.
                   \sa APS_RequestKeyInd_t
  \return None.
 ******************************************************************************/
void APS_RequestKeyInd(APS_RequestKeyInd_t *indParams);

#endif /* _SECURITY_ and _LINK_SECURITY_ */

#endif /* _APSME_REQUEST_KEY_H */
/** eof apsmeRequestKey.h */