Ubuntu Wiki

This protocol is a work in progress and is not complete.

The remote input server uses an open protocol with encryption and authentication to communicate between the clients and the server.

Security

When the client connects to the server, an SSL connection must be initiated immediately. Most remote input server installations use self-signed certificates, so the client should be able to verify the server through the SSL certificate fingerprint. The fingerprint is a digest (usually SHA1) of the DER form of the SSL certificate. It may be determined on the server by running:

$ openssl x509 -noout -in <certificate file> -fingerprint

If the client cannot verify the certificate through the certificate authority chain or by fingerprint verification it must close the connection immediately.

Authentication

After the SSL connection has been created, the client must send authentication credentials to the server. The credentials have the following form:

The credentials length field specifies the total size of the following fields. The NULL fields must be set to 0. These fields put two limits on the username and password:

1. The combined length of the username and password, not including the null terminator, must be less than 253.
2. The username and the password may not include the null character.

The server must validate the credentials. The server sends a one byte message to the client indicating whether the credentials are valid:

If the result was invalid, the server must immediately close all communication with the client after sending the credential validation result. If the client was authenticated, the client should begin the input device initialization process.

Remote Input Message Protocol

All communication after the channel has been secured and authenticated must follow the Remote Input Message Protocol. All messages are padded as necessary to have a length of 12 bytes. All values larger than one byte in length are in network byte order. The first four bytes are an unsigned integer specifying the message type. The following messages are supported in version 1 of the remote input message protocol:

Version Message

This message, sent by the remote input server, specifies the version of the remote input message protocol. This standard defines only version 1 of the protocol, so the value must be 1.

Input Device Set Bit Message

This message, sent by the remote input client, specifies a capability of the remote input device. The server must ensure that the input device instantiated is capable of receiving events of this type.

Capability Types

There a seven capability event categories. To enable event capabilities in a category, the category itself must be enabled. This is accomplished by using the Input Event Capability Category type and the category's type value as defined in linux/input.h. After enabling a capability category, event capabilities may be set. This is accomplished by using the event capability type value listed in the table below with the capability code listed in linux/input.h.

Note that the category's type value in linux/input.h may or may not match the category type value specified in the table below.

Input Device Initialization

After the communication channel has been secured and authenticated, the client must begin initializing the input device to be instantiated by the server.