idnits 2.17.1 draft-ietf-ntp-mode-6-cmds-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 27, 2018) is 2037 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 1305 (Obsoleted by RFC 5905) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Haberman, Ed. 3 Internet-Draft JHU 4 Intended status: Informational September 27, 2018 5 Expires: March 31, 2019 7 Control Messages Protocol for Use with Network Time Protocol Version 4 8 draft-ietf-ntp-mode-6-cmds-06 10 Abstract 12 This document describes the structure of the control messages that 13 were historically used with the Network Time Protocol before the 14 advent of more modern control and management approaches. These 15 control messages have been used to monitor and control the Network 16 Time Protocol application running on any IP network attached 17 computer. The information in this document was originally described 18 in Appendix B of RFC 1305. The goal of this document is to provide a 19 current, but historic, description of the control messages as 20 described in RFC 1305 and any additional commands implemented in NTP. 22 The publication of this document is not meant to encourage the 23 developement and deployment of these control messages. This document 24 is only providing a current reference for these control messages 25 given the current status of RFC 1305. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on March 31, 2019. 44 Copyright Notice 46 Copyright (c) 2018 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 This document may contain material from IETF Documents or IETF 60 Contributions published or made publicly available before November 61 10, 2008. The person(s) controlling the copyright in some of this 62 material may not have granted the IETF Trust the right to allow 63 modifications of such material outside the IETF Standards Process. 64 Without obtaining an adequate license from the person(s) controlling 65 the copyright in such materials, this document may not be modified 66 outside the IETF Standards Process, and derivative works of it may 67 not be created outside the IETF Standards Process, except to format 68 it for publication as an RFC or to translate it into languages other 69 than English. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 74 1.1. Control Message Overview . . . . . . . . . . . . . . . . 3 75 1.2. Remote Facility Message Overview . . . . . . . . . . . . 4 76 2. NTP Control Message Format . . . . . . . . . . . . . . . . . 5 77 3. Status Words . . . . . . . . . . . . . . . . . . . . . . . . 7 78 3.1. System Status Word . . . . . . . . . . . . . . . . . . . 8 79 3.2. Peer Status Word . . . . . . . . . . . . . . . . . . . . 10 80 3.3. Clock Status Word . . . . . . . . . . . . . . . . . . . . 12 81 3.4. Error Status Word . . . . . . . . . . . . . . . . . . . . 12 82 4. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 13 83 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 85 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18 86 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 87 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 88 9.1. Normative References . . . . . . . . . . . . . . . . . . 18 89 9.2. Informative References . . . . . . . . . . . . . . . . . 19 90 Appendix A. NTP Remote Facility Message Format . . . . . . . . . 19 91 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 93 1. Introduction 95 RFC 1305 [RFC1305] described a set of control messages for use within 96 the Network Time Protocol (NTP) when a comprehensive network 97 management solution was not available. The definitions of these 98 control messages were not promulgated to RFC 5905 [RFC5905] when NTP 99 version 4 was documented. These messages were intended for use only 100 in systems where no other management facilities were available or 101 appropriate, such as in dedicated-function bus peripherals. Support 102 for these messages is not required in order to conform to RFC 5905 103 [RFC5905]. The control messages are described here as a historical 104 record given their use within NTPv4. 106 The publication of this document is not meant to encourage the 107 developement and deployment of these control messages. This document 108 is only providing a current reference for these control messages 109 given the current status of RFC 1305. 111 1.1. Control Message Overview 113 The NTP Control Message has the value 6 specified in the mode field 114 of the first octet of the NTP header and is formatted as shown in 115 Figure 1. The format of the data field is specific to each command 116 or response; however, in most cases the format is designed to be 117 constructed and viewed by humans and so is coded in free-form ASCII. 118 This facilitates the specification and implementation of simple 119 management tools in the absence of fully evolved network-management 120 facilities. As in ordinary NTP messages, the authenticator field 121 follows the data field. If the authenticator is used the data field 122 is zero-padded to a 32-bit boundary, but the padding bits are not 123 considered part of the data field and are not included in the field 124 count. 126 IP hosts are not required to reassemble datagrams larger than 576 127 octets [RFC0791]; however, some commands or responses may involve 128 more data than will fit into a single datagram. Accordingly, a 129 simple reassembly feature is included in which each octet of the 130 message data is numbered starting with zero. As each fragment is 131 transmitted the number of its first octet is inserted in the offset 132 field and the number of octets is inserted in the count field. The 133 more-data (M) bit is set in all fragments except the last. 135 Most control functions involve sending a command and receiving a 136 response, perhaps involving several fragments. The sender chooses a 137 distinct, nonzero sequence number and sets the status field and "R" 138 and "E" bits to zero. The responder interprets the opcode and 139 additional information in the data field, updates the status field, 140 sets the "R" bit to one and returns the three 32-bit words of the 141 header along with additional information in the data field. In case 142 of invalid message format or contents the responder inserts a code in 143 the status field, sets the "R" and "E" bits to one and, optionally, 144 inserts a diagnostic message in the data field. 146 Some commands read or write system variables (e.g., s.offset) and 147 peer variables (e.g., p.stratum) for an association identified in the 148 command. Others read or write variables associated with a radio 149 clock or other device directly connected to a source of primary 150 synchronization information. To identify which type of variable and 151 association the Association ID is used. System variables are 152 indicated by the identifier zero. As each association is mobilized a 153 unique, nonzero identifier is created for it. These identifiers are 154 used in a cyclic fashion, so that the chance of using an old 155 identifier which matches a newly created association is remote. A 156 management entity can request a list of current identifiers and 157 subsequently use them to read and write variables for each 158 association. An attempt to use an expired identifier results in an 159 exception response, following which the list can be requested again. 161 Some exception events, such as when a peer becomes reachable or 162 unreachable, occur spontaneously and are not necessarily associated 163 with a command. An implementation may elect to save the event 164 information for later retrieval or to send an asynchronous response 165 (called a trap) or both. In case of a trap the IP address and port 166 number is determined by a previous command and the sequence field is 167 set as described below. Current status and summary information for 168 the latest exception event is returned in all normal responses. Bits 169 in the status field indicate whether an exception has occurred since 170 the last response and whether more than one exception has occurred. 172 Commands need not necessarily be sent by an NTP peer, so ordinary 173 access-control procedures may not apply; however, the optional mask/ 174 match mechanism suggested elsewhere in this document provides the 175 capability to control access by mode number, so this could be used to 176 limit access for control messages (mode 6) to selected address 177 ranges. 179 1.2. Remote Facility Message Overview 181 The original development of the NTP daemon included a remote facility 182 (ntpdc) for monitoring and configuration. This facility used mode 7 183 commands to communicate with the NTP daemon. This document 184 illustrates the mode 7 packet format only. The commands embedded in 185 the mode 7 messages are implementation specific and not standardized 186 in any way. The mode 7 message format is described in Appendix A. 188 2. NTP Control Message Format 190 The format of the NTP Control Message header, which immediately 191 follows the UDP header, is shown in Figure 1. Following is a 192 description of its fields. Bit positions marked as zero are reserved 193 and should always be transmitted as zero. 195 0 1 2 3 196 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 197 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 198 |LI | VN |Mode |R|E|M| OpCode | Sequence Number | 199 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 200 | Status | Association ID | 201 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 202 | Offset | Count | 203 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 204 | | 205 / Data (up to 468 bytes) / 206 | | 207 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 208 | Padding (optional) | 209 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 210 | | 211 / Authenticator (optional, 96 bits) / 212 | | 213 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 215 Figure 1: NTP Control Message Header 217 Leap Indicator (LI): This is a two-bit integer that is set to b00 for 218 control message requests and responses. The Leap Indicator value 219 used at this position in most NTP modes is in the System Status Word 220 provided in some control message responses. 222 Version Number (VN): This is a three-bit integer indicating a minimum 223 NTP version number. NTP servers do not respond to control messages 224 with an unrecognized version number. Requests may intentionally use 225 a lower version number to enable interoperability with earlier 226 versions of NTP. Responses carry the same version as the 227 corresponding request. 229 Mode: This is a three-bit integer indicating the mode. The value 6 230 indicates an NTP control message. 232 Response Bit (R): Set to zero for commands, one for responses. 234 Error Bit (E): Set to zero for normal response, one for error 235 response. 237 More Bit (M): Set to zero for last fragment, one for all others. 239 Operation Code (OpCode): This is a five-bit integer specifying the 240 command function. Values currently defined include the following: 242 +-------+--------------------------------------------------+ 243 | Code | Meaning | 244 +-------+--------------------------------------------------+ 245 | 0 | reserved | 246 | 1 | read status command/response | 247 | 2 | read variables command/response | 248 | 3 | write variables command/response | 249 | 4 | read clock variables command/response | 250 | 5 | write clock variables command/response | 251 | 6 | set trap address/port command/response | 252 | 7 | trap response | 253 | 8 | runtime configuration command/response | 254 | 9 | export configuration to file command/response | 255 | 10 | retrieve remote address stats command/response | 256 | 11 | retrieve ordered list command/response | 257 | 12 | request client-specific nonce command/response | 258 | 13-30 | reserved | 259 | 31 | unset trap address/port command/response | 260 +-------+--------------------------------------------------+ 262 Sequence Number: This is a 16-bit integer indicating the sequence 263 number of the command or response. Each request uses a different 264 sequence number. Each response carries the same sequence number as 265 its corresponding request. For asynchronous trap responses, the 266 responder increments the sequence number by one for each response, 267 allowing trap receivers to detect missing trap responses. The 268 sequence number of each fragment of a multiple-datagram response 269 carries the same sequence number, copied from the request. 271 Status: This is a 16-bit code indicating the current status of the 272 system, peer or clock, with values coded as described in following 273 sections. 275 Association ID: This is a 16-bit unsigned integer identifying a valid 276 association, or zero for the system clock. 278 Offset: This is a 16-bit unsigned integer indicating the offset, in 279 octets, of the first octet in the data area. The offset is set to 280 zero in requests. Responses spanning multiple datagrams use a 281 positive offset in all but the first datagram. 283 Count: This is a 16-bit unsigned integer indicating the length of the 284 data field, in octets. 286 Data: This contains the message data for the command or response. 287 The maximum number of data octets is 468. 289 Padding (optional): Conains zero to three octets with value zero, as 290 needed to ensure the overall control message size is a multiple of 4 291 octets. 293 Authenticator (optional): When the NTP authentication mechanism is 294 implemented, this contains the authenticator information defined in 295 Appendix C of RFC 1305. 297 3. Status Words 299 Status words indicate the present status of the system, associations 300 and clock. They are designed to be interpreted by network-monitoring 301 programs and are in one of four 16-bit formats shown in Figure 2 and 302 described in this section. System and peer status words are 303 associated with responses for all commands except the read clock 304 variables, write clock variables and set trap address/port commands. 305 The association identifier zero specifies the system status word, 306 while a nonzero identifier specifies a particular peer association. 307 The status word returned in response to read clock variables and 308 write clock variables commands indicates the state of the clock 309 hardware and decoding software. A special error status word is used 310 to report malformed command fields or invalid values. 312 0 1 313 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 314 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 315 | LI| Clock Src | Count | Code | 316 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 317 System Status Word 319 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 320 | Status | SEL | Count | Code | 321 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 322 Peer Status Word 324 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 325 | Clock Status | Code | 326 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 327 Radio Status Word 329 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 330 | Error Code | Reserved | 331 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 332 Error Status Word 334 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 335 | Reserved | Count | Code | 336 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 337 Clock Status Word 339 Figure 2: Status Word Formats 341 3.1. System Status Word 343 The system status word appears in the status field of the response to 344 a read status or read variables command with a zero association 345 identifier. The format of the system status word is as follows: 347 Leap Indicator (LI): This is a two-bit code warning of an impending 348 leap second to be inserted/deleted in the last minute of the current 349 day, with bit 0 and bit 1, respectively, coded as follows: 351 +------+------------------------------------------------------------+ 352 | LI | Meaning | 353 +------+------------------------------------------------------------+ 354 | 00 | no warning | 355 | 01 | insert second after 23:59:59 of the current day | 356 | 10 | delete second 23:59:59 of the current day | 357 | 11 | unsynchronized | 358 +------+------------------------------------------------------------+ 359 Clock Source (Clock Src): This is a six-bit integer indicating the 360 current synchronization source, with values coded as follows: 362 +-------+-----------------------------------------------------------+ 363 | Code | Meaning | 364 +-------+-----------------------------------------------------------+ 365 | 0 | unspecified or unknown | 366 | 1 | Calibrated atomic clock (e.g., PPS, HP 5061) | 367 | 2 | VLF (band 4) or LF (band 5) radio (e.g., OMEGA,, WWVB) | 368 | 3 | HF (band 7) radio (e.g., CHU, MSF, WWV/H) | 369 | 4 | UHF (band 9) satellite (e.g., GOES, GPS) | 370 | 5 | local net (e.g., DCN, TSP, DTS) | 371 | 6 | UDP/NTP | 372 | 7 | UDP/TIME | 373 | 8 | eyeball-and-wristwatch | 374 | 9 | telephone modem (e.g., NIST) | 375 | 10-63 | reserved | 376 +-------+-----------------------------------------------------------+ 378 System Event Counter (Count): This is a four-bit integer indicating 379 the number of system events occurring since the last time the System 380 Event Code changed. Upon reaching 15, subsequent events with the 381 same code are not counted. 383 System Event Code (Code): This is a four-bit integer identifying the 384 latest system exception event, with new values overwriting previous 385 values, and coded as follows: 387 +------+---------------------------------------------------------+ 388 | Code | Meaning | 389 +------+---------------------------------------------------------+ 390 | 0 | unspecified | 391 | 1 | frequency correction (drift) file not available | 392 | 2 | frequency correction started (frequency stepped) | 393 | 3 | spike detected and ignored, starting stepout timer | 394 | 4 | frequency training started | 395 | 5 | clock synchronized | 396 | 6 | system restart | 397 | 7 | panic stop (required step greater than panic threshold) | 398 | 8 | no system peer | 399 | 9 | leap second insertion/deletion armed for the | 400 | | of the current month | 401 | 10 | leap second disarmed | 402 | 11 | leap second inserted or deleted | 403 | 12 | clock stepped (stepout timer expired) | 404 | 13 | kernel loop discipline status changed | 405 | 14 | leapseconds table loaded from file | 406 | 15 | leapseconds table outdated, updated file needed | 407 +------+---------------------------------------------------------+ 409 3.2. Peer Status Word 411 A peer status word is returned in the status field of a response to a 412 read status, read variables or write variables command and appears 413 also in the list of association identifiers and status words returned 414 by a read status command with a zero association identifier. The 415 format of a peer status word is as follows: 417 Peer Status (Status): This is a five-bit code indicating the status 418 of the peer determined by the packet procedure, with bits assigned as 419 follows: 421 +-------------+---------------------------------------------------+ 422 | Peer Status | Meaning | 423 +-------------+---------------------------------------------------+ 424 | 0 | configured (peer.config) | 425 | 1 | authentication enabled (peer.authenable) | 426 | 2 | authentication okay (peer.authentic) | 427 | 3 | reachability okay (peer.reach != 0) | 428 | 4 | broadcast association | 429 +-------------+---------------------------------------------------+ 431 Peer Selection (SEL): This is a three-bit integer indicating the 432 status of the peer determined by the clock-selection procedure, with 433 values coded as follows: 435 +-----+-------------------------------------------------------------+ 436 | Sel | Meaning | 437 +-----+-------------------------------------------------------------+ 438 | 0 | rejected | 439 | 1 | discarded by intersection algorithm | 440 | 2 | discarded bu table overflow (not currently used) | 441 | 3 | discarded by the cluster algorithm | 442 | 4 | included by the combine algorithm | 443 | 5 | backup source (with more than sys.maxclock survivors) | 444 | 6 | system peer (synchronization source) | 445 | 7 | PPS (pulse per second) peer | 446 +-----+-------------------------------------------------------------+ 448 Peer Event Counter (Count): This is a four-bit integer indicating the 449 number of peer exception events that occurred since the last time the 450 peer event code changed. Upon reaching 15, subsequent events with 451 the same code are not counted. 453 Peer Event Code (Code): This is a four-bit integer identifying the 454 latest peer exception event, with new values overwriting previous 455 values, and coded as follows: 457 +-------+--------------------------------------------------------+ 458 | Peer | | 459 | Event | Meaning | 460 | Code | | 461 +-------+--------------------------------------------------------+ 462 | 0 | unspecified | 463 | 1 | association mobilized | 464 | 2 | association demobilized | 465 | 3 | peer unreachable (peer.reach was nonzero now zero) | 466 | 4 | peer reachable (peer.reach was zero now nonzero) | 467 | 5 | association restarted or timed out | 468 | 6 | no reply (only used with one-shot ntpd -q) | 469 | 7 | peer rate limit exceeded (kiss code RATE received) | 470 | 8 | access denied (kiss code DENY received) | 471 | 9 | leap second insertion/deletion at month's end armed | 472 | | by peer vote | 473 | 10 | became system peer (sys.peer) | 474 | 11 | reference clock event (see clock status word) | 475 | 12 | authentication failed | 476 | 13 | popcorn spike suppressed by peer clock filter register | 477 | 14 | entering interleaved mode | 478 | 15 | recovered from interleave error | 479 +-------+--------------------------------------------------------+ 481 3.3. Clock Status Word 483 There are two ways a reference clock can be attached to a NTP service 484 host, as an dedicated device managed by the operating system and as a 485 synthetic peer managed by NTP. As in the read status command, the 486 association identifier is used to identify which one, zero for the 487 system clock and nonzero for a peer clock. Only one system clock is 488 supported by the protocol, although many peer clocks can be 489 supported. A system or peer clock status word appears in the status 490 field of the response to a read clock variables or write clock 491 variables command. This word can be considered an extension of the 492 system status word or the peer status word as appropriate. The 493 format of the clock status word is as follows: 495 Reserved: An eight-bit integer that is ignored by requesters and 496 zeroed by responders. 498 Count: This is a four-bit integer indicating the number of clock 499 events that occurred since the last time the clock event code 500 changed. Upon reaching 15, subsequent events with the same code are 501 not counted. 503 Clock Code (Code): This is a four-bit integer indicating the current 504 clock status, with values coded as follows: 506 +--------------+--------------------------------------------------+ 507 | Clock Status | Meaning | 508 +--------------+--------------------------------------------------+ 509 | 0 | clock operating within nominals | 510 | 1 | reply timeout | 511 | 2 | bad reply format | 512 | 3 | hardware or software fault | 513 | 4 | propagation failure | 514 | 5 | bad date format or value | 515 | 6 | bad time format or value | 516 | 7-15 | reserved | 517 +--------------+--------------------------------------------------+ 519 3.4. Error Status Word 521 An error status word is returned in the status field of an error 522 response as the result of invalid message format or contents. Its 523 presence is indicated when the E (error) bit is set along with the 524 response (R) bit in the response. It consists of an eight-bit 525 integer coded as follows: 527 +--------------+--------------------------------------------------+ 528 | Error Status | Meaning | 529 +--------------+--------------------------------------------------+ 530 | 0 | unspecified | 531 | 1 | authentication failure | 532 | 2 | invalid message length or format | 533 | 3 | invalid opcode | 534 | 4 | unknown association identifier | 535 | 5 | unknown variable name | 536 | 6 | invalid variable value | 537 | 7 | administratively prohibited | 538 | 8-255 | reserved | 539 +--------------+--------------------------------------------------+ 541 4. Commands 543 Commands consist of the header and optional data field shown in 544 Figure 2. When present, the data field contains a list of 545 identifiers or assignments in the form 546 <>[=<>],<>[=<>],... where 547 <> is the ASCII name of a system or peer variable 548 specified in RFC 5905 and <> is expressed as a decimal, 549 hexadecimal or string constant in the syntax of the C programming 550 language. Where no ambiguity exists, the <169>sys.<170> or 551 <169>peer.<170> prefixes can be suppressed. Whitespace (ASCII 552 nonprinting format effectors) can be added to improve readability for 553 simple monitoring programs that do not reformat the data field. 554 Internet addresses are represented as follows: IPv4 addresses are 555 written in the form [n.n.n.n], where n is in decimal notation and the 556 brackets are optional; IPv6 addresses are formulated based on the 557 guidelines defined in [RFC5952]. Timestamps, including reference, 558 originate, receive and transmit values, as well as the logical clock, 559 are represented in units of seconds and fractions, preferably in 560 hexadecimal notation. Delay, offset, dispersion and distance values 561 are represented in units of milliseconds and fractions, preferably in 562 decimal notation. All other values are represented as-is, preferably 563 in decimal notation. 565 Implementations may define variables other than those described in 566 RFC 5905. Called extramural variables, these are distinguished by 567 the inclusion of some character type other than alphanumeric or 568 <169>.<170> in the name. For those commands that return a list of 569 assignments in the response data field, if the command data field is 570 empty, it is expected that all available variables defined in RFC 571 5905 will be included in the response. For the read commands, if the 572 command data field is nonempty, an implementation may choose to 573 process this field to individually select which variables are to be 574 returned. 576 Commands are interpreted as follows: 578 Read Status (1): The command data field is empty or contains a list 579 of identifiers separated by commas. The command operates in two ways 580 depending on the value of the association identifier. If this 581 identifier is nonzero, the response includes the peer identifier and 582 status word. Optionally, the response data field may contain other 583 information, such as described in the Read Variables command. If the 584 association identifier is zero, the response includes the system 585 identifier (0) and status word, while the data field contains a list 586 of binary-coded pairs <> <>, one 587 for each currently defined association. 589 Read Variables (2): The command data field is empty or contains a 590 list of identifiers separated by commas. If the association 591 identifier is nonzero, the response includes the requested peer 592 identifier and status word, while the data field contains a list of 593 peer variables and values as described above. If the association 594 identifier is zero, the data field contains a list of system 595 variables and values. If a peer has been selected as the 596 synchronization source, the response includes the peer identifier and 597 status word; otherwise, the response includes the system identifier 598 (0) and status word. 600 Write Variables (3): The command data field contains a list of 601 assignments as described above. The variables are updated as 602 indicated. The response is as described for the Read Variables 603 command. 605 Read Clock Variables (4): The command data field is empty or contains 606 a list of identifiers separated by commas. The association 607 identifier selects the system clock variables or peer clock variables 608 in the same way as in the Read Variables command. The response 609 includes the requested clock identifier and status word and the data 610 field contains a list of clock variables and values, including the 611 last timecode message received from the clock. 613 Write Clock Variables (5): The command data field contains a list of 614 assignments as described above. The clock variables are updated as 615 indicated. The response is as described for the Read Clock Variables 616 command. 618 Set Trap Address/Port (6): The command association identifier, status 619 and data fields are ignored. The address and port number for 620 subsequent trap messages are taken from the source address and port 621 of the control message itself. The initial trap counter for trap 622 response messages is taken from the sequence field of the command. 623 The response association identifier, status and data fields are not 624 significant. Implementations should include sanity timeouts which 625 prevent trap transmissions if the monitoring program does not renew 626 this information after a lengthy interval. 628 Trap Response (7): This message is sent when a system, peer or clock 629 exception event occurs. The opcode field is 7 and the R bit is set. 630 The trap counter is incremented by one for each trap sent and the 631 sequence field set to that value. The trap message is sent using the 632 IP address and port fields established by the set trap address/port 633 command. If a system trap the association identifier field is set to 634 zero and the status field contains the system status word. If a peer 635 trap the association identifier field is set to that peer and the 636 status field contains the peer status word. Optional ASCII-coded 637 information can be included in the data field. 639 Configure (8): The command data is parsed and applied as if supplied 640 in the daemon configuration file. The reference implementation 641 daemon requires authentication for this command. 643 Save Configuration (9): Write a snapshot of the current configuration 644 to the file name supplied as the command data. The reference 645 implementation daemon requires authentication for this command. 646 Further, the command is refused unless a directory in which to store 647 the resulting files has been explicitly configured by the operator. 649 Read MRU (10): Retrieves records of recently seen remote addresses 650 and associated statistics. Command data consists of name=value pairs 651 controlling the selection of records, as well as a requestor-specific 652 nonce previously retrieved using this command or opcode 12, Request 653 Nonce. The response consists of name=value pairs where some names 654 can appear multiple times using a dot followed by a zero-based index 655 to distinguish them, and to associate elements of the same record 656 with the same index. A new nonce is provided with each successful 657 response. 659 Read ordered list (11): Retrieves an ordered list. If the command 660 data is empty or the seven characters "ifstats" the associated 661 statistics, status and counters for each local address are returned. 662 If the command data is the characters "addr_restrictions" then the 663 set of IPv4 remote address restrictions followed by the set of IPv6 664 remote address restrictions (access control lists) are returned. 665 Other command data returns error code 5 (unknown variable name). 666 Similar to Read MRU, response information uses zero-based indexes as 667 part of the variable name preceding the equals sign and value, where 668 each index relates information for a single address or network. This 669 opcode requires authentication. 671 Request Nonce (12): Retrieves a 96-bit nonce specific to the 672 requesting remote address, which is valid for a limited period. 673 Command data is not used in the request. The nonce consists of a 674 64-bit NTP timestamp and 32 bits of hash derived from that timestamp, 675 the remote address, and salt known only to the server which varies 676 between daemon runs. The reference implementation honors nonces 677 which were issued less than 16 seconds prior. Inclusion of the nonce 678 by a managment agent demonstrates to the server that the agent can 679 receive datagrams sent to the source address of the request, making 680 source address "spoofing" more difficult in a similar way as TCP's 681 three-way handshake. 683 Unset Trap (31): Removes the requesting remote address and port from 684 the list of trap receivers. Command data is not used in the request. 685 If the address and port are not in the list of trap receivers, the 686 error code is 4, bad association. 688 5. IANA Considerations 690 This document makes no request of IANA. 692 Note to RFC Editor: this section may be removed on publication as an 693 RFC. 695 6. Security Considerations 697 A number of security vulnerabilities have been identified with these 698 control messages. 700 NTP's control query interface allows reading and writing of system, 701 peer, and clock variables remotely from arbitrary IP addresses using 702 commands mentioned in Section 4. Traditionally, overwriting these 703 variables, but not reading them, requires authentication by default. 704 However, this document argues that an NTP host must authenticate all 705 control queries and not just ones that overwrite these variables. 706 Alternatively, the host can use a whitelist to explicitly list IP 707 addresses that are allowed to control query the clients. These 708 access controls are required for the following reasons: 710 o NTP as a Distributed Denial-of-Service (DDoS) vector. NTP timing 711 query and response packets (modes 1-2, 3-4, 5) are usually short 712 in size. However, some NTP control queries generate a very long 713 packet in response to a short query. As such, there is a history 714 of use of NTP's control queries, which exhibit such behavior, to 715 perform DDoS attacks. These off-path attacks exploit the large 716 size of NTP control queries to cause UDP-based amplification 717 attacks (e.g., mode 7 monlist command generates a very long packet 718 in response to a small query [CVE-DOS]). These attacks only use 719 NTP as a vector for DoS atacks on other protocols, but do not 720 affect the time service on the NTP host itself. To limit the 721 sources of these malicious commands, NTP server operators are 722 recommended to deploy ingress filtering [RFC2827]. 724 o Time-shifting attacks through information leakage/overwriting. 725 NTP hosts save important system and peer state variables. An off- 726 path attacker who can read these variables remotely can leverage 727 the information leaked by these control queries to perform time- 728 shifting and DoS attacks on NTP clients. These attacks do affect 729 time synchronization on the NTP hosts. For instance, 731 * In the client/server mode, the client stores its local time 732 when it sends the query to the server in its xmt peer variable. 733 This variable is used to perform TEST2 to non-cryptographically 734 authenticate the server, i.e., if the origin timestamp field in 735 the corresponding server response packet matches the xmt peer 736 variable, then the client accepts the packet. An off-path 737 attacker, with the ability to read this variable can easily 738 spoof server response packets for the client, which will pass 739 TEST2, and can deny service or shift time on the NTP client. 740 The specific attack is described in [CVE-SPOOF]. 742 * The client also stores its local time when the server response 743 is received in its rec peer variable. This variable is used 744 for authentication in interleaved-pivot mode. An off-path 745 attacker with the ability to read this state variable can 746 easily shift time on the client by passing this test. This 747 attack is described in [CVE-SHIFT]. 749 o Fast-Scanning. NTP mode 6 control messages are usually small UDP 750 packets. Fast-scanning tools like ZMap can be used to spray the 751 entire (potentially reachable) Internet with these messages within 752 hours to identify vulnerable hosts. To make things worse, these 753 attacks can be extremely low-rate, only requiring a control query 754 for reconnaissance and a spoofed response to shift time on 755 vulnerable clients. 757 o The mode 6 and 7 messages are vulnerable to replay attacks 758 [CVE-Replay]. If an attacker observes mode 6/7 packets that 759 modify the configuration of the server in any way, the attacker 760 can apply the same change at any time later simply by sending the 761 packets to the server again. 763 NTP best practices recommend configuring ntpd with the no-query 764 parameter. The no-query parameter blocks access to all remote 765 control queries. However, sometimes the hosts do not want to block 766 all queries and want to give access for certain control queries 767 remotely. This could be for the purpose of remote management and 768 configuration of the hosts in certain scenarios. Such hosts tend to 769 use firewalls or other middleboxes to blacklist certain queries 770 within the network. 772 Significantly fewer hosts respond to mode 7 monlist queries as 773 compared to other control queries because it is a well-known and 774 exploited control query. These queries are likely blocked using 775 blacklists on firewalls and middleboxes rather than the no-query 776 option on NTP hosts. The remaining control queries that can be 777 exploited likely remain out of the blacklist because they are 778 undocumented in the current NTP specification [RFC5905]. 780 This document describes all of the mode 6 control queries allowed by 781 NTP and can help administrators make informed decisions on security 782 measures to protect NTP devices from harmful queries and likely make 783 those systems less vulnerable. Regardless of which mode 6 commands 784 an administrator elect to allow, remote access to this facility needs 785 to be protected from unauthorized access (e.g., strict ACLs). 787 7. Contributors 789 Dr. David Mills specified the vast majority of the mode 6 commands 790 during the development of RFC 1305 [RFC1305] and deserves the credit 791 for their existence and use. 793 8. Acknowledgements 795 Tim Plunkett created the original version of this document. Aanchal 796 Malhotra provided the initial version of the Security Considerations 797 section. 799 Karen O'Donoghue, David Hart, Harlan Stenn, and Philip Chimento 800 deserve credit for portions of this document due to their earlier 801 efforts to document these commands. 803 Miroshav Lichvar, Ulrich Windl, Dieter Sibold, J Ignacio Alvarez- 804 Hamelin, and Alex Campbell provided valuable comments on various 805 versions of this document. 807 9. References 809 9.1. Normative References 811 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 812 Specification, Implementation and Analysis", RFC 1305, 813 DOI 10.17487/RFC1305, March 1992, 814 . 816 [RFC2827] Ferguson, P. and D. Senie, "Network Ingress Filtering: 817 Defeating Denial of Service Attacks which employ IP Source 818 Address Spoofing", BCP 38, RFC 2827, DOI 10.17487/RFC2827, 819 May 2000, . 821 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 822 "Network Time Protocol Version 4: Protocol and Algorithms 823 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 824 . 826 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 827 Address Text Representation", RFC 5952, 828 DOI 10.17487/RFC5952, August 2010, 829 . 831 9.2. Informative References 833 [CVE-DOS] NIST National Vulnerability Database, "CVE-2013-5211, 834 https://nvd.nist.gov/vuln/detail/CVE-2013-5211", January 835 2014. 837 [CVE-Replay] 838 NIST National Vulnerability Database, "CVE-2015-8140, 839 https://nvd.nist.gov/vuln/detail/CVE-2015-8140", January 840 2015. 842 [CVE-SHIFT] 843 NIST National Vulnerability Database, "CVE-2016-1548, 844 https://nvd.nist.gov/vuln/detail/CVE-2016-1548", January 845 2017. 847 [CVE-SPOOF] 848 NIST National Vulnerability Database, "CVE-2015-8139, 849 https://nvd.nist.gov/vuln/detail/CVE-2015-8139", January 850 2017. 852 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 853 DOI 10.17487/RFC0791, September 1981, 854 . 856 Appendix A. NTP Remote Facility Message Format 858 The format of the NTP Remote Facility Message header, which 859 immediately follows the UDP header, is shown in Figure 3. Following 860 is a description of its fields. Bit positions marked as zero are 861 reserved and should always be transmitted as zero. 863 0 1 2 3 864 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 865 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 866 |R|M| VN |Mode |A| Sequence | Implementation| Req Code | 867 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 868 | Err | Count | MBZ | Size | 869 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 870 | | 871 / Data (up to 500 bytes) / 872 | | 873 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 874 | Encryption KeyID (when A bit set) | 875 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 876 | | 877 / Message Authentication Code (when A bit set) / 878 | | 879 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 881 Figure 3: NTP Remote Facility Message Header 883 Response Bit (R) : Set to 0 if the packet is a request. Set to 1 if 884 the packet is a reponse. 886 More Bit (M) : Set to 0 if this is the last packet in a response, 887 otherwise set to 1 in responses requiring more then one packet. 889 Version Number (VN) : Set to the version number of the NTP daemon. 891 Mode : Set to 7 for Remote Facility messages. 893 Authenticated Bit (A) : If set to 1, this packet contains 894 authentication information. 896 Sequence : For a multi-packet response, this field contains the 897 sequence number of this packet. Packets in a multi-packet response 898 are numbered starting with 0. The More Bit is set to 1 for all 899 packets but the last. 901 Implementation : The version number of the implementation that 902 defined the request code used in this message. An implementation 903 number of 0 is used for a Request Code supported by all versions of 904 the NTP daemon. The value 255 is reserved for future extensions. 906 Request Code (Req Code) : An implementation-specific code which 907 specifies the operation being requested. A Request Code definition 908 includes the format and semantics of the data included in the packet. 910 Error (Err) : Set to 0 for a request. For a response, this field 911 contains an error code relating to the request. If the Error is non- 912 zero, the operation requested wasn't performed. 914 0 - no error 916 1 - incompatible implementation number 918 2 - unimplemented request code 920 3 - format error 922 4 - no data available 924 7 - authentication failure 926 Count : The number of data items in the packet. Range is 0 to 500. 928 Must Be Zero (MBZ) : A reserved field set to 0 in requests and 929 responses. 931 Size : The size of each data item in the packet. Range is 0 to 500. 933 Data : A variable-sized field containing request/response data. For 934 requests and responses, the size in octets must be greater than or 935 equal to the product of the number of data items (Count) and the size 936 of a data item (Size). For requests, the data area is exactly 40 937 octets in length. For responses, the data area will range from 0 to 938 500 octets, inclusive. 940 Encryption KeyID : A 32-bit unsigned integer used to designate the 941 key used for the Message Authentication Code. This field is included 942 only when the A bit is set to 1. 944 Message Authentication Code : An optional Message Authentication Code 945 defined by the version of the NTP daemon indicated in the 946 Implementation field. This field is included only when the A bit is 947 set to 1. 949 Author's Address 951 Brian Haberman (editor) 952 JHU 954 Email: brian@innovationslab.net