effectively hides the fact that there are a pair of 16-bit fields in
L2TPv2, and a single 32-bit field in L2TPv3.
If the peer implementation is L2TPv3-capable, a control message with
the Ver field set to 3 and an L2TPv3 header and message format will
be sent in response to the SCCRQ. Operation may then continue as
L2TPv3. If a message is received with the Ver field set to 2, it
must be assumed that the peer implementation is L2TPv2-only, thus
enabling fallback to L2TPv2 mode to safely occur.
Note Well: The L2TPv2/v3 auto-detection mode requires that all L2TPv3
implementations over UDP be liberal in accepting an SCCRQ control
message with the Ver field set to 2 or 3 and the presence of L2TPv2-
specific AVPs. An L2TPv3-only implementation MUST ignore all L2TPv2
AVPs (e.g., those defined in RFC 2661 and not in this document)
within an SCCRQ with the Ver field set to 2 (even if the M bit is set
on the L2TPv2-specific AVPs).
5. Control Message Attribute Value Pairs
To maximize extensibility while permitting interoperability, a
uniform method for encoding message types is used throughout L2TP.
This encoding will be termed AVP (Attribute Value Pair) for the
remainder of this document.
5.1. AVP Format
Each AVP is encoded as follows:
Figure 5.1: AVP Format
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|M|H| rsvd | Length | Vendor ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Attribute Type | Attribute Value ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(until Length is reached) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The first six bits comprise a bit mask that describes the general
attributes of the AVP. Two bits are defined in this document; the
remaining bits are reserved for future extensions. Reserved bits
MUST be set to 0 when sent and ignored upon receipt.
Mandatory (M) bit: Controls the behavior required of an
implementation that receives an unrecognized AVP. The M bit of a
given AVP MUST only be inspected and acted upon if the AVP is
unrecognized (see Section 5.2).
Hidden (H) bit: Identifies the hiding of data in the Attribute Value
field of an AVP. This capability can be used to avoid the passing of
sensitive data, such as user passwords, as cleartext in an AVP.
Section 5.3 describes the procedure for performing AVP hiding.
Length: Contains the number of octets (including the Overall Length
and bit mask fields) contained in this AVP. The Length may be
calculated as 6 + the length of the Attribute Value field in octets.
The field itself is 10 bits, permitting a maximum of 1023 octets of
data in a single AVP. The minimum Length of an AVP is 6. If the
Length is 6, then the Attribute Value field is absent.
Vendor ID: The IANA-assigned "SMI Network Management Private
Enterprise Codes" [RFC1700] value. The value 0, corresponding to
IETF-adopted attribute values, is used for all AVPs defined within
this document. Any vendor wishing to implement its own L2TP
extensions can use its own Vendor ID along with private Attribute
values, guaranteeing that they will not collide with any other
vendor’s extensions or future IETF extensions. Note that there are
16 bits allocated for the Vendor ID, thus limiting this feature to
the first 65,535 enterprises.
Attribute Type: A 2-octet value with a unique interpretation across
all AVPs defined under a given Vendor ID.
Attribute Value: This is the actual value as indicated by the Vendor
ID and Attribute Type. It follows immediately after the Attribute
Type field and runs for the remaining octets indicated in the Length
(i.e., Length minus 6 octets of header). This field is absent if the
Length is 6.
In the event that the 16-bit Vendor ID space is exhausted, vendor-
specific AVPs with a 32-bit Vendor ID MUST be encapsulated in the
following manner:
Figure 5.2: Extended Vendor ID AVP Format
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|M|H| rsvd | Length | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 58 | 32-bit Vendor ID ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Attribute Type |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Attribute Value ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(until Length is reached) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This AVP encodes a vendor-specific AVP with a 32-bit Vendor ID space
within the Attribute Value field. Multiple AVPs of this type may
exist in any message. The 16-bit Vendor ID MUST be 0, indicating
that this is an IETF-defined AVP, and the Attribute Type MUST be 58,
indicating that what follows is a vendor-specific AVP with a 32-bit
Vendor ID code. This AVP MAY be hidden (the H bit MAY be 0 or 1).
The M bit for this AVP MUST be set to 0. The Length of the AVP is 12
plus the length of the Attribute Value.
5.2. Mandatory AVPs and Setting the M Bit
If the M bit is set on an AVP that is unrecognized by its recipient,
the session or control connection associated with the control message
containing the AVP MUST be shut down. If the control message
containing the unrecognized AVP is associated with a session (e.g.,
an ICRQ, ICRP, ICCN, SLI, etc.), then the session MUST be issued a
CDN with a Result Code of 2 and Error Code of 8 (as defined in
Section 5.4.2) and shut down. If the control message containing the
unrecognized AVP is associated with establishment or maintenance of a
Control Connection (e.g., SCCRQ, SCCRP, SCCCN, Hello), then the
associated Control Connection MUST be issued a StopCCN with Result
Code of 2 and Error Code of 8 (as defined in Section 5.4.2) and shut
down. If the M bit is not set on an unrecognized AVP, the AVP MUST
be ignored when received, processing the control message as if the
AVP were not present.
Receipt of an unrecognized AVP that has the M bit set is catastrophic
to the session or control connection with which it is associated.
Thus, the M bit should only be set for AVPs that are deemed crucial
to proper operation of the session or control connection by the
sender. AVPs that are considered crucial by the sender may vary by
application and configured options. In no case shall a receiver of
an AVP "validate" if the M bit is set on a recognized AVP. If the
AVP is recognized (as all AVPs defined in this document MUST be for a
compliant L2TPv3 specification), then by definition, the M bit is of
no consequence.
The sender of an AVP is free to set its M bit to 1 or 0 based on
whether the configured application strictly requires the value
contained in the AVP to be recognized or not. For example,
"Automatic L2TPv2 Fallback" in Section 4.7.3 requires the setting of
the M bit on all new L2TPv3 AVPs to zero if fallback to L2TPv2 is
supported and desired, and 1 if not.
The M bit is useful as extra assurance for support of critical AVP
extensions. However, more explicit methods may be available to
determine support for a given feature rather than using the M bit
alone. For example, if a new AVP is defined in a message for which
there is always a message reply (i.e., an ICRQ, ICRP, SCCRQ, or SCCRP
message), rather than simply sending an AVP in the message with the M
bit set, availability of the extension may be identified by sending
an AVP in the request message and expecting a corresponding AVP in a
reply message. This more explicit method, when possible, is
preferred.
The M bit also plays a role in determining whether or not a malformed
or out-of-range value within an AVP should be ignored or should
result in termination of a session or control connection (see Section
7.1 for more details).
5.3. Hiding of AVP Attribute Values
The H bit in the header of each AVP provides a mechanism to indicate
to the receiving peer whether the contents of the AVP are hidden or
present in cleartext. This feature can be used to hide sensitive
control message data such as user passwords, IDs, or other vital
information.
The H bit MUST only be set if (1) a shared secret exists between the
LCCEs and (2) Control Message Authentication is enabled (see Section
4.3). If the H bit is set in any AVP(s) in a given control message,
at least one Random Vector AVP must also be present in the message
and MUST precede the first AVP having an H bit of 1.
The shared secret between LCCEs is used to derive a unique shared key
for hiding and unhiding calculations. The derived shared key is
obtained via an HMAC-MD5 keyed hash [RFC2104], with the key
consisting of the shared secret, and with the data being hashed
consisting of a single octet containing the value 1.
shared_key = HMAC_MD5 (shared_secret, 1)
Hiding an AVP value is done in several steps. The first step is to
take the length and value fields of the original (cleartext) AVP and
encode them into the Hidden AVP Subformat, which appears as follows:
Figure 5.3: Hidden AVP Subformat
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Length of Original Value | Original Attribute Value ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
... | Padding ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Length of Original Attribute Value: This is length of the Original
Attribute Value to be obscured in octets. This is necessary to
determine the original length of the Attribute Value that is lost
when the additional Padding is added.
Original Attribute Value: Attribute Value that is to be obscured.
Padding: Random additional octets used to obscure length of the
Attribute Value that is being hidden.
To mask the size of the data being hidden, the resulting subformat
MAY be padded as shown above. Padding does NOT alter the value
placed in the Length of Original Attribute Value field, but does
alter the length of the resultant AVP that is being created. For
example, if an Attribute Value to be hidden is 4 octets in length,
the unhidden AVP length would be 10 octets (6 + Attribute Value
length). After hiding, the length of the AVP would become 6 +
Attribute Value length + size of the Length of Original Attribute
Value field + Padding. Thus, if Padding is 12 octets, the AVP length
would be 6 + 4 + 2 + 12 = 24 octets.
Next, an MD5 [RFC1321] hash is performed (in network byte order) on
the concatenation of the following:
+ the 2-octet Attribute number of the AVP
+ the shared key
+ an arbitrary length random vector
The value of the random vector used in this hash is passed in the
value field of a Random Vector AVP. This Random Vector AVP must be
placed in the message by the sender before any hidden AVPs. The same
random vector may be used for more than one hidden AVP in the same
message, but not for hiding two or more instances of an AVP with the
same Attribute Type unless the Attribute Values in the two AVPs are
also identical. When a different random vector is used for the
hiding of subsequent AVPs, a new Random Vector AVP MUST be placed in
the control message before the first AVP to which it applies.
The MD5 hash value is then XORed with the first 16-octet (or less)
segment of the Hidden AVP Subformat and placed in the Attribute Value
field of the Hidden AVP. If the Hidden AVP Subformat is less than 16
octets, the Subformat is transformed as if the Attribute Value field
had been padded to 16 octets before the XOR. Only the actual octets
present in the Subformat are modified, and the length of the AVP is
not altered.
If the Subformat is longer than 16 octets, a second one-way MD5 hash
is calculated over a stream of octets consisting of the shared key
followed by the result of the first XOR. That hash is XORed with the
second 16-octet (or less) segment of the Subformat and placed in the
corresponding octets of the Value field of the Hidden AVP.
If necessary, this operation is repeated, with the shared key used
along with each XOR result to generate the next hash to XOR the next
segment of the value with.
The hiding method was adapted from [RFC2865], which was taken from
the "Mixing in the Plaintext" section in the book "Network Security"
by Kaufman, Perlman and Speciner [KPS]. A detailed explanation of
the method follows:
Call the shared key S, the Random Vector RV, and the Attribute Type
A. Break the value field into 16-octet chunks p_1, p_2, etc., with
the last one padded at the end with random data to a 16-octet
boundary. Call the ciphertext blocks c_1, c_2, etc. We will also
define intermediate values b_1, b_2, etc.
b_1 = MD5 (A + S + RV) c_1 = p_1 xor b_1
b_2 = MD5 (S + c_1) c_2 = p_2 xor b_2
. .
. .
. .
b_i = MD5 (S + c_i-1) c_i = p_i xor b_i
The String will contain c_1 + c_2 +...+ c_i, where "+" denotes
concatenation.
On receipt, the random vector is taken from the last Random Vector
AVP encountered in the message prior to the AVP to be unhidden. The
above process is then reversed to yield the original value.
5.4. AVP Summary
The following sections contain a list of all L2TP AVPs defined in
this document.
Following the name of the AVP is a list indicating the message types
that utilize each AVP. After each AVP title follows a short
description of the purpose of the AVP, a detail (including a graphic)
of the format for the Attribute Value, and any additional information
needed for proper use of the AVP.
5.4.1. General Control Message AVPs
Message Type (All Messages)
The Message Type AVP, Attribute Type 0, identifies the control
message herein and defines the context in which the exact meaning
of the following AVPs will be determined.
The Attribute Value field for this AVP has the following format:
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Type |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The Message Type is a 2-octet unsigned integer.
The Message Type AVP MUST be the first AVP in a message,
immediately following the control message header (defined in
Section 3.2.1). See Section 3.1 for the list of defined control
message types and their identifiers.
The Mandatory (M) bit within the Message Type AVP has special
meaning. Rather than an indication as to whether the AVP itself
should be ignored if not recognized, it is an indication as to
whether the control message itself should be ignored. If the M
bit is set within the Message Type AVP and the Message Type is
unknown to the implementation, the control connection MUST be
cleared. If the M bit is not set, then the implementation may
ignore an unknown message type. The M bit MUST be set to 1 for
all message types defined in this document. This AVP MUST NOT be
hidden (the H bit MUST be 0). The Length of this AVP is 8.
A vendor-specific control message may be defined by setting the
Vendor ID of the Message Type AVP to a value other than the IETF
Vendor ID of 0 (see Section 5.1). The Message Type AVP MUST still
be the first AVP in the control message.
Message Digest (All Messages)
The Message Digest AVP, Attribute Type 59 is used as an integrity
and authentication check of the L2TP Control Message header and
body.
The Attribute Value field for this AVP has the following format:
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Digest Type | Message Digest ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
... (16 or 20 octets) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Digest Type is a one-octet integer indicating the Digest
calculation algorithm:
0 HMAC-MD5 [RFC2104]
1 HMAC-SHA-1 [RFC2104]
Digest Type 0 (HMAC-MD5) MUST be supported, while Digest Type 1
(HMAC-SHA-1) SHOULD be supported.
The Message Digest is of variable length and contains the result
of the control message authentication and integrity calculation.
For Digest Type 0 (HMAC-MD5), the length of the digest MUST be 16
bytes. For Digest Type 1 (HMAC-SHA-1) the length of the digest
MUST be 20 bytes.
If Control Message Authentication is enabled, at least one Message
Digest AVP MUST be present in all messages and MUST be placed
immediately after the Message Type AVP. This forces the Message
Digest AVP to begin at a well-known and fixed offset. A second
Message Digest AVP MAY be present in a message and MUST be placed
directly after the first Message Digest AVP.
The shared secret between LCCEs is used to derive a unique shared
key for Control Message Authentication calculations. The derived
shared key is obtained via an HMAC-MD5 keyed hash [RFC2104], with
the key consisting of the shared secret, and with the data being
hashed consisting of a single octet containing the value 2.
shared_key = HMAC_MD5 (shared_secret, 2)
Calculation of the Message Digest is as follows for all messages
other than the SCCRQ (where "+" refers to concatenation):
Message Digest = HMAC_Hash (shared_key, local_nonce +
remote_nonce + control_message)
HMAC_Hash: HMAC Hashing algorithm identified by the Digest Type
(MD5 or SHA1)
local_nonce: Nonce chosen locally and advertised to the remote
LCCE.
remote_nonce: Nonce received from the remote LCCE
(The local_nonce and remote_nonce are advertised via the
Control Message Authentication Nonce AVP, also defined in this
section.)
shared_key: Derived shared key for this control connection
control_message: The entire contents of the L2TP control
message, including the control message header and all AVPs.
Note that the control message header in this case begins after
the all-zero Session ID when running over IP (see Section
4.1.1.2), and after the UDP header when running over UDP (see
Section 4.1.2.1).
When calculating the Message Digest, the Message Digest AVP MUST
be present within the control message with the Digest Type set to
its proper value, but the Message Digest itself set to zeros.
When receiving a control message, the contents of the Message
Digest AVP MUST be compared against the expected digest value
based on local calculation. This is done by performing the same
digest calculation above, with the local_nonce and remote_nonce
reversed. This message authenticity and integrity checking MUST
be performed before utilizing any information contained within the
control message. If the calculation fails, the message MUST be
dropped.
The SCCRQ has special treatment as it is the initial message
commencing a new control connection. As such, there is only one
nonce available. Since the nonce is present within the message
itself as part of the Control Message Authentication Nonce AVP,
there is no need to use it in the calculation explicitly.
Calculation of the SCCRQ Message Digest is performed as follows:
Message Digest = HMAC_Hash (shared_key, control_message)
To allow for graceful switchover to a new shared secret or hash
algorithm, two Message Digest AVPs MAY be present in a control
message, and two shared secrets MAY be configured for a given
LCCE. If two Message Digest AVPs are received in a control
message, the message MUST be accepted if either Message Digest is
valid. If two shared secrets are configured, each (separately)
MUST be used for calculating a digest to be compared to the
Message Digest(s) received. When calculating a digest for a
control message, the Value field for both of the Message Digest
AVPs MUST be set to zero.
This AVP MUST NOT be hidden (the H bit MUST be 0). The M bit for
this AVP SHOULD be set to 1, but MAY vary (see Section 5.2). The
Length is 23 for Digest Type 1 (HMAC-MD5), and 27 for Digest Type
2 (HMAC-SHA-1).
Control Message Authentication Nonce (SCCRQ, SCCRP)