mirror/btstack
1
0
Fork 0
mirror of https://github.com/bluekitchen/btstack.git synced 2025-04-17 02:42:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

draft on security manager

Browse Source
This commit is contained in:
Matthias Ringwald 2015-04-13 15:59:33 +02:00
parent f6c32422ce
commit ee22265b17
1 changed files with 52 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
docs/manual/protocols_profiles.tex
View File

@ -553,12 +553,61 @@ The ATT protocol is used by the ATT client to read and write attribute values st
The GATT profile is built upon ATT and provides higher level organization of the ATT attributes into GATT Services and GATT Characteristics. In BTstack, the complete ATT client functionality is included within the GATT Client. On the server side, one ore more GATT profiles are converted ahead of time into the corresponding ATT attribute database and provided by the \emph{att\_server} implementation. While constant data is automatically served, dynamic data can be queried from the application. In addition, notifications and indications can be sent. Please see section \ref{section:GATT} for more.
\subsection{SMP - Security Manager Protocol }
The SMP protocol allows to setup authenticated and encrypted LE connection. To activate the security manager, call \emph{sm\_init()}. If you're creating a product, you should also call \emph{sm\_set\_ir()} and \emph{sm\_set\_er()} with a fixed, but different from BTstack's default, 16 byte random number.
\todo{\textbf{Explain SMP and what you can do with it, what it does for you}} \\
The SMP protocol allows to setup authenticated and encrypted LE connection. After initialization and configuration, SMP handles security related functions on it's own but emits events when feedback from the main app or even the user is required. The two main tasks of the SMP are: bonding and identity resolving.
\subsubsection{Initialization}
% \newcommand{\FreeBSDHandbook}{\urlfoot{http://www.freebsd.org/doc/en\_US.ISO8859-1/books/handbook/network-bluetooth.html}{FreeBSD Handbook}}
To activate the security manager, call \emph{sm\_init()}.
If you're creating a product, you should also call \emph{sm\_set\_ir()} and \emph{sm\_set\_er()} with a fixed random 16 byte number. If possible use a unique random number per device instead of deriving it from the product serial number something similar. The encryption key generated by the BLE peripheral ultimately will be derived from the ER key seed. See Blueooth Core V4.0, Vol 3, Part G, 5.2.2 for more details on deriving the different keys. The IR key is used to identify a device if private, resolvable Bluetooth addresses are used.
\subsubsection{Configuration}
To receive events from the Security Manager, a call back is neccessary. How to register this packet handler depends on your application configuration.
When \emph{att\_server.c} is used to provide a GATT/ATT service, \emph{att\_server.c} registers itself as the Security Manager packet handler. Security Manager events are then are received by the application via the \emph{att\_server} packet handler.
If \emph{att\_server} is not used, you can directly register your packet handler with the security manager.
The default Security Manager configuration in BTstack is to be as open as possible: accept all Short Term Key (STK) Generation methods, accepted encryption key size from 7..16 bytes, and no authentication requirements. The default IO Capabilities are \emph{IO\_CAPABILITY\_NO\_INPUT\_NO\_OUTPUT}.
To configure the bonding options, you can use the following functions:
\begin{itemize}
\item \emph{sm\_set\_accepted\_stk\_generation\_methods}
\item \emph{sm\_set\_encryption\_key\_size\_range}
\item \emph{sm\_set\_authentication\_requirements}
\item \emph{sm\_set\_io\_capabilities}
\end{itemize}
\subsubsection{Identity Resolving}
Identity resolving is the process of matching a private, resolvable Bluetooth address to a previously paired device using its Identity Resolving (IR) key. For this, each device in the le central device db needs to get compared to the device address in question. After an LE connection gets established, BTstack automatically tries to resolve the address of this device. During this lookup, BTstack first emits the \emph{SM\_IDENTITY\_RESOLVING\_STARTED} event and later \emph{SM\_IDENTITY\_RESOLVING\_SUCCEEDED} or \emph{SM\_IDENTITY\_RESOLVING\_FAILED}.
\subsubsection{Bonding process}
In Bluetooth LE, there are thee main methods of establishing a first encrypted connection. From most secure to least secure, these are: Out-of-Band (OOB) Data , Passkey, and Just Works.
With OOB data, there needs to be a pre-shared secret 16 byte key. In most cases, this is not an option, especially since popular OS like iOS don't provide a way to specify it. It some applications, where both sides of a Bluetooth link are developed together, this could provide a viable option.
To provide OOB data, you can register an OOB data callback with \emph{sm\_register\_oob\_data\_callback}.
Depending on the authentication requirements, available OOB data, and the enabled STK generation methods, BTstack will request feedback from the app in the form of an event:
\begin{itemize}
\item \emph{SM\_PASSKEY\_INPUT\_NUMBER}: request user to input a passkey
\item \emph{SM\_PASSKEY\_DISPLAY\_NUMBER}: show a passkey to the user
\item \emph{SM\_JUST\_WORKS\_REQUEST}: request a user to accept a Just Works pairing
\end{itemize}
If the user stops the bonding process, \emph{sm\_bonding\_decline} should be called. Otherwise, \emph{sm\_just\_works\_confirm} or \emph{sm\_passkey\_input} can be called.
After the bonding process, \emph{SM\_PASSKEY\_DISPLAY\_CANCEL} is emitted to update the user interface.
% /subsubsection {Authorization}
% SM_AUTHORIZATION_REQUEST
% SM_AUTHORIZATION_RESULT
% ------
\section{Profiles}
As promised in the previous chapter, we explain how to implement various Bluetooth profiles in this one.