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