Security

Overview

Robot Raconteur supports using credentials to authenticate clients, and supports encrypted communication using TLS. The security features of Robot Raconteur are designed to be flexible and easy to use.

Authentication

Robot Raconteur supports using credentials to authenticate clients. The server can require clients to provide a username and credentials, an optionally a TLS client certificate. The credentials are typically a password, but can be any Robot Raconteur Map containing other information such as a token or one-time password.

The following examples demonstrate connecting to a service that requires a username and password:

# authentication_example.py - Example of using authentication in Python

from RobotRaconteur.Client import *

url = 'rr+tcp://localhost:53226?service=authentication_example'

# Create the user credentials
username = "testuser1"
cred = {"password": RR.VarValue("testpass1", "string")}

# Connect to the service
c = RRN.ConnectService(url, username, cred)

# Use the service
c.say("Message to secure service")

% authentication_example.m - Example of using authentication from Matlab

url = 'rr+tcp://localhost:53226?service=authentication_example';

% Create the user credentials
username = "testuser1";
cred = containers.Map({'password'}, {RobotRaconteurVarValue('testpass1', 'string')});

% Connect to the service
c = RobotRaconteur.ConnectService(url, username, cred);

% Use the service
c.say('Message to secure service');

RobotRaconteur.DisconnectService(c);

// authentication_example.cs - Example of handling exceptions in C#

using RobotRaconteur;
using System;
using System.Diagnostics;
using System.Linq;
using System.Collections.Generic;

using (var node_setup = new ClientNodeSetup(args))
{
    // Create the user credentials
    string username = "testuser1";
    var cred = new Dictionary<string, object>() { { "password", "testpass1" } };

    // Connect to the service
    var c = (experimental.reynard_the_robot.Reynard)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:53226?service=authentication_example", username, cred);

    // Use the service
    c.say("Message to secure service");
}

// authentication_example.cpp - Example of using Robot Raconteur authentication

#include <stdio.h>
#include <iostream>
#include <boost/range/algorithm.hpp>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;

int main(int argc, char* argv[])
{
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    // Create the user credentials
    std::string username = "testuser1";
    RR::RRMapPtr<std::string, RR::RRValue> credentials = RR::AllocateEmptyRRMap<std::string, RR::RRValue>();
    credentials->insert(std::make_pair("password", RR::stringToRRArray("testpass1")));

    // Connect to the service using credentials
    experimental::reynard_the_robot::ReynardPtr c =
        RR::rr_cast<experimental::reynard_the_robot::Reynard>(RR::RobotRaconteurNode::s()->ConnectService(
            "rr+tcp://localhost:53226?service=authentication_example", username, credentials));

    // Use the service
    c->say("Message to secure service");

    std::cout << "authentication_example.cpp example complete" << std::endl;
    return 0;
}

TLS Encryption

Robot Raconteur supports encrypted communication using TLS. Wason Technology provides a certificate authority and sells certificates for use with Robot Raconteur. All production devices using Robot Raconteur are expected to use certificates provided by Wason Technology.

On the server side, the server should use SecureServerNodeSetup to set up the service node with the appropriate configuration. There must be a certificate and private key file available that matches the NodeID uuid of the service node. See the framework documentation for more information.

On the client side, simply replace the rr+tcp:// or rr+ws:// URL scheme with rr+tcps:// or rrs+ws://. For instance, to connect to a service using TLS, use the URL rrs+tcp://192.168.1.10:1234?service=my_service instead of rr+tcp://192.168.1.10:1234?service=my_service. Otherwise no other changes are necessary for the client, although it is highly recommended to include the ?nodeid=xxx parameter in the URL to prevent sending credentials to the wrong device. For example, rrs+tcp://192.168.1.10:1234?nodeid=7932d2a6-b7e1-4068-82d9-16f93e868ed9&service=my_service.

When connecting to web servers, the URL scheme should be rr+wss:// should be used. The rr+wss:// scheme uses standard DNS based certificate validation, and the certificate must be signed by a standard certificate authority. This is in contrast to the rrs+tcp:// scheme, which uses the Robot Raconteur certificate authority. For example, the URL used in the web server example rr+wss://wstest2.wasontech.com/robotraconteur?service=testobj will use standard certificate validation.