6. Test Setup Request and Response
Cette section conserve le texte RFC relatif à UDPSTP, y compris One-Way IP Capacity metrics, Control and Data phases, Load and Status Feedback PDUs, KDF/HMAC authentication, optional checksum handling, IANA registries et security considerations.
Texte RFC original
6. Test Setup Request and Response
The client source IP address and the server destination IP address
MUST NOT be a broadcast or multicast address. Any Test Setup Request
or Test Setup Response packet containing a multicast or broadcast
source or destination IP address MUST be silently dropped and
ignored.
The measurement method and the protocol specified by this document
are expected to function with unicast and anycast IP addresses.
6.1. Client Generates Test Setup Request
The client SHALL begin the Control phase exchange by sending a Test
Setup Request message to the server's (standard) control port. This
standard UDPSTP port number is utilized for each connection of a
multi-connection test.
The client SHALL simultaneously start a test initiation timer so that
if the Control phase fails to complete Test Setup and Test Activation
exchanges in the allocated time, the client software SHALL exit
(i.e., the UDP socket will be closed and an error message will be
displayed to the user). Lost messages result in a Test Setup and
Test Activation failure. The test initiation timer MAY reuse the
test termination timeout value.
The watchdog timeout is configured as a 1-second interval to trigger
a warning message that the received traffic has stopped. The test
termination timeout is based on the watchdog interval and implements
a wait time of 2 additional seconds before triggering a non-graceful
termination.
Note: Any field labeled as 'reserved for alignment', in any PDU, MUST
be set to 0 and MUST be ignored upon receipt.
The UDP PDU format layout SHALL be as follows (big-endian AB,
starting with the most significant byte and ending with the least
significant byte):
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| pduId | protocolVer |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| mcIndex | mcCount | mcIdent |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| cmdRequest | cmdResponse | maxBandwidth |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| testPort |modifierBitmap | authMode |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| authUnixTime |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. authDigest (32 octets) .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| keyId | reservedAuth1 | checkSum |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 2: Test Setup PDU Layout
Additional details regarding the Setup Request and Response fields
are as follows:
pduId: A two-octet field. IANA has assigned the hex value 0xACE1
(Section 12.3.1).
protocolVer: A two-octet field identifying the actual protocol
version. IANA has assigned 20 as the value (Section 12.3.2).
mcIndex: A one-octet field indicating the index of a connection
relative to all connections that make up a single test (starting
at 0, incremented by 1 per connection). It is used to
differentiate separate connections within a multi-connection test.
An implementation may restrict the number of connections supported
for a single test to a value less than or equal to 255.
mcCount: A one-octet field indicating the total count of connections
that the client is attempting to set up.
mcIdent: A two-octet field containing a pseudorandom non-zero
identifier (via a Random Number Generator, source port number,
...) that is common to all connections of a single test. It is
used by clients/servers to associate separate connections with a
single multi-connection test.
cmdRequest: A one-octet field set to CHSR_CREQ_SETUPREQ to indicate
a Setup Request message. Note that CHSR_CREQ_NONE remains unused.
cmdResponse: A one-octet field. All Request PDUs always have a
Command Response of XXXX_CRSP_NONE (i.e., CHSR_CRSP_NONE,
CHNR_CRSP_NONE, or CHTA_CRSP_NONE).
maxBandwidth: A two-octet field. A non-zero value of this field
specifies the maximum bit rate the client expects to send or
receive during the requested test in Mbps. The server compares
this value to its currently available configured limit for test
admission control. This field MAY be used to rate-limit the
maximum rate the server should attempt. The maxBandwidth field's
most significant bit, the CHSR_USDIR_BIT, is set to 0 by default
to indicate "downstream" and has to be set to 1 to indicate
"upstream".
testPort: A two-octet field set to zero in the Test Setup Request
and populated by the server in the Test Setup Response. It
contains the UDP ephemeral port number on the server that the
client has to use for the Test Activation Request and subsequent
Load or Status PDUs.
modifierBitmap: A one-octet field. This document only assigns two
bits in this bitmap; see Section 12.3.3:
CHSR_JUMBO_STATUS (0x01): This bit SHALL be set by default. By
default, sending rates up to 1 Gbps SHALL NOT produce IP packet
sizes greater than 1250 bytes (unless CHSR_TRADITIONAL_MTU is
set), while rates above 1 Gbps MAY produce IP packet sizes up
to 9000 bytes. When CHSR_JUMBO_STATUS is not set, all sending
rates SHALL NOT produce IP packet sizes greater than 1250 bytes
(unless CHSR_TRADITIONAL_MTU is set).
CHSR_TRADITIONAL_MTU (0x02): This bit SHALL NOT be set by
default. If set, sending rates up to 1 Gbps MAY produce IP
packets up to the traditional size of 1500 bytes. If
CHSR_JUMBO_STATUS is simultaneously not set, all sending rates
SHALL NOT produce IP packets greater than the traditional size
of 1500 bytes.
Other bit positions are left unassigned per this document.
authMode: A one-octet field. The authMode field currently has two
values assigned (see Section 12.3.4). One of the following has to
be set (see Section 5.3 for requirements and details of
operation):
AUTHMODE_1: Required authentication for the Control phase.
AUTHMODE_2: Required authentication for the Control and Data
phases (Status Feedback PDU only).
A range of 60 through 63 is reserved for experimentation. IANA has
created the "Test Setup PDU Authentication Mode" registry for the
assigned values; see Section 12.3.4.
authUnixTime: A 32-bit timestamp of the current system (wall-clock)
time since the Unix Epoch on January 1, 1970 at 00:00:00 UTC.
authDigest: This field contains the 32-octet HMAC-SHA-256 hash that
covers the entire PDU. Normally, the calculation is done as the
last step of building the PDU. However, if the optional checkSum
field is being utilized, it becomes the penultimate step and is
done just prior to the checksum calculation (with the checkSum
field set to zero).
keyId: A one-octet field carrying localKeyName, the numeric key
identifier for a key in the shared key table.
reservedAuth1: A one-octet field. This field MUST be set to 0 and
MUST be ignored upon receipt. Consistent naming and placement of
the reservedAuth1 field across all PDUs is done to minimize
authentication-related changes in future UDPSTP versions.
checkSum: A two-octet field containing an optional checksum of the
entire PDU (see Section 5.6 for guidance). The calculation is
done as the very last step of building the PDU, with the checkSum
field set to zero.
6.2. Server Test Setup Request Processing and Response Generation
This section describes the processes at the server that are used to
evaluate the Test Setup Request and determine the next steps. When
the server receives the Setup Request, it SHALL first perform the
following:
Message Verification Procedure:
1. Verify that the size of the message is correct.
2. If the optional checkSum field is being utilized, validate the
checksum as described in Section 5.6 and (if valid) zero the
checkSum field prior to authentication verification.
3. Verify that the authMode value is valid and appropriate (per
Section 5.3) for the message type.
4. If the authMode is valid and appropriate, authenticate the
message by checking the authDigest as prescribed in Section 5.3.
5. If the message is authentic, check the authUnixTime field for
acceptable immediacy.
Note: If any of the above checks fail, the message SHALL be
considered invalid.
6.2.1. Test Setup Request Processing -- Rejection
The server SHALL then evaluate the other fields in the protocol
header, such as the protocol version, the PDU ID (to validate the
type of message), the maximum bandwidth requested for the test, and
the modifierBitmap for use of options such as Jumbo datagram status
and Traditional MTU (1500 bytes).
If the client has selected options for
* Jumbo datagram support (modifierBitmap),
* Traditional MTU (modifierBitmap), and
* Authentication mode (authMode)
that do not match the server configuration, the server MUST reject
the Setup Request.
If the Setup Request must be rejected, the conditions below determine
whether the server sends a response:
* If the authDigest is valid, a Test Setup Response SHALL be sent
back to the client with a corresponding Command Response value
indicating the reason for the rejection.
* If the authDigest is invalid, then the Test Setup Request SHOULD
fail silently. The exception is for operations support: server
administrators are permitted to send a Setup Response to support
operations and troubleshooting.
The additional circumstances when a server SHALL NOT communicate the
appropriate Command Response code for an error condition (fail
silently) are when:
* the Setup Request PDU size is not equal to the 'struct
controlHdrSR' size shown in Figure 3,
* the PDU ID is not 0xACE1 (Test Setup PDU), or
* a directed attack has been detected.
In this case, the server will allow setup attempts to terminate
silently. Attack detection is beyond the scope of this
specification.
When the server replies to a Test Setup Request message, the Test
Setup Response PDU is structured identically to the Test Setup
Request PDU and SHALL retain the original values received in it, with
the following exceptions:
* The cmdRequest field is set to CHSR_CREQ_SETUPRSP, indicating a
response.
* The cmdResponse field is set to an error code (starting at
cmdResponse 2, Bad Protocol Version; see Section 12.3.5),
indicating the reason for rejection. If cmdResponse indicates a
bad protocol version (CHSR_CRSP_BADVER), the protocolVer field is
also updated to indicate the current expected version.
* The authUnixTime field is updated to the current system (wall-
clock) time and, after the authDigest and checkSum fields are
zeroed, the authDigest is recalculated and inserted. If the
optional checkSum field is being utilized, it is then also
calculated and inserted.
The Setup Request/Response message PDU SHALL be organized as follows
(here and in all following code figures coded by programming language
C [C-Prog]):
<CODE BEGINS>
//
// Control header for UDP payload of Setup Request/Response PDUs
//
struct controlHdrSR {
#define CHSR_ID 0xACE1
uint16_t pduId; // PDU ID
#define PROTOCOL_VER 20
uint16_t protocolVer; // Protocol version
uint8_t mcIndex; // Multi-connection index
uint8_t mcCount; // Multi-connection count
uint16_t mcIdent; // Multi-connection identifier
#define CHSR_CREQ_NONE 0
#define CHSR_CREQ_SETUPREQ 1 // Setup Request
#define CHSR_CREQ_SETUPRSP 2 // Setup Response
uint8_t cmdRequest; // Command Request
#define CHSR_CRSP_NONE 0 // (used with request)
#define CHSR_CRSP_ACKOK 1 // Acknowledgment
#define CHSR_CRSP_BADVER 2 // Bad version
#define CHSR_CRSP_BADJS 3 // Jumbo setting mismatch
#define CHSR_CRSP_AUTHNC 4 // Auth. not configured
#define CHSR_CRSP_AUTHREQ 5 // Auth. required
#define CHSR_CRSP_AUTHINV 6 // Auth. (mode) invalid
#define CHSR_CRSP_AUTHFAIL 7 // Auth. failure
#define CHSR_CRSP_AUTHTIME 8 // Auth. time invalid
#define CHSR_CRSP_NOMAXBW 9 // Max bandwidth required
#define CHSR_CRSP_CAPEXC 10 // Capacity exceeded
#define CHSR_CRSP_BADTMTU 11 // Trad. MTU mismatch
#define CHSR_CRSP_MCINVPAR 12 // Multi-conn. invalid params
#define CHSR_CRSP_CONNFAIL 13 // Conn. allocation failure
uint8_t cmdResponse; // Command Response
#define CHSR_USDIR_BIT 0x8000 // Upstream direction bit
uint16_t maxBandwidth; // Required bandwidth in Mbps
uint16_t testPort; // Test port on server
#define CHSR_JUMBO_STATUS 0x01
#define CHSR_TRADITIONAL_MTU 0x02
uint8_t modifierBitmap; // Modifier bitmap
// ========== Integrity Verification ==========
#define AUTHMODE_1 1 // Mode 1: Authenticated Control
#define AUTHMODE_2 2 // Mode 2: Authenticated Control+Status
uint8_t authMode; // Authentication mode
uint32_t authUnixTime; // Authentication timestamp
#define AUTH_DIGEST_LENGTH 32 // SHA-256 digest length
uint8_t authDigest[AUTH_DIGEST_LENGTH];
uint8_t keyId; // Key ID in shared table
uint8_t reservedAuth1; // (reserved for alignment)
uint16_t checkSum; // Header checksum
};
#define SHA256_KEY_LEN 32 // Authentication key length
<CODE ENDS>
Figure 3: Test Setup PDU
6.2.2. Test Setup Request Processing -- Acceptance
If the server finds that the Setup Request matches its configuration
and is otherwise acceptable, the server SHALL initiate a new
connection to receive the Test Activation Request from the client,
using a new UDP socket allocated from the UDP ephemeral port range.
This new socket will also be used for the subsequent Load and Status
PDUs that are part of testing (with the port number communicated back
to the client in testPort field of the Test Setup Response). Then,
the server SHALL start a watchdog timer (to terminate the new
connection if the client goes silent) and SHALL send the Test Setup
Response back to the client. The watchdog timer is set to the same
value as on the client side (see Section 6)
When the server replies to the Test Setup Request message, the Test
Setup Response PDU is structured identically to the Test Setup
Request PDU and SHALL retain the original values received in it, with
the following exceptions:
* The cmdRequest field is set to CHSR_CREQ_SETUPRSP, indicating a
response.
* The cmdResponse field is set to CHSR_CRSP_ACKOK, indicating an
acknowledgment.
* The testPort field is set to the ephemeral port number to be used
for the client's Test Activation Request and all subsequent
communication.
* The authUnixTime field is updated to the current system (wall-
clock) time and, after the authDigest and checkSum fields are
zeroed, the authDigest is recalculated and inserted. If the
optional checkSum field is being utilized, it is then also
calculated and inserted.
Finally, the new UDP connection associated with the new socket and
port number are made ready, and the server awaits further
communication there.
To ensure that a server's local firewall will successfully allow
packets received for the new ephemeral port number, the server SHALL
immediately send a Null Request with the corresponding values
including the source and destination IP addresses and port numbers.
The source port SHALL be the new ephemeral port. This operation
allows communication to the server even when the server's local
firewall prohibits open ranges of ephemeral ports. The packet is not
expected to arrive successfully at the client if the client-side
firewall blocks unexpected traffic. If the Null Request arrives at
the client, it is a confirmation that further exchanges are possible
on the new port-pair (but this is not strictly necessary). If
received, the client SHALL follow the Message Verification Procedure
listed in Section 6.2, Paragraph 2. Note that there is no response
to a Null Request.
The UDP PDU format layout SHALL be as follows (big-endian AB):
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| pduId | protocolVer |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| cmdRequest | cmdResponse | reserved1 | authMode |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| authUnixTime |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. authDigest (32 octets) .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| keyId | reservedAuth1 | checkSum |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 4: Null Request PDU Layout
The authentication and checkSum fields follow the same methodology as
with the Setup Request and Response.
Additional details regarding the Null Request fields are as follows:
pduId: IANA has assigned the hex value 0xDEAD (Section 12.3.1).
cmdRequest: Set to CHNR_CREQ_NULLREQ to indicate a Null Request
message.
cmdResponse: Set to CHNR_CRSP_NONE.
authMode: Same as in Section 6.1.
authUnixTime: Same as in Section 6.1.
authDigest: Same as in Section 6.1.
keyId: Same as in Section 6.1.
reservedAuth1: Same as in Section 6.1.
checkSum: Same as in Section 6.1.
If a Test Activation Request is not subsequently received from the
client on the new ephemeral port number before the watchdog timer
expires, the server SHALL close the socket and deallocate the
associated resources.
The Null Request message PDU SHALL be organized as follows:
<CODE BEGINS>
//
// Control header for UDP payload of Null Request PDU
//
struct controlHdrNR {
#define CHNR_ID 0xDEAD
uint16_t pduId; // PDU ID
uint16_t protocolVer; // Protocol version
#define CHNR_CREQ_NONE 0
#define CHNR_CREQ_NULLREQ 1 // Null Request
uint8_t cmdRequest; // Command Request
#define CHNR_CRSP_NONE 0 // (used with request)
uint8_t cmdResponse; // Command Response
uint8_t reserved1; // (reserved for alignment)
// ========== Integrity Verification ==========
uint8_t authMode; // Authentication mode
uint32_t authUnixTime; // Authentication timestamp
uint8_t authDigest[AUTH_DIGEST_LENGTH];
uint8_t keyId; // Key ID in shared table
uint8_t reservedAuth1; // (reserved for alignment)
uint16_t checkSum; // Header checksum
};
<CODE ENDS>
Figure 5: Null Request PDU
6.3. Setup Response Processing at the Client
When the client receives the Test Setup Response message, it SHALL
first follow the Message Verification Procedure listed in
Section 6.2, Paragraph 2.
The client SHALL then proceed to evaluate the other fields in the
protocol, beginning with the protocol version, PDU ID (to validate
the type of message), and cmdRequest for the role of the message,
which MUST be Test Setup Response, CHSR_CREQ_SETUPRSP, as indicated
by Figure 3.
If the cmdResponse value indicates an error (values greater than
CHSR_CRSP_ACKOK), the client SHALL display/report a relevant message
to the user or management process and exit. If the client receives a
Command Response code that is not equal to one of the codes defined,
the client MUST terminate the connection and terminate operation of
the current Setup Request. If the Command Response code value
indicates success (CHSR_CRSP_ACKOK), the client SHALL compose a Test
Activation Request with all the test parameters it desires, such as
the test direction, the test duration, etc., as described below.