summaryrefslogtreecommitdiff
path: root/cp2/sta/action/action.h
blob: a390fa34357e5efda26fb7ac794b7c0cbba56953 (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
#ifndef cp_sta_action_action_h
#define cp_sta_action_action_h
/* Cesar project {{{
 *
 * Copyright (C) 2008 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    cp/sta/action/action.h
 * \brief   STA action.
 * \ingroup cp_sta
 *
 * This module implements actions defined in the FSM and actions corresponding
 * to MME reception.
 */

BEGIN_DECLS

/**
 * Process a CC_WHO_RU.REQ, 11.2.26.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  nid  NID of network being queried
 *
 * Provide AVLN identity and CCo MAC address.  If the NID correspond to our
 * NID, send a CC_WHO_RU.CNF.  In other cases, drop.
 *
 * Need:
 *  - our CCo MAC address.
 *  - our AVLN HFID.
 */
void
cp_sta_action_process_cc_who_ru_req (cp_t *ctx, cp_mme_t *mme, cp_nid_t nid);

/**
 * Process a CC_ASSOC.CNF, 11.2.29.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  result  association result
 * \param  nid  NID of the sender network
 * \param  snid  SNID of the sender network
 * \param  tei  new TEI to use, valid if association is successful
 * \param  lease_time_min  period of time of TEI validity
 *
 * Confirmation from the CCo on association request.  If this does not
 * correspond to a previously sent request, drop.  If the CCo accepted our
 * association, update TEI and lease time.  Post an event according to
 * association result.
 *
 * Need:
 *  - whether a association is pending and its characteristics.
 *
 * Update:
 *  - our TEI.
 *  - our TEI lease time (update lease timer).
 */
void
cp_sta_action_process_cc_assoc_cnf (cp_t *ctx, cp_mme_t *mme,
                                    cp_msg_cc_assoc_cnf_result_t result,
                                    cp_nid_t nid, cp_snid_t snid,
                                    cp_tei_t tei, uint lease_time_min);

/**
 * Process a CC_LEAVE.CNF, 11.2.31.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 *
 * Confirmation from the CCo on leave request.  If this does not correspond to
 * a previously sent request, drop.  Else, post an event to leave the AVLN.
 *
 * Need:
 *  - whether a leave is pending and its characteristics.
 */
void
cp_sta_action_process_cc_leave_cnf (cp_t *ctx, cp_mme_t *mme);

/**
 * Process a CC_LEAVE.IND, 11.2.32.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  reason  reason for the disassociation
 * \param  nid  NID
 *
 * The CCo ask us to leave the AVLN.  Send a CC_LEAVE.RSP, and post an event
 * to leave the AVLN.
 *
 * Need:
 *  - our AVLN NID (to check message).
 */
void
cp_sta_action_process_cc_leave_ind (cp_t *ctx, cp_mme_t *mme,
                                    cp_msg_cc_leave_ind_reason_t reason,
                                    nid_t nid);

/**
 * Process a CC_SET_TEI_MAP.IND, 11.2.35.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  mode  update, add or remove
 *
 * The CCo send an update of the AVLN list of STA.  According to the mode,
 * update the whole list, add or remove a STA.
 *
 * Need:
 *  - use a cp_msg function to read the rest of the message.
 *
 * Update:
 *  - STA mgr.
 */
void
cp_sta_action_process_cc_set_tei_map_ind_update (
    cp_t *ctx, cp_mme_t *mme, cp_msg_cc_set_tei_map_ind_mode_t mode);

/**
 * Process a CC_RELAY.REQ, 11.2.36.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  fda  final destination address
 * \param  ftei  final destination TEI
 * \param  len  payload size
 *
 * Extract the payload from the MME, and encapsulate it in a CC_RELAY.IND to
 * the final destination.
 *
 * There is special behaviour depending on the contained payload.  If the
 * relay request is not encrypted, only relay MME which are permitted to be
 * unencrypted.  If the relay request is not encrypted and contains a
 * CM_ENCRYPTED_PAYLOAD.IND, the CC_RELAY.IND should be sent broadcast. This
 * could be done by the cp_msg module.
 *
 * - What to do with the MAC address?
 */
void
cp_sta_action_process_cc_relay_req (cp_t *ctx, cp_mme_t *mme, mac_t fda,
                                    cp_tei_t ftei, uint len);

/**
 * Process a CC_RELAY.IND, 11.2.37.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  osa  original source address
 * \param  otei  original source TEI
 * \param  len  payload size
 *
 * Extract the payload and insert the message back.
 *
 * Relay station is trusted as long as it is authenticated.  It should have
 * filtered unauthorised payload.
 */
void
cp_sta_action_process_cc_relay_ind (cp_t *ctx, cp_mme_t *mme, mac_t osa,
                                    cp_tei_t otei, uint len);

/**
 * Process a CM_UNASSOCIATED_STA.IND, 11.5.1.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  nid  NID the STA try to associate with
 * \param  cco_cap  CCo capabilities of the sending STA
 *
 * Update the STA list and if should become CCo, post an event to do so.
 *
 * Need:
 *  - our NID
 *
 * Update:
 *  - STA mgr.
 */
void
cp_sta_action_process_cm_unassociated_sta_ind (cp_t *ctx, cp_mme_t *mme,
                                               cp_nid_t nid,
                                               cp_cco_cap_t cco_cap);

/**
 * Process a CM_SET_KEY.REQ, 11.5.4.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  key_type  key type being set
 * \param  my_nounce  to be used in next message
 * \param  your_nounce  used in previous message
 * \param  pid  protocol identifier
 * \param  prn  protocol run number
 * \param  pmn  protocol message number
 * \param  cco_cap  CCo capabilities of the sending STA
 * \param  nid  NID of the sender network, associated with the NMK
 * \param  new_eks  EKS of the key being set
 * \param  new_key  new key, or NULL if none.
 *
 * This message is used in several protocol.  First check that this message is
 * legitimate, then depending of the protocol, generated the corresponding
 * events.
 *
 * \todo List all the possible usages in order to split this message handling.
 */
void
cp_sta_action_process_cm_set_key_req (cp_t *ctx, cp_mme_t *mme,
                                      cp_key_type_t key_type,
                                      u32 my_nounce, u32 your_nounce,
                                      cp_pid_t pid,
                                      u16 prn, u8 pmn,
                                      cp_cco_cap_t cco_cap,
                                      cp_nid_t nid,
                                      u8 new_eks,
                                      cp_key_t *new_key);

/**
 * Process a CM_SET_KEY.CNF, 11.5.5.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  result  transaction result
 * \param  my_nounce  to be used in next message
 * \param  your_nounce  used in previous message
 * \param  pid  protocol identifier
 * \param  prn  protocol run number
 * \param  pmn  protocol message number
 * \param  cco_cap  CCo capabilities of the sending STA
 *
 * Response from a preceding CM_SET_KEY.REQ.  First check that this message is
 * legitimate and that it correspond to a sent request.
 *
 * This message can be forwarded to the CCo module.
 *
 * \todo List all the possible usages in order to split this message handling.
 */
void
cp_sta_action_process_cm_set_key_cnf (cp_t *ctx, cp_mme_t *mme,
                                      cp_msg_cm_set_key_cnf_result_t result,
                                      u32 my_nounce, u32 your_nounce,
                                      cp_pid_t pid,
                                      u16 prn, u8 pmn,
                                      cp_cco_cap_t cco_cap);

/**
 * Process a CM_GET_KEY.REQ, 11.5.6.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  req_type  request type (relayed or not)
 * \param  key_type  requested key type
 * \param  nid  NID of the network of the sender, or the sender want to join
 * \param  my_nounce  to be used in next message
 * \param  pid  protocol identifier
 * \param  prn  protocol run number
 * \param  pmn  protocol message number
 * \param  hash  HASH key, used to generate a TEK, or NULL if not present
 *
 * Can only be sent unencrypted for UKE to derive a TEK from HASH exchange.
 *
 * If requested key is the NEK, forward to CCo module.
 *
 * If requested key is the NMK, this is a NMK provisioning.
 *
 * \todo List all the possible usages in order to split this message handling.
 */
void
cp_sta_action_process_cm_get_key_req (cp_t *ctx, cp_mme_t *mme,
                                      cp_msg_cm_get_key_req_type_t req_type,
                                      cp_key_type_t key_type,
                                      cp_nid_t nid,
                                      u32 my_nounce,
                                      cp_pid_t pid,
                                      u16 prn, u8 pmn,
                                      u8 *hash);

/**
 * Process a CM_GET_KEY.CNF, 11.5.7.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  result  transaction result
 * \param  key_type  requested key type
 * \param  my_nounce  to be used in next message
 * \param  your_nounce  used in previous message
 * \param  nid  NID of the sender network
 * \param  eks  EKS of the received key
 * \param  pid  protocol identifier
 * \param  prn  protocol run number
 * \param  pmn  protocol message number
 * \param  hash  HASH key, used to generate a TEK, or NULL if not present
 * \param  key  received key, or NULL if not present
 *
 * Response from a CM_GET_KEY.REQ.
 *
 * \todo List all the possible usages in order to split this message handling.
 */
void
cp_sta_action_process_cm_get_key_cnf (cp_t *ctx, cp_mme_t *mme,
                                      cp_msg_cm_get_key_cnd_result_t result,
                                      cp_key_type_t key_type,
                                      u32 my_nounce, u32 your_nounce,
                                      cp_nid_t nid,
                                      u8 eks,
                                      cp_pid_t pid,
                                      u16 prn, u8 pmn,
                                      u8 *hash, cp_key_t *key);

/**
 * Process a CM_MME_ERROR.IND, 11.5.32.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 * \param  reason  reason of the error
 * \param  rx_mmv  MMV of the erroneous MME
 * \param  rx_mmtype  MMTYPE of the erroneous MME
 * \param  invalid_byte_offset  offset in the MME of the error
 *
 * Used for debug.  Trace the error.
 */
void
cp_sta_action_process_cm_mme_error_ind (
    cp_t *ctx, cp_mme_t *mme, cp_msg_cm_mme_error_ind_reason_t reason,
    u8 rx_mmv, u16 rx_mmtype, u16 invalid_byte_offset);

END_DECLS

#endif /* cp_sta_action_action_h */