Tutorial - Authentifizierung¶

Konzept¶

Wenn Authentifizierung aktiviert ist kann jeglicher Client (z.B. API Bindings und Brick Viewer) zwar noch eine TCP/IP Verbindung zum Brick Daemon und der Ethernet/WIFI Extension herstellen, aber die Verbindung befindet sich initial im nicht-authentifizierten Zustand. In diesem Zustand werden alle eingehenden Nachrichten zur Kontrolle der Bricks und Bricklets sowie ausgehende Callbacks verworfen. Im nicht-authentifizierten Zustand findet keine normale Kommunikation statt.

Um eine TCP/IP Verbindung vom nicht-authentifizierten in den authentifizierten Zustand zu überführen muss der Client sich authentifizierten. Er muss dem Brick Daemon oder der Ethernet/WIFI Extension beweisen, dass er das Authentifizierungsgeheimnis kennt und daher berechtigt ist die Bricks und Bricklets zu kontrollieren. Dieser Beweis wird über einen HMAC-SHA1 basierten Handshake erbracht, wobei das Authentifizierungsgeheimnis aber niemals direkt übertragen wird.

Ist der Handshake erfolgreich dann wechselt die Verbindung vom nicht-authentifizierten in den authentifizierten Zustand und die Kommunikation kann normal weitergeführt werden. Schlägt der Handshake fehl wird die Verbindung durch die Gegenseite geschlossen. Die Authentifizierung kann fehlschlagen wenn das Authentifizierungsgeheimnis nicht übereinstimmt oder Authentifizierung für den Brick Daemon oder die Ethernet/WIFI Extension nicht aktiviert ist.

Konfiguration¶

Die Authentifizierung ist standardmäßig nicht aktiviert und muss erst konfiguriert werden. Dazu muss ein Authentifizierungsgeheimnis festgelegt werden, welches maximal 64 ASCII Zeichen lang sein kann. In diesem Tutorial wird My Authentication Secret! als Geheimnis verwendet. Weitere Informationen wie das Authentifizierungsgeheimnis beim Brick Daemon und der Ethernet/WIFI Extension konfiguriert wird finden sich in den jeweiligen Dokumentationsabschnitten:

• Brick Daemon: Authentifizierung
• Ethernet Extension: Authentifizierung
• WIFI Extension: Authentifizierung
• WIFI Extension 2.0: Authentifizierung

Verwendung¶

Wenn Authentifizierung aktiviert ist muss der Authentifizierung-Handshake vom Client durchgeführt werden, um die TCP/IP Verbindung vom nicht-authentifizierten in den authentifizierten Zustand zu überführen.

Im Brick Viewer muss dazu nur das Häkchen für "Use Authentication" auf dem Setup Tab gesetzt und das Authentifizierungsgeheimnis vor dem Klick auf den "Connect" Knopf eingegeben werden. Ab dann arbeitet Brick Viewer wie gewohnt.

Im eigenen Programm muss stattdessen die authenticate() Funktion aufgerufen werden, die allen API Bindings hinzugefügt wurde. Diese Funktion bekommt als Parameter das Geheimnis übergeben und führt den Handshake durch. Dies ist entweder erfolgreich oder schlägt mit einem Fehlercode oder einer Exception fehl. In diesem Fall stimmt entweder das Geheimnis nicht überein, oder Authentifizierung für den Brick Daemon oder die Ethernet/WIFI Extension ist nicht aktiviert.

Es gibt zwei Arten authenticate() aufzurufen, ohne und mit Callbacks.

func main() {
    ipcon.connect(HOST, PORT);
    ipcon.authenticate("My Authentication Secret!");

    // here comes the rest of your program
}

func connected_callback(...) {
    ipcon.authenticate("My Authentication Secret!");
    ipcon.enumerate();
}

func main() {
    ipcon.connect(HOST, PORT);

    // here comes the rest of your program
}