tech-invite   World Map
3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search     Home

RFC 4656

Proposed STD
Pages: 56
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: IPPM

A One-way Active Measurement Protocol (OWAMP)

Part 1 of 2, p. 1 to 27
None       Next RFC Part

Updated by:    7717    7718


Top       ToC       Page 1 
Network Working Group                                        S. Shalunov
Request for Comments: 4656                                 B. Teitelbaum
Category: Standards Track                                        A. Karp
                                                                J. Boote
                                                            M. Zekauskas
                                                               Internet2
                                                          September 2006


             A One-way Active Measurement Protocol (OWAMP)

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   The One-Way Active Measurement Protocol (OWAMP) measures
   unidirectional characteristics such as one-way delay and one-way
   loss.  High-precision measurement of these one-way IP performance
   metrics became possible with wider availability of good time sources
   (such as GPS and CDMA).  OWAMP enables the interoperability of these
   measurements.

Table of Contents

   1. Introduction ....................................................2
      1.1. Relationship of Test and Control Protocols .................3
      1.2. Logical Model ..............................................4
   2. Protocol Overview ...............................................5
   3. OWAMP-Control ...................................................6
      3.1. Connection Setup ...........................................6
      3.2. Integrity Protection (HMAC) ...............................11
      3.3. Values of the Accept Field ................................11
      3.4. OWAMP-Control Commands ....................................12
      3.5. Creating Test Sessions ....................................13
      3.6. Send Schedules ............................................18
      3.7. Starting Test Sessions ....................................19
      3.8. Stop-Sessions .............................................20
      3.9. Fetch-Session .............................................24

Top      ToC       Page 2 
   4. OWAMP-Test .....................................................27
      4.1. Sender Behavior ...........................................28
           4.1.1. Packet Timings .....................................28
           4.1.2. OWAMP-Test Packet Format and Content ...............29
      4.2. Receiver Behavior .........................................33
   5. Computing Exponentially Distributed Pseudo-Random Numbers ......35
      5.1. High-Level Description of the Algorithm ...................35
      5.2. Data Types, Representation, and Arithmetic ................36
      5.3. Uniform Random Quantities .................................37
   6. Security Considerations ........................................38
      6.1. Introduction ..............................................38
      6.2. Preventing Third-Party Denial of Service ..................38
      6.3. Covert Information Channels ...............................39
      6.4. Requirement to Include AES in Implementations .............39
      6.5. Resource Use Limitations ..................................39
      6.6. Use of Cryptographic Primitives in OWAMP ..................40
      6.7. Cryptographic Primitive Replacement .......................42
      6.8. Long-term Manually Managed Keys ...........................43
      6.9. (Not) Using Time as Salt ..................................44
      6.10. The Use of AES-CBC and HMAC ..............................44
   7. Acknowledgements ...............................................45
   8. IANA Considerations ............................................45
   9. Internationalization Considerations ............................46
   10. References ....................................................46
      10.1. Normative References .....................................46
      10.2. Informative References ...................................47
   Appendix A: Sample C Code for Exponential Deviates ................49
   Appendix B: Test Vectors for Exponential Deviates .................54

1.  Introduction

   The IETF IP Performance Metrics (IPPM) working group has defined
   metrics for one-way packet delay [RFC2679] and loss [RFC2680] across
   Internet paths.  Although there are now several measurement platforms
   that implement collection of these metrics [SURVEYOR] [SURVEYOR-INET]
   [RIPE] [BRIX], there is not currently a standard that would permit
   initiation of test streams or exchange of packets to collect
   singleton metrics in an interoperable manner.

   With the increasingly wide availability of affordable global
   positioning systems (GPS) and CDMA-based time sources, hosts
   increasingly have available to them very accurate time sources,
   either directly or through their proximity to Network Time Protocol
   (NTP) primary (stratum 1) time servers.  By standardizing a technique
   for collecting IPPM one-way active measurements, we hope to create an
   environment where IPPM metrics may be collected across a far broader
   mesh of Internet paths than is currently possible.  One particularly
   compelling vision is of widespread deployment of open OWAMP servers

Top      ToC       Page 3 
   that would make measurement of one-way delay as commonplace as
   measurement of round-trip time using an ICMP-based tool like ping.

   Additional design goals of OWAMP include: being hard to detect and
   manipulate, security, logical separation of control and test
   functionality, and support for small test packets.  (Being hard to
   detect makes interference with measurements more difficult for
   intermediaries in the middle of the network.)

   OWAMP test traffic is hard to detect because it is simply a stream of
   UDP packets from and to negotiated port numbers, with potentially
   nothing static in the packets (size is negotiated, as well).  OWAMP
   also supports an encrypted mode that further obscures the traffic and
   makes it impossible to alter timestamps undetectably.

   Security features include optional authentication and/or encryption
   of control and test messages.  These features may be useful to
   prevent unauthorized access to results or man-in-the-middle attacks
   that attempt to provide special treatment to OWAMP test streams or
   that attempt to modify sender-generated timestamps to falsify test
   results.

   In this document, the key words "MUST", "REQUIRED", "SHOULD",
   "RECOMMENDED", and "MAY" are to be interpreted as described in
   [RFC2119].

1.1.  Relationship of Test and Control Protocols

   OWAMP actually consists of two inter-related protocols: OWAMP-Control
   and OWAMP-Test.  OWAMP-Control is used to initiate, start, and stop
   test sessions and to fetch their results, whereas OWAMP-Test is used
   to exchange test packets between two measurement nodes.

   Although OWAMP-Test may be used in conjunction with a control
   protocol other than OWAMP-Control, the authors have deliberately
   chosen to include both protocols in the same RFC to encourage the
   implementation and deployment of OWAMP-Control as a common
   denominator control protocol for one-way active measurements.  Having
   a complete and open one-way active measurement solution that is
   simple to implement and deploy is crucial to ensuring a future in
   which inter-domain one-way active measurement could become as
   commonplace as ping.  We neither anticipate nor recommend that
   OWAMP-Control form the foundation of a general-purpose extensible
   measurement and monitoring control protocol.

   OWAMP-Control is designed to support the negotiation of one-way
   active measurement sessions and results retrieval in a
   straightforward manner.  At session initiation, there is a

Top      ToC       Page 4 
   negotiation of sender and receiver addresses and port numbers,
   session start time, session length, test packet size, the mean
   Poisson sampling interval for the test stream, and some attributes of
   the very general [RFC 2330] notion of packet type, including packet
   size and per-hop behavior (PHB) [RFC2474], which could be used to
   support the measurement of one-way network characteristics across
   differentiated services networks.  Additionally, OWAMP-Control
   supports per-session encryption and authentication for both test and
   control traffic, measurement servers that can act as proxies for test
   stream endpoints, and the exchange of a seed value for the pseudo-
   random Poisson process that describes the test stream generated by
   the sender.

   We believe that OWAMP-Control can effectively support one-way active
   measurement in a variety of environments, from publicly accessible
   measurement beacons running on arbitrary hosts to network monitoring
   deployments within private corporate networks.  If integration with
   Simple Network Management Protocol (SNMP) or proprietary network
   management protocols is required, gateways may be created.

1.2.  Logical Model

   Several roles are logically separated to allow for broad flexibility
   in use.  Specifically, we define the following:

   Session-Sender      The sending endpoint of an OWAMP-Test session;

   Session-Receiver    The receiving endpoint of an OWAMP-Test session;

   Server              An end system that manages one or more OWAMP-Test
                       sessions, is capable of configuring per-session
                       state in session endpoints, and is capable of
                       returning the results of a test session;

   Control-Client      An end system that initiates requests for
                       OWAMP-Test sessions, triggers the start of a set
                       of sessions, and may trigger their termination;
                       and

   Fetch-Client        An end system that initiates requests to fetch
                       the results of completed OWAMP-Test sessions.

Top      ToC       Page 5 
   One possible scenario of relationships between these roles is shown
   below.

       +----------------+               +------------------+
       | Session-Sender |--OWAMP-Test-->| Session-Receiver |
       +----------------+               +------------------+
         ^                                     ^
         |                                     |
         |                                     |
         |                                     |
         |  +----------------+<----------------+
         |  |     Server     |<-------+
         |  +----------------+        |
         |    ^                       |
         |    |                       |
         | OWAMP-Control         OWAMP-Control
         |    |                       |
         v    v                       v
       +----------------+     +-----------------+
       | Control-Client |     |   Fetch-Client  |
       +----------------+     +-----------------+

   (Unlabeled links in the figure are unspecified by this document and
   may be proprietary protocols.)

   Different logical roles can be played by the same host.  For example,
   in the figure above, there could actually be only two hosts: one
   playing the roles of Control-Client, Fetch-Client, and Session-
   Sender, and the other playing the roles of Server and Session-
   Receiver.  This is shown below.

       +-----------------+                   +------------------+
       | Control-Client  |<--OWAMP-Control-->| Server           |
       | Fetch-Client    |                   |                  |
       | Session-Sender  |---OWAMP-Test----->| Session-Receiver |
       +-----------------+                   +------------------+

   Finally, because many Internet paths include segments that transport
   IP over ATM, delay and loss measurements can include the effects of
   ATM segmentation and reassembly (SAR).  Consequently, OWAMP has been
   designed to allow for small test packets that would fit inside the
   payload of a single ATM cell (this is only achieved in
   unauthenticated mode).

Top      ToC       Page 6 
2.  Protocol Overview

   As described above, OWAMP consists of two inter-related protocols:
   OWAMP-Control and OWAMP-Test.  The former is layered over TCP and is
   used to initiate and control measurement sessions and to fetch their
   results.  The latter protocol is layered over UDP and is used to send
   singleton measurement packets along the Internet path under test.

   The initiator of the measurement session establishes a TCP connection
   to a well-known port, 861, on the target point and this connection
   remains open for the duration of the OWAMP-Test sessions.  An OWAMP
   server SHOULD listen to this well-known port.

   OWAMP-Control messages are transmitted only before OWAMP-Test
   sessions are actually started and after they are completed (with the
   possible exception of an early Stop-Sessions message).

   The OWAMP-Control and OWAMP-Test protocols support three modes of
   operation: unauthenticated, authenticated, and encrypted.  The
   authenticated or encrypted modes require that endpoints possess a
   shared secret.

   All multi-octet quantities defined in this document are represented
   as unsigned integers in network byte order unless specified
   otherwise.

3.  OWAMP-Control

   The type of each OWAMP-Control message can be found after reading the
   first 16 octets.  The length of each OWAMP-Control message can be
   computed upon reading its fixed-size part.  No message is shorter
   than 16 octets.

   An implementation SHOULD expunge unused state to prevent denial-of-
   service attacks, or unbounded memory usage, on the server.  For
   example, if the full control message is not received within some
   number of minutes after it is expected, the TCP connection associated
   with the OWAMP-Control session SHOULD be dropped.  In absence of
   other considerations, 30 minutes seems like a reasonable upper bound.

3.1.  Connection Setup

   Before either a Control-Client or a Fetch-Client can issue commands
   to a Server, it has to establish a connection to the server.

   First, a client opens a TCP connection to the server on a well-known
   port 861.  The server responds with a server greeting:

Top      ToC       Page 7 
      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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                      Unused (12 octets)                       |
     |                                                               |
     |+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                            Modes                              |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                     Challenge (16 octets)                     |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                        Salt (16 octets)                       |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                        Count (4 octets)                       |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                        MBZ (12 octets)                        |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   The following Mode values are meaningful: 1 for unauthenticated, 2
   for authenticated, and 4 for encrypted.  The value of the Modes field
   sent by the server is the bit-wise OR of the mode values that it is
   willing to support during this session.  Thus, the last three bits of
   the Modes 32-bit value are used.  The first 29 bits MUST be zero.  A
   client MUST ignore the values in the first 29 bits of the Modes
   value.  (This way, the bits are available for future protocol
   extensions.  This is the only intended extension mechanism.)

   Challenge is a random sequence of octets generated by the server; it
   is used subsequently by the client to prove possession of a shared
   secret in a manner prescribed below.

   Salt and Count are parameters used in deriving a key from a shared
   secret as described below.

   Salt MUST be generated pseudo-randomly (independently of anything
   else in this document).

   Count MUST be a power of 2.  Count MUST be at least 1024.  Count
   SHOULD be increased as more computing power becomes common.

Top      ToC       Page 8 
   If the Modes value is zero, the server does not wish to communicate
   with the client and MAY close the connection immediately.  The client
   SHOULD close the connection if it receives a greeting with Modes
   equal to zero.  The client MAY close the connection if the client's
   desired mode is unavailable.

   Otherwise, the client MUST respond with the following Set-Up-Response
   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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                             Mode                              |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     .                                                               .
     .                       KeyID (80 octets)                       .
     .                                                               .
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     .                                                               .
     .                       Token (64 octets)                       .
     .                                                               .
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     .                                                               .
     .                     Client-IV (16 octets)                     .
     .                                                               .
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Here Mode is the mode that the client chooses to use during this
   OWAMP-Control session.  It will also be used for all OWAMP-Test
   sessions started under control of this OWAMP-Control session.  In
   Mode, one or zero bits MUST be set within last three bits.  If it is
   one bit that is set within the last three bits, this bit MUST
   indicate a mode that the server agreed to use (i.e., the same bit
   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.

Top      ToC       Page 9 
   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).

Top      ToC       Page 10 
   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-

Top      ToC       Page 11 
   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).

Top      ToC       Page 12 
     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.

Top      ToC       Page 13 
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.

Top      ToC       Page 14 
   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)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Top      ToC       Page 15 
   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.)

Top      ToC       Page 16 
   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.

Top      ToC       Page 17 
   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               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
     |                                                               |
     |                        SID (16 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                        MBZ (12 octets)                        |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                       HMAC (16 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   In this message, zero in the Accept field means that the server is
   willing to conduct the session.  A non-zero value indicates rejection
   of the request.  The full list of available Accept values is
   described in Section 3.3, "Values of the Accept Field".

   If the server rejects a Request-Session message, it SHOULD not close
   the TCP connection.  The client MAY close it if it receives a
   negative response to the Request-Session message.

   The meaning of Port in the response depends on the values of Conf-
   Sender and Conf-Receiver in the query that solicited the response.
   If both were set, the Port field is unused.  If only Conf-Sender was
   set, Port is the port from which to expect OWAMP-Test packets.  If

Top      ToC       Page 18 
   only Conf-Receiver was set, Port is the port to which OWAMP-Test
   packets are sent.

   If only Conf-Sender was set, the SID field in the response is unused.
   Otherwise, SID is a unique server-generated session identifier.  It
   can be used later as handle to fetch the results of a session.

   SIDs SHOULD be constructed by concatenation of the 4-octet IPv4 IP
   number belonging to the generating machine, an 8-octet timestamp, and
   a 4-octet random value.  To reduce the probability of collisions, if
   the generating machine has any IPv4 addresses (with the exception of
   loopback), one of them SHOULD be used for SID generation, even if all
   communication is IPv6-based.  If it has no IPv4 addresses at all, the
   last four octets of an IPv6 address MAY be used instead.  Note that
   SID is always chosen by the receiver.  If truly random values are not
   available, it is important that the SID be made unpredictable, as
   knowledge of the SID might be used for access control.

3.6.  Send Schedules

   The sender and the receiver both need to know the same send schedule.
   This way, when packets are lost, the receiver knows when they were
   supposed to be sent.  It is desirable to compress common schedules
   and still to be able to use an arbitrary one for the test sessions.
   In many cases, the schedule will consist of repeated sequences of
   packets: this way, the sequence performs some test, and the test is
   repeated a number of times to gather statistics.

   To implement this, we have a schedule with a given number of slots.
   Each slot has a type and a parameter.  Two types are supported:
   exponentially distributed pseudo-random quantity (denoted by a code
   of 0) and a fixed quantity (denoted by a code of 1).  The parameter
   is expressed as a timestamp and specifies a time interval.  For a
   type 0 slot (exponentially distributed pseudo-random quantity), this
   interval is the mean value (or 1/lambda if the distribution density
   function is expressed as lambda*exp(-lambda*x) for positive values of
   x).  For a type 1 (fixed quantity) slot, the parameter is the delay
   itself.  The sender starts with the beginning of the schedule and
   executes the instructions in the slots: for a slot of type 0, wait an
   exponentially distributed time with a mean of the specified parameter
   and then send a test packet (and proceed to the next slot); for a
   slot of type 1, wait the specified time and send a test packet (and
   proceed to the next slot).  The schedule is circular: when there are
   no more slots, the sender returns to the first slot.

   The sender and the receiver need to be able to reproducibly execute
   the entire schedule (so, if a packet is lost, the receiver can still
   attach a send timestamp to it).  Slots of type 1 are trivial to

Top      ToC       Page 19 
   reproducibly execute.  To reproducibly execute slots of type 0, we
   need to be able to generate pseudo-random exponentially distributed
   quantities in a reproducible manner.  The way this is accomplished is
   discussed later in Section 5, "Computing Exponentially Distributed
   Pseudo-Random Numbers".

   Using this mechanism, one can easily specify common testing
   scenarios.  The following are some examples:

   +  Poisson stream: a single slot of type 0.

   +  Periodic stream: a single slot of type 1.

   +  Poisson stream of back-to-back packet pairs: two slots, type 0
      with a non-zero parameter and type 1 with a zero parameter.

   Further, a completely arbitrary schedule can be specified (albeit
   inefficiently) by making the number of test packets equal to the
   number of schedule slots.  In this case, the complete schedule is
   transmitted in advance of an OWAMP-Test session.

3.7.  Starting Test Sessions

   Having requested one or more test sessions and received affirmative
   Accept-Session responses, an OWAMP client MAY start the execution of
   the requested test sessions by sending a Start-Sessions message to
   the server.

   The format of this 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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |      2        |                                               |
     +-+-+-+-+-+-+-+-+                                               |
     |                        MBZ (15 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                       HMAC (16 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   The server MUST respond with an Start-Ack message (which SHOULD be
   sent as quickly as possible).  Start-Ack messages have the following
   format:

Top      ToC       Page 20 
      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 (15 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                       HMAC (16 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   If Accept is non-zero, the Start-Sessions request was rejected; zero
   means that the command was accepted.  The full list of available
   Accept values is described in Section 3.3, "Values of the Accept
   Field".  The server MAY, and the client SHOULD, close the connection
   in the case of a rejection.

   The server SHOULD start all OWAMP-Test streams immediately after it
   sends the response or immediately after their specified start times,
   whichever is later.  If the client represents a Sender, the client
   SHOULD start its OWAMP-Test streams immediately after it sees the
   Start-Ack response from the Server (if the Start-Sessions command was
   accepted) or immediately after their specified start times, whichever
   is later.  See more on OWAMP-Test sender behavior in a separate
   section below.

3.8.  Stop-Sessions

   The Stop-Sessions message may be issued by either the Control-Client
   or the Server.  The format of this command 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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |      3        |    Accept     |              MBZ              |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                      Number of Sessions                       |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                        MBZ (8 octets)                         |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   This is immediately followed by zero or more session description
   records (the number of session description records is specified in

Top      ToC       Page 21 
   the "Number of Sessions" field above).  The session description
   record is used to indicate which packets were actually sent by the
   sender process (rather than skipped).  The header of the session
   description record 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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
     |                                                               |
     |                        SID (16 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                           Next Seqno                          |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                     Number of Skip Ranges                     |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   This is immediately followed by zero or more Skip Range descriptions
   as specified by the "Number of Skip Ranges" field above.  Skip Ranges
   are simply two sequence numbers that, together, indicate a range of
   packets that were not sent:

      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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
     |                      First Seqno Skipped                      |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                       Last Seqno Skipped                      |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Skip Ranges MUST be in order.  The last (possibly full, possibly
   incomplete) block (16 octets) of data MUST be padded with zeros, if
   necessary.  This ensures that the next session description record
   starts on a block boundary.

   Finally, a single block (16 octets) of HMAC is concatenated on the
   end to complete the Stop-Sessions message.

     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                       HMAC (16 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   All these records comprise one logical message: the Stop-Sessions
   command.

Top      ToC       Page 22 
   Above, the first octet (3) indicates that this is the Stop-Sessions
   command.

   Non-zero Accept values indicate a failure of some sort.  Zero values
   indicate normal (but possibly premature) completion.  The full list
   of available Accept values is described in Section 3.3, "Values of
   the Accept Field".

   If Accept had a non-zero value (from either party), results of all
   OWAMP-Test sessions spawned by this OWAMP-Control session SHOULD be
   considered invalid, even if a Fetch-Session with SID from this
   session works for a different OWAMP-Control session.  If Accept was
   not transmitted at all (for whatever reason, including the TCP
   connection used for OWAMP-Control breaking), the results of all
   OWAMP-Test sessions spawned by this OWAMP-control session MAY be
   considered invalid.

   Number of Sessions indicates the number of session description
   records that immediately follow the Stop-Sessions header.

   Number of Sessions MUST contain the number of send sessions started
   by the local side of the control connection that have not been
   previously terminated by a Stop-Sessions command (i.e., the Control-
   Client MUST account for each accepted Request-Session where Conf-
   Receiver was set; the Control-Server MUST account for each accepted
   Request-Session where Conf-Sender was set).  If the Stop-Sessions
   message does not account for exactly the send sessions controlled by
   that side, then it is to be considered invalid and the connection
   SHOULD be closed and any results obtained considered invalid.

   Each session description record represents one OWAMP-Test session.

   SID is the session identifier (SID) used to indicate which send
   session is being described.

   Next Seqno indicates the next sequence number that would have been
   sent from this send session.  For completed sessions, this will equal
   NumPackets from the Request-Session.

   Number of Skip Ranges indicates the number of holes that actually
   occurred in the sending process.  This is a range of packets that
   were never actually sent by the sending process.  For example, if a
   send session is started too late for the first 10 packets to be sent
   and this is the only hole in the schedule, then "Number of Skip
   Ranges" would be 1.  The single Skip Range description will have
   First Seqno Skipped equal to 0 and Last Seqno Skipped equal to 9.
   This is described further in the "Sender Behavior" section.

Top      ToC       Page 23 
   If the OWAMP-Control connection breaks when the Stop-Sessions command
   is sent, the receiver MAY not completely invalidate the session
   results.  It MUST discard all record of packets that follow (in other
   words, that have greater sequence number than) the last packet that
   was actually received before any lost packet records.  This will help
   differentiate between packet losses that occurred in the network and
   packets the sending process may have never sent.

   If a receiver of an OWAMP-Test session learns, through an OWAMP-
   Control Stop-Sessions message, that the OWAMP-Test sender's last
   sequence number is lower than any sequence number actually received,
   the results of the complete OWAMP-Test session MUST be invalidated.

   A receiver of an OWAMP-Test session, upon receipt of an OWAMP-Control
   Stop-Sessions command, MUST discard any packet records -- including
   lost packet records -- with a (computed) send time that falls between
   the current time minus Timeout and the current time.  This ensures
   statistical consistency for the measurement of loss and duplicates in
   the event that the Timeout is greater than the time it takes for the
   Stop-Sessions command to take place.

   To effect complete sessions, each side of the control connection
   SHOULD wait until all sessions are complete before sending the Stop-
   Sessions message.  The completed time of each session is determined
   as Timeout after the scheduled time for the last sequence number.
   Endpoints MAY add a small increment to the computed completed time
   for send endpoints to ensure that the Stop-Sessions message reaches
   the receiver endpoint after Timeout.

   To effect a premature stop of sessions, the party that initiates this
   command MUST stop its OWAMP-Test send streams to send the Session
   Packets Sent values before sending this command.  That party SHOULD
   wait until receiving the response Stop-Sessions message before
   stopping the receiver streams so that it can use the values from the
   received Stop-Sessions message to validate the data.

Top      ToC       Page 24 
3.9.  Fetch-Session

   The format of this client command 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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |      4        |                                               |
     +-+-+-+-+-+-+-+-+                                               |
     |                        MBZ (7 octets)                         |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                         Begin Seq                             |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                          End Seq                              |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                        SID (16 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                       HMAC (16 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Begin Seq is the sequence number of the first requested packet.  End
   Seq is the sequence number of the last requested packet.  If Begin
   Seq is all zeros and End Seq is all ones, complete session is said to
   be requested.

   If a complete session is requested and the session is still in
   progress or has terminated in any way other than normally, the
   request to fetch session results MUST be denied.  If an incomplete
   session is requested, all packets received so far that fall into the
   requested range SHOULD be returned.  Note that, since no commands can
   be issued between Start-Sessions and Stop-Sessions, incomplete
   requests can only happen on a different OWAMP-Control connection
   (from the same or different host as Control-Client).

Top      ToC       Page 25 
   The server MUST respond with a Fetch-Ack message.  The format of this
   server response 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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |     Accept    | Finished      |          MBZ (2 octets)       |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                           Next Seqno                          |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                    Number of Skip Ranges                      |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                       Number of Records                       |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                                                               |
     |                       HMAC (16 octets)                        |
     |                                                               |
     |                                                               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Again, non-zero in the Accept field means a rejection of command.
   The server MUST specify zero for all remaining fields if Accept is
   non-zero.  The client MUST ignore all remaining fields (except for
   the HMAC) if Accept is non-zero.  The full list of available Accept
   values is described in Section 3.3, "Values of the Accept Field".

   Finished is non-zero if the OWAMP-Test session has terminated.

   Next Seqno indicates the next sequence number that would have been
   sent from this send session.  For completed sessions, this will equal
   NumPackets from the Request-Session.  This information is only
   available if the session has terminated.  If Finished is zero, then
   Next Seqno MUST be set to zero by the server.

   Number of Skip Ranges indicates the number of holes that actually
   occurred in the sending process.  This information is only available
   if the session has terminated.  If Finished is zero, then Skip Ranges
   MUST be set to zero by the server.

   Number of Records is the number of packet records that fall within
   the requested range.  This number might be less than the Number of
   Packets in the reproduction of the Request-Session command because of
   a session that ended prematurely, or it might be greater because of
   duplicates.

   If Accept was non-zero, this concludes the response to the Fetch-
   Session message.  If Accept was 0, the server then MUST immediately
   send the OWAMP-Test session data in question.

Top      ToC       Page 26 
   The OWAMP-Test session data consists of the following (concatenated):

   +  A reproduction of the Request-Session command that was used to
      start the session; it is modified so that actual sender and
      receiver port numbers that were used by the OWAMP-Test session
      always appear in the reproduction.

   +  Zero or more (as specified) Skip Range descriptions.  The last
      (possibly full, possibly incomplete) block (16 octets) of Skip
      Range descriptions is padded with zeros, if necessary.

   +  16 octets of HMAC.

   +  Zero or more (as specified) packet records.  The last (possibly
      full, possibly incomplete) block (16 octets) of data is padded
      with zeros, if necessary.

   +  16 octets of HMAC.

   Skip Range descriptions are simply two sequence numbers that,
   together, indicate a range of packets that were not sent:

      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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
     |                      First Seqno Skipped                      |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                       Last Seqno Skipped                      |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Skip Range descriptions should be sent out in order, as sorted by
   First Seqno.  If any Skip Ranges overlap or are out of order, the
   session data is to be considered invalid and the connection SHOULD be
   closed and any results obtained considered invalid.

   Each packet record is 25 octets and includes 4 octets of sequence
   number, 8 octets of send timestamp, 2 octets of send timestamp error
   estimate, 8 octets of receive timestamp, 2 octets of receive
   timestamp error estimate, and 1 octet of Time To Live (TTL), or Hop
   Limit in IPv6:

Top      ToC       Page 27 
        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
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     00|                          Seq Number                           |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     04|      Send Error Estimate      |    Receive Error Estimate     |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     08|                         Send Timestamp                        |
     12|                                                               |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     16|                       Receive Timestamp                       |
     20|                                                               |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     24|    TTL        |
       +-+-+-+-+-+-+-+-+

   Packet records are sent out in the same order the actual packets were
   received.  Therefore, the data is in arrival order.

   Note that lost packets (if any losses were detected during the
   OWAMP-Test session) MUST appear in the sequence of packets.  They can
   appear either at the point when the loss was detected or at any later
   point.  Lost packet records are distinguished as follows:

   +  A send timestamp filled with the presumed send time (as computed
      by the send schedule).

   +  A send error estimate filled with Multiplier=1, Scale=64, and S=0
      (see the OWAMP-Test description for definition of these quantities
      and explanation of timestamp format and error estimate format).

   +  A normal receive error estimate as determined by the error of the
      clock being used to declare the packet lost.  (It is declared lost
      if it is not received by the Timeout after the presumed send time,
      as determined by the receiver's clock.)

   +  A receive timestamp consisting of all zero bits.

   +  A TTL value of 255.



(page 27 continued on part 2)

Next RFC Part