summaryrefslogtreecommitdiff
path: root/cp2/sta/action/assoc.h
blob: 2e8a872133673fa0522e0a4c3c826005cb49868d (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
#ifndef cp_sta_action_assoc_h
#define cp_sta_action_assoc_h
/* Cesar project {{{
 *
 * Copyright (C) 2008 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    cp/sta/action/assoc.h
 * \brief   STA action, association related definitions.
 * \ingroup cp_sta
 *
 * 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.
 */

BEGIN_DECLS

/**
 * Start a association procedure.
 * \param  ctx  control plane context
 * \param  cco  CCo to associate with
 *
 * Send a CC_ASSOC.REQ to the CCo and 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);

/**
 * 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 we were associating and if the CCo accepted our association, update
 * association information, send the CC_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.
 *
 * If we were renewing, just update the lease time.
 *
 * Need:
 *  - whether a association is pending and its characteristics.
 *
 * Update:
 *  - our TEI.
 *  - our TEI lease time (update lease timer).
 *  - our AVLN.
 *  - our AVLN SNID.
 *  - CCo failure info.
 */
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);

END_DECLS

#endif /* cp_sta_action_assoc_h */