RemoteInputProtocol
9598
Comment:
|
9521
|
Deletions are marked like this. | Additions are marked like this. |
Line 152: | Line 152: |
Message Type; Capability Type (From Remote Input Set Capability Message Capability Types); Capability Code (From linux/input.h) | Message Type; Capability Category; Capability Code |
This protocol is a work in progress and is not complete.
Contents
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 field must be set to 0. These fields put two limits on the username and password:
- The combined length of the username and password, not including the null terminator, must be less than 253.
- 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. The remote input client may terminate the connection with the server at any point, and the server must immediately destroy all state associated with the connection. The server must not terminate the connection except after an error message with a type that requires the server to do so. Any other connection termination by the server should be interpreted by the client to be in error.
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:
Remote Input 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 Capability 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 Categories
The following capability categories are specified for version 1 of the remote input message protocol. Values are provided in rinput.h header file.
Event capability categories not listed above, such as force feedback events, are not supported in this version of the remote input message protocol.
Input Device Create Message
This message informs the remote input server that the full capabilities of the remote input device have been set. The server must then create the input device.
Input Device Destroy Message
This message informs the remote input server that the input device must be destroyed.
Input Device Event Message
This message informs the remote input server that the remote input client had an input event.
Input Device Error Message
The remote input server must send an error message to the client if certain errors are encountered.
Error Events and Codes
If any of the following events occurs in the remote input server, it must send the matching event error code to the client. If the error requires the server to close the connection, the server must close the connection immediately after sending the error message.
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. All messages after authentication must conform to the remote input message protocol.
At any point the server may send an error message to the client and, if allowed for the error type, then terminate the connection.
The following initialization steps must be performed by the client in order:
Receive remote input protocol version message from server
The client must receive the protocol version and determine whether to proceed based on whether the client supports the protocol version. If the client does not proceed, it must immediately terminate communication with the server.
Set input device capabilities
The client must send the capabilities of the input device it represents.
Example: Simple one button mouse
To set the capabilities for a simple remote mouse with one button and no scroll wheels, send input event set capability messages with the following values (defined in rinput.h header file):
Create input device
The client must send the input device create message after all the device capabilities have been set.
Input Device Events
After the remote input device has been initialized, the client may send input device event messages. There is no explicit documentation for the values allowed, but they may be inferred from the rinput.h header file.
One special addition to the input protocol is necessary for momentary key presses. When the server receives a key event with value 256 it must immediately propagate two key events with the same code to the input subsystem: the first with value 1 and the second with value 0.
After any message, the server may send an error message back. The error message is in reference to a previous remote input event message, but the specific message causing the error is left unspecified.
When the remote input client intends to end the remote input session it must immediately close the communication channel to the remote input server.
RemoteInput/RemoteInputProtocol (last edited 2009-10-12 16:02:52 by cpe-75-180-27-10)