<<PackageHeader(rosauth)>>
<<TOC(4)>>

== About ==

Rosauth is a dependency of rosbridge_suite, providing server side tools for authorization and authentication of ROS bridge clients.

== Nodes ==
{{{
#!clearsilver CS/NodeAPI
node.0 {
  name=ros_mac_authentication
  desc=Server side MAC authentication
  srv {
    0.name=authenticate
    0.type=rosauth/Authentication
    0.desc=Server side authentication request
  }
  param {
    0.name=~allowed_time_delta
    0.default=5
    0.type=float
    0.desc=Allowed time delta from client to server (negative value means no time check)
    1.name=~secret_file_location
    1.type=string
    1.desc=Path to authentication secret (should be 16 characters)
  }
}
}}}

== Usage rosbridge suite authenticated server client connection ==

Configure the rosbridge to use authentication:

{{{
roslaunch rosbridge_server rosbridge_websocket.launch authenticate:=true
}}}

Set-up the rosauth node (for example purposes we disable time delta checking):

{{{
echo "1234567890abcdef" > /tmp/secret.txt  # Example secret
rosrun rosauth ros_mac_authentication _secret_file_location:=/tmp/secret.txt _allowed_time_delta:=-1
}}}

In order to test whether your authentication works, generate a mac via the command line:

{{{
echo -n "1234567890abcdefclientdestrand0level0" | sha512sum
}}}

Call auth service via command line:

{{{
rosservice call /authenticate "mac: '19d9d2166799f1ffd6fee6379f957502aff8716bfebc8cc8b3bac57ade14441bb9678be89d0a7eec9c81291f854d754d7a4de2278bede56f162c2faeb468c68a'
client: 'client'
dest: 'dest'
rand: 'rand'
t: {secs: 0, nsecs: 0}
level: 'level'
end: {secs: 0, nsecs: 0}"
}}}

This will result in the following response:

{{{
authenticated: True
}}}

The rosbridge server is responsible for calling the /authenticate service on a request of the client. This can be done using the authenticate method of roslibjs: http://robotwebtools.org/jsdoc/roslibjs/current/Ros.html#authenticate

Example:

{{{
let secret = 'myawesomesecret1'
let dest = this.url
let rand = randomString(10)
let time = new Date().getTime() / 1000
let timeEnd = time + 1000
let level = "admin"
let mac = sha512(secret + client.getUA() + dest + rand + parseInt(time).toString() + level + parseInt(timeEnd).toString())  // using sha512 library js-sha512 and client library clientjs
this.authenticate(mac, client.getUA(), dest, rand, time, level, timeEnd)  // method from roslibjs
}}}