diff options
Diffstat (limited to 'doc/rfc/rfc9327.txt')
| -rw-r--r-- | doc/rfc/rfc9327.txt | 1148 |
1 files changed, 1148 insertions, 0 deletions
diff --git a/doc/rfc/rfc9327.txt b/doc/rfc/rfc9327.txt new file mode 100644 index 0000000..75fa23d --- /dev/null +++ b/doc/rfc/rfc9327.txt @@ -0,0 +1,1148 @@ + + + + +Internet Engineering Task Force (IETF) B. Haberman, Ed. +Request for Comments: 9327 JHU +Category: Historic November 2022 +ISSN: 2070-1721 + + + Control Messages Protocol for Use with Network Time Protocol Version 4 + +Abstract + + This document describes the structure of the control messages that + were historically used with the Network Time Protocol (NTP) before + the advent of more modern control and management approaches. These + control messages have been used to monitor and control the NTP + application running on any IP network attached computer. The + information in this document was originally described in Appendix B + of RFC 1305. The goal of this document is to provide an updated + description of the control messages described in RFC 1305 in order to + conform with the updated NTP specification documented in RFC 5905. + + The publication of this document is not meant to encourage the + development and deployment of these control messages. This document + is only providing a current reference for these control messages + given the current status of RFC 1305. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for the historical record. + + This document defines a Historic Document for the Internet community. + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Not all documents + approved by the IESG are candidates for any level of Internet + Standard; see Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9327. + +Copyright Notice + + Copyright (c) 2022 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD License. + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + +Table of Contents + + 1. Introduction + 1.1. Terminology + 1.2. Control Message Overview + 1.3. Remote Facility Message Overview + 2. NTP Control Message Format + 3. Status Words + 3.1. System Status Word + 3.2. Peer Status Word + 3.3. Clock Status Word + 3.4. Error Status Word + 4. Commands + 5. IANA Considerations + 6. Security Considerations + 7. References + 7.1. Normative References + 7.2. Informative References + Appendix A. NTP Remote Facility Message Format + Acknowledgements + Contributors + Author's Address + +1. Introduction + + [RFC1305] describes a set of control messages for use within the + Network Time Protocol (NTP) when a comprehensive network management + solution was not available. The definitions of these control + messages were not promulgated to [RFC5905] when NTP version 4 was + documented. These messages were intended for use only in systems + where no other management facilities were available or appropriate, + such as in dedicated-function bus peripherals. Support for these + messages is not required in order to conform to [RFC5905]. The + control messages are described here as a current reference for use + with an implementation of NTP from RFC 5905. + + The publication of this document is not meant to encourage the + development and deployment of these control messages. This document + is only providing a current reference for these control messages + given the current status of RFC 1305. + +1.1. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +1.2. Control Message Overview + + The NTP mode 6 control messages are used by NTP management programs + (e.g., ntpq) when a more robust network management facility (e.g., + SNMP) is not available. These control messages provide rudimentary + control and monitoring functions to manage a running instance of an + NTP server. These commands are not designed to be used for + communication between instances of running NTP servers. + + The NTP control message has the value 6 specified in the mode field + of the first octet of the NTP header and is formatted as shown in + Figure 1. The format of the data field is specific to each command + or response; however, in most cases, the format is designed to be + constructed and viewed by humans and so is coded in free-form ASCII. + This facilitates the specification and implementation of simple + management tools in the absence of fully evolved network-management + facilities. As in ordinary NTP messages, the authenticator field + follows the data field. If the authenticator is used, the data field + is zero-padded to a 32-bit boundary, but the padding bits are not + considered part of the data field and are not included in the field + count. + + IP hosts are not required to reassemble datagrams over a certain size + (576 octets for IPv4 [RFC0791] and 1280 octets for IPv6 [RFC8200]); + however, some commands or responses may involve more data than will + fit into a single datagram. Accordingly, a simple reassembly feature + is included in which each octet of the message data is numbered + starting with zero. As each fragment is transmitted, the number of + its first octet is inserted in the offset field and the number of + octets is inserted in the count field. The more-data (M) bit is set + in all fragments except the last. + + Most control functions involve sending a command and receiving a + response, perhaps involving several fragments. The sender chooses a + distinct, nonzero sequence number and sets the status field, "R" bit, + and "E" bit to zero. The responder interprets the opcode and + additional information in the data field, updates the status field, + sets the "R" bit to one and returns the three 32-bit words of the + header along with additional information in the data field. In the + case of invalid message format or contents, the responder inserts a + code in the status field, sets the "R" and "E" bits to one and, + optionally, inserts a diagnostic message in the data field. + + Some commands read or write system variables (e.g., s.offset) and + peer variables (e.g., p.stratum) for an association identified in the + command. Others read or write variables associated with a radio + clock or other device directly connected to a source of primary + synchronization information. To identify which type of variable and + association, the Association ID is used. System variables are + indicated by the identifier zero. As each association is mobilized a + unique, nonzero identifier is created for it. These identifiers are + used in a cyclic fashion, so that the chance of using an old + identifier that matches a newly created association is remote. A + management entity can request a list of current identifiers and + subsequently use them to read and write variables for each + association. An attempt to use an expired identifier results in an + exception response, following which the list can be requested again. + + Some exception events, such as when a peer becomes reachable or + unreachable, occur spontaneously and are not necessarily associated + with a command. An implementation may elect to save the event + information for later retrieval, to send an asynchronous response + (called a trap), or both. In case of a trap, the IP address and port + number are determined by a previous command and the sequence field is + set as described below. Current status and summary information for + the latest exception event is returned in all normal responses. Bits + in the status field indicate whether an exception has occurred since + the last response and whether more than one exception has occurred. + + Commands need not necessarily be sent by an NTP peer, so ordinary + access-control procedures may not apply; however, the optional mask/ + match mechanism suggested in Section 6 provides the capability to + control access by mode number, so this could be used to limit access + for control messages (mode 6) to selected address ranges. + +1.3. Remote Facility Message Overview + + The original development of the NTP daemon included a Remote Facility + for monitoring and configuration. This facility used mode 7 commands + to communicate with the NTP daemon. This document illustrates the + mode 7 packet format only. The commands embedded in the mode 7 + messages are implementation specific and not standardized in any way. + The mode 7 message format is described in Appendix A. + +2. NTP Control Message Format + + The format of the NTP Control Message header, which immediately + follows the UDP header, is shown in Figure 1. Following the figure + is a description of its header fields. + + 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 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |LI | VN |Mode |R|E|M| opcode | Sequence Number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Status | Association ID | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Offset | Count | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + / Data (up to 468 bytes) / + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Padding (optional) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + / Authenticator (optional, 20 or 24 bits) / + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + Figure 1: NTP Control Message Header + + Leap Indicator (LI): + This is a 2-bit integer that is set to b00 for control message + requests and responses. The Leap Indicator value used at this + position in most NTP modes is in the system status word provided + in some control message responses. + + Version Number (VN): + This is a 3-bit integer indicating a minimum NTP version number. + NTP servers do not respond to control messages with an + unrecognized version number. Requests may intentionally use a + lower version number to enable interoperability with earlier + versions of NTP. Responses carry the same version as the + corresponding request. + + Mode: + This is a 3-bit integer indicating the mode. The value 6 + indicates an NTP control message. + + Response Bit (R): + Set to zero for commands; set to one for responses. + + Error Bit (E): + Set to zero for normal responses; set to one for an error + response. + + More Bit (M): + Set to zero for the last fragment; set to one for all others. + + Operation Code (opcode): + This is a 5-bit integer specifying the command function. Values + currently defined include the following: + + +=======+================================================+ + | Code | Meaning | + +=======+================================================+ + | 0 | reserved | + +-------+------------------------------------------------+ + | 1 | read status command/response | + +-------+------------------------------------------------+ + | 2 | read variables command/response | + +-------+------------------------------------------------+ + | 3 | write variables command/response | + +-------+------------------------------------------------+ + | 4 | read clock variables command/response | + +-------+------------------------------------------------+ + | 5 | write clock variables command/response | + +-------+------------------------------------------------+ + | 6 | set trap address/port command/response | + +-------+------------------------------------------------+ + | 7 | trap response | + +-------+------------------------------------------------+ + | 8 | runtime configuration command/response | + +-------+------------------------------------------------+ + | 9 | export configuration to file command/response | + +-------+------------------------------------------------+ + | 10 | retrieve remote address stats command/response | + +-------+------------------------------------------------+ + | 11 | retrieve ordered list command/response | + +-------+------------------------------------------------+ + | 12 | request client-specific nonce command/response | + +-------+------------------------------------------------+ + | 13-30 | reserved | + +-------+------------------------------------------------+ + | 31 | unset trap address/port command/response | + +-------+------------------------------------------------+ + + Table 1: Operation Codes + + Sequence Number: + This is a 16-bit integer indicating the sequence number of the + command or response. Each request uses a different sequence + number. Each response carries the same sequence number as its + corresponding request. For asynchronous trap responses, the + responder increments the sequence number by one for each response, + allowing trap receivers to detect missing trap responses. The + sequence number of each fragment of a multiple-datagram response + carries the same sequence number, copied from the request. + + Status: + This is a 16-bit code indicating the current status of the system, + peer, or clock with values coded as described in following + sections. + + Association ID: + This is a 16-bit unsigned integer identifying a valid association + or zero for the system clock. + + Offset: + This is a 16-bit unsigned integer indicating the offset, in + octets, of the first octet in the data area. The offset is set to + zero in requests. Responses spanning multiple datagrams use a + positive offset in all but the first datagram. + + Count: + This is a 16-bit unsigned integer indicating the length of the + data field, in octets. + + Data: + This contains the message data for the command or response. The + maximum number of data octets is 468. + + Padding (optional): + Contains zero to 3 octets with a value of zero, as needed to + ensure the overall control message size is a multiple of 4 octets. + + Authenticator (optional): + When the NTP authentication mechanism is implemented, this + contains the authenticator information defined in Appendix C of + [RFC1305]. + +3. Status Words + + Status words indicate the present status of the system, associations, + and clock. They are designed to be interpreted by network-monitoring + programs and are in one of four 16-bit formats shown in Figure 2 and + described in this section. System and peer status words are + associated with responses for all commands except the read clock + variables, write clock variables, and set trap address/port commands. + The association identifier zero specifies the system status word, + while a nonzero identifier specifies a particular peer association. + The status word returned in response to read clock variables and + write clock variables commands indicates the state of the clock + hardware and decoding software. A special error status word is used + to report malformed command fields or invalid values. + + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | LI| Clock Src | Count | Code | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + System Status Word + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Status | SEL | Count | Code | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + Peer Status Word + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Clock Status | Code | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + Radio Status Word + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Error Code | Reserved | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + Error Status Word + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Reserved | Count | Code | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + Clock Status Word + + Figure 2: Status Word Formats + +3.1. System Status Word + + The system status word appears in the status field of the response to + a read status or read variables command with a zero association + identifier. The format of the system status word is as follows: + + Leap Indicator (LI): + This is a 2-bit code warning of an impending leap second to be + inserted/deleted in the last minute of the current day, with bit 0 + and bit 1, respectively, coded as follows: + + +====+=================================================+ + | LI | Meaning | + +====+=================================================+ + | 00 | no warning | + +----+-------------------------------------------------+ + | 01 | insert second after 23:59:59 of the current day | + +----+-------------------------------------------------+ + | 10 | delete second 23:59:59 of the current day | + +----+-------------------------------------------------+ + | 11 | unsynchronized | + +----+-------------------------------------------------+ + + Table 2: Leap Indicator Codes + + Clock Source (Clock Src): + This is a 6-bit integer indicating the current synchronization + source, with values coded as follows: + + +=======+========================================================+ + | Code | Meaning | + +=======+========================================================+ + | 0 | unspecified or unknown | + +-------+--------------------------------------------------------+ + | 1 | Calibrated atomic clock (e.g., PPS, HP 5061) | + +-------+--------------------------------------------------------+ + | 2 | VLF (band 4) or LF (band 5) radio (e.g., OMEGA,, WWVB) | + +-------+--------------------------------------------------------+ + | 3 | HF (band 7) radio (e.g., CHU, MSF, WWV/H) | + +-------+--------------------------------------------------------+ + | 4 | UHF (band 9) satellite (e.g., GOES, GPS) | + +-------+--------------------------------------------------------+ + | 5 | local net (e.g., DCN, TSP, DTS) | + +-------+--------------------------------------------------------+ + | 6 | UDP/NTP | + +-------+--------------------------------------------------------+ + | 7 | UDP/TIME | + +-------+--------------------------------------------------------+ + | 8 | eyeball-and-wristwatch | + +-------+--------------------------------------------------------+ + | 9 | telephone modem (e.g., NIST) | + +-------+--------------------------------------------------------+ + | 10-63 | reserved | + +-------+--------------------------------------------------------+ + + Table 3: Clock Source Values + + System Event Counter (Count): + This is a 4-bit integer indicating the number of system events + occurring since the last time the System Event Code changed. Upon + reaching 15, subsequent events with the same code are not counted. + + System Event Code (Code): + This is a 4-bit integer identifying the latest system exception + event, with new values overwriting previous values, and coded as + follows: + + +======+============================================================+ + | Code | Meaning | + +======+============================================================+ + | 0 | unspecified | + +------+------------------------------------------------------------+ + | 1 | frequency correction (drift) file not available | + +------+------------------------------------------------------------+ + | 2 | frequency correction started (frequency stepped) | + +------+------------------------------------------------------------+ + | 3 | spike detected and ignored, starting stepout timer | + +------+------------------------------------------------------------+ + | 4 | frequency training started | + +------+------------------------------------------------------------+ + | 5 | clock synchronized | + +------+------------------------------------------------------------+ + | 6 | system restart | + +------+------------------------------------------------------------+ + | 7 | panic stop (required step greater than panic threshold) | + +------+------------------------------------------------------------+ + | 8 | no system peer | + +------+------------------------------------------------------------+ + | 9 | leap second insertion/deletion armed for the current | + | | month | + +------+------------------------------------------------------------+ + | 10 | leap second disarmed | + +------+------------------------------------------------------------+ + | 11 | leap second inserted or deleted | + +------+------------------------------------------------------------+ + | 12 | clock stepped (stepout timer expired) | + +------+------------------------------------------------------------+ + | 13 | kernel loop discipline status changed | + +------+------------------------------------------------------------+ + | 14 | leapseconds table loaded from file | + +------+------------------------------------------------------------+ + | 15 | leapseconds table outdated, updated file needed | + +------+------------------------------------------------------------+ + + Table 4: System Event Codes + +3.2. Peer Status Word + + A peer status word is returned in the status field of a response to a + read status, read variables, or write variables command and appears + in the list of Association IDs and status words returned by a read + status command with a zero Association ID. The format of a peer + status word is as follows: + + Peer Status (Status): + This is a 5-bit code indicating the status of the peer determined + by the packet procedure, with bits assigned as follows: + + +=================+==========================================+ + | Peer Status bit | Meaning | + +=================+==========================================+ + | 0 | configured (peer.config) | + +-----------------+------------------------------------------+ + | 1 | authentication enabled (peer.authenable) | + +-----------------+------------------------------------------+ + | 2 | authentication okay (peer.authentic) | + +-----------------+------------------------------------------+ + | 3 | reachability okay (peer.reach != 0) | + +-----------------+------------------------------------------+ + | 4 | broadcast association | + +-----------------+------------------------------------------+ + + Table 5: Peer Status Bits + + Peer Selection (SEL): + This is a 3-bit integer indicating the status of the peer + determined by the clock-selection procedure, with values coded as + follows: + + +=====+=======================================================+ + | Sel | Meaning | + +=====+=======================================================+ + | 0 | rejected | + +-----+-------------------------------------------------------+ + | 1 | discarded by intersection algorithm | + +-----+-------------------------------------------------------+ + | 2 | discarded by table overflow (not currently used) | + +-----+-------------------------------------------------------+ + | 3 | discarded by the cluster algorithm | + +-----+-------------------------------------------------------+ + | 4 | included by the combine algorithm | + +-----+-------------------------------------------------------+ + | 5 | backup source (with more than sys.maxclock survivors) | + +-----+-------------------------------------------------------+ + | 6 | system peer (synchronization source) | + +-----+-------------------------------------------------------+ + | 7 | PPS (pulse per second) peer | + +-----+-------------------------------------------------------+ + + Table 6: Peer Selection Values + + Peer Event Counter (Count): + This is a 4-bit integer indicating the number of peer exception + events that occurred since the last time the peer event code + changed. Upon reaching 15, subsequent events with the same code + are not counted. + + Peer Event Code (Code): + This is a 4-bit integer identifying the latest peer exception + event, with new values overwriting previous values, and coded as + follows: + + +=================+===================================+ + | Peer Event Code | Meaning | + +=================+===================================+ + | 0 | unspecified | + +-----------------+-----------------------------------+ + | 1 | association mobilized | + +-----------------+-----------------------------------+ + | 2 | association demobilized | + +-----------------+-----------------------------------+ + | 3 | peer unreachable (peer.reach was | + | | nonzero now zero) | + +-----------------+-----------------------------------+ + | 4 | peer reachable (peer.reach was | + | | zero now nonzero) | + +-----------------+-----------------------------------+ + | 5 | association restarted or timed | + | | out | + +-----------------+-----------------------------------+ + | 6 | no reply (only used with one-shot | + | | clock set command) | + +-----------------+-----------------------------------+ + | 7 | peer rate limit exceeded (kiss | + | | code RATE received) | + +-----------------+-----------------------------------+ + | 8 | access denied (kiss code DENY | + | | received) | + +-----------------+-----------------------------------+ + | 9 | leap second insertion/deletion at | + | | month's end armed by peer vote | + +-----------------+-----------------------------------+ + | 10 | became system peer (sys.peer) | + +-----------------+-----------------------------------+ + | 11 | reference clock event (see clock | + | | status word) | + +-----------------+-----------------------------------+ + | 12 | authentication failed | + +-----------------+-----------------------------------+ + | 13 | popcorn spike suppressed by peer | + | | clock filter register | + +-----------------+-----------------------------------+ + | 14 | entering interleaved mode | + +-----------------+-----------------------------------+ + | 15 | recovered from interleave error | + +-----------------+-----------------------------------+ + + Table 7: Peer Event Code Values + +3.3. Clock Status Word + + There are two ways a reference clock can be attached to an NTP + service host: as a dedicated device managed by the operating system + and as a synthetic peer managed by NTP. As in the read status + command, the Association ID is used to identify the correct variable + for each clock: zero for the system clock and nonzero for a peer + clock. Only one system clock is supported by the protocol, although + many peer clocks can be supported. A system or peer clock status + word appears in the status field of the response to a read clock + variables or write clock variables command. This word can be + considered to be an extension of the system status word or the peer + status word as appropriate. The format of the clock status word is + as follows: + + Reserved: + This is an 8-bit integer that is ignored by requesters and zeroed + by responders. + + Count: + This is a 4-bit integer indicating the number of clock events that + occurred since the last time the clock event code changed. Upon + reaching 15, subsequent events with the same code are not counted. + + Clock Code (Code): + This is a 4-bit integer indicating the current clock status, with + values coded as follows: + + +==============+=================================+ + | Clock Status | Meaning | + +==============+=================================+ + | 0 | clock operating within nominals | + +--------------+---------------------------------+ + | 1 | reply timeout | + +--------------+---------------------------------+ + | 2 | bad reply format | + +--------------+---------------------------------+ + | 3 | hardware or software fault | + +--------------+---------------------------------+ + | 4 | propagation failure | + +--------------+---------------------------------+ + | 5 | bad date format or value | + +--------------+---------------------------------+ + | 6 | bad time format or value | + +--------------+---------------------------------+ + | 7-15 | reserved | + +--------------+---------------------------------+ + + Table 8: Clock Code Values + +3.4. Error Status Word + + An error status word is returned in the status field of an error + response as the result of invalid message format or contents. Its + presence is indicated when the E (error) bit is set along with the + response (R) bit in the response. It consists of an 8-bit integer + coded as follows: + + +==============+==================================+ + | Error Status | Meaning | + +==============+==================================+ + | 0 | unspecified | + +--------------+----------------------------------+ + | 1 | authentication failure | + +--------------+----------------------------------+ + | 2 | invalid message length or format | + +--------------+----------------------------------+ + | 3 | invalid opcode | + +--------------+----------------------------------+ + | 4 | unknown Association ID | + +--------------+----------------------------------+ + | 5 | unknown variable name | + +--------------+----------------------------------+ + | 6 | invalid variable value | + +--------------+----------------------------------+ + | 7 | administratively prohibited | + +--------------+----------------------------------+ + | 8-255 | reserved | + +--------------+----------------------------------+ + + Table 9: Error Status Word Codes + +4. Commands + + Commands consist of the header and optional data field shown in + Figure 1. When present, the data field contains a list of + identifiers or assignments in the form + <<identifier>>[=<<value>>],<<identifier>>[=<<value>>],... where + <<identifier>> is the ASCII name of a system or peer variable such as + the ones specified in RFC 5905 and <<value>> is expressed as a + decimal, hexadecimal, or string constant in the syntax of the C + programming language. Where no ambiguity exists, the "sys." or + "peer." prefixes can be suppressed. Space characters (ASCII + nonprinting format effectors) can be added to improve readability for + simple monitoring programs that do not reformat the data field. + Representations of note are as follows: + + * IPv4 internet addresses are written in the form [n.n.n.n], where n + is in decimal notation and the brackets are optional + + * IPv6 internet addresses are formulated based on the guidelines + defined in [RFC5952]. + + * Timestamps (including reference, originate, receive, and transmit + values) and the logical clock are represented in units of seconds + and fractions, preferably in hexadecimal notation. + + * Delay, offset, dispersion, and distance values are represented in + units of milliseconds and fractions, preferably in decimal + notation. + + * All other values are represented as is, preferably in decimal + notation. + + Implementations may define variables other than those described in + RFC 5905; called "extramural variables", these are distinguished by + the inclusion of some character type other than alphanumeric or "." + in the name. For those commands that return a list of assignments in + the response data field, if the command data field is empty, it is + expected that all available variables defined in RFC 5905 will be + included in the response. For the read commands, if the command data + field is nonempty, an implementation may choose to process this field + to individually select which variables are to be returned. + + Commands are interpreted as follows: + + Read Status (1): + The command data field is empty or contains a list of identifiers + separated by commas. The command operates in two ways depending + on the value of the Association ID. If this identifier is + nonzero, the response includes the peer identifier and status + word. Optionally, the response data field may contain other + information, such as described in the Read Variables command. If + the association identifier is zero, the response includes the + system identifier (0) and status word; the data field contains a + list of binary-coded pairs <<Association ID>> <<status word>>, one + for each currently defined association. + + Read Variables (2): + The command data field is empty or contains a list of identifiers + separated by commas. If the Association ID is nonzero, the + response includes the requested peer identifier and status word; + the data field contains a list of peer variables and values as + described above. If the Association ID is zero, the data field + contains a list of system variables. If a peer has been selected + as the synchronization source, the response includes the peer + identifier and status word; otherwise, the response includes the + system identifier (0) and status word. + + Write Variables (3): + The command data field contains a list of assignments as described + above. The variables are updated as indicated. The response is + as described for the Read Variables command. + + Read Clock Variables (4): + The command data field is empty or contains a list of identifiers + separated by commas. The Association ID selects the system clock + variables or peer clock variables in the same way as in the Read + Variables command. The response includes the requested clock + identifier and status word; the data field contains a list of + clock variables and values, including the last timecode message + received from the clock. + + Write Clock Variables (5): + The command data field contains a list of assignments as described + above. The clock variables are updated as indicated. The + response is as described for the read clock variables command. + + Set Trap Address/Port (6): + The command Association ID, status, and data fields are ignored. + The address and port number for subsequent trap messages are taken + from the source address and port of the control message itself. + The initial trap counter for trap response messages is taken from + the sequence field of the command. The response association + identifier, status, and data fields are not significant. + Implementations should include logical timeouts that prevent trap + transmissions if the monitoring program does not renew this + information after a lengthy interval. + + Trap Response (7): + This message is sent when a system, peer, or clock exception event + occurs. The opcode field is 7 and the R bit is set. The trap + counter is incremented by one for each trap sent and the sequence + field set to that value. The trap message is sent using the IP + address and port fields established by the set trap address/port + command. If a system trap, the Association ID field is set to + zero and the status field contains the system status word. If a + peer trap, the Association ID field is set to that peer and the + status field contains the peer status word. Optional ASCII-coded + information can be included in the data field. + + Configure (8): + The command data is parsed and applied as if supplied in the + daemon configuration file. + + Save Configuration (9): + Writes a snapshot of the current configuration to the file name + supplied as the command data. Further, the command is refused + unless a directory in which to store the resulting files has been + explicitly configured by the operator. + + Read Most Recently Used (MRU) list (10): + Retrieves records of recently seen remote addresses and associated + statistics. This command supports all of the state variables + defined in Section 9 of [RFC5905]. Command data consists of + name=value pairs controlling the selection of records, as well as + a requestor-specific nonce previously retrieved using this command + or opcode 12 (Request Nonce). The response consists of name=value + pairs where some names can appear multiple times using a dot + followed by a zero-based index to distinguish them and to + associate elements of the same record with the same index. A new + nonce is provided with each successful response. + + Read ordered list (11): + Retrieves a list ordered by IP address (IPv4 information precedes + IPv6 information). If the command data is empty or is the seven + characters "ifstats", the associated statistics, status, and + counters for each local address are returned. If the command data + is the characters "addr_restrictions", then the set of IPv4 remote + address restrictions followed by the set of IPv6 remote address + restrictions (access control lists) are returned. Other command + data returns error code 5 (unknown variable name). Similar to + Read MRU, response information uses zero-based indexes as part of + the variable name preceding the equals sign and value, where each + index relates information for a single address or network. This + opcode requires authentication. + + Request Nonce (12): + Retrieves a 96-bit nonce specific to the requesting remote + address, which is valid for a limited period. Command data is not + used in the request. The nonce consists of a 64-bit NTP timestamp + and 32 bits of hash derived from that timestamp, the remote + address, and salt known only to the server, which varies between + daemon runs. Inclusion of the nonce by a management agent + demonstrates to the server that the agent can receive datagrams + sent to the source address of the request, making source address + "spoofing" more difficult in a similar way as TCP's three-way + handshake. + + Unset Trap (31): + Removes the requesting remote address and port from the list of + trap receivers. Command data is not used in the request. If the + address and port are not in the list of trap receivers, the error + code is 4 (bad association). + +5. IANA Considerations + + This document has no IANA actions. + +6. Security Considerations + + A number of security vulnerabilities have been identified with these + control messages. + + NTP's control query interface allows reading and writing of system, + peer, and clock variables remotely from arbitrary IP addresses using + commands mentioned in Section 4. Overwriting these variables, but + not reading them, requires authentication by default. However, this + document argues that an NTP host must authenticate all control + queries and not just ones that overwrite these variables. + Alternatively, the host can use an access control list to explicitly + list IP addresses that are allowed to control query the clients. + These access controls are required for the following reasons: + + NTP as a Distributed Denial-of-Service (DDoS) vector: + NTP timing query and response packets (modes 1-2, 3-4, and 5) are + usually short in size. However, some NTP control queries generate + a very long packet in response to a short query. As such, there + is a history of use of NTP's control queries, which exhibit such + behavior, to perform DoS attacks. These off-path attacks exploit + the large size of NTP control queries to cause UDP-based + amplification attacks (e.g., mode 7 monlist command generates a + very long packet in response to a small query [CVE-DOS]). These + attacks only use NTP as a vector for DoS attacks on other + protocols, but do not affect the time service on the NTP host + itself. To limit the sources of these malicious commands, NTP + server operators are recommended to deploy ingress filtering + [RFC3704]. + + Time-shifting attacks through information leakage/overwriting: + NTP hosts save important system and peer state variables. An off- + path attacker who can read these variables remotely can leverage + the information leaked by these control queries to perform time- + shifting and DDoS attacks on NTP clients. These attacks do affect + time synchronization on the NTP hosts. For instance: + + * In the client/server mode, the client stores its local time when + it sends the query to the server in its xmt peer variable. This + variable is used to perform TEST2 to non-cryptographically + authenticate the server (i.e., if the origin timestamp field in + the corresponding server response packet matches the xmt peer + variable, then the client accepts the packet). An off-path + attacker with the ability to read this variable can easily spoof + server response packets for the client, which will pass TEST2 and + can deny service or shift time on the NTP client. The specific + attack is described in [CVE-SPOOF]. + + * The client also stores its local time when the server response is + received in its rec peer variable. This variable is used for + authentication in interleaved-pivot mode. An off-path attacker + with the ability to read this state variable can easily shift time + on the client by passing this test. This attack is described in + [CVE-SHIFT]. + + Fast-Scanning: + NTP mode 6 control messages are usually small UDP packets. Fast- + scanning tools like ZMap can be used to spray the entire + (potentially reachable) Internet with these messages within hours + to identify vulnerable hosts. To make things worse, these attacks + can be extremely low-rate, only requiring a control query for + reconnaissance and a spoofed response to shift time on vulnerable + clients. + + The mode 6 and 7 messages are vulnerable to replay attacks + [CVE-Replay]: + If an attacker observes mode 6/7 packets that modify the + configuration of the server in any way, the attacker can apply the + same change at any time later by simply sending the packets to the + server again. The use of the nonce (Request Nonce command) + provides limited protection against replay attacks. + + NTP best practices recommend configuring NTP with the no-query + parameter. The no-query parameter blocks access to all remote + control queries. However, sometimes the hosts do not want to block + all queries and want to give access for certain control queries + remotely. This could be for the purpose of remote management and + configuration of the hosts in certain scenarios. Such hosts tend to + use firewalls or other middleboxes to blacklist certain queries + within the network. + + Significantly fewer hosts respond to mode 7 monlist queries as + compared to other control queries because it is a well-known and + exploited control query. These queries are likely blocked using + blacklists on firewalls and middleboxes rather than the no-query + option on NTP hosts. The remaining control queries that can be + exploited likely remain out of the blacklist because they are + undocumented in the current NTP specification [RFC5905]. + + This document describes all of the mode 6 control queries allowed by + NTP and can help administrators make informed decisions on security + measures to protect NTP devices from harmful queries and likely make + those systems less vulnerable. The use of the legacy mode 6 + interface is NOT RECOMMENDED. Regardless of which mode 6 commands an + administrator may elect to allow, remote access to this facility + needs to be protected from unauthorized access (e.g., strict Access + Control Lists (ACLs)). Additionally, the legacy interface for mode 6 + commands SHOULD NOT be utilized in new deployments or implementation + of NTP. + +7. References + +7.1. Normative References + + [RFC1305] Mills, D., "Network Time Protocol (Version 3) + Specification, Implementation and Analysis", RFC 1305, + DOI 10.17487/RFC1305, March 1992, + <https://www.rfc-editor.org/info/rfc1305>. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <https://www.rfc-editor.org/info/rfc2119>. + + [RFC3704] Baker, F. and P. Savola, "Ingress Filtering for Multihomed + Networks", BCP 84, RFC 3704, DOI 10.17487/RFC3704, March + 2004, <https://www.rfc-editor.org/info/rfc3704>. + + [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, + "Network Time Protocol Version 4: Protocol and Algorithms + Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, + <https://www.rfc-editor.org/info/rfc5905>. + + [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 + Address Text Representation", RFC 5952, + DOI 10.17487/RFC5952, August 2010, + <https://www.rfc-editor.org/info/rfc5952>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + +7.2. Informative References + + [CVE-DOS] NIST National Vulnerability Database, "CVE-2013-5211 + Detail", 2 January 2014, + <https://nvd.nist.gov/vuln/detail/CVE-2013-5211>. + + [CVE-Replay] + NIST National Vulnerability Database, "CVE-2015-8140 + Detail", 30 January 2015, + <https://nvd.nist.gov/vuln/detail/CVE-2015-8140>. + + [CVE-SHIFT] + NIST National Vulnerability Database, "CVE-2016-1548 + Detail", 6 January 2017, + <https://nvd.nist.gov/vuln/detail/CVE-2016-1548>. + + [CVE-SPOOF] + NIST National Vulnerability Database, "CVE-2015-8139 + Detail", 30 January 2017, + <https://nvd.nist.gov/vuln/detail/CVE-2015-8139>. + + [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, + DOI 10.17487/RFC0791, September 1981, + <https://www.rfc-editor.org/info/rfc791>. + + [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 + (IPv6) Specification", STD 86, RFC 8200, + DOI 10.17487/RFC8200, July 2017, + <https://www.rfc-editor.org/info/rfc8200>. + +Appendix A. NTP Remote Facility Message Format + + The format of the NTP Remote Facility Message header, which + immediately follows the UDP header, is shown in Figure 3. A + description of its fields follows Figure 3. Bit positions marked as + zero are reserved and should always be transmitted as zero. + + 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 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |R|M| VN |Mode |A| Sequence | Implementation| Req Code | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Err | Count | MBZ | Size | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + / Data (up to 500 bytes) / + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Encryption KeyID (when A bit set) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + / Message Authentication Code (when A bit set) / + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + Figure 3: NTP Remote Facility Message Header + + Response Bit (R): + Set to 0 if the packet is a request. Set to 1 if the packet is a + response. + + More Bit (M): + Set to 0 if this is the last packet in a response; otherwise, set + to 1 in responses requiring more than one packet. + + Version Number (VN): + Set to the version number of the NTP daemon. + + Mode: + Set to 7 for Remote Facility messages. + + Authenticated Bit (A): + If set to 1, this packet contains authentication information. + + Sequence: + For a multi-packet response, this field contains the sequence + number of this packet. Packets in a multi-packet response are + numbered starting with 0. The More Bit is set to 1 for all + packets but the last. + + Implementation: + The version number of the implementation that defined the request + code used in this message. An implementation number of 0 is used + for a request code supported by all versions of the NTP daemon. + The value 255 is reserved for future extensions. + + Request Code (Req Code): + An implementation-specific code that specifies the operation being + requested. A request code definition includes the format and + semantics of the data included in the packet. + + Error (Err): + Set to 0 for a request. For a response, this field contains an + error code relating to the request. If the Error is nonzero, the + operation requested wasn't performed. + + 0: no error + + 1: incompatible implementation number + + 2: unimplemented request code + + 3: format error + + 4: no data available + + 7: authentication failure + + Count: + The number of data items in the packet. Range is 0 to 500. + + Must Be Zero (MBZ): + A reserved field set to 0 in requests and responses. + + Size: + The size of each data item in the packet. Range is 0 to 500. + + Data: + A variable-sized field containing request/response data. For + requests and responses, the size in octets must be greater than or + equal to the product of the number of data items (Count) and the + size of a data item (Size). For requests, the data area is + exactly 40 octets in length. For responses, the data area will + range from 0 to 500 octets, inclusive. + + Encryption KeyID: + A 32-bit unsigned integer used to designate the key used for the + Message Authentication Code. This field is included only when the + A bit is set to 1. + + Message Authentication Code: + An optional Message Authentication Code defined by the version of + the NTP daemon indicated in the Implementation field. This field + is included only when the A bit is set to 1. + +Acknowledgements + + Tim Plunkett created the original version of this document. Aanchal + Malhotra provided the initial version of the Security Considerations + section. + + Karen O'Donoghue, David Hart, Harlan Stenn, and Philip Chimento + deserve credit for portions of this document due to their earlier + efforts to document these commands. + + Miroshav Lichvar, Ulrich Windl, Dieter Sibold, J Ignacio Alvarez- + Hamelin, and Alex Campbell provided valuable comments on various + draft versions of this document. + +Contributors + + Dr. David Mills specified the vast majority of the mode 6 commands + during the development of [RFC1305] and deserves the credit for their + existence and use. + +Author's Address + + Brian Haberman (editor) + JHU + Email: brian@innovationslab.net |