D.1 Message Format and Magic Constants

only for RuBoard - do not distribute or recompile

D.1 Message Format and Magic Constants

An HTCP message consists of three sections: HEADER, DATA, and AUTH. All multioctet fields are encoded in network byte order.

D.1.1 HEADER

Figure D-1 shows the four-octet, fixed- size HTCP HEADER section. The LENGTH field specifies the size of the UDP message, and it should be equal to the number of octets written to and read from the network. MAJOR and MINOR specify the protocol version the sender is using. A change in the minor version number must not affect compatibility. In particular, when a reserved field is placed into service, the minor version number is incremented. When new fields or identifiers are added, the major version number is incremented.

Figure D-1. HTCP HEADER format

D.1.2 DATA

The DATA section, shown in Figure D-2, is where all the interesting stuff happens. It consists of eight fixed-format octets followed by a variable- sized OP-DATA field.

Figure D-2. HTCP DATA format

These are the DATA section fields:

LENGTH

This LENGTH field, not to be confused with the HEADER section LENGTH field, specifies the number of octets comprising the DATA section. This is needed, of course, because the OP-DATA field varies in size.

OPCODE

HTCP Version 0.0 defines five opcodes: NOP, TST, MON, SET, and CLR. These are fully discussed in Section D.3. Note that the OPCODE field is only 4 bits wide, which allows for up to 16 opcodes.

RESPONSE

RESPONSE is a numeric error code set for response messages only. Furthermore, this field is only meaningful when the F1 flag is set. This field must be ignored for query messages (RR=0) and when F1 equals 0.

When F1 is set, RESPONSE codes are interpreted as given in Table D-1. When F1 is not set, the RESPONSE code has an opcode-specific meaning, as described in Section D.3.

Table  D-1. HTCP Overall Response Codes

Code	Description
	AUTHENTICATION wasn't used but is required.
1	AUTHENTICATION was used but unsatisfactorily.
2	OPCODE not implemented.
3	MAJOR version not supported.
4	MINOR version not supported (MAJOR version is okay).
5	Inappropriate, disallowed , or undesirable OPCODE.

RESERVED

In HTCP/0.0, these 6 bits are reserved for future use.

F1

F1 is a single-bit flag whose meaning is different for requests and responses. In a request, F1 indicates whether a response is desired. Certain opcodes, such as TST, are meaningless unless F1 is set. For other opcodes, such as CLR, the response is optional.

When F1 is set in a response message, the RESPONSE code refers to the overall message. F1 is set only when an error occurs. If the operation succeeds, F1 is not set and RESPONSE takes on an opcode-specific meaning, which may indicate some other kind of error.

RR

The RR bit simply indicates whether a particular message is a request or a response. The bit is not set for requests and set for responses.

MSG-ID

This is a 32-bit identifier that uniquely identifies an HTCP transaction. The MSG-ID value must be copied from a request message into the corresponding response. Usually, there is a one-to-one pairing between requests and responses. The MON request, however, may result in numerous MON responses. Thus, many MON responses may have the same MSG-ID.

OP-DATA

The content of the OP-DATA field is opcode-specific and usually different for requests and responses. These are fully explained in Section D.3.

D.1.3 AUTH

Figure D-3 shows the AUTH section, which is optional in HTCP/0.x. Its purpose is to provide some level of assurance that a particular message has not been spoofed by a third party.

Figure D-3. HTCP AUTH format

The following list describes the AUTH section fields:

LENGTH

The LENGTH field specifies the number of octets in the entire AUTH section. If authentication is not to be used for a particular message, then the LENGTH field is set to 2, and the remaining fields are dropped.

SG-TIME

SIG-TIME is the time at which the SIGNATURE is generated. The time is expressed as the number of seconds since midnight on January 1, 1970 UTC (also known as "Unix time").

SIG-EXPIRE

This is the time at which the SIGNATURE expires . It is also expressed as the number of seconds since midnight on January 1, 1970.

KEY- NAME

This field is the name of a shared secret key. It is only a name used to identify a key and not the key itself. The secret key named by this field is used in the HMAC-MD5 algorithm.

SIGNATURE

The SIGNATURE is an HMAC-MD5 digest [Krawczyk, Bellare and Canetti, 1997] of the concatenation of the ten fields shown in Figure D-4.

Figure D-4. HTCP SIGNATURE format

only for RuBoard - do not distribute or recompile