asciidoctor-rfc 0.1.0 → 0.2.0

data/spec/examples/rfc3514.md.adoc

@@ -0,0 +1,324 @@
+= The Security Flag in the IPv4 Header
+Steven M. Bellovin <bellovin@acm.org>
+:doctype: internet-draft
+:abbrev: The Security Flag in the IPv4 Header
+:status: info
+:name: rfc-3514
+:ipr: trust200902
+:area: Internet
+:workgroup: Network Working Group
+:revdate: 2003-04-01T00:00:00Z
+:forename_initials: S.
+:organization: AT&T Labs Research
+:phone: +1 973-360-8656
+:street: 180 Park Avenue
+:city: Florham Park
+:code: NJ 07932
+:smart-quotes: false
+
+[abstract]
+Firewalls, packet filters, intrusion detection systems, and the like
+often have difficulty distinguishing between packets that have
+malicious intent and those that are merely unusual.  We define a
+security flag in the IPv4 header as a means of distinguishing the two
+cases.
+
+[[introduction]]
+== Introduction
+
+Firewalls <<CBR03>>, packet filters, intrusion detection systems, and
+the like often have difficulty distinguishing between packets that
+have malicious intent and those that are merely unusual.  The problem
+is that making such determinations is hard.  To solve this problem,
+we define a security flag, known as the "evil" bit, in the IPv4
+<<RFC0791>> header.  Benign packets have this bit set to 0; those that
+are used for an attack will have the bit set to 1.
+
+[[terminology]]
+=== Terminology
+
+The keywords **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**,
+**SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL**, when they appear in this
+document, are to be interpreted as described in <<RFC2119>>.
+
+[[syntax]]
+== Syntax
+
+The high-order bit of the IP fragment offset field is the only unused
+bit in the IP header.  Accordingly, the selection of the bit position
+is not left to IANA.
+
+The bit field is laid out as follows:
+
+....
+     0
+    +-+
+    |E|
+    +-+
+....
+
+Currently-assigned values are defined as follows:
+
+0x0:: 
++
+If the bit is set to 0, the packet has no evil intent.  Hosts,
+    network elements, etc., **SHOULD** assume that the packet is
+    harmless, and **SHOULD NOT** take any defensive measures.  (We note
+    that this part of the spec is already implemented by many common
+    desktop operating systems.)
+
+0x1:: 
++
+If the bit is set to 1, the packet has evil intent.  Secure
+    systems **SHOULD** try to defend themselves against such packets.
+    Insecure systems **MAY** chose to crash, be penetrated, etc.
+
+[[setting-the-evil-bit]]
+== Setting the Evil Bit
+
+There are a number of ways in which the evil bit may be set.  Attack
+applications may use a suitable API to request that it be set.
+Systems that do not have other mechanisms **MUST** provide such an API;
+attack programs **MUST** use it.
+
+Multi-level insecure operating systems may have special levels for
+attack programs; the evil bit **MUST** be set by default on packets
+emanating from programs running at such levels.  However, the system
+*MAY* provide an API to allow it to be cleared for non-malicious
+activity by users who normally engage in attack behavior.
+
+Fragments that by themselves are dangerous **MUST** have the evil bit
+set.  If a packet with the evil bit set is fragmented by an
+intermediate router and the fragments themselves are not dangerous,
+the evil bit **MUST** be cleared in the fragments, and **MUST** be turned
+back on in the reassembled packet.
+
+Intermediate systems are sometimes used to launder attack
+connections.  Packets to such systems that are intended to be relayed
+to a target SHOULD have the evil bit set.
+
+Some applications hand-craft their own packets.  If these packets are
+part of an attack, the application **MUST** set the evil bit by itself.
+
+In networks protected by firewalls, it is axiomatic that all
+attackers are on the outside of the firewall.  Therefore, hosts
+inside the firewall **MUST NOT** set the evil bit on any packets.
+
+Because NAT <<RFC3022>> boxes modify packets, they **SHOULD** set the evil
+bit on such packets.  "Transparent" http and email proxies **SHOULD** set
+the evil bit on their reply packets to the innocent client host.
+
+Some hosts scan other hosts in a fashion that can alert intrusion
+detection systems.  If the scanning is part of a benign research
+project, the evil bit **MUST NOT** be set.  If the scanning per se is
+innocent, but the ultimate intent is evil and the destination site
+has such an intrusion detection system, the evil bit **SHOULD** be set.
+
+[[processing-of-the-evil-bit]]
+== Processing of the Evil Bit
+
+Devices such as firewalls **MUST** drop all inbound packets that have the
+evil bit set.  Packets with the evil bit off **MUST NOT** be dropped.
+Dropped packets **SHOULD** be noted in the appropriate MIB variable.
+
+Intrusion detection systems (IDSs) have a harder problem.  Because of
+their known propensity for false negatives and false positives, IDSs
+**MUST** apply a probabilistic correction factor when evaluating the evil
+bit.  If the evil bit is set, a suitable random number generator
+<<RFC1750>> must be consulted to determine if the attempt should be
+logged.  Similarly, if the bit is off, another random number
+generator must be consulted to determine if it should be logged
+despite the setting.
+
+The default probabilities for these tests depends on the type of IDS.
+Thus, a signature-based IDS would have a low false positive value but
+a high false negative value.  A suitable administrative interface
+**MUST** be provided to permit operators to reset these values.
+
+Routers that are not intended as as security devices **SHOULD NOT**
+examine this bit. This will allow them to pass packets at higher
+speeds.
+
+As outlined earlier, host processing of evil packets is operating-
+system dependent; however, all hosts **MUST** react appropriately
+according to their nature.
+
+[[related-work]]
+== Related Work
+
+Although this document only defines the IPv4 evil bit, there are
+complementary mechanisms for other forms of evil.  We sketch some of
+those here.
+
+For IPv6 <<RFC2460>>, evilness is conveyed by two options.  The first,
+a hop-by-hop option, is used for packets that damage the network,
+such as DDoS packets.  The second, an end-to-end option, is for
+packets intended to damage destination hosts.  In either case, the
+option contains a 128-bit strength indicator, which says how evil the
+packet is, and a 128-bit type code that describes the particular type
+of attack intended.
+
+Some link layers, notably those based on optical switching, may
+bypass routers (and hence firewalls) entirely.  Accordingly, some
+link-layer scheme **MUST** be used to denote evil.  This may involve evil
+lambdas, evil polarizations, etc.
+
+DDoS attack packets are denoted by a special diffserv code point.
+
+An application/evil MIME type is defined for Web- or email-carried
+mischief.  Other MIME types can be embedded inside of evil sections;
+this permit easy encoding of word processing documents with macro
+viruses, etc.
+
+[[iana-considerations]]
+== IANA Considerations
+
+This document defines the behavior of security elements for the 0x0
+and 0x1 values of this bit.  Behavior for other values of the bit may
+be defined only by IETF consensus <<RFC2434>>.
+
+[[security-considerations]]
+== Security Considerations
+
+Correct functioning of security mechanisms depend critically on the
+evil bit being set properly.  If faulty components do not set the
+evil bit to 1 when appropriate, firewalls will not be able to do
+their jobs properly.  Similarly, if the bit is set to 1 when it
+shouldn't be, a denial of service condition may occur.
+
+
+[bibliography]
+== Normative References
+++++
+
+<reference anchor="RFC0791" target="https://www.rfc-editor.org/info/rfc791">
+<front>
+<title>Internet Protocol</title>
+<author initials="J." surname="Postel" fullname="J. Postel">
+<organization/>
+</author>
+<date year="1981" month="September"/>
+</front>
+<seriesInfo name="STD" value="5"/>
+<seriesInfo name="RFC" value="791"/>
+<seriesInfo name="DOI" value="10.17487/RFC0791"/>
+</reference>
+
+<reference anchor="RFC1750" target="https://www.rfc-editor.org/info/rfc1750">
+<front>
+<title>Randomness Recommendations for Security</title>
+<author initials="D." surname="Eastlake 3rd" fullname="D. Eastlake 3rd">
+<organization/>
+</author>
+<author initials="S." surname="Crocker" fullname="S. Crocker">
+<organization/>
+</author>
+<author initials="J." surname="Schiller" fullname="J. Schiller">
+<organization/>
+</author>
+<date year="1994" month="December"/>
+<abstract>
+<t>
+Choosing random quantities to foil a resourceful and motivated adversary is surprisingly difficult. This paper points out many pitfalls in using traditional pseudo-random number generation techniques for choosing such quantities. It recommends the use of truly random hardware techniques and shows that the existing hardware on many systems can be used for this purpose. This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind.
+</t>
+</abstract>
+</front>
+<seriesInfo name="RFC" value="1750"/>
+<seriesInfo name="DOI" value="10.17487/RFC1750"/>
+</reference>
+
+<reference anchor="RFC2119" target="https://www.rfc-editor.org/info/rfc2119">
+<front>
+<title>
+Key words for use in RFCs to Indicate Requirement Levels
+</title>
+<author initials="S." surname="Bradner" fullname="S. Bradner">
+<organization/>
+</author>
+<date year="1997" month="March"/>
+<abstract>
+<t>
+In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
+</t>
+</abstract>
+</front>
+<seriesInfo name="BCP" value="14"/>
+<seriesInfo name="RFC" value="2119"/>
+<seriesInfo name="DOI" value="10.17487/RFC2119"/>
+</reference>
+
+<reference anchor="RFC2434" target="https://www.rfc-editor.org/info/rfc2434">
+<front>
+<title>
+Guidelines for Writing an IANA Considerations Section in RFCs
+</title>
+<author initials="T." surname="Narten" fullname="T. Narten">
+<organization/>
+</author>
+<author initials="H." surname="Alvestrand" fullname="H. Alvestrand">
+<organization/>
+</author>
+<date year="1998" month="October"/>
+<abstract>
+<t>
+This document discusses issues that should be considered in formulating a policy for assigning values to a name space and provides guidelines to document authors on the specific text that must be included in documents that place demands on the IANA. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
+</t>
+</abstract>
+</front>
+<seriesInfo name="RFC" value="2434"/>
+<seriesInfo name="DOI" value="10.17487/RFC2434"/>
+</reference>
+
+<reference anchor="RFC2460" target="https://www.rfc-editor.org/info/rfc2460">
+<front>
+<title>Internet Protocol, Version 6 (IPv6) Specification</title>
+<author initials="S." surname="Deering" fullname="S. Deering">
+<organization/>
+</author>
+<author initials="R." surname="Hinden" fullname="R. Hinden">
+<organization/>
+</author>
+<date year="1998" month="December"/>
+<abstract>
+<t>
+This document specifies version 6 of the Internet Protocol (IPv6), also sometimes referred to as IP Next Generation or IPng. [STANDARDS-TRACK]
+</t>
+</abstract>
+</front>
+<seriesInfo name="RFC" value="2460"/>
+<seriesInfo name="DOI" value="10.17487/RFC2460"/>
+</reference>
+
+<reference anchor="RFC3022" target="https://www.rfc-editor.org/info/rfc3022">
+<front>
+<title>
+Traditional IP Network Address Translator (Traditional NAT)
+</title>
+<author initials="P." surname="Srisuresh" fullname="P. Srisuresh">
+<organization/>
+</author>
+<author initials="K." surname="Egevang" fullname="K. Egevang">
+<organization/>
+</author>
+<date year="2001" month="January"/>
+<abstract>
+<t>
+The NAT operation described in this document extends address translation introduced in RFC 1631 and includes a new type of network address and TCP/UDP port translation. In addition, this document corrects the Checksum adjustment algorithm published in RFC 1631 and attempts to discuss NAT operation and limitations in detail. This memo provides information for the Internet community.
+</t>
+</abstract>
+</front>
+<seriesInfo name="RFC" value="3022"/>
+<seriesInfo name="DOI" value="10.17487/RFC3022"/>
+</reference>
+
+<reference anchor='CBR03' target=''>
+ <front>
+ <title>Firewalls and Internet Security: Repelling the Wily Hacker, Second Edition</title>
+  <author initials='W.R.' surname='Cheswick' fullname='W.R. Cheswick'></author>
+  <author initials='S.M.' surname='Bellovin' fullname='S.M. Bellovin'></author>
+  <author initials='A.D.' surname='Rubin' fullname='A.D. Rubin'></author>
+  <date year='2003' />
+ </front>
+ <seriesInfo name="Addison-Wesley" value='' />
+ </reference>
+++++

data/spec/examples/rfc5841.md

@@ -0,0 +1,342 @@
+% Title = "TCP Option to Denote Packet Mood"
+% abbrev = "TCP Option to Denote Packet Mood"
+% category = "info"
+% docName = "rfc-5841"
+% ipr= "trust200902"
+% area = "Internet"
+% workgroup = "Network Working Group"
+% keyword = [""]
+%
+% date = 2010-04-01T00:00:00Z
+%
+% [pi]
+% toc = "no"
+%
+% #Independent Submission
+% [[author]]
+% initials="R."
+% surname="Hay"
+% fullname="Richard Hay"
+% organization = "Google"
+%   [author.address]
+%   email = "rhay@google.com"
+%   [author.address.postal]
+%   street = "1600 Amphitheatre Pkwy"
+%   city = "Mountain View"
+%   code = "CA 94043"
+%
+% [[author]]
+% initials="W."
+% surname="Turkal"
+% fullname="Warren Turkal"
+% organization = "Google"
+%   [author.address]
+%   email = "turkal@google.com"
+%   [author.address.postal]
+%   street = "1600 Amphitheatre Pkwy"
+%   city = "Mountain View"
+%   code = "CA 94043"
+
+.# Abstract
+
+This document proposes a new TCP option to denote packet mood.
+
+{mainmatter}
+
+# Introduction
+
+In an attempt to anthropomorphize the bit streams on countless
+physical layer networks throughout the world, we propose a TCP option
+to express packet mood [@?DSM-IV].
+
+Packets cannot feel.  They are created for the purpose of moving data
+from one system to another.  However, it is clear that in specific
+situations some measure of emotion can be inferred or added.  For
+instance, a packet that is retransmitted to resend data for a packet
+for which no ACK was received could be described as an 'angry'
+packet, or a 'frustrated' packet (if it is not the first
+retransmission for instance).  So how can these kinds of feelings be
+conveyed in the packets themselves.  This can be addressed by adding
+TCP Options [@?RFC0793] to the TCP header, using ASCII characters that
+encode commonly used "emoticons" to convey packet mood.
+
+## Terminology
+
+The keywords **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**,
+**SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL**, when they appear in this
+document, are to be interpreted as described in [@?RFC2119].
+
+# Syntax
+
+A TCP Option has a 1-byte kind field, followed by a 1-byte length
+field @RFC0793.  It is proposed that option 25 (released 2000-12-18)
+be used to define packet mood.  This option would have a length value
+of 4 or 5 bytes.  All the simple emotions described as expressible
+via this mechanism can be displayed with two or three 7-bit, ASCII-
+encoded characters.  Multiple mood options may appear in a TCP
+header, so as to express more complex moods than those defined here
+(for instance if a packet were happy and surprised).
+
+{align="center"}
+         Kind     Length     Meaning
+         ----     --------   -------
+          25      Variable   Packet Mood
+Figure: TCP Header Format
+
+In more detail:
+
+{align="left"}
+           +--------+--------+--------+--------+
+           |00011001|00000100|00111010|00101001|
+           +--------+--------+--------+--------+
+            Kind=25  Length=4 ASCII :  ASCII )
+
+           +--------+--------+--------+--------+--------+
+           |00011001|00000101|00111110|00111010|01000000|
+           +--------+--------+--------+--------+--------+
+            Kind=25  Length=5 ASCII >  ACSII :  ASCII @
+
+# Simple Emotional Representation
+
+It is proposed that common emoticons be used to denote packet mood.
+Packets do not "feel" per se.  The emotions they could be tagged with
+are a reflection of the user mood expressed through packets.
+
+So the humanity expressed in a packet would be entirely sourced from
+humans.
+
+To this end, it is proposed that simple emotions be used convey mood
+as follows.
+
+{align="left"}
+      ASCII                Mood
+      =====                ====
+      :)                   Happy
+      :(                   Sad
+      :D                   Amused
+      %(                   Confused
+      :o                   Bored
+      :O                   Surprised
+      :P                   Silly
+      :@                   Frustrated
+      >:@                  Angry
+      :|                   Apathetic
+      ;)                   Sneaky
+      >:)                  Evil
+
+Proposed ASCII character encoding
+
+{align="left"}
+      Binary          Dec  Hex     Character
+      ========        ===  ===     =========
+      010 0101        37   25      %
+      010 1000        40   28      (
+      010 1001        41   29      )
+      011 1010        58   3A      :
+      011 1011        59   3B      ;
+      011 1110        62   3E      >
+      100 0000        64   40      @
+      100 0100        68   44      D
+      100 1111        79   4F      O
+      101 0000        80   50      P
+      110 1111        111  6F      o
+      111 1100        124  7C      |
+
+For the purposes of this RFC, 7-bit ASCII encoding is sufficient for
+representing emoticons.  The ASCII characters will be sent in 8-bit
+bytes with the leading bit always set to 0.
+
+# Use Cases
+
+There are two ways to denote packet mood.  One is to infer the mood
+based on an event in the TCP session.  The other is to derive mood
+from a higher-order action at a higher layer (subject matter of
+payload for instance).
+
+For packets where the 'mood' is inferred from activity within the TCP
+session, the 'mood' **MUST** be set by the host that is watching for the
+trigger event.  If a client sends a frame and receives no ACK, then
+the retransmitted frame **MAY** contain the TCP OPTION header with a mood
+set.
+
+Any packet that exhibits behavior that allows for mood to be inferred
+**SHOULD** add the TCP OPTION to the packets with the implied mood.
+
+Applications can take advantage of the defined moods by expressing
+them in the packets.  This can be done in the SYN packet sent from
+the client.  All packets in the session can be then tagged with the
+mood set in the SYN packet, but this would have a per-packet
+performance cost (see (#performance-considerations) "Performance Considerations").
+
+Each application **MUST** define the preconditions for marking packets as
+happy, sad, bored, confused, angry, apathetic, and so on.  This is a
+framework for defining how such moods can be expressed, but it is up
+to the developers to determine when to apply these encoded labels.
+
+## Happy Packets
+
+Healthy packets are happy packets you could say.  If the ACK packets
+return within <10 ms end-to-end from a sender's stack to a receiver's
+stack and back again, this would reflect high-speed bidirectional
+capability, and if no retransmits are required and all ACKs are
+received, all subsequent packets in that session **SHOULD** be marked as
+'happy'.
+
+No loss, low-latency packets also makes for happy users.  So the
+packet would be reflecting the end-user experience.
+
+## Sad Packets
+
+If retransmission rates achieve greater than 20% of all packets sent
+in a session, it is fair to say the session can be in mourning for
+all of the good packets lost in the senseless wasteland of the wild
+Internet.
+
+This should not be confused with retransmitted packets marked as
+'angry' since this tag would apply to all frames in the session
+numbed by the staggering loss of packet life.
+
+## Amused Packets
+
+Any packet that is carrying a text joke **SHOULD** be marked as 'amused'.
+
+Example:
+
+{align="left"}
+      1: Knock Knock
+      2: Who's there?
+      1: Impatient chicken
+      2: Impatient chi...
+      1: BAWK!!!!
+
+If such a joke is in the packet payload then, honestly, how can you
+not be amused by one of the only knock-knock jokes that survives the
+3rd grade?
+
+## Confused Packets
+
+When is a packet confused?  There are network elements that perform
+per-packet load balancing, and if there are asymmetries in the
+latencies between end-to-end paths, out-of-order packet delivery can
+occur.
+
+When a receiver host gets out-of-order packets, it **SHOULD** mark TCP
+ACK packets sent back to the sender as confused.
+
+The same can be said for packets that are sent to incorrect VLAN
+segments or are misdirected.  The receivers might be aware that the
+packet is confused, but there is no way to know at ingress if that
+will be the fate of the frame.
+
+That being said, application developers **SHOULD** mark packets as
+confused if the payload contains complex philosophical questions that
+make one ponder the meaning of life and one's place in the universe.
+
+## Bored Packets
+
+Packets carrying accounting data with debits, credits, and so on **MUST**
+be marked as 'bored'.
+
+It could be said that many people consider RFCs boring.  Packets
+containing RFC text **MAY** be marked as 'bored'.
+
+Packets with phone book listings **MUST** be marked 'bored'.
+
+Packets containing legal disclaimers and anything in Latin **SHOULD** be
+marked 'bored'.
+
+## Surprised Packets
+
+Who doesn't love when the out-of-order packets in your session
+surprise you while waiting in a congested queue for 20 ms?
+
+Packets do not have birthdays, so packets can be marked as surprised
+when they encounter unexpected error conditions.
+
+So when ICMP destination unreachable messages are received (perhaps
+due to a routing loop or congestion discards), all subsequent packets
+in that session **SHOULD** be marked as surprised.
+
+## Silly Packets
+
+Not all packets are sent as part of a session.  Random keepalives
+during a TCP session **MAY** be set up as a repartee between systems
+connected as client and server.  Such random and even playful
+interchanges **SHOULD** be marked as silly.
+
+## Frustrated Packets
+
+Packets that are retransmitted more than once **SHOULD** be marked as
+frustrated.
+
+## Angry Packets
+
+Packets that are retransmitted **SHOULD** be marked as angry.
+
+## Apathetic Packets
+
+When sending a RST packet to a connected system, the packet should be
+marked as apathetic so that the receiver knows that your system does
+not care what happens after that.
+
+##  Sneaky Packets
+
+When a packet is used in a particularly clever way, it **SHOULD** be
+marked as sneaky.  What is "clever" is rather subjective, so it would
+be prudent to get a few opinions about a particular use to make sure
+that it is clever.
+
+## Evil Packets
+
+It is hard for a TCP packet to discern higher moral quandaries like
+the meaning of life or what exactly defines 'evil' and from whose
+perspective such a characterization is being made.  However,
+developers of TCP-based applications **MAY** choose to see some
+activities as evil when viewed through their particular lens of the
+world.  At that point, they **SHOULD** mark packets as evil.
+
+Some organizations are prohibited from using this mood by mission
+statement.  This would also prohibit using the security flag in the
+IP header described in [@?RFC3514] for the same reasons.
+
+# Performance Considerations
+
+Adding extensions to the TCP header has a cost.  Using TCP extensions
+with the ASCII-encoded mood of the packet would detract from the
+available MSS usable for data payload.  If the TCP header is more
+than 20 bytes, then the extra bytes would be unavailable for use in
+the payload of the frame.
+
+This added per-packet overhead should be considered when using packet
+mood extensions.
+
+# Security Considerations
+
+The TCP checksum, as a 16-bit value, could be mistaken if ASCII
+characters with the same number of zeros and ones were substituted
+out.  A happy `:)` could be replaced with a frown by a malicious
+attacker, by using a winking eye `;(`.  This could misrepresent the
+intended mood of the sender to the receiver.
+
+# Related Work
+
+This document does not seek to build a sentient network stack.
+However, this framework could be used to express the emotions of a
+sentient stack.  If that were to happen, a new technical job class of
+network psychologists could be created.  Who doesn't like new jobs? :)
+
+# IANA Considerations
+
+If this work is standardized, IANA is requested to officially assign
+value 25 as described in (#simple-emotional-representation).  Additional moods and emoticon
+representations would require IESG approval or standards action [@?RFC5226].
+
+<reference anchor='DSM-IV' target='http://www.psychiatryonline.com/resourceTOC.aspx?resourceID=1'>
+  <front>
+   <title>Diagnostic and Statistical Manual of Mental Disorders (DSM)</title>
+   <author></author>
+   <date></date>
+  </front>
+</reference>
+
+{backmatter}