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