summaryrefslogtreecommitdiffhomepage
path: root/digital/zigbit/bitcloud/stack/Components/NWK/include/nwkSecurity.h
blob: d06fa66a6af5e4f3bcbd9294f29b0069c7ec004d (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
/**************************************************************************//**
  \file nwkSecurity.h

  \brief Network security interface.

  \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:
    2009-04-13 Max Gekk - Created.
    2009-08-15 Max Gekk - Refactoring.
    2011-01-29 Max Gekk - Redesign.
   Last change:
    $Id: nwkSecurity.h 18245 2011-08-16 09:23:15Z arazinkov $
 ******************************************************************************/
/**//**
 *  The NWK layer is responsible for the processing steps needed to securely
 * transmit outgoing frames and securely receive incoming frames. Upper layers
 * control the security processing operations by setting up the appropriate keys
 * and frame counters and establishing which security level to use.
 * ZigBee spec r17, 4.3, page 426.
 **/
#if !defined _NWK_SECURITY_H && defined _SECURITY_
#define _NWK_SECURITY_H
/******************************************************************************
                                Includes section
 ******************************************************************************/
#include <sspCommon.h>
#include <mac.h>
#include <nlmeReset.h>

/******************************************************************************
                                Define(s) section
 ******************************************************************************/
#define NWK_PRECONFIGURED_NETWORK_KEY 0U
#define NWK_NOT_PRECONFIGURED_NETWORK_KEY 3U

/** Amount of incoming frame counters. */
#define NWK_IN_FRAMES_MAX 4U
/** Startup active network key sequence number */
#define NWK_STARTUP_ACTIVE_KEY_SEQUENCE_NUMBER 0U
/** Size of security counter in bytes */
#define NWK_SIZE_OF_SECURITY_COUNTER 4U

/******************************************************************************
                                 Types section
 ******************************************************************************/
/** Type of NWK Key Sequence Number. */
typedef uint8_t NWK_KeySeqNum_t;
/** Type of NWK Key Index and amount. */
typedef uint8_t NwkKeyAmount_t;
typedef NwkKeyAmount_t NwkKeyIndex_t;

/** Type of outgoing frame counter used for outgoing frames. */
typedef uint32_t NwkOutFrameCounter_t;
/** Type of incoming frame counter used for incoming frames. */
typedef uint32_t NwkInFrameCounter_t;
/** Type of outgoing frame counter higher bytes. */
typedef uint16_t NwkOutFrameCounterTop_t;
/** Type of outgoing frame counter lower bytes. */
typedef uint16_t NwkOutFrameCounterLow_t;

/** Outgoing security frame counter handle type. */
BEGIN_PACK
typedef union PACK
{
  NwkOutFrameCounter_t value;
  struct
  {
    LITTLE_ENDIAN_OCTET(2,
      (NwkOutFrameCounterLow_t low,
       NwkOutFrameCounterTop_t top
      ))
  } part;
} NwkOutFrameCounterHandle_t;
END_PACK

BEGIN_PACK
typedef union PACK _NwkUnalignedInFrameCounter_t
{
  NwkInFrameCounter_t value;
  uint8_t raw[sizeof(NwkInFrameCounter_t)];
} NwkUnalignedInFrameCounter_t;
END_PACK

/** The Incoming Frame Counter Descriptor. */
typedef struct _NWK_InFrameCounterSet_t
{
  bool isSet; /** Flag indicates busy status of entry. */
  /** Extended device address. */
  ExtAddr_t senderAddress;
  /** Incoming frame counter used for incoming frames. */
  NwkInFrameCounter_t value;
} NWK_InFrameCounterSet_t;

/** The Network Security Material Descriptor - key and key sequence number. */
typedef struct _NWK_SecurityKey_t
{
  bool isSet; /** Flag indicates busy status of entry. */

  /** 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. */
  NWK_KeySeqNum_t seqNum;
  /** Outgoing frame counter higher bytes. */
  NwkOutFrameCounterTop_t outCounterTop;
  /** The actual value of the key. */
  uint8_t value[SECURITY_KEY_SIZE];
} NWK_SecurityKey_t;

/** The Network Mutable Security Material Descriptor - incoming and outgoing
 * frame counters. */
typedef struct _NWK_SecurityFrameCounters_t
{
  /** Outgoing frame counter lower bytes. */
  NwkOutFrameCounterLow_t outCounterLow;
  /** Set of incoming frame counter values and corresponding device addresses. */
  /* NWK_InFrameCounterSet_t inCounters[NWK_IN_FRAMES_MAX]; */
} NWK_SecurityFrameCounters_t;

/** Security-Related NIB Attributes. */
typedef struct _NWK_SecurityIB_t
{
  /** Private field for internal use - the index of active key. */
  NwkKeyIndex_t activeIndex;
  /** The security level for outgoing and incoming NWK frames. */
  uint8_t securityLevel;
  /** Indicates whether security shall be applied to incoming
   * and outgoing NWK data frames. */
  bool secureAllFrames;
  /** Total amount of NWK security keys. */
  NwkKeyAmount_t keyAmount;
  /** Set of network security material descriptors capable of maintaining
   * an active and alternate network key. */
  NWK_SecurityKey_t *key;
  /** Pointer to set of security incoming and outgoing key frame counters.*/
  NWK_SecurityFrameCounters_t *counter;
} NWK_SecurityIB_t;

/******************************************************************************
                               Prototypes section
 ******************************************************************************/
/**************************************************************************//**
  \brief Get value of the nwkSecurityLevel attribute.

    ZigBee spec r17, page 344, Table 3.44.

  \return Current value of nwkSecurityLevel.
 ******************************************************************************/
uint8_t NWK_GetSecurityLevel(void);

/**************************************************************************//**
  \brief Getting value of nwkSecureAllFrames attribute.
    ZigBee spec r17, page 344, Table 3.44.

  \return Current value of nwkSecureAllFrames.
 ******************************************************************************/
bool NWK_GetSecureAllFrames(void);

/**************************************************************************//**
  \brief Set a new network key.

  \param[in] key - a new network security key.
  \param[in] keySeqNum - key sequence number.
  \return 'true' if operation was completed successfully otherwise 'false'.
 ******************************************************************************/
bool NWK_SetKey(const uint8_t *const key, const NWK_KeySeqNum_t keySeqNum);

/**************************************************************************//**
  \brief Set NWK key as active.

  \param[in] keySeqNum - key sequence number.
  \return 'true' if operation was completed successfully otherwise 'false'.
 ******************************************************************************/
bool NWK_ActivateKey(const NWK_KeySeqNum_t keySeqNum);

/**************************************************************************//**
  \brief Check active network key.

  \return 'true' if active NWK key is set otherwise 'false'.
 ******************************************************************************/
bool NWK_IsAnyKeyActivated(void);

/**************************************************************************//**
  \brief Get active network key.

  \return Pointer to value of active network key.
 ******************************************************************************/
const uint8_t* NWK_GetActiveKey(void);

/**************************************************************************//**
  \brief Getting value of nwkActiveKeySeqNumber attribute.
     ZigBee spec r17, page 344, Table 3.44.

  \return Current value of nwkActiveKeySeqNumber.
 ******************************************************************************/
NWK_KeySeqNum_t NWK_GetActiveKeySeqNumber(void);

/**************************************************************************//**
  \brief Update outgoing security frame counter of active NWK key and return
         it's value.

  \return Outgoing frame counter in little-endian format.
 ******************************************************************************/
NwkOutFrameCounter_t NWK_GetUpdatedSecOutCounter(void);

/**************************************************************************//**
  \brief Return outgoing security frame counter value of active NWK key

  \return Outgoing frame counter in little-endian format.
 ******************************************************************************/
NwkOutFrameCounter_t NWK_GetSecOutCounter(void);

/**************************************************************************//**
  \brief Update the incoming frame counter.

  \param[in] srcExtAddr - an extended source address.
  \param[in] newValue - a new value of the incoming frame counter.
  \return None.
 ******************************************************************************/
void NWK_SetInFrameCounter(const ExtAddr_t srcExtAddr,
  const NwkInFrameCounter_t counter);

/**************************************************************************//**
  \brief Deactivate current active NWK key.
 ******************************************************************************/
void NWK_DeactivateKey(void);

/**************************************************************************//**
  \brief Set all incoming and outgoing frame counters to zero.
 ******************************************************************************/
void NWK_ResetAllSecurityCounters(void);

/**************************************************************************//**
  \brief Reseting the network security subsystem.

  \param[in] powerFailureControl - stack restoring after power failure control bitfield;
                                  affects on initialization procedure.
  \return None.
 ******************************************************************************/
void NWK_ResetSecurityIB(const NWK_PowerFailureControl_t powerFailureControl);

/**************************************************************************//**
  \brief Checks, if security services are provided by NWK.

  \return True, if security services are provided by NWK, false - otherwise.
 ******************************************************************************/
bool NWK_IsSecurityProvided(void);

#if defined _CERTIFICATION_
/**************************************************************************//**
  \brief Changes the maximum number of stored NWK security keys.

  \param[in] keyAmount - new total amount of NWK keys.

  \return NWK_SUCCESS_STATUS if keyAmount is changed successfuly otherwise
          return NWK_INVALID_PARAMETERS_STATUS.
 ******************************************************************************/
NWK_Status_t NWK_SetKeyAmount(const uint8_t keyAmount);
#endif /* _CERTIFICATION_ */

#endif /* _NWK_SECURITY_H and _SECURITY_ */
/** eof nwkSecurity.h */