Meshcentral.com
Meshcentral
Binary Channel
Design, implementation and use of
binary control channel.
Version 0.0.3
Tuesday, October 14, 2012
Ylian Saint-Hilaire
© 2011 Intel Corporation. All Rights Reserved.
Meshcentral Binary Channel
MeshCentral.com
Legal Notices and Disclaimers
Disclaimers
INTEL CORPORATION MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE. INTEL CORPORATION ASSUMES NO RESPONSIBILITY FOR ANY
ERRORS THAT MAY APPEAR IN THIS DOCUMENT. INTEL CORPORATION MAKES NO COMMITMENT
TO UPDATE NOR TO KEEP CURRENT THE INFORMATION CONTAINED IN THIS DOCUMENT.
THIS SPECIFICATION IS COPYRIGHTED BY AND SHALL REMAIN THE PROPERTY OF INTEL
CORPORATION. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE TO ANY
INTELLECTUAL PROPERTY RIGHTS IS GRANTED HEREIN.
INTEL DISCLAIMS ALL LIABILITY, INCLUDING LIABILITY FOR INFRINGEMENT OF ANY
PROPRIETARY RIGHTS, RELATING TO IMPLEMENTATION OF INFORMATION IN THIS
SPECIFICATION. INTEL DOES NOT WARRANT OR REPRESENT THAT SUCH IMPLEMENTATIONS WILL
NOT INFRINGE SUCH RIGHTS.
NO PART OF THIS DOCUMENT MAY BE COPIED OR REPRODUCED IN ANY FORM OR BY ANY MEANS
WITHOUT PRIOR WRITTEN CONSENT OF INTEL CORPORATION.
INTEL CORPORATION RETAINS THE RIGHT TO MAKE CHANGES TO THESE SPECIFICATIONS AT ANY
TIME, WITHOUT NOTICE.
Legal Notices
Intel software products are copyrighted by and shall remain the property of Intel Corporation. Use,
duplication or disclosure is subject to restrictions stated in Intel's Software License Agreement, or
in the case of software delivered to the government, in accordance with the software license
agreement as defined in FAR 52.227-7013.
The Intel logo is a registered trademark of Intel Corporation.
Other brands and names are the property of their respective owners.
i
Meshcentral Binary Channel
MeshCentral.com
Table of Contents
Legal Notices and Disclaimers .......................................................................................................... i
Disclaimers....................................................................................................................................... i
Legal Notices ................................................................................................................................... i
1.
Abstract ................................................................................................................................... 1
2.
Introduction ............................................................................................................................. 1
3.
Binary Connections ................................................................................................................. 1
4.
Binary Commands .................................................................................................................. 2
5.
Console Login ......................................................................................................................... 2
6.
Ping the server ........................................................................................................................ 3
7.
Mesh enumeration (JSON) ..................................................................................................... 3
8.
Node enumeration (JSON) ..................................................................................................... 4
9.
Mesh events ............................................................................................................................ 6
9.1
Mesh list change .............................................................................................................. 6
9.2
Node state change........................................................................................................... 6
9.3
Node push block change ................................................................................................. 7
9.4
Mesh policy block change ............................................................................................... 7
10.
Conclusion ........................................................................................................................... 7
11.
Annex 1: Command Types .................................................................................................. 8
ii
Meshcentral Binary Channel
MeshCentral.com
Document Changes
October 9, 2012 – 0.0.1
Initial version
October 10, 2012 – 0.0.2
User authentication fixed, added node state change.
October 14, 2012 – 0.0.2
Added console AJAX cookie login in the latest version of the Swarm Server.
iii
Meshcentral Binary Channel
MeshCentral.com
1. Abstract
In this document, we review the design, implementation and use of the Mesh binary protocol used
to communicate between various mesh components. This binary protocol is defined to be very
lightweight, mostly stateless and is intended to multiplex many different types on payloads into a
single communication channel.
2. Introduction
In order to efficiently pass messages between various mesh actors, a mesh binary protocol was
defined. It is intended to be very lightweight and easy to encode and decode. We also opted to
create this protocol so that we would make most efficient use of a TCP connection and have full
two-way communication between two nodes.
This document is intended for developers that want to build their own mesh binary code. Most
developers will likely use an existing library like “Meshcentral.js” in Javascript or the existing C#
library.
3. Binary Connections
The most likely use of this document is to build a management console that connects directly to
the SwarmServer (generally port 8080) and uses the two way channel to list meshes and nodes,
perform management operations, get events and open TCP data tunnels.
In order to get started, open a TLS connection to the SwarmServer. If a client certificate is used,
the Swarm Server will use that certificate to determine if this is a mesh agent or an Intel AMT
CIRA connection. If no client certificate is used, the swarm server will establish the connection as
being from a management console. In this document, we will cover only the management console
1
Meshcentral Binary Channel
MeshCentral.com
case. So, developer should just open a TLS connection to the swarm server without a client
certificate.
4. Binary Commands
Each mesh binary command starts with a 4 byte header. Two bytes for the command type and
two bytes for the command size like this:
The type and size fields and most of the content in the data for various messages are encoded
using network byte order. The size field contains the size of the entire command; this includes
both the header and the data.
As a reminder, when reading from a TCP stream, a single TCP data read may contain many
commands or partial commands. It’s important to read at least 4 bytes and then, using the size
field, to continue reading until an entire command is read.
5. Console Login
Once connected to the Swarm Server using TLS, the first command an administrative console
program must send is a log-in. If any other command is sent, the Swarm Server will disconnect.
This is a single command that includes the UTF-8 encoded username and password. If the user
length field is zero followed by a password length and a password, the password is understood to
be an “AJAX cookie” which is a temporary login token. Using an AJAX cookie can be useful when
an application is launched from the web site. The web site can provide a temporary token so that
the user does not have to log in again.
If invalid credentials are passed, the returned command will be an error message:
2
Meshcentral Binary Channel
MeshCentral.com
Following this message, the connection will be closed by the Swarm Server. If the login is
successful, the following short message will be returned:
This indicates that the login was successful and that a new command can be sent to the Swarm
Server
6. Ping the server
For testing, developers can PING the server using the PING command. With this command all
data is ignored, so a short 4-byte command is generally sent:
As a reply, the Swarm Server sends back an empty NODEID command:
Note: the NODEID was used as the reply because we are re-using command identifiers. The
command names make more sense in communications between mesh agents.
7. Mesh enumeration (JSON)
The next step is generally to enumerate the meshes that are associated with this user account.
There are two ways to enumerate meshes. An easy way is to have the server send back a JSON
document with all of the meshes. To make this happen, just send the following command:
3
Meshcentral Binary Channel
MeshCentral.com
The server will build a JSON response with the list of all meshes accessible for this account along
with extra information for each mesh. The returned command is:
The JSON is UTF-8 encoded; here is an example of what it looks like:
[
{"meshid":"7EADAF3F460CD55C40E45ECD7ADE5C787B6230A7956AAFFA9D5660DB8AD71DF4",
"rights":"1","serial":"83","name":"Intel Oregon Mesh Lab","nodecount":"29"},
{"meshid":"836C4169D276FB3900D22DF5384B05647389A3F1CF42A2645EAF8700057F55E5",
"rights":"1","serial":"6","name":"vProCloud-Test","nodecount":"9"},
{"meshid":"8B2A1475B911790EF60674E3DDDCAEA0A9B3F5AA248527DBE879CD8B87BB5523",
"rights":"1","serial":"1","name":"tst","nodecount":"0"},
{"meshid":"8D65C9167E3268F0EE024813C9C32C4247EDEC6D9E5C60C5AACE10C0D68E8492",
"rights":"1","serial":"1","name":"MyMesh","nodecount":"8"},
{"meshid":"8DA18D35873052F6C95A0951B9C6E1FE7B7312D92E3C10EDD3E362D0BBC2052B",
"rights":"1","serial":"1","name":"Intel Labs","nodecount":"0"}
]
The response is a simple JSON array with a list of elements. Each element has a MeshId, rights,
serial, name and nodecount.
MeshId: The SHA256 hash of the public key of the mesh. This uniquely identifies a
mesh. The value is HEX encoded.
Rights: The right this account has on the mesh. 1 is administrator, 2 is viewer.
Serial: The current serial number of the latest mesh policy. Starts at 1 when a new mesh
is creates and goes up each time a mesh policy is changed.
Name: The name of the mesh. This can be changed by updating the mesh policy.
NodeCount: The number of nodes known to be attached to this mesh.
8. Node enumeration (JSON)
After enumerating the meshes of an account, developers will generally want to enumerate nodes
associated with each mesh. To enumerate the nodes in a mesh, send the following command to
the swarm server:
In response, the swarm server will return a JSON document:
4
Meshcentral Binary Channel
MeshCentral.com
The JSON data is UTF-8 encoded and looks something like this:
[
{"nodeid":"8388D0A3CFC16B43C1B77748E04AE3505513FCA3A0CE42200F6DC23517C5E2DF",
"serial":"2165","name":"AmtMachine1","desc":"Windows NT 5.1.2600",
"agentversion":"156","agentid":"3","type":"1","powerstate":"1",
"amt":{"version":"v3.0.30","mode":"2","state":"2","tls":"False"}},
{"nodeid":"A65C5D5D54BD72E70FDEF2FA9BF696F0BAE80BA74513D3EC2AE535C2BFEBC43C",
"serial":"181","name":"AmtMachine2","desc":"Windows NT 6.1.7601",
"agentversion":"156","agentid":"3","type":"1","powerstate":"0",
"amt":{"version":"v2.1.22","mode":"2","state":"2","tls":"False"}},
{"nodeid":"84BA55DC15EED7CF94D2DAD1511ECA289FD16A1432B8276D6860FB58E60EF453",
"serial":"116","name":"Classmate","desc":"POSIX","agentversion":"156",
"agentid":"5","type":"2","powerstate":"0"},
{"nodeid":"17617FF5F8CFF875B80731C8BF69F97040236371FC3C02094FE3B5D17B4D3B43",
"serial":"1857","name":"CorwinSprings","desc":"Windows NT 6.1.7601",
"agentversion":"156","agentid":"3","type":"1","powerstate":"1",
"amt":{"version":"v5.2.0","mode":"1","state":"0","tls":"False"}},
{"nodeid":"DE718694BF8BF7509706292081E8AC093D19C9092199DBF18669E34F4E4FFF20",
"serial":"23","name":"default-desktop","desc":"POSIX",
"agentversion":"156","agentid":"5","type":"2","powerstate":"0"},
]
The response is a simple JSON array with a list of elements. Each element has: nodeid, serial,
name, description, agentversion, agentid, type and power state. Some nodes will additionally
have an AMT element with sub-elements.
NodeId: The SHA256 hash of the public key of the node. This uniquely identifies a node.
The value is HEX encoded.
Serial: The current serial number of the latest mesh push block. Starts at 1 when a new
node is installed and goes up each time a node push block is changed.
Name: The name of the node, this is the name provided by the node in its push block.
Desc: Description string for this node. Generally the OS type and version, but could be
any string.
AgentVersion: The version of the mesh agent installed on this node.
AgentId: The architecture type of the mesh agent installed on this node.
Type: The icon number for this node: 1 = Desktop, 2 = Mobile, 3 = Cell phone, 4 =
Server, 5 = Set top box, 6 = Router.
PowerState: The current power state for this node. The state is zero for unknown, 1 for
S0 (Full Power), 2 for S1 (Sleep), 4 for S3 (Sleep), 5 for S4 (Hibernating), 6 for S5 (Softoff). 7 is a present state, indicating we know the machine is present of the network but
don’t know its state.
Amt: An optional set of values pulled from the HECI driver of this machine. Values
include:
5
Meshcentral Binary Channel
MeshCentral.com
o
Version: The Intel AMT version.
o
Mode: 0 = Pre-Provisioning, 1 = In-Provisioning, 2 = Provisioned.
o
State: 1 = Enterprise mode, 2 = Small Business, 3 = Remote.
o
TLS: True if Intel AMT TLS is configured with TLS, false if not.
9. Mesh events
While connected to the Swarm Server, some messages can be sent by the server at any time.
These messages are the MeshAccessChange (1011), NodePush (1) and Policy (17). Any
console software connecting to the swarm server should be able to handle or ignore these
messages.
9.1 Mesh list change
If the list of meshes available to this account changes in any way, this short message is sent by
the server. Reception of this message should trigger a re-query of the mesh list and possibly the
nodes associates with each mesh.
9.2 Node state change
When a node changes power state, this message is sent to all consoles that can view or manage
this node. The message includes the node identifier and the new and old state.
The state values are the following:
0 = S0, power on
1, 2, 3 = S1, S2, S3, sleeping
4 = S4, hibernating
5 = S5, soft off.
6 = Present on the network, but unknown power state.
999 = Unknown state, disconnected.
6
Meshcentral Binary Channel
MeshCentral.com
The node state change event will tend to lag the actual state of the node by up to 2 minutes
depending on the type of state transition that occurred. To better handle the many state
transitions that can occur at the same time on different nodes, the Swarm Servers batch up
transitions. As a result, node state transition events may occur in “bursts”.
9.3 Node push block change
If a node push block is updated, the block is sent out to any console software that has access
rights to that node. The node block contains information about that node including, name, mac
addresses, network interface IP address and more. The block is signed by the node and contains
a serial number that increments each time the block is updated. The node block is PKCS#7
signed and tricky to decode; it’s probably best to use the existing C or C# decoding code if you
need to decode node push blocks.
9.4 Mesh policy block change
If a mesh policy block is updated by the administrator, it will be sent out to any console software
that has access rights to that mesh. The mesh block contains policy information that all nodes on
this mesh should follow including what swarm server to connect to, access rights, mesh name
and more. The mesh policy block is PKCS#7 signed and tricky to decode; it’s probably best to
use the existing C or C# decoding code if you need to decode mesh policy blocks.
10. Conclusion
The Mesh technology binary protocol offers an efficient, two-way stateless communication
channel that can be used to efficiently monitor and manage computers over the internet. With this
document, any developer can write a cloud management application.
7
Meshcentral Binary Channel
MeshCentral.com
11. Annex 1: Command Types
Here is the list of all the possible commands defined so far. Some of these commands are only
possible between the mesh agent and the swarm server, some between an administration
console and the mesh server and some both.
NODEPUSH = 1,
NODEPULL = 2,
NODENOTIFY = 3,
NODECHALLENGE = 4,
NODECRESPONSE = 5,
TARGETSTATUS = 6,
LOCALEVENT = 7,
AESCRYPTO = 8,
SESSIONKEY = 9,
SYNCSTART = 10,
SYNCMETADATA = 11,
SYNCREQUEST = 12,
NODEID = 13,
AGENTID = 14,
PING = 15,
SETUPADMIN = 16,
POLICY = 17,
POLICYSECRET = 18,
EVENTMASK = 19,
RECONNECT = 20,
GETSTATE = 21,
CERTENCRYPTED = 22,
GETCOOKIE = 23,
COOKIE = 24,
SESSIONCKEY = 25,
INTERFACE = 26,
MULTICAST = 27,
SELFEXE = 28,
LEADERBADGE = 29,
NODEINFO = 30,
TARGETEVENT = 31,
DEBUG = 33,
TCPRELAY = 34,
CERTSIGNED = 35,
ERRORCODE = 36,
MESSAGE = 37,
CMESSAGE = 38,
EMESSAGE = 39,
SEARCH = 40,
MESSAGERELAY = 41,
USERINPUT = 42,
APPID = 43,
APPSUBSCRIBE = 44,
APPDIRECT = 45,
APPREQACK = 46,
APPACK = 47,
SERVERECHO = 48,
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
Used to send a node block to another peer.
Used to send a pull block to another peer.
Used to indicate the node ID to other peers.
Used to challenge a node identity.
Used to respond to a node challenge.
Used to send the peer connection status list.
Used to send local events to subscribers.
Used to send an encrypted block of data.
Used to send a session key to a remote node.
Used to send kick off the SYNC request, send the start NodeID.
Used to send a sequence of NodeID & serial numbers.
Used to send a sequence of NodeID's to request.
Used to send the NodeID in the clear. Used for multicast.
Used to send the AgentID & version to the other node.
Used to query a target for the presence of the mesh agent
(PB_NODEID response expected).
Used to set the trusted mesh identifier
this code can only be used from local settings file.
Used to send a policy block to another peer.
Used to encode the PKCS12 private key of a policy block.
Used by the mesh service to change the event mask.
Used by the mesh service to indicate
disconnect & reconnection after n seconds.
Used by the mesh service to obtain agent state.
Used to send a certificate encrypted message to a node.
Used to request a certificate encryption anti-replay cookie.
Used to carry an anti-replay cookie to a requestor.
Used to send a session key to a remote console.
Used to send a local interface blob to a management console.
Used by the mesh service to cause the agent to
send a multicast.
Used to transfer our own agent executable.
User to send a leadership badge.
Used to indicate a block information update to the
web service.
Used to send a single target update event.
Used to send debug information to web service.
Used to operate mesh leader TCP relay sockets
Used to send a certificate signed message to a node.
Used to notify of an error.
Used to route messages between nodes.
Used to embed an interface identifier along with a PB_MESSAGE.
Used to embed a target encryption certificate
along with a MESSAGE or CMESSAGE.
Used to send a custom search to one or more remote nodes.
Used by no-certificate consoles to send hopping
messages to nodes.
Used to send user keyboard input to a target computer
Used to send a block of data to a specific
application identifier.
Used to perform local app subscription to an agent.
Used to send message directly to remote applications.
Used to request an ack message.
Used to ack a received message.
Server will echo this message, used for testing.
8
Meshcentral Binary Channel
KVMINFO = 49,
REMOTEWAKE = 50,
CUSTOM = 100,
USERAUTH = 1000,
USERMESH = 1001,
USERMESHS = 1002,
USERNODES = 1003,
JUSERMESHS = 1004,
JUSERNODES = 1005,
USERPOWERSTATE = 1006,
JMESHPOWERTIMELINE = 1007,
JMESHPOWERSUMMARY = 1008,
USERCOMMAND = 1009,
POWERBLOCK = 1010,
MESHACCESSCHANGE = 1011,
COOKIEAUTH = 1012,
NODESTATECHANGE = 1013,
JUSERNODE = 1014,
MeshCentral.com
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
Used to send local KVM slave process information
to mesh agent.
Used to send remote wake information to server.
Message containing application specific data.
Authenticate a user to the swarm server.
Request or return the mesh list for this console.
Send mesh overview information to the console.
Send node overview information to the console.
Send mesh overview information to the console in JSON format.
Send node overview information to the console in JSON format.
Used to send a power command from the console to the server.
Send the power timeline for all nodes in a mesh.
Send the power summary for sum of all nodes in a mesh.
Send a user admin text command to and from the server.
Request/Response of block of power state information.
Notify a console of a change in accessible meshes.
Authenticate a user using a crypto cookie.
Indicates a node has changed power state.
Send node overview information to the console in JSON format.
9
