Tutorial - Authentication¶

Concept¶

With authentication enabled any client (e.g. API bindings and Brick Viewer) can still connect to the TCP/IP interface of Brick Daemon and the Ethernet/WIFI Extension, but the connection starts in non-authenticated state. In this state all incoming communication to control Bricks and Bricklets is dropped and all outgoing callbacks from the devices are dropped as well. No normal communication happens in non-authenticated state.

To switch a TCP/IP connection from non-authenticated to authenticated state the client has to authenticate itself, it has to prove to the Brick Daemon or the Ethernet/WIFI Extension that it knows the authentication secret and thus is allowed to control the Bricks and Bricklets. This prove is done by a HMAC-SHA1 based handshake during which the authentication secret is never directly exchanged over the wire.

If the handshake succeeds the connection switches from non-authenticated to authenticated state and communication can continue as normal. If the handshake fails then the connection gets closed. Authentication can fail if the wrong secret was used or if authentication is not enabled at all on the Brick Daemon or the Ethernet/WIFI Extension.

Configuration¶

Authentication is not enabled by default it has to be configured first. Select an authentication secret. This can be up to 64 ASCII characters long. In this tutorial My Authentication Secret! will be used as secret. See the Brick Daemon and Ethernet/WIFI Extension documentation for detail on how to configure the authentication secret:

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

Usage¶

Once authentication is enabled you need to perform the authentication handshake in your client to switch the connection from non-authenticated to authenticated state.

In Brick Viewer you just tick the "Use Authentication" check box on the Setup tab and enter your authentication secret before clicking connect and Brick Viewer will just work as normal.

In your own program you need to call the authenticate() function that was added to all API bindings. This function takes the secret and performs the handshake. It'll either succeed or fail with and error or exception indicating that you provided the wrong secret or that authentication is not enabled at all on the Brick Daemon or the Ethernet/WIFI Extension.

There are two ways to call authenticate() in your program, one without callbacks and one with 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
}