Skip to content

CONTRIBUTING.md from a generic IETF repo #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
antonyantony wants to merge 4 commits into from
Closed

CONTRIBUTING.md from a generic IETF repo #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e99fae0
Some changes we agreed on last week.
klassert Mar 31, 2025
63eeb89
eesp.org : make sequence number mandatory
antonyantony Mar 31, 2025
2384718
Work in feedback from Piere and do adjustments we agreed
klassert Apr 1, 2025
8057117
CONTRIBUTING.md from a generic IETF repo
antonyantony Apr 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Contributing

This repository relates to activities in the Internet Engineering Task Force
([IETF](https://www.ietf.org/)). All material in this repository is considered
Contributions to the IETF Standards Process, as defined in the intellectual
property policies of IETF currently designated as
[BCP 78](https://www.rfc-editor.org/info/bcp78),
[BCP 79](https://www.rfc-editor.org/info/bcp79) and the
[IETF Trust Legal Provisions (TLP) Relating to IETF Documents](http://trustee.ietf.org/trust-legal-provisions.html).

Any edit, commit, pull request, issue, comment or other change made to this
repository constitutes Contributions to the IETF Standards Process
(https://www.ietf.org/).

You agree to comply with all applicable IETF policies and procedures, including,
BCP 78, 79, the TLP, and the TLP rules regarding code components (e.g. being
subject to a Simplified BSD License) in Contributions.


## Working Group Information

Discussion of this work occurs on the [IP Security Maintenance and Extensions](https://datatracker.ietf.org/wg/ipsecme/)
Working Group mailing list](mailto:ipsec@ietf.org)
([archive](https://mailarchive.ietf.org/arch/browse/ipsecme/),
[subscribe](https://www.ietf.org/mailman/listinfo/ipsec)).
In addition to contributions in GitHub, you are encouraged to participate in
discussions there.

**Note**: Some working groups adopt a policy whereby substantive discussion of
technical issues needs to occur on the mailing list.

You might also like to familiarize yourself with other
[Working Group documents](https://datatracker.ietf.org/wg/ipsecme/documents/).
142 changes: 24 additions & 118 deletions eesp.org
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,9 @@ previously mandatory fields to optional,
and moves the ESP trailer into the EESP header. Additionally, EESP
adds header options adapted from IPv6 to allow for future extension.
New header options are defined which add Flow IDs (e.g., for CPU
pinning and QoS support), and a crypt-offset to allow for exposing
inner flow information for middlebox use.
pinning and QoS support based on the inner traffic flow), and a
crypt-offset to allow for exposing inner flow information for
middlebox use.

#+end_abstract
#+RFC_KEYWORDS: ("EESP" "IKEv2")
Expand Down Expand Up @@ -179,10 +180,9 @@ Unlike ESP, EESP does not have a trailer. Instead, these values have
moved to a ~Payload Info Header~ directly following the ~Peer Header~.
With classic transport and tunnel mode, the ~Payload Info Header~
is encrypted, and therefore private to the IPsec peers. However,
with ~Payload Encryption Mode~ as specified in
[[Payload Encryption Mode Processing]] or with a positive crypt offset
with a positive crypt offset
(see [[EESP Crypt Offset Option]]), the ~Payload Info Header~
might be left unencrypted. In these modes, protocol parsing engines
might be left unencrypted. In this case, protocol parsing engines
of middleboxes can act upon it (e.g., for telemetry).

# :NOTE: doesn't the Payload Data structure depend on the mode of
Expand Down Expand Up @@ -251,21 +251,15 @@ The Flags field in the fixed Base Header is defined as follows:
#+begin_src
0 1 2 3 4 5
+-+-+-+-+-+-+
|F|P|S| R |
|F| R |
+-+-+-+-+-+-+
#+end_src

- Packet Format (F) :: 1 bit: Set to zero for full EESP packet Format (i.e., the EESP header includes the
~Payload Info Header~), set to 1 for Optimized EESP Packet format.
- Payload Encryption Mode (P) :: 1 bit: If set, the
following Layer 4 Header is authenticated, but not encrypted.
This bit MUST be set to 0 on any mode other than payload encryption mode .
The receiver MUST drop packets with this bit set, if the mode is
different to payload encryption mode. See [[Payload Encryption Mode Processing]]
- Sequence Number absent (S) :: 1 bit: If set, the peer header does not
carry the sequence number field in the packet. This bit MUST be set
to the same value for all packets on a given SA.
- Reserved (R) :: 3 bits: Reserved for future versions, MUST be set to 0,
~Payload Info Header~), set to 1 for Optimized EESP Packet format. This bit
MAY be only set to 1 if the Crypt Offset is positive. It MUST be set to
0 otherwise.
- Reserved (R) :: 5 bits: Reserved for future versions, MUST be set to 0,
and ignored by the receiver.


Expand Down Expand Up @@ -303,16 +297,12 @@ algorithms as done in [[PSP]].

When options are present, padding options (i.e., ~Pad1~ and ~PadN~)
MUST be used to align the fields following the ~Options~ field. This
alignment is dictated by the packet format. For the Full EESP
packet format the ~Payload Info Header~ must be 4 byte aligned. For
the optimized packet format the alignment is given by the contained
packet type, namely, 4 byte alignment for an IPv4 packet, and 8 byte
alignment for IPv6 packet.
alignment is dictated by the packet format, see [[Payload Data]].

** Peer Header

The ~Peer Header~ follows the ~Base Header~ and ~Options~ field.
The ~Peer Header~ containing an optional ~Sequence Number~ and an
The ~Peer Header~ containing a ~Sequence Number~ and an
optional ~Initialization Vector~, and the format is shown below.
The Peer Header is private to the IPsec peers, middleboxes MUST
NOT act upon the Peer Header fields.
Expand All @@ -324,15 +314,15 @@ NOT act upon the Peer Header fields.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sequence Number (optional) |
| Sequence Number |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IV (optional) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
#+end_src

When present, the ~Sequence Number~ is a full 64bit sequence number.
The ~Sequence Number~ is a full 64bit sequence number.
EESP only support 64bit sequence numbers, a.k.a ESN and transmits the
entire sequence number on each packet. The actual size of the
~Initialization Vector~ depends on the choice of the cipher suite.
Expand Down Expand Up @@ -565,7 +555,7 @@ packet format for use with IPv4 or IPv6 Tunnel Mode when the
~ Options (variable, optional) ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sequence Number (optional) |
| Sequence Number |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IV* (optional) |
Expand Down Expand Up @@ -599,7 +589,7 @@ packet format for use with IPv4 or IPv6 Tunnel Mode when the
~ Options (variable, optional) ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sequence Number (optional) |
| Sequence Number |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IV* (optional) |
Expand Down Expand Up @@ -646,7 +636,7 @@ processing details are described in later sections.
|---------------------+------------+-----------+----------------+--------------+------------|
| Base Header | 8 | M | | Y | plain |
| Options | variable | O | | Y | plain |
| Sequence Number | 8 | O | | Y | plain |
| Sequence Number | 8 | M | | Y | plain |
| IV | variable | O | | Y | plain |
| Payload Info Hdr[4] | 4 | O | Y | Y | cipher [3] |
| Payload [2] | variable | M | Y | Y | cipher [3] |
Expand Down Expand Up @@ -676,13 +666,14 @@ are always present in the EESP packet format for all SAs.
This section specifies the use of the Session ID as a Sub SA ID.
The use of the Session ID as a Sub SA ID MUST be negotiated by IKEv2,
or any other suitable protocol. In this case, Session ID is used as a
16 bits Replay Subspace ID.
Replay Subspaces were initially defined in [[I-D.ponchon-ipsecme-anti-replay-subspaces]].
16 bits Sub SA ID.
Sub SA IDs were initially defined in [[I-D.ponchon-ipsecme-anti-replay-subspaces]]
and called ~Replay Subspaces~ there.

# :NOTE: Why are Replay Subspaces and IDs mentioned here? Why define
# that identifier in addition to Sub SA ID?

Each number of the 16 bits Replay Subspace ID encodes a single
Each number of the 16 bits Sub SA ID encodes a single
64 bit anti-replay sequence number space.
This means that each core, path, or QoS class, or any combination of
those, can then use their own unique anti-replay sequence number subspace.
Expand Down Expand Up @@ -902,10 +893,7 @@ basis inside any inner flow to avoid packet reordering.
The Flow Identifier SHOULD be negotiated by IKEv2 or another
suitable protocol. The detailed specification of FIDs MAY be provided
in subsequent documents. The precise meaning of a FID is opaque to
intermediate devices; however, intermediate devices MAY use it for
identifying flows for ECMP or similar purposes. e.g. Sub-Child SAs,
in [[I-D.mrossberg-ipsecme-multiple-sequence-counters]] could be encoded
here.
intermediate devices.

#+caption: Flow Identifier Option
#+name: fid-option
Expand All @@ -926,36 +914,6 @@ here.
- FID :: Variable length, carries characteristic information of a
inner flow and MUST NOT change for a given inner flow within a SA.

# XXX I don't think this is right, I think we want to allow multiple
# FIDs (e.g., multiple tcp connections) per SA.

*** EESP Flow Identifiers combined with replay protection

Flow Identifiers characterize the inner i.e. the protected flows.
Packets of these flows should not be reordered while EESP protected.

# NOTE STK: Is the above text clear?

#+caption: Flow Identifier with replay protection
#+name: fid-replay
#+begin_src
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Option Type | Option Length | Replay Subspace ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
| |
~ Flow Identifier (FID) ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
#+end_src

- Option Type :: 8 bits: See [[EESP Header Options]]
- Option Length :: 8 bits: See [[EESP Header Options]]
- Replay Subspace ID :: 16 bits:
- FID :: Variable length, carries characteristic information of a
inner flow and MUST NOT change for a given inner flow within a SA.

*** EESP Crypt Offset Option
This option is typically used for within one Datacenter use case
such as [[PSP]].
Expand Down Expand Up @@ -1007,8 +965,8 @@ be employed.

*** Layer 4 Encapsulation Modes

Layer 4 Encapsulation Modes are transport mode, BEET mode
and payload encryption mode. Layer 4 Encapsulation Modes
Layer 4 Encapsulation Modes are transport mode and BEET mode.
Layer 4 Encapsulation Modes
distinguish from tunnel mode on the position of the EESP
header in the packet. On Layer 4 Encapsulation Modes the
EESP header is inserted between the original IPv4/IPv6
Expand Down Expand Up @@ -1092,58 +1050,6 @@ packet.
* = if present, could be before EESP, after EESP, or both
#+end_src

**** Payload Encryption Mode Processing

In payload encryption mode, EESP is inserted exactly at the same position
as it is done for transport mode. The only difference to transport mode
is that the next layer protocol header following the original IP or IPv6
header is left in cleartext. Additionally to that, the 'C' bit in the EESP
header flags is set.


The following diagrams illustrate EESP payload encryption mode
positioning for a typical IPv4 and IPv6 packet, on a "before and after" basis.


#+caption: IPv4 Payload Encryption Mode
#+name: ipv4-pe-mode
#+begin_src
BEFORE APPLYING EESP
----------------------------
IPv4 |orig IP hdr | | |
|(any options)| TCP | Data |
----------------------------

AFTER APPLYING EESP
----------------------------------------------------
IPv4 |orig IP hdr | EESP | | | EESP |
|(any options)| Hdr | TCP | L4 pyld Data | ICV |
----------------------------------------------------
|<- encryption ->|
|<-------- integrity -------->|
#+end_src

#+caption: IPv6 Payload Encryption Mode
#+name: ipv6-pe-mode
#+begin_src

BEFORE APPLYING EESP
---------------------------------------
IPv6 | | ext hdrs | | |
| orig IP hdr |if present| TCP | Data |
---------------------------------------

AFTER APPLYING EESP
--------------------------------------------------------------
IPv6 | orig |hop-by-hop,dest*,|EESP|dest| | Layer 4 |EESP|
|IP hdr|routing,fragment.|Hdr |opt*|TCP| Payload Data |ICV |
--------------------------------------------------------------
|<- encryption ->|
|<-------- integrity --------->|

* = if present, could be before EESP, after EESP, or both
#+end_src

**** BEET Mode Processing

In BEET mode, EESP is inserted exactly at the same position
Expand Down