doc: Add RFC documents

1 files changed, 451 insertions, 0 deletions

diff --git a/doc/rfc/rfc7822.txt b/doc/rfc/rfc7822.txt
new file mode 100644
index 0000000..194ffa2
--- /dev/null
+++ b/doc/rfc/rfc7822.txt
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                        T. Mizrahi
+Request for Comments: 7822                                       Marvell
+Updates: 5905                                                   D. Mayer
+Category: Standards Track                        Network Time Foundation
+ISSN: 2070-1721                                               March 2016
+
+
+        Network Time Protocol Version 4 (NTPv4) Extension Fields
+
+Abstract
+
+   The Network Time Protocol version 4 (NTPv4) defines the optional
+   usage of extension fields.  An extension field, as defined in RFC
+   5905, is an optional field that resides at the end of the NTP header
+   and that can be used to add optional capabilities or additional
+   information that is not conveyed in the standard NTP header.  This
+   document updates RFC 5905 by clarifying some points regarding NTP
+   extension fields and their usage with Message Authentication Codes
+   (MACs).
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   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).  Further information on
+   Internet Standards is available in Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc7822.
+
+Copyright Notice
+
+   Copyright (c) 2016 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
+   (http://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 Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+
+
+Mizrahi & Mayer              Standards Track                    [Page 1]
+
+RFC 7822                  NTP Extension Fields                March 2016
+
+
+Table of Contents
+
+   1. Introduction ....................................................2
+   2. Conventions Used in This Document ...............................3
+      2.1. Terminology ................................................3
+      2.2. Terms and Abbreviations ....................................3
+   3. NTP Extension Fields - RFC 5905 Update ..........................3
+   4. Security Considerations .........................................6
+   5. References ......................................................7
+      5.1. Normative References .......................................7
+      5.2. Informative References .....................................7
+   Acknowledgments ....................................................8
+   Authors' Addresses .................................................8
+
+1.  Introduction
+
+   The NTP header format consists of a set of fixed fields that may be
+   followed by some optional fields.  Two types of optional fields are
+   defined: Message Authentication Codes (MACs), and extension fields as
+   defined in Section 7.5 of [NTPv4].
+
+   If a MAC is used, it resides at the end of the packet.  This field
+   can be either 24 octets long, 20 octets long, or a 4-octet
+   crypto-NAK.
+
+   NTP extension fields were defined in [NTPv4] as a generic mechanism
+   that allows the addition of future extensions and features without
+   modifying the NTP header format (Section 16 of [NTPv4]).
+
+   The only currently defined extension fields are those fields used by
+   the Autokey protocol [Autokey] and the Checksum Complement [RFC7821].
+   The Autokey extension field is always followed by a MAC, and
+   Section 10 of [Autokey] specifies the parsing rules that allow a host
+   to distinguish between an extension field and a MAC.  However, a MAC
+   is not mandatory after an extension field; an NTPv4 packet can
+   include one or more extension fields without including a MAC.  This
+   behavior is specified in Section 7.5 of [NTPv4] and in [Err3627], and
+   is further clarified in this document.
+
+   This document updates [NTPv4] (RFC 5905) by clarifying some points
+   regarding the usage of extension fields.  These updates include
+   changes to address errors found after the publication of [NTPv4] with
+   respect to extension fields.  Specifically, this document updates
+   Section 7.5 of [NTPv4], clarifying the relationship between extension
+   fields and MACs, and defining the behavior of a host that receives an
+   unknown extension field.
+
+
+
+
+
+Mizrahi & Mayer              Standards Track                    [Page 2]
+
+RFC 7822                  NTP Extension Fields                March 2016
+
+
+2.  Conventions Used in This Document
+
+2.1.  Terminology
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+   document are to be interpreted as described in [KEYWORDS].
+
+2.2.  Terms and Abbreviations
+
+   MAC          Message Authentication Code
+
+   NTPv4        Network Time Protocol version 4 [NTPv4]
+
+3.  NTP Extension Fields - RFC 5905 Update
+
+   This document updates Section 7.5 of [NTPv4] as follows:
+
+   OLD:
+
+   7.5.  NTP Extension Field Format
+
+      In NTPv4, one or more extension fields can be inserted after the
+      header and before the MAC, which is always present when an
+      extension field is present.  Other than defining the field format,
+      this document makes no use of the field contents.  An extension
+      field contains a request or response message in the format shown
+      in Figure 14.
+
+       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
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      |          Field Type           |            Length             |
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      .                                                               .
+      .                            Value                              .
+      .                                                               .
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      |                       Padding (as needed)                     |
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+                      Figure 14: Extension Field Format
+
+      All extension fields are zero-padded to a word (four octets)
+      boundary.  The Field Type field is specific to the defined
+      function and is not elaborated here.  While the minimum field
+      length containing required fields is four words (16 octets), a
+      maximum field length remains to be established.
+
+
+
+Mizrahi & Mayer              Standards Track                    [Page 3]
+
+RFC 7822                  NTP Extension Fields                March 2016
+
+
+      The Length field is a 16-bit unsigned integer that indicates the
+      length of the entire extension field in octets, including the
+      Padding field.
+
+   NEW:
+
+   7.5.  NTP Extension Field Format
+
+      In NTPv4, one or more extension fields can be inserted after the
+      header and before the MAC, if a MAC is present.
+
+      Other than defining the field format, this document makes no use
+      of the field contents.  An extension field contains a request or
+      response message in the format shown in Figure 14.
+
+       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
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      |          Field Type           |            Length             |
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      .                                                               .
+      .                            Value                              .
+      .                                                               .
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      |                       Padding (as needed)                     |
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+                      Figure 14: Extension Field Format
+
+      All extension fields are zero-padded to a word (four octets)
+      boundary.
+
+      The Field Type, Value, and Padding fields are specific to the
+      defined function and are not elaborated here; the Field Type value
+      is defined in an IANA registry, and its Length, Value, and Padding
+      values are defined by the document referred to by the registry.
+      If a host receives an extension field with an unknown Field Type,
+      the host SHOULD ignore the extension field and MAY drop the packet
+      altogether if policy requires it.
+
+      While the minimum field length containing required fields is
+      four words (16 octets), the maximum field length cannot be longer
+      than 65532 octets, due to the maximum size of the Length field.
+
+      The Length field is a 16-bit unsigned integer that indicates the
+      length of the entire extension field in octets, including the
+      Padding field.
+
+
+
+
+Mizrahi & Mayer              Standards Track                    [Page 4]
+
+RFC 7822                  NTP Extension Fields                March 2016
+
+
+   7.5.1.  Extension Fields and MACs
+
+   7.5.1.1.  Extension Fields in the Presence of a MAC
+
+      An extension field can be used in an NTP packet that includes a
+      MAC -- for example, as defined in [Autokey].  A specification that
+      defines a new extension field MUST specify whether the extension
+      field requires a MAC or not.  If the extension field requires a
+      MAC, the extension field specification MUST define the algorithm
+      to be used to create the MAC and the length of the MAC thus
+      created.  An extension field MAY allow for the use of more than
+      one algorithm, in which case the information about which algorithm
+      was used MUST be included in the extension field itself.
+
+   7.5.1.2.  Multiple Extension Fields with a MAC
+
+      If there are multiple extension fields that require a MAC, they
+      MUST all require the use of the same algorithm and MAC length.
+      Extension fields that do not require a MAC can be included with
+      extension fields that do require a MAC.
+
+      An NTP packet MUST NOT be sent with two or more extension fields
+      that require a MAC with different algorithms.
+
+      If an NTP packet is received with two or more extension fields
+      that this receiver recognizes and those fields require a MAC with
+      different algorithms, the packet MUST be discarded.
+
+   7.5.1.3.  MAC in the Absence of an Extension Field
+
+      A MAC MUST NOT be longer than 24 octets if there is no extension
+      field present, unless a longer MAC is agreed upon by both client
+      and server.  The client and server can negotiate this behavior
+      using a previous exchange of packets with an extension field that
+      defines the size and algorithm of the MAC transmitted in NTP
+      packets.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mizrahi & Mayer              Standards Track                    [Page 5]
+
+RFC 7822                  NTP Extension Fields                March 2016
+
+
+   7.5.1.4.  Extension Fields in the Absence of a MAC
+
+      If a MAC is not present, one or more extension fields can be
+      inserted after the header, according to the following rules:
+
+      o  If the packet includes a single extension field, the length of
+         the extension field MUST be at least 7 words, i.e., at least
+         28 octets.
+
+      o  If the packet includes more than one extension field, the
+         length of the last extension field MUST be at least 28 octets.
+         The length of the other extension fields in this case MUST be
+         at least 16 octets each.
+
+4.  Security Considerations
+
+   The security considerations of time protocols in general are
+   discussed in [SecTime], and the security considerations of NTP are
+   discussed in [NTPv4].
+
+   Distributed Denial-of-Service (DDoS) attacks on NTP servers involve
+   flooding a server with a high rate of NTP packets.  Malicious usage
+   of extension fields cannot amplify such DDoS attacks; such malicious
+   attempts are mitigated by NTP servers, since the servers ignore
+   unknown extension fields (as discussed in Section 3) and only
+   respond, if needed, with known extension fields.  Extension fields
+   from incoming packets are neither propagated by NTP servers nor
+   included in any response.  NTP servers create their own extension
+   fields if needed for a response.  A large number of extension fields
+   should be flagged by an NTP server as a potential attack.  Large
+   extension field sizes should also be flagged, unless they are
+   expected to be large.
+
+   Middleboxes such as firewalls MUST NOT filter NTP packets based on
+   their extension fields.  Such middleboxes should not examine
+   extension fields in the packets, since NTP packets may contain new
+   extension fields that the middleboxes have not been updated to
+   recognize.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mizrahi & Mayer              Standards Track                    [Page 6]
+
+RFC 7822                  NTP Extension Fields                March 2016
+
+
+5.  References
+
+5.1.  Normative References
+
+   [KEYWORDS]  Bradner, S., "Key words for use in RFCs to Indicate
+               Requirement Levels", BCP 14, RFC 2119,
+               DOI 10.17487/RFC2119, March 1997,
+               <http://www.rfc-editor.org/info/rfc2119>.
+
+   [NTPv4]     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, <http://www.rfc-editor.org/info/rfc5905>.
+
+5.2.  Informative References
+
+   [Autokey]   Haberman, B., Ed., and D. Mills, "Network Time Protocol
+               Version 4: Autokey Specification", RFC 5906,
+               DOI 10.17487/RFC5906, June 2010,
+               <http://www.rfc-editor.org/info/rfc5906>.
+
+   [Err3627]   RFC Errata, Erratum ID 3627, RFC 5905.
+
+   [RFC7821]   Mizrahi, T., "UDP Checksum Complement in the Network Time
+               Protocol (NTP)", RFC 7821, DOI 10.17487/RFC7821,
+               March 2016, <http://www.rfc-editor.org/info/rfc7821>.
+
+   [SecTime]   Mizrahi, T., "Security Requirements of Time Protocols in
+               Packet Switched Networks", RFC 7384,
+               DOI 10.17487/RFC7384, October 2014,
+               <http://www.rfc-editor.org/info/rfc7384>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mizrahi & Mayer              Standards Track                    [Page 7]
+
+RFC 7822                  NTP Extension Fields                March 2016
+
+
+Acknowledgments
+
+   The authors gratefully acknowledge Dave Mills for his insightful
+   comments.  The authors also thank Tim Chown, Sean Turner, Miroslav
+   Lichvar, Suresh Krishnan, and Jari Arkko for their thorough review
+   and helpful comments.
+
+Authors' Addresses
+
+   Tal Mizrahi
+   Marvell
+   6 Hamada St.
+   Yokneam, 20692
+   Israel
+
+   Email: talmi@marvell.com
+
+
+   Danny Mayer
+   Network Time Foundation
+   PO Box 918
+   Talent, OR  97540
+   United States
+
+   Email: mayer@ntp.org
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mizrahi & Mayer              Standards Track                    [Page 8]
+