RFC 5572
IPv6 Tunnel Broker with the Tunnel Setup Protocol (TSP)
RFC 5572: IPv6 Tunnel Broker with the Tunnel Setup Protocol (TSP) 🎀
okay bestie, let's get into this one 💖 it's an Independent Submission and the document number is RFC 5572 🦋
- Title: IPv6 Tunnel Broker with the Tunnel Setup Protocol (TSP)
- Authors: M. Blanchet (Viagenie) and F. Parent (Beon Solutions) 💅
- Category: Experimental 🧪
- ISSN: 2070-1721
- Date: February 2010 📅
- Obsoletes/Updates: the title block doesn't list anything this RFC obsoletes or updates, so it stands alone 🌸
Abstract
okay so a tunnel broker running the Tunnel Setup Protocol (TSP) lets you set up tunnels for all kinds of inner protocols, like IPv6 or IPv4, wrapped inside all kinds of outer packets, like IPv4, IPv6, or UDP over IPv4 for IPv4 NAT traversal ✨ TSP is the control protocol the tunnel client uses to negotiate the tunnel with the broker 🤝 A mobile node running TSP can be hooked up to IPv4 and IPv6 networks, whether it's on IPv4 only, IPv4 behind a NAT, or IPv6 only, and it's giving flexibility 🦋 The tunnel broker can end the tunnels on remote tunnel servers or on itself 🌈 This document explains TSP inside the tunnel broker model 💜
Status of This Memo
this one is not an Internet Standards Track spec, it's published for examination, experimental implementation, and evaluation 🧪 It defines an Experimental Protocol for the Internet community, and it's a contribution to the RFC Series that's independent of any other RFC stream 🌸 The RFC Editor picked to publish it at their discretion and makes no statement about its value for implementation or deployment 🙈 Documents the RFC Editor approves for publication aren't candidates for any level of Internet Standard, see Section 2 of RFC 5741 💅
For the latest status, errata, and how to give feedback, check http://www.rfc-editor.org/info/rfc5572 🔗
IESG Note
this RFC was once considered by the IETF, so it might look like a current IETF work in progress or a published IETF work 👀
Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. 🎀
this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the publication date. Read those carefully, because they spell out your rights and restrictions for this document 📜
Table of Contents
1. Introduction ....................................................4
2. Description of the TSP Framework ................................4
2.1. NAT Discovery ..............................................6
2.2. Any Encapsulation ..........................................6
2.3. Mobility ...................................................6
3. Advantages of TSP ...............................................7
4. Protocol Description ............................................7
4.1. Terminology ................................................7
4.2. Topology ...................................................8
4.3. Overview ...................................................8
4.4. TSP Signaling ..............................................9
4.4.1. Signaling Transport .................................9
4.4.2. Authentication Phase ...............................11
4.4.3. Command and Response Phase .........................14
4.5. Tunnel Establishment ......................................16
4.5.1. IPv6-over-IPv4 Tunnels .............................16
4.5.2. IPv6-over-UDP Tunnels ..............................16
4.6. Tunnel Keep-Alive .........................................16
4.7. XML Messaging .............................................17
4.7.1. Tunnel .............................................17
4.7.2. Client Element .....................................18
4.7.3. Server Element .....................................19
4.7.4. Broker Element .....................................19
5. Tunnel Request Examples ........................................19
5.1. Host Tunnel Request and Reply .............................19
5.2. Router Tunnel Request with a /48 Prefix Delegation
and Reply .................................................20
5.3. IPv4 over IPv6 Tunnel Request .............................22
5.4. NAT Traversal Tunnel Request ..............................23
6. Applicability of TSP in Different Networks .....................24
6.1. Provider Networks with Enterprise Customers ...............24
6.2. Provider Networks with Home/Small Office Customers ........25
6.3. Enterprise Networks .......................................25
6.4. Wireless Networks .........................................25
6.5. Unmanaged Networks ........................................26
6.6. Mobile Hosts and Mobile Networks ..........................26
7. IANA Considerations ............................................26
8. Security Considerations ........................................27
9. Conclusion .....................................................27
10. Acknowledgements ..............................................27
11. References ....................................................28
11.1. Normative References .....................................28
11.2. Informative References ...................................28
Appendix A. The TSP DTD ..........................................30
Appendix B. Error Codes ..........................................311. Introduction
okay so first up, this doc walks through the TSP framework, the protocol details, and the different profiles used 🧚 Then it covers where TSP fits in different environments, some of which were described in the v6ops scenario documents 🗺️
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 [RFC2119]. 📖✨
2. Description of the TSP Framework
Tunnel Setup Protocol (TSP) is a signaling protocol for setting up tunnel parameters between two tunnel endpoints 💖 TSP is built as a tiny client in the requesting tunnel endpoint 🤏 The other endpoint is the server that sets up the tunnel service 🖥️ TSP uses XML [W3C.REC-xml-2004] basic messaging over TCP or UDP, and XML is what gives it extensibility and easy option processing 🫶
TSP negotiates tunnel parameters between the two tunnel endpoints. These are the parameters that always get negotiated:
- Authentication of the users, using any kind of authentication mechanism (through Simple Authentication and Security Layer (SASL) [RFC4422]) including anonymous
- Tunnel encapsulation:
- IP address assignment for the tunnel endpoints
- DNS registration of the IP endpoint address (AAAA)
And these are the other tunnel parameters that may be negotiated 🌈
- Tunnel keep-alive
- IPv6 prefix assignment when the client is a router
- DNS delegation of the inverse tree, based on the IPv6 prefix assigned
- Routing protocols
The tunnel encapsulation can be specified explicitly by the client, or it can be figured out during the TSP exchange by the broker 🕵️♀️ The second option is used to detect the presence of NAT in the path and pick IPv6 over UDP-IPv4 encapsulation 💜
The TSP connection can be set up between two nodes, where each node can control a tunnel endpoint 🦋 The nodes in the framework are:
- the TSP client
- the client tunnel endpoint
- the TSP server
- the server tunnel endpoint
1,3, and 4 form the tunnel broker model [RFC3053], where 3 is the tunnel broker and 4 is the tunnel server (Figure 1) 👑 The tunnel broker can control one or many tunnel servers 🌸
In the simplest model, one node is the client configured as a tunnel endpoint (1 and 2 on the same node), and the second node is the server configured as the other tunnel endpoint (3 and 4 on the same node). This model is shown in Figure 2:
_______________
| TUNNEL BROKER |--> Databases (DNS)
| |
| TSP |
| SERVER |
|_______________|
| |
__________ | | ________
| | | | | |
| TSP |--[TSP]-- +---------| |
| CLIENT | | TUNNEL |--[NETWORK]--
[HOST]--| |<==[CONFIGURED TUNNEL]==>| SERVER |
|___________| | |
|________|
Figure 1: Tunnel Setup Protocol Used on Tunnel Broker Model
___________ ________
| | | TSP |
| TSP |-----------[TSP]---------| SERVER |
| CLIENT | | |--[NETWORK]--
[HOST]--| |<==[CONFIGURED TUNNEL]==>| TUNNEL |
|___________| | SERVER |
|________|
Figure 2: Tunnel Setup Protocol Used on Tunnel Server ModelFrom the point of view of an operating system, TSP is a client application that can configure the operating system's network parameters 🖥️✨
2.1. NAT Discovery
TSP is also used to discover whether a NAT is in the path 🔍 In this discovery mode, the client sends a TSP message over UDP to the TSP server, and that message contains its tunnel request information (such as its source IPv4 address) 📨 The TSP server compares the IPv4 source address of the packet with the address in the TSP message. If they differ, one or many IPv4 NATs are in the path 🙈
If an IPv4 NAT is discovered, IPv6 over UDP-IPv4 tunnel encapsulation gets selected 🧚 Once the TSP signaling is done, the tunnel is established over the same UDP channel used for TSP, so the same NAT address-port mapping is used for both the TSP session and the IPv6 traffic 💅 If the TSP server doesn't detect an IPv4 NAT in the path, then IPv6 over IPv4 encapsulation is used 🌈
A keep-alive mechanism is also included, to keep the NAT mapping active 💖
The IPv4 NAT discovery builds the most effective tunnel for all cases, including a dynamic situation where the client moves 🦋
2.2. Any Encapsulation
TSP is used to negotiate IPv6 over IPv4 tunnels, IPv6 over UDP-IPv4 tunnels, and IPv4 over IPv6 tunnels 🎀 IPv4 over IPv6 tunnels are used in the Dual-Stack Transition Mechanism (DSTM) together with TSP [DSTM] ✨
2.3. Mobility
When a node moves to a different IP network (that is, its IPv4 address changes while it's doing IPv6 over IPv4 encapsulation), the TSP client automatically reconnects to the broker to re-establish the tunnel, using the keep-alive mechanism 🚗💨 On the IPv6 layer, if the client uses user authentication, the same IPv6 address and prefix are kept and re-established, even if the IPv4 address or tunnel encapsulation type changes 👑🫶
3. Advantages of TSP ✨
okay so here's why TSP is lowkey iconic 💅
- Static tunnels, so it's more secure 🔒 Tunnels set up by TSP are static tunnels, which are more secure than automated tunnels [RFC3964]. And there's no third-party relay required! 🙌
- Stable addresses 🦋 The IP address and prefix stay stable, so apps that need a steady address can be deployed and used. Like, when you're tunneling IPv6, there's no dependency on the underlying IPv4 address. Main character energy 👑
- Prefix assignment 🎀 Prefix assignment is supported, and you can use provider address space.
- Flexible, extensible signaling 🧚 The signaling protocol is flexible and extensible (XML, SASL). Very customizable, very slay.
- One solution for lots of encapsulations 🌈 It handles IPv6 in IPv4, IPv4 in IPv6, and IPv6 over UDP over IPv4. It can even be extended to other encapsulation types, such as IPv6 in IPv6. Literally one tool, so many options 😭
- NAT discovery 🔍 It can discover IPv4 NAT in the path, which lets it establish the most optimized tunneling technique depending on what it finds. Smart, bestie 🧠
4. Protocol Description 🌸
4.1. Terminology 📖
Okay, let's get our vocab down first, because these terms are everywhere 💖
Tunnel Broker: In a tunnel broker model, the broker takes charge of all communication between tunnel servers (TSs) and tunnel clients (TCs). Tunnel clients query brokers for a tunnel. The broker finds a suitable tunnel server, asks that tunnel server to set up the tunnel, and then sends the tunnel information to the tunnel client. It's basically the matchmaker 💘
Tunnel Server: Tunnel servers provide the specific tunnel service to a tunnel client. A tunnel server can receive the tunnel request from a tunnel broker (as in the tunnel broker model) or directly from the tunnel client. The tunnel server is the tunnel endpoint 🎯
Tunnel Client: The tunnel client is the entity that needs a tunnel for a particular service or connectivity. A tunnel client can be either a host or a router. The tunnel client is the other tunnel endpoint 🫶
v6v4: IPv6-over-IPv4 tunnel encapsulation
v6udpv4: IPv6-over-UDP-over-IPv4 tunnel encapsulation
v4v6: IPv4-over-IPv6 tunnel encapsulation
4.2. Topology 🗺️
The following diagrams describe typical TSP scenarios. The goal is to establish a tunnel between a tunnel client and a tunnel server ✨
4.3. Overview 🧭
The Tunnel Setup Protocol is initiated from a client node to a tunnel broker. The Tunnel Setup Protocol has three phases, and honestly they're super easy to remember:
- Authentication phase: This is when the tunnel broker/server advertises its capability to a tunnel client, and when a tunnel client authenticates to the broker/server. Hello, introductions 🤝
- Command phase: This is where the client requests or updates a tunnel. Ask for what you want 🙏
- Response phase: This is where the tunnel client receives the request response from the tunnel broker/server, and the client accepts or rejects the tunnel offered. Yes or no, babe 💅
For each command sent by a tunnel client, there is an expected response from the server.
After the response phase is completed, a tunnel is established as requested by the client. If requested, periodic keep-alive packets can be sent from the client to the server 💓
tunnel tunnel
client broker
+| Send version +
||---------------------------------> ||
|| Send capabilities ||
||<--------------------------------- +| Authentication
|| SASL authentication || phase
||<--------------------------------> ||
TSP || Authentication OK ||
signaling||<--------------------------------- +
|| Tunnel request || Command
||---------------------------------> || phase
|| Tunnel response +
||<--------------------------------- || Response
|| Tunnel acknowledge || phase
||---------------------------------> +
+| |
|| Tunnel established |
Data ||===================================|
phase || |
+| (keep-alive) |Figure 3: Tunnel Setup Protocol Exchange 📸
4.4. TSP Signaling 📡
The following sections describe in detail the TSP and the different phases in the TSP signaling. Let's dive in 🌊
4.4.1. Signaling Transport 🚚
TSP signaling can be transported over TCP or UDP, and over IPv4 or IPv6. The tunnel client selects the transport according to the tunnel encapsulation being requested. Figure 4 shows the transport used for TSP signaling with the possible tunnel encapsulations requested 🔍
TSP signaling over UDP/v4 MUST be used if a v6 over UDP over IPv4 (v6udpv4) tunnel is to be requested (e.g., for NAT traversal). This one's non-negotiable, no cap 🙅♀️
Tunnel
Encapsulation Valid Valid
Requested Transport Address family
------------------------------------------
v6anyv4 TCP UDP IPv4
v6v4 TCP UDP IPv4
v6udpv4 UDP IPv4
v4v6 TCP UDP IPv6Figure 4: TSP Signaling Transport 📊
Note that the TSP framework allows for other types of encapsulation to be defined, such as IPv6 over Generic Routing Encapsulation (GRE) or IPv6 over IPv6. So the door is open for future vibes 🚪✨
4.4.1.1. TSP Signaling over TCP 🧵
TSP over TCP is sent over port number 3653 (IANA assigned). The TSP data used during signaling is detailed in the next sections 💜
+------+-----------+----------+
| IP | TCP | TSP data |
| | port 3653 | |
+------+-----------+----------+
where IP is IPv4 or IPv6Figure 5: Tunnel Setup Protocol Packet Format (TCP) 📦
4.4.1.2. TSP Signaling over UDP/v4 📮
Okay, the tea is that TCP gives you the connection-oriented and reliable data delivery that the TSP signaling session needs, but UDP doesn't offer any reliability at all 😭 So reliability gets added inside the TSP session as an extra header at the beginning of the UDP payload. Clever, right? 🧠
+------+-----------+------------+----------+
| IPv4 | UDP | TSP header | TSP data |
| | port 3653 | | |
+------+-----------+------------+----------+Figure 6: Tunnel Setup Protocol Packet Format (UDP) 📦
The algorithm used to add reliability to TSP packets sent over UDP is described in Section 22.5 of [UNP]. Go check that out if you want the deep dive 🤓
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0xF | Sequence Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Timestamp |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| TSP data |
...Figure 7: TSP Header for Reliable UDP 🧩
The 4-bit field (0-3) is set to 0xF. This marker is used by the tunnel broker to identify a TSP signaling packet that is sent after an IPv6 over UDP is established. This is explained in Section 4.5.2 🔖
Sequence Number: 28-bit field. Set by the tunnel client. The value is increased by one for every new packet sent to the tunnel broker. The return packet from the broker contains the unaltered sequence number 🔢
Timestamp: 32-bit field. Set by the tunnel client. Generated from the client local-time value. The return packet from the broker contains the unaltered timestamp ⏰
TSP data: Same as in the TCP/v4 case. Content is described in later sections 📝
The TSP client builds its UDP packet as described above and sends it to the tunnel broker. When the tunnel broker responds, the same values for the sequence number and timestamp MUST be sent back to the client. The TSP client can use the timestamp to determine the retransmission timeout (current time minus the packet timestamp). The client SHOULD retransmit the packet when the retransmission timeout is reached. The retransmitted packet MUST use the same sequence number as the original packet so that the server can detect duplicate packets. And the client SHOULD use exponential backoff when retransmitting packets to avoid network congestion 🚦💖
Heads up: the sequence number has to stay the same on retransmits, or the server can't spot duplicates. Don't get creative with it, bestie 🙈
4.4.2. Authentication Phase 🔐
okay so the authentication phase has 3 steps, bestie 💖
- Client's protocol version identification
- Server's capability advertisement
- Client authentication
when a TCP or UDP session gets set up to a tunnel broker, the tunnel client sends the protocol version it's running. the version number syntax is:
VERSION=2.0.0 CR LFversion 2.0.0 is the version number of this spec 🎀. version 1.0.0 was defined in earlier documents, so that's the older era 🦋
if the server doesn't support the protocol version, it sends an error message and closes the session. it can also send a server list that might support the client's version, optionally 🌸
here's an example of an unsupported client version with no server list:
-- Successful TCP Connection --
C:VERSION=0.1 CR LF
S:302 Unsupported client version CR LF
-- Connection closed --Figure 8: Example of Unsupported Client Version
and here's a version that isn't supported, but this time the server includes a server list:
-- Successful TCP Connection --
C:VERSION=1.1 CR LF
S:1302 Unsupported client version CR LF
<tunnel action="list" type="broker">
<broker>
<address type="ipv4">1.2.3.4</address>
</broker>
<broker>
<address type="dn">ts1.isp1.com</address>
</broker>
</tunnel>
-- Connection closed --Figure 9: Example of Unsupported Client Version, with Server Redirection
if the server DOES support the version the client sent, then it sends a list of the capabilities it supports for authentication and tunnels. main character energy ✨
CAPABILITY TUNNEL=V6V4 TUNNEL=V6UDPV4 AUTH=ANONYMOUS AUTH=PLAIN
AUTH=DIGEST-MD5 CR LFtunnel types must be registered with IANA, and their profiles are defined in Section 7. authentication is done using SASL [RFC4422]. each authentication mechanism should be a registered SASL mechanism. the description of those mechanisms is not in the scope of this doc, so we're leaving that one alone 🙈
the tunnel client can totally choose to close the session if none of the capabilities fit what it needs. if it wants to keep going, it authenticates to the server with one of the advertised mechanisms using SASL. if the authentication fails, the server sends an error message and closes the session 💀
the example in Figure 10 shows a failed authentication, where the tunnel client asks for anonymous auth and the server doesn't support it. rip 😭
Note that linebreaks and indentation within a "C:" or "S:" are editorial and not part of the protocol. so don't stress about the formatting 🫶
-- Successful TCP Connection --
C:VERSION=2.0.0 CR LF
S:CAPABILITY TUNNEL=V6V4 AUTH=DIGEST-MD5 CR LF
C:AUTHENTICATE ANONYMOUS CR LF
S:300 Authentication failed CR LFFigure 10: Example of Failed Authentication
Figure 11 shows a successful anonymous authentication, and it's giving clean ✨
-- Successful TCP Connection --
C:VERSION=2.0.0 CR LF
S:CAPABILITY TUNNEL=V6V4 TUNNEL=V6UDPV4 AUTH=ANONYMOUS AUTH=PLAIN
AUTH=DIGEST-MD5 CR LF
C:AUTHENTICATE ANONYMOUS CR LF
S:200 Success CR LFFigure 11: Successful Anonymous Authentication
digest-MD5 authentication with SASL follows [RFC2831]. Figure 12 shows a successful digest-MD5 SASL authentication, and the base64 is giving chaotic but it's fine, we decode it below 🧚
-- Successful TCP Connection --
C:VERSION=2.0.0 CR LF
S:CAPABILITY TUNNEL=V6V4 TUNNEL=V6UDPV4 AUTH=ANONYMOUS AUTH=PLAIN
AUTH=DIGEST-MD5 CR LF
C:AUTHENTICATE DIGEST-MD5 CR LF
S:cmVhbG09aGV4b3Msbm9uY2U9MTExMzkwODk2OCxxb3A9YXV0aCxhbGdvcml0aG09bWQ
1LXNlc3MsY2hhcnNldD11dGY4
C:Y2hhcnNldD11dGY4LHVzZXJuYW1lPSJ1c2VybmFtZTEiLHJlYWxtPSJoZXhvcyIsbm9
uY2U9IjExMTM5MDg5NjgiLG5jPTAwMDAwMDAxLGNub25jZT0iMTExMzkyMzMxMSIsZG
lnZXN0LXVyaT0idHNwL2hleG9zIixyZXNwb25zZT1mOGU0MmIzYzUwYzU5NzcxODUzZ
jYyNzRmY2ZmZDFjYSxxb3A9YXV0aA==
S:cnNwYXV0aD03MGQ1Y2FiYzkyMzU1NjhiZTM4MGJhMmM5MDczODFmZQ==
S:200 Success CR LFFigure 12: Successful Digest-MD5 Authentication
and here's the base64-decoded version of that SASL exchange, so you can actually read it 👑
S:realm="hexos",nonce="1113908968",qop="auth",algorithm=md5-sess,
charset=utf8
C:charset=utf8,username="username1",realm="hexos",nonce="1113908968",
nc=00000001,cnonce="1113923311",digest-uri="tsp/hexos",
response=f8e42b3c50c59771853f6274fcffd1ca,qop=auth
S:rspauth=70d5cabc9235568be380ba2c907381feonce the authentication succeeds, the server sends a success return code and the protocol enters the Command phase. we made it bestie 🎉
4.4.3. Command and Response Phase 📨
the Command phase is where the tunnel client sends a tunnel request or a tunnel update to the server. in this phase, commands are sent as XML messages. the first line is a "Content-length" directive that indicates the size of the XML message that follows. when the server sends a response, the first line is the "Content-length" directive, the second is the return code, and the third is the XML message, if there is one. the "Content-length" is calculated from the first character of the return code line to the last character of the XML message, inclusively. counting is serious business 🔥
spaces can be inserted freely 💅
-- UDP session established --
C:VERSION=2.0.0 CR LF
S:CAPABILITY TUNNEL=V6V4 TUNNEL=V6UDPV4 AUTH=ANONYMOUS
AUTH=PLAIN AUTH=DIGEST-MD5 CR LF
C:AUTHENTICATE ANONYMOUS CR LF
S:200 Success CR LF
C:Content-length: 205 CR LF
<tunnel action="create" type="v6udpv4">
<client>
<address type="ipv4">192.0.2.135</address>
<keepalive interval="30"></keepalive>
</client>
</tunnel> CR LF
S:Content-length: 501 CR LF
200 Success CR LF
<tunnel action="info" type="v6udpv4" lifetime="604800">
<server>
<address type="ipv4">192.0.2.115</address>
<address type="ipv6">
2001:db8:8000:0000:0000:0000:0000:38b2
</address>
</server>
<client>
<address type="ipv4">192.0.2.135</address>
<address type="ipv6">
2001:db8:8000:0000:0000:0000:0000:38b3
</address>
<keepalive interval="30">
<address type="ipv6">
2001:db8:8000:0000:0000:0000:0000:38b2
</address>
</keepalive>
</client>
</tunnel> CR LF
C:Content-length: 35 CR LF
<tunnel action="accept"></tunnel> CR LFFigure 13: Example of a Command/Response Sequence
Figure 13 shows a client requesting an anonymous v6udpv4 tunnel, and it says a keep-alive packet will be sent every 30 seconds. the tunnel broker responds with the tunnel parameters and accepts that keep-alive period (Section 4.6). finally, the client sends an accept message to the server. the full sequence is a whole vibe 🦋
once the accept message has been sent, the server and client configure their tunnel endpoint based on the negotiated tunnel parameters ✨
4.5. Tunnel Establishment 🌈
4.5.1. IPv6-over-IPv4 Tunnels
once the TSP signaling is complete, a tunnel can be established on the tunnel server and client node. if a v6v4 tunnel has been negotiated, then an IPv6-over-IPv4 tunnel [RFC4213] is established using the operating system tunneling interface. on the client node, this is done by the TSP client calling the appropriate OS commands or system calls 💻
4.5.2. IPv6-over-UDP Tunnels
if a v6udpv4 tunnel is configured, the same source/destination address and port used during the TSP signaling get used to configure the v6udpv4 tunnel. if there's a NAT in the path between the TSP client and the tunnel broker, the TSP signaling session will have created a UDP state in the NAT. by reusing the same UDP socket parameters to transport IPv6, the traffic will flow across the NAT using that same state. it's so smart, I'm obsessed 😭
+------+-----------+--------+
| IPv4 | UDP | IPv6 |
| hdr. | port 3653 | |
+------+-----------+--------+Figure 14: IPv6 Transport over UDP
at any time, a client may re-establish a TSP signaling session. the client disconnects the current tunnel and starts a new TSP signaling session as described in Section 4.4.1.2. if a NAT is present and the new TSP session uses the same UDP mapping in the NAT as the tunnel, the tunnel broker will need to disconnect the client tunnel before the client can set up a new TSP session. the NAT drama is real 🙈
4.6. Tunnel Keep-Alive 💜
a TSP client may choose to send periodic keep-alive messages to the server to keep its tunnel connectivity alive. this lets the client detect network changes and enable automatic tunnel re-establishment. for IPv6-over-UDP tunnels, periodic keep-alive messages can help refresh the connection state in a NAT if one of those is in the tunnel path. keeping the vibes alive 🫶
for IPv6-over-IPv4 and IPv6-over-UDP tunnels, the keep-alive message is an ICMPv6 echo request [RFC4443] sent from the client to the tunnel server. the IPv6 destination address of the echo message MUST be the address from the 'keepalive' element sent in the tunnel response during the TSP signaling (Section 4.4.3). the echo message is sent over the configured tunnel 🍓
the tunnel server responds to the ICMPv6 echo requests and can keep track of which tunnel is active. any client traffic can also be used to verify if the tunnel is active. the broker can use this to disconnect tunnels that are no longer in use, so no ghost tunnels allowed 👻
the broker can send a different keep-alive interval from the one in the client request. the client MUST conform to the broker-specified keep-alive interval. the client SHOULD apply a random "jitter" value so that keep-alive messages from lots of clients don't all sync up and hit the server at once [FJ93]. this is done by using an interval value in the range of [0.75T - T], where T is the keep-alive interval specified by the server. jitter is the anti-clump move 🌸
4.7. XML Messaging 💬
this section describes the XML messaging used in the TSP signaling during the command and response phase. the XML elements and attributes are listed in the DTD (Appendix A) 📜
4.7.1. Tunnel 🦋
the client and server use the tunnel token with an action attribute. valid actions for this profile are: 'create', 'delete', 'info', 'accept', and 'reject'.
create: action used to request a new tunnel or update an existing tunnel. sent by the tunnel client.delete: action used to remove an existing tunnel from the server. sent by the tunnel client.info: action used to request current properties of an existing tunnel. this action is also used by the tunnel broker to send tunnel parameters following a client 'create' action.accept: action used by the client to acknowledge to the server that the tunnel parameters are accepted. the client will establish a tunnel.reject: action used by the client to signal to the server that the tunnel parameters offered are rejected and no tunnel will be established.
the tunnel 'lifetime' attribute is set by the tunnel broker and specifies the lifetime of the tunnel in minutes. the lifetime is an administratively set value. when a tunnel lifetime has expired, it is disconnected on the tunnel server. time's up, bye 👋
the 'tunnel' message contains three elements:
<client>: client's information<server>: server's information<broker>: list of other servers
4.7.2. Client Element 💖
okay so the 'client' element is giving main character 💅 It has 3 sub-elements: 'address', 'router', and 'keepalive' 🫶 The client uses them to describe its request, and the server reads them to build the right tunnel 🦋 Fr, the client element is only the element a client sends 👑
The 'address' element identifies the client IP endpoint of the tunnel 🌸 When you're tunneling over IPv4, the client MUST send only its IPv4 address to the server 🍓 When you're tunneling over IPv6, the client MUST only send its IPv6 address to the server 💜
Then the broker sends back the assigned IPv6 or IPv4 address endpoint and domain name inside the 'client' element when the tunnel is created or updated ✨ If the broker supports it, the 'client' element MAY contain the registered DNS name for the address endpoint assigned to the client 🧚
Optionally, a client MAY send a 'router' element to ask for a prefix delegation 🌈
Optionally, a client MAY send a 'keepalive' element that contains the keep-alive time interval requested by the client 💫
4.7.3. Server Element 🦋
The 'server' element has two elements inside it: 'address' and 'router' 🎀 These describe the server's tunnel endpoint. The 'address' element gives both IPv4 and IPv6 addresses of the server's tunnel endpoint, and the 'router' element gives info for the routing method the client picked 🫶
4.7.4. Broker Element 🌷
The 'broker' element is how a tunnel broker offers a client an alternate list of brokers, for when the server can't provide the requested tunnel 🤝
The 'broker' element contains an 'address' element or a series of 'address' elements 🍭
5. Tunnel Request Examples 🎀
Okay, here's where it gets fun 🥳 This section shows a bunch of examples of requests.
5.1. Host Tunnel Request and Reply 🌸
A simple tunnel request is a 'tunnel' element that only contains an 'address' element 💅 The tunnel action is 'create', and it specifies a 'v6v4' tunnel encapsulation type. The response from the tunnel broker is an 'info' action. Note that the registered Fully-Qualified Domain Name (FQDN) of the assigned client IPv6 address also gets returned to the tunnel client 💖
-- Successful TCP Connection --
C:VERSION=2.0.0 CR LF
S:CAPABILITY TUNNEL=V6V4 AUTH=ANONYMOUS CR LF
C:AUTHENTICATE ANONYMOUS CR LF
S:200 Authentication successful CR LF
C:Content-length: 123 CR LF
<tunnel action="create" type="v6v4">
<client>
<address type="ipv4">1.1.1.1</address>
</client>
</tunnel> CR LF
S: Content-length: 234 CR LF
200 OK CR LF
<tunnel action="info" type="v6v4" lifetime="1440">
<server>
<address type="ipv4">192.0.2.114</address>
<address type="ipv6">
2001:db8:c18:ffff:0000:0000:0000:0000
</address>
</server>
<client>
<address type="ipv4">1.1.1.1</address>
<address type="ipv6">
2001:db8:c18:ffff::0000:0000:0000:0001
</address>
<address type="dn">userid.domain</address>
</client>
</tunnel> CR LF
C: Content-length: 35 CR LF
<tunnel action="accept"></tunnel> CR LF
Figure 15: Simple Tunnel Request Made by a Client5.2. Router Tunnel Request with a /48 Prefix Delegation and Reply 🧁
A tunnel request with a prefix is a 'tunnel' element that contains an 'address' element and a 'router' element 🍓 The 'router' element also contains the 'dns_server' element, which asks for a DNS delegation of the assigned IPv6 prefix ✨ The 'dns_server' element lists the IP addresses of the DNS servers to be registered for the reverse-mapping zone 🌈
Tunnel request with prefix and static routes.
C: Content-length: 234 CR LF
<tunnel action="create" type="v6v4">
<client>
<address type="ipv4">192.0.2.9</address>
<router>
<prefix length="48"/>
<dns_server>
<address type="ipv4">192.0.2.5</address>
<address type="ipv4">192.0.2.4</address>
<address type="ipv6">2001:db8::1</address>
</dns_server>
</router>
</client>
</tunnel> CR LF
S: Content-length: 234 CR LF
200 OK CR LF
<tunnel action="info" type="v6v4" lifetime="1440">
<server>
<address type="ipv4">192.0.2.114</address>
<address type="ipv6">
2001:db8:c18:ffff:0000:0000:0000:0000
</address>
</server>
<client>
<address type="ipv4">192.0.2.9</address>
<address type="ipv6">
2001:db8:c18:ffff::0000:0000:0000:0001
</address>
<address type="dn">userid.domain</address>
<router>
<prefix length="48">2001:db8:c18:1234::</prefix>
<dns_server>
<address type="ipv4">192.0.2.5</address>
<address type="ipv4">192.0.2.4</address>
<address type="ipv6">2001:db8::1</address>
</dns_server>
</router>
</client>
</tunnel> CR LF
C: Content-length: 35 CR LF
<tunnel action="accept"></tunnel> CR LF
Figure 16: Tunnel Request with Prefix and DNS Delegation5.3. IPv4 over IPv6 Tunnel Request 🦋
This is basically the same as the previous 'create' action, except the tunnel type is set to 'v4v6' 💜
-- Successful TCP Connection --
C:VERSION=1.0 CR LF
S:CAPABILITY TUNNEL=V4V6 AUTH=DIGEST-MD5 AUTH=ANONYMOUS
CR LF
C:AUTHENTICATE ANONYMOUS CR LF
S:OK Authentication successful CR LF
C:Content-length: 228 CR LF
<tunnel action="create" type="v4v6">
<client>
<address type="ipv6">
2001:db8:0c18:ffff:0000:0000:0000:0001
</address>
</client>
</tunnel> CR LF
Figure 17: Simple Tunnel Request Made by a ClientIf the allocation request is accepted, the broker acknowledges the allocation to the client by sending a 'tunnel' element with 'action' set to 'info', 'type' set to 'v4v6', and the 'lifetime' attribute set to the period of validity or lease time of the allocation 🎀 The 'tunnel' element contains 'server' and 'client' elements 🌸
S: Content-length: 370 CR LF
200 OK CR LF
<tunnel action="info" type="v4v6" lifetime="1440">
<server>
<address type="ipv4" length="30">
192.0.2.2
</address>
<address type="ipv6">
2001:db8:c18:ffff:0000:0000:0000:0002
</address>
</server>
<client>
<address type="ipv4" length="30">
192.0.2.1
</address>
<address type="ipv6">
2001:db8:c18:ffff::0000:0000:0000:0001
</address>
</client>
</tunnel> CR LF
Figure 18: IPv4 over IPv6 Tunnel ResponseIn DSTM [DSTM] terminology, the DSTM server is the TSP broker and the Tunnel Endpoint (TEP) is the tunnel server 🧚
5.4. NAT Traversal Tunnel Request 🌷
When a client can do both IPv6 over IPv4 and IPv6 over UDP over IPv4 encapsulation, it can ask the broker, using the "v6anyv4" tunnel mode, to figure out whether it's behind a NAT and to send the appropriate tunnel encapsulation mode as part of the response 🕵️♀️ The client can also explicitly request an IPv6 over UDP over IPv4 tunnel by putting "v6udpv4" in its request 💫
In the following example, the client tells the broker it wants to send keep-alives every 30 seconds. In its response, the broker accepts the client-suggested keep-alive interval, and the IPv6 destination address for the keep-alive packets is specified 🍓
C:VERSION=2.0.0 CR LF
S:CAPABILITY TUNNEL=V6V4 TUNNEL=V6UDPV4 AUTH=DIGEST-MD5 CR LF
C:AUTHENTICATE ... CR LF
S:200 Authentication successful CR LF
C:Content-length: ... CR LF
<tunnel action="create" type="v6anyv4">
<client>
<address type="ipv4">10.1.1.1</address>
<keepalive interval="30"></keepalive>
</client>
</tunnel> CR LF
S: Content-length: ... CR LF
200 OK CR LF
<tunnel action="info" type="v6udpv4" lifetime="1440">
<server>
<address type="ipv4">192.0.2.114</address>
<address type="ipv6">
2001:db8:c18:ffff:0000:0000:0000:0002
</address>
</server>
<client>
<address type="ipv4">10.1.1.1</address>
<address type="ipv6">
2001:db8:c18:ffff::0000:0000:0000:0003
</address>
<keepalive interval="30">
<address type="ipv6">
2001:db8:c18:ffff:0000:0000:0000:0002
</address>
</keepalive>
</client>
</tunnel> CR LF
Figure 19: Tunnel Request Using v6anyv4 Mode6. Applicability of TSP in Different Networks 🌈
This section is all about where TSP fits in different networks 🗺️
6.1. Provider Networks with Enterprise Customers 🏢
In a provider network where IPv4 is dominant, a tunneled infrastructure can be used to give enterprise customers IPv6 services before a full IPv6 native infrastructure is built 🚀 To start deploying in a controlled way and to give enterprise customers a prefix, the TSP framework gets used. The TSP server can live in the core, in the aggregation points, or in the Points of Presence (PoPs) to offer the service to customers 💜 IPv6 over IPv4 encapsulation can be used. If the customers sit behind an IPv4 NAT, then IPv6 over UDP-IPv4 encapsulation can be used 🌸 TSP can also be combined with other techniques ✨
6.2. Provider Networks with Home/Small Office Customers 🏠
In a provider network where IPv4 is dominant, a tunneled infrastructure can be used to give home and small office customers IPv6 services before a full IPv6 native infrastructure is built 🧁 Small networks like home and small offices have a non-upgradable gateway with NAT. TSP with NAT traversal is used to offer IPv6 connectivity and a prefix to the internal network 🫶
Automating the prefix assignment and DNS delegation, which TSP does, is a very important feature for a provider 😭 It helps substantially decrease support costs 💸 The provider can use the same Authentication, Authorization, and Accounting (AAA) database that authenticates its IPv4 broadband users. Customers can deploy home IPv6 networks without any help from the provider's support people 🎉
With the NAT discovery function of TSP, providers can use the same TSP infrastructure for both the NAT and non-NAT parts of the network 🦋
6.3. Enterprise Networks 💼
In an enterprise network where IPv4 is dominant, a tunneled infrastructure can be used to give IPv6 services to the IPv6 islands (hosts or networks) inside the enterprise, before a full IPv6 native infrastructure is built [RFC4057] 🏝️ TSP can give IPv6 connectivity, a prefix, and routing for those islands. This gives the enterprise fully controlled IPv6 deployment while keeping the IPv6 assignments to the islands automated and permanent 👑
6.4. Wireless Networks 📶
Okay so in a wireless network where IPv4 is the main character 👑, hosts and networks are always moving around, and their IPv4 address keeps changing. TSP handles the automatic re-establishment of the tunnel when that IPv4 address changes 🦋.
Now flip it: in a wireless network where IPv6 is dominant, hosts and networks still move around 🌈. TSP takes care of the automatic re-establishment of the IPv4 over IPv6 tunnel so nobody gets left behind 💖.
6.5. Unmanaged Networks 🧚
An unmanaged network is one where there's no network manager or staff around to configure the network devices [RFC3904]. TSP is especially iconic here because it automates everything needed for IPv6 connectivity: tunnel endpoint parameters, prefix assignment, DNS delegation, and routing 💅.
An unmanaged network may (or may not) be behind a NAT 🙈. Either way, the NAT discovery function means TSP works automatically in both cases ✨.
6.6. Mobile Hosts and Mobile Networks 🦋
Mobile hosts are super common now 💜. Laptops that hop from wireless to a wired connection in an office, at home, etc. are the perfect examples. They often have IPv4 connectivity, but not necessarily IPv6 🥺. The TSP framework lets mobile hosts have IPv6 connectivity wherever they are, because the TSP client sends updated info about the new environment to the TSP server whenever something changes 🔥. Pair that with NAT discovery and traversal and the mobile host can stay IPv6 connected wherever it goes 🌸.
Mobile here only means the change of IPv4 address 🙃. Mobile-IP mechanisms and fast hand-off handle the extra constraints of mobile environments.
Mobile networks get the same applicability as mobile hosts. On top of that, in the TSP framework they also keep their prefix assignment and can control the routing 👑. NAT discovery can be used here too.
7. IANA Considerations 🎀
A tunnel type registry has been created by IANA 📋. The following strings are defined in this document:
"v6v4"for IPv6 in IPv4 encapsulation (using IPv4 protocol 41)"v6udpv4"for IPv6 in UDP in IPv4 encapsulation"v6anyv4"for IPv6 in IPv4 or IPv6 in UDP in IPv4 encapsulation"v4v6"for IPv4 in IPv6 encapsulation
Registering a new tunnel type can be done on a first come, first served policy [RFC5226]. A new registration should provide a point of contact, the tunnel type string, and a brief description of the applicability ✨.
IANA assigned 3653 as the TSP port number 🫶.
8. Security Considerations 🚨
Buckle up bestie, this part is SERIOUS 💀. Security is not a vibe to skip.
Authentication of the TSP session uses the SASL [RFC4422] framework 🔐. The authentication mechanism gets negotiated between the client and the server. The framework uses whatever level of authentication is needed to secure the session, based on the policies.
Static tunnels are created when the TSP negotiation is terminated 🧊. Static tunnels are not open gateways, and they have fewer security issues than automated tunnels. Security considerations for static IPv6 in IPv4 tunnels are described in [RFC4213].
To help make sure traffic can be traced back to its correct source network, a tunnel server implementation should allow ingress filtering on the user tunnel [RFC3704] 🕵️♀️.
Here's the drama 😭: a customer A behind a NAT can use a huge number of (private) IPv4 addresses and/or source ports and request multiple v6udpv4 tunnels. That would quickly saturate the tunnel server capacity 💥. So the tunnel broker implementation should offer a way to throttle and limit the number of tunnels established to the same IPv4 address 🛑.
9. Conclusion 👑
The Tunnel Setup Protocol (TSP) is applicable in lots of environments, such as: providers, enterprises, wireless, unmanaged networks, mobile hosts, and networks 🌍. TSP gives the two tunnel endpoints the ability to negotiate tunnel parameters, plus prefix assignment, DNS delegation, and routing, all in an authenticated session 🔐. It also provides an IPv4 NAT discovery function by using the most effective encapsulation 🧠. And it supports the IPv4 mobility of the nodes 🦋.
10. Acknowledgements 🫶
This document is the merge of many previous documents about TSP 💖. Octavio Medina contributed to an earlier document (IPv4 in IPv6) 🙌. Thanks to the following people for comments on improving and clarifying this document: Pekka Savola, Alan Ford, Jeroen Massar, and Jean-Francois Tremblay 🎀.
11. References 📚
11.1. Normative References
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC2473] Conta, A. and S. Deering, "Generic Packet Tunneling in IPv6 Specification", RFC 2473, December 1998.
- [RFC2831] Leach, P. and C. Newman, "Using Digest Authentication as a SASL Mechanism", RFC 2831, May 2000.
- [RFC4213] Nordmark, E. and R. Gilligan, "Basic Transition Mechanisms for IPv6 Hosts and Routers", RFC 4213, October 2005.
- [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006.
- [RFC4443] Conta, A., Deering, S., and M. Gupta, "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification", RFC 4443, March 2006.
- [W3C.REC-xml-2004] Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T., and E. Maler, "Extensible Markup Language (XML) 1.0 (Third Edition)", W3C REC REC-xml-20040204, February 2004.
11.2. Informative References
- [DSTM] Bound, J., Toutain, L., and JL. Richier, "Dual Stack IPv6 Dominant Transition Mechanism", Work in Progress, October 2005.
- [FJ93] Floyd, S. and V. Jacobson, "The Synchronization of Periodic Routing Messages", Proceedings of ACM SIGCOMM, September 1993.
- [RFC3053] Durand, A., Fasano, P., Guardini, I., and D. Lento, "IPv6 Tunnel Broker", RFC 3053, January 2001.
- [RFC3704] Baker, F. and P. Savola, "Ingress Filtering for Multihomed Networks", BCP 84, RFC 3704, March 2004.
- [RFC3904] Huitema, C., Austein, R., Satapati, S., and R. van der Pol, "Evaluation of IPv6 Transition Mechanisms for Unmanaged Networks", RFC 3904, September 2004.
- [RFC3964] Savola, P. and C. Patel, "Security Considerations for 6to4", RFC 3964, December 2004.
- [RFC4057] Bound, J., "IPv6 Enterprise Network Scenarios", RFC 4057, June 2005.
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008.
- [UNP] Stevens, R., Fenner, B., and A. Rudoff, "Unix Network Programming, 3rd edition", Addison Wesley ISBN 0-13-141155-1, 2004.
Appendix A. The TSP DTD 🧾
<?xml version="1.0"?>
<!DOCTYPE tunnel [
<!ELEMENT tunnel (server?,client?,broker?)>
<!ATTLIST tunnel action
(create|delete|info|accept|reject) #REQUIRED >
<!ATTLIST tunnel type
(v6v4|v4v6|v6anyv4|v6udpv4) #REQUIRED >
<!ATTLIST tunnel lifetime CDATA "1440" >
<!ELEMENT server (address+,router?)>
<!ELEMENT client (address+,router?)>
<!ELEMENT broker (address+)>
<!ELEMENT router (prefix?,dns_server?)>
<!ELEMENT dns_server (address+)>
<!ELEMENT prefix (#PCDATA)>
<!ATTLIST prefix length CDATA #REQUIRED>
<!ELEMENT address (#PCDATA)>
<!ATTLIST address type (ipv4|ipv6|dn) #REQUIRED>
<!ATTLIST address length CDATA "">
<!ELEMENT keepalive (address?)>
<!ATTLIST keepalive interval CDATA #REQUIRED>
]>Figure 20: TSP DTD
Appendix B. Error Codes 🚦
Error codes get sent as a numeric value followed by a text message describing the code, kind of like SMTP 📨. The codes are sent from the broker to the client. The currently defined error codes are listed below. When the client gets an error, it displays the appropriate message to the user 💬.
New error messages may be defined in the future. For interoperability purposes, the error code range to use should be from 300 to 599 🔢.
The reply code 200 tells the client that an action successfully completed 🎉. For example, this reply code is used in response to an authentication request and a tunnel creation request.
The server may redirect the client to another broker. How these brokers are known or discovered is beyond the scope of this document 🤷♀️. When a list of tunnel brokers follows the error code as a referral service, 1000 is added to the error code 🔁.
The predefined values are:
200 Success:Successful operation.300 Authentication failed:Invalid userid, password, or authentication mechanism.301 No more tunnels available:The server has reached its capacity limit.302 Unsupported client version:The client version is not supported by the server.303 Unsupported tunnel type:The server does not provide the requested tunnel type.310 Server side error:Undefined server error.500 Invalid request format or specified length:The received request has invalid syntax or is truncated.501 Invalid IPv4 address:The IPv4 address specified by the client is invalid.502 Invalid IPv6 address:The IPv6 address specified by the client is invalid.506 IPv4 address already used for existing tunnel:An IPv6-over-IPv4 tunnel already exists using the same IPv4 address endpoints.507 Requested prefix length cannot be assigned:The requested prefix length cannot be allocated on the server.521 Request already in progress:The client tunnel request is being processed by the server. Temporary error.530 Server too busy:Request cannot be processed, insufficient resources. Temporary error.
Authors' Addresses 💌
Marc Blanchet
Viagenie
2600 boul. Laurier, suite 625
Quebec, QC G1V 4W1
Canada
Phone: +1-418-656-9254
EMail: Marc.Blanchet@viagenie.ca
Florent Parent
Beon Solutions
Quebec, QC
Canada
Phone: +1 418 265 7357
EMail: Florent.Parent@beon.ca📦 where this page comes from
- ietf: rfc5572 2010-02
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms