summaryrefslogtreecommitdiff
path: root/cesar/cp2/sta/action/assoc.h
blob: 57c82fde2bcb17732b409078dd62e217de8ff25f (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
#ifndef cp2_sta_action_assoc_h
#define cp2_sta_action_assoc_h
/* Cesar project {{{
 *
 * Copyright (C) 2008 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    cp2/sta/action/assoc.h
 * \brief   STA action, association related definitions.
 * \ingroup cp2_sta_action
 *
 * Association/disassociation
 * ==========================
 *
 * This part relates to association and disassociation for a STA.  A state
 * machine is used to handle the association status of the station:
 *
 * \image html assoc.png "Association state machine"
 *
 *  - (1) send CC_ASSOC.REQ
 *  - (2) send CM_GET_KEY.REQ
 *  - (3) send CC_ASSOC.REQ for renewal
 *  - (4) send CM_SET_KEY.CNF
 *  - (5) send CC_LEAVE.REQ
 *  - (6) send CC_LEAVE.RSP
 *  - (7) cleanup data plane
 *
 * For the moment, only one association scheme is supported: association with
 * matching NID, without proxy network.
 *
 * Related: 7.3.2, 7.3.3, 7.3.4.1, 7.3.5.1, 7.3.6.
 *
 *
 * Association
 * -----------
 *
 * When the station wants to associate, it set the association parameters and
 * trigger the "to assoc" event.  This will send the CC_ASSOC.REQ message to
 * the CCo and wait for response.
 *
 * If no response is received, retry.  Retry is needed because we are not
 * associated and broadcast is used.
 *
 * If a negative response is received, association has failed, this is
 * remembered in order not to try to associate too often to the same CCo.
 *
 * If a positive response is received, go to associated state.
 *
 *
 * Authentication
 * --------------
 *
 * When entering this state, send a payload encrypted CM_GET_KEY.REQ to
 * request the NEK.
 *
 * Once the station is authenticated, CC_SET_TEI_MAP.IND messages can be
 * received.
 *
 * As unicast transmissions are used, a timeout will directly break the
 * association sequence.
 *
 * If a negative response is received, association has failed, the CCo is
 * using a different NMK.  This is remembered in order not to associate with
 * this CCo again (until keys are changed).
 *
 * If a positive response is received, the station is authenticated.
 *
 * Once authenticated, the CCo can change the NEK periodically.
 *
 * Lease renewal
 * -------------
 *
 * Association is granted for a given time.  When the station is associated,
 * program a timer to renew the association.  When this timer expires, send a
 * CC_ASSOC.REQ for renewal and set the timer for a second chance.
 *
 * The station will not leave the AVLN by itself due to lease expiration.  It
 * will wait an eventual CC_LEAVE.IND message to do so.
 *
 * When the CCo confirms the renewal, the renew timer is reset to the value
 * given in its confirmation message.  Ignore renewal failure, will wait for
 * the CC_LEAVE.IND message.
 *
 *
 * Leaving
 * -------
 *
 * If the request comes from the sta, trigger the "leave" event.  This will
 * send the CC_LEAVE.REQ message to the CCo and wait for response.  If no
 * response cames for three beacon periods, resend and go to the "leave wait"
 * state.
 *
 * If the request comes from the CCo (CC_LEAVE.IND), send a response and go to
 * the "leave wait" state.
 *
 * The "leave wait" state is there to give time to the data plane to send the
 * MME.  After a fixed timer, go back to unassociated state and cleanup the
 * data plane from all AVLN related parameters.
 */
#include "cp2/sta/mgr/sta.h"

BEGIN_DECLS

/**
 * Start a association procedure.
 * \param  ctx  control plane context
 * \param  cco  CCo to associate with
 *
 * Trigger TO_ASSOC event.
 *
 * Need:
 *  - CCo to associate to (MAC, TEI, NID).
 *  - our CCo cap and proxy network cap.
 */
void
cp_sta_action_assoc_start (cp_t *ctx, cp_sta_t *cco);

/**
 * Request to leave the current AVLN.
 * \param  ctx  control plane context
 *
 * Trigger a TO_LEAVE event.
 */
void
cp_sta_action_assoc_leave (cp_t *ctx);

/**
 * Handle UNASSOCIATED => TO_ASSOC event.
 * \param  ctx  control plane context
 *
 * Send a CC_ASSOC.REQ to the CCo.
 */
void
cp_sta_action_assoc__unassociated__to_assoc (cp_t *ctx);

/**
 * Handle WAIT_ASSOC_CNF => CC_ASSOC.CNF.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 *
 * If the CCo accepted our association, update association information, send
 * the CM_GET_KEY.REQ, and post a TO_SUCCESS event.  If the CCo refused, post
 * a TO_FAILURE and update the CCo information to remember the failure.
 *
 * Update:
 *  - our TEI.
 *  - our TEI lease time (update lease timer).
 *  - our AVLN.
 *  - our AVLN SNID.
 *  - CCo failure info.
 */
void
cp_sta_action_assoc__wait_assoc_cnf__cc_assoc_cnf (cp_t *ctx,
                                                   cp_mme_rx_t *mme);

/**
 * Handle WAIT_ASSOC_CNF => TIMEOUT.
 * \param  ctx  control plane context
 *
 * If retry count is not zero, resend the CC_ASSOC.REQ.
 *
 * If retry count is zero, post a TO_FAILURE.
 */
void
cp_sta_action_assoc__wait_assoc_cnf__timeout (cp_t *ctx);

/**
 * Handle ASSOCIATED => CM_GET_KEY.CNF (PID=0).
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 *
 * If this is a success, trigger a TO_SUCCESS event and update station status.
 *
 * If authentication has failed, remember this and trigger a TO_FAILURE.
 *
 * Update:
 *  - authenticated status.
 *  - NEK.
 *  - CCo failure info.
 */
void
cp_sta_action_assoc__associated__cm_get_key_cnf_pid_0 (cp_t *ctx,
                                                       cp_mme_rx_t *mme);

/**
 * Handle ASSOCIATED => TIMEOUT.
 * \param  ctx  control plane context
 *
 * Authentication failed, trigger a TO_FAILURE and update the CCo information
 * to remember the failure.
 */
void
cp_sta_action_assoc__associated__timeout (cp_t *ctx);

/**
 * Handle AUTHENTICATED => RENEW.
 * \param  ctx  control plane context
 *
 * Time to renew our lease.  Send a CC_ASSOC.REQ.
 */
void
cp_sta_action_assoc__authenticated__renew (cp_t *ctx);

/**
 * Handle AUTHENTICATED => CC_ASSOC.CNF.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 *
 * Update:
 *  - our TEI lease time (update lease timer).
 */
void
cp_sta_action_assoc__authenticated__cc_assoc_cnf (cp_t *ctx,
                                                  cp_mme_rx_t *mme);

/**
 * Handle AUTHENTICATED => CM_SET_KEY.REQ (PID=1), NEK renewal.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 *
 * Sent periodically by the CCo to change the NEK.
 *
 * Update:
 *  - NEK.
 */
void
cp_sta_action_assoc__authenticated__cm_set_key_req_pid_1 (cp_t *ctx,
                                                          cp_mme_rx_t *mme);

/**
 * Handle AUTHENTICATED => TO_ASSOC.
 * \param  ctx  control plane context
 *
 * Send the CC_LEAVE.REQ message to the CCo.  Set a timeout in three beacon
 * periods.
 */
void
cp_sta_action_assoc__authenticated__to_leave (cp_t *ctx);

/**
 * Handle AUTHENTICATED => CC_LEAVE.IND.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 *
 * The CCo request us to leave the AVLN.  Send a response and trigger the
 * TO_LEAVE_WAIT event.
 */
void
cp_sta_action_assoc__authenticated__cc_leave_ind (cp_t *ctx,
                                                  cp_mme_rx_t *mme);

/**
 * Handle LEAVING => CC_LEAVE.CNF.
 * \param  ctx  control plane context
 * \param  mme  received MME handle
 *
 * Leave the AVLN, cleanup data plane and trigger the TO_SUCCESS event.
 */
void
cp_sta_action_assoc__leaving__cc_leave_cnf (cp_t *ctx, cp_mme_rx_t *mme);

/**
 * Handle LEAVING => TIMEOUT.
 * \param  ctx  control plane context
 *
 * Send a CC_LEAVE.REQ again.
 */
void
cp_sta_action_assoc__leaving__timeout (cp_t *ctx);

/**
 * Handle LEAVE_WAIT => TIMEOUT.
 * \param  ctx  control plane context
 *
 * Leave the AVLN and cleanup data plane.
 */
void
cp_sta_action_assoc__leave_wait__timeout (cp_t *ctx);

END_DECLS

#endif /* cp2_sta_action_assoc_h */