MUST have been set by the server in the server greeting). The first
29 bits of Mode MUST be zero. A server MUST ignore the values of the
first 29 bits. If zero Mode bits are set by the client, the client
indicates that it will not continue with the session; in this case,
the client and the server SHOULD close the TCP connection associated
with the OWAMP-Control session.
In unauthenticated mode, KeyID, Token, and Client-IV are unused.
Otherwise, KeyID is a UTF-8 string, up to 80 octets in length (if the
string is shorter, it is padded with zero octets), that tells the
server which shared secret the client wishes to use to authenticate
or encrypt, while Token is the concatenation of a 16-octet challenge,
a 16-octet AES Session-key used for encryption, and a 32-octet HMAC-
SHA1 Session-key used for authentication. The token itself is
encrypted using the AES (Advanced Encryption Standard) [AES] in
Cipher Block Chaining (CBC). Encryption MUST be performed using an
Initialization Vector (IV) of zero and a key derived from the shared
secret associated with KeyID. (Both the server and the client use
the same mappings from KeyIDs to shared secrets. The server, being
prepared to conduct sessions with more than one client, uses KeyIDs
to choose the appropriate secret key; a client would typically have
different secret keys for different servers. The situation is
analogous to that with passwords.)
The shared secret is a passphrase; it MUST not contain newlines. The
secret key is derived from the passphrase using a password-based key
derivation function PBKDF2 (PKCS #5) [RFC2898]. The PBKDF2 function
requires several parameters: the PRF is HMAC-SHA1 [RFC2104]; the salt
and count are as transmitted by the server.
AES Session-key, HMAC Session-key and Client-IV are generated
randomly by the client. AES Session-key and HMAC Session-key MUST be
generated with sufficient entropy not to reduce the security of the
underlying cipher [RFC4086]. Client-IV merely needs to be unique
(i.e., it MUST never be repeated for different sessions using the
same secret key; a simple way to achieve that without the use of
cumbersome state is to generate the Client-IV values using a
cryptographically secure pseudo-random number source: if this is
done, the first repetition is unlikely to occur before 2^64 sessions
with the same secret key are conducted).
The server MUST respond with the following Server-Start message:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| MBZ (15 octets) |
| |
| +-+-+-+-+-+-+-+-+
| | Accept |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| Server-IV (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Start-Time (Timestamp) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| MBZ (8 octets) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The MBZ parts MUST be zero. The client MUST ignore their value. MBZ
(MUST be zero) fields here and after have the same semantics: the
party that sends the message MUST set the field so that all bits are
equal to zero; the party that interprets the message MUST ignore the
value. (This way, the field could be used for future extensions.)
Server-IV is generated randomly by the server. In unauthenticated
mode, Server-IV is unused.
The Accept field indicates the server’s willingness to continue
communication. A zero value in the Accept field means that the
server accepts the authentication and is willing to conduct further
transactions. Non-zero values indicate that the server does not
accept the authentication or, for some other reason, is not willing
to conduct further transactions in this OWAMP-Control session. The
full list of available Accept values is described in Section 3.3,
"Values of the Accept Field".
If a negative (non-zero) response is sent, the server MAY (and the
client SHOULD) close the connection after this message.
Start-Time is a timestamp representing the time when the current
instantiation of the server started operating. (For example, in a
multi-user general purpose operating system, it could be the time
when the server process was started.) If Accept is non-zero, Start-
Time SHOULD be set so that all of its bits are zeros. In
authenticated and encrypted modes, Start-Time is encrypted as
described in Section 3.4, "OWAMP-Control Commands", unless Accept is
non-zero. (Authenticated and encrypted mode cannot be entered unless
the control connection can be initialized.)
Timestamp format is described in Section 4.1.2. The same
instantiation of the server SHOULD report the same exact Start-Time
value to each client in each session.
The previous transactions constitute connection setup.
3.2. Integrity Protection (HMAC)
Authentication of each message (also referred to as a command in this
document) in OWAMP-Control is accomplished by adding an HMAC to it.
The HMAC that OWAMP uses is HMAC-SHA1 truncated to 128 bits. Thus,
all HMAC fields are 16 octets. An HMAC needs a key. The HMAC
Session-key is communicated along with the AES Session-key during
OWAMP-Control connection setup. The HMAC Session-key SHOULD be
derived independently of the AES Session-key (an implementation, of
course, MAY use the same mechanism to generate the random bits for
both keys). Each HMAC sent covers everything sent in a given
direction between the previous HMAC (but not including it) and up to
the beginning of the new HMAC. This way, once encryption is set up,
each bit of the OWAMP-Control connection is authenticated by an HMAC
exactly once.
When encrypting, authentication happens before encryption, so HMAC
blocks are encrypted along with the rest of the stream. When
decrypting, the order, of course, is reversed: first one decrypts,
then one checks the HMAC, then one proceeds to use the data.
The HMAC MUST be checked as early as possible to avoid using and
propagating corrupt data.
In open mode, the HMAC fields are unused and have the same semantics
as MBZ fields.
3.3. Values of the Accept Field
Accept values are used throughout the OWAMP-Control protocol to
communicate the server response to client requests. The full set of
valid Accept field values are as follows:
0 OK.
1 Failure, reason unspecified (catch-all).
2 Internal error.
3 Some aspect of request is not supported.
4 Cannot perform request due to permanent resource limitations.
5 Cannot perform request due to temporary resource limitations.
All other values are reserved. The sender of the message MAY use the
value of 1 for all non-zero Accept values. A message sender SHOULD
use the correct Accept value if it is going to use other values. The
message receiver MUST interpret all values of Accept other than these
reserved values as 1. This way, other values are available for
future extensions.
3.4. OWAMP-Control Commands
In authenticated or encrypted mode (which are identical as far as
OWAMP-Control is concerned, and only differ in OWAMP-Test), all
further communications are encrypted with the AES Session-key (using
CBC mode) and authenticated with HMAC Session-key. The client
encrypts everything it sends through the just-established OWAMP-
Control connection using stream encryption with Client-IV as the IV.
Correspondingly, the server encrypts its side of the connection using
Server-IV as the IV.
The IVs themselves are transmitted in cleartext. Encryption starts
with the block immediately following the block containing the IV.
The two streams (one going from the client to the server and one
going back) are encrypted independently, each with its own IV, but
using the same key (the AES Session-key).
The following commands are available for the client: Request-Session,
Start-Sessions, Stop-Sessions, and Fetch-Session. The command Stop-
Sessions is available to both the client and the server. (The server
can also send other messages in response to commands it receives.)
After the client sends the Start-Sessions command and until it both
sends and receives (in an unspecified order) the Stop-Sessions
command, it is said to be conducting active measurements. Similarly,
the server is said to be conducting active measurements after it
receives the Start-Sessions command and until it both sends and
receives (in an unspecified order) the Stop-Sessions command.
While conducting active measurements, the only command available is
Stop-Sessions.
These commands are described in detail below.
3.5. Creating Test Sessions
Individual one-way active measurement sessions are established using
a simple request/response protocol. An OWAMP client MAY issue zero
or more Request-Session messages to an OWAMP server, which MUST
respond to each with an Accept-Session message. An Accept-Session
message MAY refuse a request.
The format of Request-Session message is as follows:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 | MBZ | IPVN | Conf-Sender | Conf-Receiver |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Number of Schedule Slots |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Number of Packets |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sender Port | Receiver Port |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sender Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| Sender Address (cont.) or MBZ (12 octets) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Receiver Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| Receiver Address (cont.) or MBZ (12 octets) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| SID (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Padding Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Start Time |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Timeout, (8 octets) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type-P Descriptor |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| MBZ (8 octets) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| HMAC (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This is immediately followed by one or more schedule slot
descriptions (the number of schedule slots is specified in the
"Number of Schedule Slots" field above):
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Slot Type | |
+-+-+-+-+-+-+-+-+ MBZ (7 octets) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Slot Parameter (Timestamp) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
These are immediately followed by HMAC:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| HMAC (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
All these messages constitute one logical message: the Request-
Session command.
Above, the first octet (1) indicates that this is the Request-Session
command.
IPVN is the IP version numbers for Sender and Receiver. When the IP
version number is 4, 12 octets follow the 4-octet IPv4 address stored
in Sender Address and Receiver Address. These octets MUST be set to
zero by the client and MUST be ignored by the server. Currently
meaningful IPVN values are 4 and 6.
Conf-Sender and Conf-Receiver MUST be set to 0 or 1 by the client.
The server MUST interpret any non-zero value as 1. If the value is
1, the server is being asked to configure the corresponding agent
(sender or receiver). In this case, the corresponding Port value
SHOULD be disregarded by the server. At least one of Conf-Sender and
Conf-Receiver MUST be 1. (Both can be set, in which case the server
is being asked to perform a session between two hosts it can
configure.)
Number of Schedule Slots, as mentioned before, specifies the number
of slot records that go between the two blocks of HMAC. It is used
by the sender to determine when to send test packets (see next
section).
Number of Packets is the number of active measurement packets to be
sent during this OWAMP-Test session (note that either the server or
the client can abort the session early).
If Conf-Sender is not set, Sender Port is the UDP port from which
OWAMP-Test packets will be sent. If Conf-Receiver is not set,
Receiver Port is the UDP port OWAMP-Test to which packets are
requested to be sent.
The Sender Address and Receiver Address fields contain, respectively,
the sender and receiver addresses of the end points of the Internet
path over which an OWAMP test session is requested.
SID is the session identifier. It can be used in later sessions as
an argument for the Fetch-Session command. It is meaningful only if
Conf-Receiver is 0. This way, the SID is always generated by the
receiving side. See the end of the section for information on how
the SID is generated.
Padding length is the number of octets to be appended to the normal
OWAMP-Test packet (see more on padding in discussion of OWAMP-Test).
Start Time is the time when the session is to be started (but not
before Start-Sessions command is issued). This timestamp is in the
same format as OWAMP-Test timestamps.
Timeout (or a loss threshold) is an interval of time (expressed as a
timestamp). A packet belonging to the test session that is being set
up by the current Request-Session command will be considered lost if
it is not received during Timeout seconds after it is sent.
Type-P Descriptor covers only a subset of (very large) Type-P space.
If the first two bits of the Type-P Descriptor are 00, then the
subsequent six bits specify the requested Differentiated Services
Codepoint (DSCP) value of sent OWAMP-Test packets, as defined in
[RFC2474]. If the first two bits of Type-P descriptor are 01, then
the subsequent 16 bits specify the requested PHB Identification Code
(PHB ID), as defined in [RFC2836].
Therefore, the value of all zeros specifies the default best-effort
service.
If Conf-Sender is set, the Type-P Descriptor is to be used to
configure the sender to send packets according to its value. If
Conf-Sender is not set, the Type-P Descriptor is a declaration of how
the sender will be configured.
If Conf-Sender is set and the server does not recognize the Type-P
Descriptor, or it cannot or does not wish to set the corresponding
attributes on OWAMP-Test packets, it SHOULD reject the session
request. If Conf-Sender is not set, the server SHOULD accept or
reject the session, paying no attention to the value of the Type-P
Descriptor.
To each Request-Session message, an OWAMP server MUST respond with an
Accept-Session message:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Accept | MBZ | Port |