docu: document LE security authentication models

doc/manual/docs/picts/le_security_flow_control.txt

@@ -0,0 +1,154 @@
+@startuml
+start
+: A connects to B;
+: App triggers GATT Client request on A;
+if (called gatt_client_set_required_security_level) then (yes)
+
+  if (LTK available) then (yes)
+     : start encryption;
+  else (no)
+     : start pairing;
+  endif
+  if (paired/re-encrypted) then (yes)
+     : GATT Client request sent;
+     #23DB2B : App receives GATT Response;
+     stop
+  else (no)
+     #FD5B41 : App receives a GATT Client error;
+     stop
+  endif
+endif
+
+if (ENABLE_LE_PROACTIVE_AUTHENTICATION and LTK available) then (yes)
+  : starts encryption;
+  if (re-encrypted) then (yes)
+     : GATT Client request sent;
+     #23DB2B : App receives GATT Response;
+     stop
+  else (no) 
+     #FD5B41 : App receives a GATT Client error;
+     stop
+     note left
+        App can delete bonding 
+        information and repeat 
+        the GATT Client request
+     end note
+  endif
+endif
+
+: GATT Client request is sent to GATT Server;
+if (GATT Server returns an 'insufficient x' error) then (yes)
+  if (ENABLE_GATT_CLIENT_PAIRING) then (yes)
+    if (LTK available) then (yes)
+      : start encryption;
+    else (no)
+      : start pairing;
+    endif
+    if (paired/re-encrypted) then (yes)
+      : GATT Client request sent;
+      #23DB2B : App receives GATT Response;
+      stop
+    else (no)
+      #FD5B41 : App receives a GATT Client error;
+      stop
+    endif
+  else (no)
+    #FD5B41 : App receives a GATT Client error;
+    stop
+  endif
+endif
+#23DB2B : App receives GATT Response;
+stop
+@enduml
+
+@startuml
+title Mandatory Authentication
+start
+: App calls gatt_client_set_required_security_level (level > 0);
+: A connects to B;
+: App triggers GATT Client request on A;
+
+if (LTK available) then (yes)
+   : start encryption;
+else (no)
+   : start pairing;
+endif
+if (paired/re-encrypted) then (yes)
+   : GATT Client request sent;
+   #23DB2B : App receives GATT Response;
+   stop
+else (no)
+   #FD5B41 : App receives a GATT Client error;
+   stop
+endif
+@enduml
+
+
+@startuml
+title Proactive Authentication with LTK
+start
+: A connects to B;
+: App triggers GATT Client request on A;
+if (role) then (Central)
+: start encryption;
+else (Peripheral)
+: send security request;
+endif
+if (re-encrypted) then (yes)
+   : GATT Client request sent;
+   #23DB2B : App receives GATT Response;
+   stop
+else (no) 
+   #FD5B41 : App receives a GATT Client error;
+   stop
+   note right
+      App can delete bonding 
+      information and repeat 
+      the GATT Client request
+   end note
+endif
+@enduml
+
+@startuml
+title Reactive Authentication
+start
+: A connects to B;
+: App triggers GATT Client request on A;
+: GATT Client request sent;
+
+if (GATT Server returns an 'insufficient x' error) then (yes)
+  if (ENABLE_GATT_CLIENT_PAIRING) then (yes)
+    if (LTK available) then (yes)
+      : start encryption;
+      if (re-encrypted) then (yes)
+        : GATT Client request sent;
+        #23DB2B : App receives GATT Response;
+        stop
+      else (no)
+        : delete bonding information;
+      endif
+      -> no;
+   endif
+    -> no;
+    : start pairing;
+      if (paired) then (yes)
+        : GATT Client request sent;
+        #23DB2B : App receives GATT Response;
+        stop
+      else (no)
+        #FD5B41 : App receives a GATT Client error;
+        stop
+      endif
+  else (no)
+    #FD5B41 : App receives a GATT Client error;
+    stop
+    note left
+      App can trigger pairing and 
+      repeat the GATT Client request
+    end note
+  endif
+else (no)
+  #23DB2B : App receives GATT Response;
+  stop
+endif
+@enduml