Version 1.4

Syntax conventions: Boldtype are literal string commands. Italics are strings to be specified by the caller. Commas within specified values must be escaped with a backslash ‘\’. Commands are case insensitive, but specified values are case sensitive. There are no spaces between comma delimited parameters. The [a|b] style syntax is “either a or b” syntax where the underlined value is the default value. The […] style syntax is optional syntax. All commands, as well as responses from the server, are terminated with a CR/LF pair.

The Protocol

A client first connects to the Fairmount SSH Server on a specified port (which defaults to 22 unless configured differently at the server), and then authenticates with either a password or a public key. The specific usernames, passwords, and public keys allowed by the server are beyond the scope of this document. After successfully authenticating with the server, the client is logged in, and a “hello” string is returned in the format:

Where x.x.x is the product version number and 1.3 is the protocol version number. It is assumed that the protocol major version numbers must match between client and server. If the protocol major version numbers do not match, the client should disconnect. If the protocol minor version numbers do not match, the client or server may choose to support a lower minor version number for backward compatibility. Starting with 1.3, clients can issue a query to determine which commands are supported by the server, reducing reliance on this protocol version number.

Commands are initiated at the client, their format is as documented below, and they are always terminated with a CR/LF pair. Commands may be chained together when appropriate in order to avoid making several round-trips to the server.

Replies from the server are also terminated by a CR/LF pair. All replies, as required by the SSH protocol, may be split up into several messages that must be concatenated together back at the client. The client should continue to read for more data until a CR/LF pair is received.

All commands have the general format:

The optional ReqID is an unsigned 32-bit decimal integer that will be returned by the returned data. If the ReqID parameter is omitted, a session-unique number will be generated by the server.

Data returned will follow the general syntax:

Synchronous data replies always will have a request ID returned. Asynchronous data replies only will return a request ID if the reply is associated with an asynchronous request. Errors will be returned as:

The error code is a 32-bit unsigned integer formatted as a hexadecimal string. Synchronous error replies always will have a request ID returned. Asynchronous error replies only will return a request ID if the reply is associated with an asynchronous request. Optionally, all commands immediately return an acknowledgment reply. If the Acks option is turned on, the client receives an immediate reply "@ReqID;OK;" followed by the command that was recognized.

The API Sets

There are three API sets available in the Fairmount SSH Server: the Fairmount Network Data Access (FANDA) APIs, the Configuration APIs, and the internal use APIs.

Access to API sets may be limited based on authentication credentials. The GetCaps command provides a mechanism to determine the capabilities of the current connection.

The FANDA APIs

GetNDL

This command requests a download of the NDL string. Returns “@ReqID;NDL=xml string” or “@ReqID;Error=code;error message”. The format of xml string is documented elsewhere.

GetMulticastKey

This command requests a download of the multicast encryption key(s). If a particular Multicast ID is not specified, all multicast keys are reported. Returns “@ReqID;MulticastKey=MulticastID,KeyGen,Base64KeyData,Base64NextKeyData” or “@ReqID;Error=code;error message”. If all multicast keys are requested, each key will be reported with a MulticastKey= response. KeyGen specifies the current key generation number in use, Base64KeyData is the current encryption key in use, and Base64NextKeyData is the next encryption key to be used after rekeying. The format of Base64KeyData and Base64NextKeyData is little-endian binary encryption key encoded as a Base64 string. The key cipher and length are described in the NDL. If multicasts are not encrypted, KeyGen will be 0 and no key data follows.

GetVar

Get the value of the variable VariableName and return it in the format specified by the SetDataFormat option. If VariableName contains embedded whitespace or periods, it must be enclosed in double quotes. At this point, VariableName must be defined in Design Pad as a global variable with network access enabled. The second form of the command may be used for structure type variables. In that case, the requested structure member is returned. If the SetDataFormat option is Base64 (the default) or String, the format of the returned data is:

The format of Base64Value is a little-endian binary value encoded as a Base64 string. The format of StringValue is a human-readable decimal value (i.e. formatted using the C-language sprintf function). If the SetDataFormat option is XML, the format of the returned data is:

where XMLString is an XML representation of the data. See Design Pad Structures for details on the XML format returned for structure data and underlying simple type data.

SetVar

Sets the value of the variable VariableName to Base64Value. Base64Value is a little-endian binary value encoded as a Base64 string. At this point, VariableName must be defined in Design Pad as a global variable with network access enabled. The second form of the command may be used for structure type variables. In that case, the requested structure member value is set. Returns "@ReqID;SetVar=Success” or “@ReqID;Error=code;error message”.

Configuration APIs

These meta-commands affect the FANDA connection itself.

Echo

The Echo command turns on or off echoing of all characters received by the server back to the client before processing. This is useful during debugging when using a command shell SSH client to talk to the server directly. No reply is given to this command.

Acks

Specifies whether acknowledgements are returned. If the client wishes to operate asynchronously, this option may be turned on. This will cause the server to immediately respond to all commands with an “<tt>@ReqID;OK;Command</tt>” string where Command is the recognized command (which may differ in case from the transmitted command). No reply is given to this command.

EOF

The EOF command signifies that the client is about to disconnect. (Future version: If the client does not send the EOF command before disconnecting, the server will maintain workspace information about the session until the session times out. This feature allows the client to reconnect after an unintended disconnect using the same logon credentials as the previous connection.) No reply is given to this command.

SetTimeout

Specifies the length of time the client may stay connected without sending a request before the server automatically disconnects. The default timeout interval is 300 seconds.
Returns “@ReqID;SetTimeout=Success” or “@ReqID;Error=code;error message”.

Keepalive

This command resets the timeout timer. The client may use this command at any time to reset the timeout timer. No reply is given to this command..

SetDataFormat

Specifies the reply format of data returned by the GetVar command.

GetCaps

This command requests a bit field indicating the capabilities of the current connection. The contents may depend on the device type, software version, and rights of the current FANDA user. Additional bits may be defined as new commands and capabilities are added in the future without requiring a change to the protocol version. Clients should simply ignore unsupported bits.

The response is:

HexByteList is a comma-separated list of capability bytes, starting with Byte 0. The client should ignore unknown bytes in the response, and should treat any missing bytes as zero. The currently defined capability flags are (Mask is in the format used by GetCaps and SetCaps):

The current max-capability response is

Asynchronous Messages

The following messages may be sent from the server to the client at any time.

EOF

The EOF asynchronous message that the server is ending the FANDA session. If present, Reason provides additional information on the reason the session is being ended.

EOF;Timeout

If a client session does not send any requests to the server within the configured timeout period, the server will send an “EOF;Timeout” string to the client and then immediately disconnect. The client may use this information to differentiate between disconnects due to timeouts and unexpected disconnects for other reasons. (Future version: Client sessions that are unexpectedly disconnected may be reconnected in the future up until the timeout period elapses by using the same logon credentials.)

EOF;Update

If a client starts an update, the server sends this message to indicate the end of the FANDA session. Any additional data transferred over the session after this message is to/from the stdin/stdout/stderr streams of the update program.

EOF;Shutdown

If a client is connected when the server is shut down, the server will send this message then immediately disconnect.

NDL

This message will be sent after the initial connection to inform the client of the current NDL in use. The format of xml string is documented elsewhere.

This message will be sent whenever there is a program change causing the NDL format to change. When the schema program is erased, an empty NDL is sent (xml string is blank). When a new schema program is loaded, the new NDL string is sent.

Internal Use APIs 

These APIs are for internal use only, and are not intended to be called by client software.

GetCapsAsync

It has no synchronous response, and causes the current caps to be sent as an asynchronous message.

SetCaps

The response is the same as the GetCaps command.

The bytes in HexByteList have the same format as a GetCaps response. The connection's current capabilities are masked with the capabilities given in this command. After this command completes, the connection's capabilities are reduced to the intersection of the two sets.

SetCapsAsync

This is an asynchronous version of SetCaps. The format and effect is the same as the SetCaps command, but there is no response.

GetNDLAsync

There is no synchronous response this command, but it will cause the NDL to be returned as an asynchronous message.

GetMulticastKeyAsync

There is no synchronous response this command, but it will cause the multicast encryption keys to be returned as an asynchronous message.

Change History

• Changes in Protocol Version 1.4:
  • Add GetMulticastKey command.
  • Add MulticastKey async message.
• Changes in Protocol Version 1.3:
  • Add Device ID to hello message.
  • Add GetCaps command.
  • Add Fairnet command.
  • Add Update command.
  • Add Lock and Unlock commands.
  • This update to the protocol is backwards-compatible with the 1.2 protocol. Existing 1.2 clients may use a 1.3 server.
• Changes in Protocol Version 1.2:
  • Initial published version?