xref: /btstack/doc/manual/docs-template/picts/gatt_client_security.txt (revision 503a627edab6ba8492c3d0cdd9ac598fe2b0f08a) 
1@startuml
2title Reactive Authentication in Central Role
3start
4: App on A connects to B;
5: App on A triggers GATT Client request;
6: GATT Client request sent;
7if (GATT Server returns an ATT_ERROR_INSUFFICIENT_X error?) then (yes)
8  if (ENABLE_GATT_CLIENT_PAIRING defined?) then (yes)
9    if (LTK available?) then (yes)
10      : SM_EVENT_REENCRYPTION_STARTED;
11      : start encryption;
12      if (re-encrypted) then (yes)
13        : SM_EVENT_REENCRYPTION_COMPLETE(ERROR_CODE_SUCCESS);
14        : GATT Client request re-sent;
15        #23DB2B : App receives GATT Response;
16        stop
17      else (no)
18        : SM_EVENT_REENCRYPTION_COMPLETE(error);
19        : delete bonding information;
20      endif
21    endif
22    : SM_EVENT_PAIRING_STARTED;
23    : start pairing;
24    if (pairing success?) then (yes)
25        : SM_EVENT_PAIRING_COMPLETE(ERROR_CODE_SUCCESS);
26        : GATT Client request re-sent;
27        #23DB2B : App receives GATT Response;
28        stop
29    else (no)
30        : SM_EVENT_PAIRING_COMPLETE(error);
31        #FD5B41 : App receives a GATT Client error;
32        stop
33    endif
34  else (no)
35    #FD5B41: ATT_QUERY_COMPLETE(ATT_ERROR_INSUFFICIENT_X);
36    stop
37    note left
38      App can trigger pairing and
39      repeat the GATT Client request
40    end note
41  endif
42else (no)
43  #23DB2B : App receives GATT Response;
44  stop
45endif
46@enduml
47
48
49
50@startuml
51title Reactive Authentication in Peripheral Role
52start
53: App on B connects to A;
54: App on A triggers GATT Client request;
55: GATT Client request sent;
56if (GATT Server returns an ATT_ERROR_INSUFFICIENT_X error?) then (yes)
57  if (ENABLE_GATT_CLIENT_PAIRING define?) then (yes)
58    if (LTK available?) then (yes)
59      : SM_EVENT_REENCRYPTION_STARTED;
60      : SM on A sends SECURITY REQUEST;
61      : SM on B should encrypt connection if LTK available;
62      if (re-encrypted) then (yes)
63        : SM_EVENT_REENCRYPTION_COMPLETE(ERROR_CODE_SUCCESS);
64        : GATT Client request re-sent;
65        #23DB2B : App receives GATT Response;
66        stop
67      else (no)
68        : SM_EVENT_REENCRYPTION_COMPLETE(error);
69        : delete bonding information;
70      endif
71    endif
72    : SM_EVENT_PAIRING_STARTED;
73    : SM on A sends SECURITY REQUEST;
74    : SM on B should perform pairing sequence;
75    if (pairing success?) then (yes)
76        : SM_EVENT_PAIRING_COMPLETE(ERROR_CODE_SUCCESS);
77        : GATT Client request re-sent;
78        #23DB2B : App receives GATT Response;
79        stop
80    else (no)
81        : SM_EVENT_PAIRING_COMPLETE(error);
82        #FD5B41 : App receives a GATT Client error;
83        stop
84    endif
85  else (no)
86    #FD5B41: ATT_QUERY_COMPLETE(ATT_ERROR_INSUFFICIENT_X);
87    stop
88    note left
89      App can trigger pairing and
90      repeat the GATT Client request
91    end note
92  endif
93else (no)
94  #23DB2B : App receives GATT Response;
95  stop
96endif
97@enduml
98
99
100@startuml
101title Mandatory Authentication in Central Role
102start
103: App calls gatt_client_set_required_security_level (level > 0);
104: App on A connects to B;
105: App on A triggers GATT Client request;
106: GATT Client request sent;
107if (LTK available?) then (yes)
108   : SM_EVENT_REENCRYPTION_STARTED;
109   : start encryption;
110   if (re-encrypted) then (yes)
111     : SM_EVENT_REENCRYPTION_COMPLETE(ERROR_CODE_SUCCESS);
112     : GATT Client request sent;
113     #23DB2B : App receives GATT Response;
114     stop
115  else (no)
116     : SM_EVENT_REENCRYPTION_COMPLETE(error);
117     #FD5B41: App receives GATT_QUERY_COMPLETE event
118          with ATT_ERROR_BONDING_INFORMATION_MISSING;
119     stop
120  endif
121else (no)
122  : SM_EVENT_PAIRING_STARTED;
123  : start pairing;
124  if (pairing success?) then (yes)
125     : SM_EVENT_PAIRING_COMPLETE(ERROR_CODE_SUCCESS);
126     : GATT Client request sent;
127     #23DB2B : App receives GATT Response;
128     stop
129  else (no)
130    : SM_EVENT_PAIRING_COMPLETE(error);
131    if (level >= 3) then (yes)
132      #FD5B41: App receives GATT_QUERY_COMPLETE event
133          with ATT_ERROR_INSUFFICIENT_AUTHENTICATION;
134      stop
135    else (no)
136      #FD5B41: App receives GATT_QUERY_COMPLETE event
137          with ATT_ERROR_INSUFFICIENT_ENCRYPTION;
138      stop
139    endif
140  endif
141@enduml
142
143
144
145@startuml
146title Mandatory Authentication in Peripheral Role
147start
148: App calls gatt_client_set_required_security_level (level > 0);
149: App on B connects to A;
150: App on A triggers GATT Client request;
151: GATT Client request sent;
152if (LTK available?) then (yes)
153   : SM_EVENT_REENCRYPTION_STARTED;
154   : SM on A sends SECURITY REQUEST;
155   : SM on B should encrypt connection if LTK available;
156   if (re-encrypted) then (yes)
157     : SM_EVENT_REENCRYPTION_COMPLETE(ERROR_CODE_SUCCESS);
158     : GATT Client request sent;
159     #23DB2B : App receives GATT Response;
160     stop
161  else (no)
162     : SM_EVENT_REENCRYPTION_COMPLETE(error);
163     #FD5B41: App receives GATT_QUERY_COMPLETE event
164          with ATT_ERROR_BONDING_INFORMATION_MISSING;
165     stop
166  endif
167else (no)
168  : SM_EVENT_PAIRING_STARTED;
169  : SM on A sends SECURITY REQUEST;
170  : SM on B should perform pairing sequence;
171  if (pairing success?) then (yes)
172     : SM_EVENT_PAIRING_COMPLETE(ERROR_CODE_SUCCESS);
173     : GATT Client request sent;
174     #23DB2B : App receives GATT Response;
175     stop
176  else (no)
177    : SM_EVENT_PAIRING_COMPLETE(error);
178    if (level >= 3) then (yes)
179      #FD5B41: App receives GATT_QUERY_COMPLETE event
180          with ATT_ERROR_INSUFFICIENT_AUTHENTICATION;
181      stop
182    else (no)
183      #FD5B41: App receives GATT_QUERY_COMPLETE event
184          with ATT_ERROR_INSUFFICIENT_ENCRYPTION;
185      stop
186    endif
187  endif
188@enduml
189
190
191@startuml
192title Proactive Authentication in Central Role
193start
194: A connects to B;
195: SM checks if LTK available;
196note right
197  SM actions triggered by
198  connection complete
199  (independent from GATT Client)
200end note
201: App triggers GATT Client request on A;
202if (LTK available?) then (no)
203  : GATT Client request sent;
204  if (GATT Server returns an ATT_ERROR_INSUFFICIENT_X error?) then (no)
205    #23DB2B : App receives GATT Response;
206    stop
207  else (yes)
208    if (ENABLE_GATT_CLIENT_PAIRING defined?) then (no)
209      #FD5B41: App receives GATT_QUERY_COMPLETE event
210          with ATT_ERROR_INSUFFICIENT_X;
211      stop
212    else (yes)
213      : SM_EVENT_PAIRING_STARTED;
214      : start pairing;
215      if (pairing success?) then (yes)
216          : SM_EVENT_PAIRING_COMPLETE(ERROR_CODE_SUCCESS);
217          : GATT Client request re-sent;
218          #23DB2B : App receives GATT Response;
219          stop
220      else (no)
221          : SM_EVENT_PAIRING_COMPLETE(error);
222         #FD5B41: App receives GATT_QUERY_COMPLETE event
223              with ATT_ERROR_INSUFFICIENT_X;
224          stop
225      endif
226    endif
227  endif
228else (yes)
229   : SM_EVENT_REENCRYPTION_STARTED;
230   : start encryption;
231   if (re-encrypted) then (yes)
232     : SM_EVENT_REENCRYPTION_COMPLETE(ERROR_CODE_SUCCESS);
233     : GATT Client request sent;
234     #23DB2B : App receives GATT Response;
235     stop
236   else (no)
237     : SM_EVENT_REENCRYPTION_COMPLETE(error);
238     #FD5B41: App receives GATT_QUERY_COMPLETE event
239          with ATT_ERROR_BONDING_INFORMATION_MISSING;
240     stop
241     note right
242       App can delete bonding
243       information and repeat
244       the GATT Client request
245    end note
246  endif
247endif
248@enduml
249
250@startuml
251title Proactive Authentication in Peripheral Role
252start
253: A connects to B;
254: SM checks if LTK available;
255note right
256  SM actions triggered by
257  connection complete
258  (independent from GATT Client)
259end note
260: App triggers GATT Client request on A;
261if (LTK available?) then (no)
262  : GATT Client request sent;
263  if (GATT Server returns an ATT_ERROR_INSUFFICIENT_X error?) then (no)
264    #23DB2B : App receives GATT Response;
265    stop
266  else (yes)
267    if (ENABLE_GATT_CLIENT_PAIRING defined?) then (no)
268      #FD5B41: App receives GATT_QUERY_COMPLETE event
269          with ATT_ERROR_INSUFFICIENT_X;
270      stop
271    else (yes)
272      : SM_EVENT_PAIRING_STARTED;
273      : start pairing;
274      if (pairing success?) then (yes)
275          : SM_EVENT_PAIRING_COMPLETE(ERROR_CODE_SUCCESS);
276          : GATT Client request re-sent;
277          #23DB2B : App receives GATT Response;
278          stop
279      else (no)
280          : SM_EVENT_PAIRING_COMPLETE(error);
281         #FD5B41: App receives GATT_QUERY_COMPLETE event
282              with ATT_ERROR_INSUFFICIENT_X;
283          stop
284      endif
285    endif
286  endif
287else (yes)
288   : SM_EVENT_REENCRYPTION_STARTED;
289   : start encryption;
290   if (re-encrypted) then (yes)
291     : SM_EVENT_REENCRYPTION_COMPLETE(ERROR_CODE_SUCCESS);
292     : GATT Client request sent;
293     #23DB2B : App receives GATT Response;
294     stop
295   else (no)
296     : SM_EVENT_REENCRYPTION_COMPLETE(error);
297     #FD5B41: App receives GATT_QUERY_COMPLETE event
298          with ATT_ERROR_BONDING_INFORMATION_MISSING;
299     stop
300     note right
301       App can delete bonding
302       information and repeat
303       the GATT Client request
304    end note
305  endif
306endif
307@enduml
308