[pisa-src] r2427 - docs/protocol_spec/application.tex
- From: Thomas Jansen <mithi@xxxxxxxxx>
- To: pisa-src@xxxxxxxxxxxxx
- Date: Thu, 27 Jan 2011 13:54:28 +0100
Author: tjansen
Date: Thu Jan 27 13:54:27 2011
New Revision: 2427
Log:
first draft for connection modes and control packet format
Modified:
docs/protocol_spec/application.tex
Modified: docs/protocol_spec/application.tex
==============================================================================
--- docs/protocol_spec/application.tex Wed Jan 26 18:21:56 2011 (r2426)
+++ docs/protocol_spec/application.tex Thu Jan 27 13:54:27 2011 (r2427)
@@ -142,7 +142,43 @@
\section{Connections}
+A connection represents the state shared between a two PISA hosts.
+Each connection corresponds to a HIP tunnel used to transport control packets
and payload packets between the two hosts.
+In contrast to HIP, where the notion of initiator and responder is dropped
after the initial handshake, PISA keeps the notion of client and server
throughout the entire connection lifetime.
+The \emph{PISA client} initiates the connection, while the \emph{PISA server}
waits for incoming connection requests.
+A PISA client can either be a native client or a legacy router acting on
behalf of a legacy client.
+A PISA server can either be a trustpoint or a service relay.
+
\subsection{Modes}
+
+Each connection is characterized by its mode, describing the semantics of that
connection.
+The mode loosely corresponds to a combination of roles in the network.
+Since by definition there can exist only one connection between a PISA client
and a PISA server, subsequent tries to establish a connection between the same
PISA client and PISA server with another mode must fail.
+Trying to establish an already existing connection with the same mode is
allowed and treated as a retry for packet loss robustness.
+
+\begin{description}
+
+\item[Relay]
+A \emph{relay connection} must only be established between a native client and
a trustpoint.
+The PISA server (i.e., the trustpoint) assigns an IPv4 address from its local
address pool to the PISA client (i.e., the native client) and transmits it in
the initial handshake.
+The PISA client must use this IPv4 address as the source address for packets
routed to the Internet.
+The PISA server must only accept relay connections from PISA clients,
identified by their Host Identity Tag, that are whitelisted (e.g., by having
completed the pairing procedure).
+
+\item[Service]
+A \emph{service connection} must only be established between a native client
and a service relay.
+In the initial handshake, the PISA client (i.e., the native client) specifies
what source IP address will be used for packets originating from the PISA
client.
+The PISA server (i.e., the service relay) creates a NAT mapping for that
source address to an unused IPv4 address from its address pool.
+Thus, requesting a service connection always implicitly includes requesting a
native NAT mapping.
+
+\item[Legacy Router]
+A \emph{legacy router connection} must only be established between a legacy
router and a service relay.
+The PISA client (i.e., the legacy relay) specifies the MAC and IP source
address of the legacy client.
+The PISA server (i.e., the service relay) creates a NAT mapping for that
source address and MAC address or updates an already existing NAT mapping.
+A PISA client may send a new request for another legacy client.
+In that case, the server must not create a new connection, only a new NAT
mapping.
+
+\end{description}
+
\subsection{Management}
\subsection{NAT steps performed}
@@ -150,17 +186,148 @@
\section{Packet Types}
+This section introduces packet formats for the PISA control channel and the
PISA data channel.
+
+\subsection{Control Channel}
+
+All control packets are sent as UDP packets over a HIP tunnel, thus using the
HITs in form of IPv6 addresses.
+The PISA server listens for control packets on port \textbf{TODO}.
+All fields are in network byte order.
+
\paragraph{PISA Header}
-\paragraph{Register}
-\paragraph{Register ACK}
+Each control packet starts with the common PISA header, containing packet
type, packet length, and the PISA version.
+
+\begin{small}
+\begin{verbatim}
+ 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
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Type | Length |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Flags | Version | Reserved |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+\end{verbatim}
+\end{small}
+
+Since this specification is not entirely compatible with the prior
implementation, the version field must be set to 2.
+The flags and reserved fields are currently unused and must be set to 0.
+The length field indicates the length of the PISA control packet in bytes.
\textbf{TODO: check that}
+The type field must be set according to the following PISA control packet
+types:
+
+\begin{center}
+\begin{tabular}{r|l}
+Type & Name \\ \hline \hline
+0 & \emph{deprecated} \\ \hline
+1 & De-Register \\ \hline
+2 & De-Register ACK \\ \hline
+3 & Heartbeat \\ \hline
+4 & Heartbeat ACK \\ \hline
+5 & Register REQ \\ \hline
+6 & Register RESP \\ \hline
+7 & \emph{deprecated} \\ \hline
+8 & Legacy Handover IND \\ \hline
+\end{tabular}
+\end{center}
+
+\paragraph{Register REQ}
+A \emph{register request} is sent by a PISA client to a PISA server to,
depending on the connection type, request a new connection and/or NAT mapping.
+After the PISA header, the following data structure is appended:
+
+\begin{small}
+\begin{verbatim}
+ 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
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Client PISA IPv4 |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Connection Type | |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Client MAC +
+ | |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+\end{verbatim}
+\end{small}
+
+\textbf{TODO: Note that the current implementation doesn't have the Client
MAC.}
+
+Depending on the connection type, the client PISA IPv4 and client MAC fields
may be unused and must then be set to 0.
+The client PISA IPv4 field contains the source IP of the client device in the
PISA address space on the client side.
+This field is not used for connections of type relay.
+The Client MAC contains the MAC address of the client device and is only used
for legacy connections.
+Valid connection types are:
+\begin{itemize}
+\item \textbf{Relay} Connection type: 1.
+Used by a native client to route traffic to the Internet.
+Both client PISA IPv4 and client MAC are unused and must be set to 0.
+\item \textbf{Service} Connection type: 2.
+Used by a native client to request a NAT mapping at a service gateway.
+Client PISA IPv4 must be set to the local IPv4 address of the client in its
PISA address space.
+Client MAC is unused and must be set to 0.
+\item \textbf{Legacy} Connection type: 3.
+Used by a legacy router to request a NAT mapping at a service gateway on
behalf of a legacy client.
+Client PISA IPv4 must be set to the local IPv4 address of the client in the
legacy router's PISA address space.
+Client MAC must be set to the MAC address of the legacy client for handover
detection.
+\end{itemize}
+
+
+\paragraph{Register RESP}
+A \emph{register response} must be sent by a PISA server as a reply to a
register request to indicates success or failure.
+
+\begin{small}
+\begin{verbatim}
+ 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
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Server IPv4 |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Client IPv4 |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Error code |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+\end{verbatim}
+\end{small}
+
+\textbf{TODO: Note that the current implementation doesn't have the error
code.}
+
+\begin{center}
+\begin{tabular}{r|l}
+Errorcode & Semantics \\ \hline \hline
+0x0000 & Success, new connection \\ \hline
+0x0001 & Success, connection already existed \\ \hline
+0x0002 & Success, legacy handover \\ \hline \hline
+0x0100 & Failure, unsupported mode \\ \hline
+0x0101 & Failure, unpaired HIT \\ \hline
+0x0102 & Failure, expired HIT \\ \hline
+0x0103 & Failure, no free resources \\ \hline
+\end{tabular}
+\end{center}
+
+The server IPv4 field must be set to the PISA server's own PISA address.
+The client IPv4 field must be set to the PISA client's virtual address in the
server's PISA address space.
+
+\textbf{TODO: Verify if both IPv4 addresses are only relevant for the relay
connection type.}
+
\paragraph{Heartbeat}
+The heartbeat packet is sent by a PISA client to keep the connection alive and
ensure the PISA server still answers.
+No additional data is appended after the PISA header.
+
\paragraph{Heartbeat ACK}
+The heartbeat ACK packet is sent by a PISA server as a response to a heartbeat
packet, if the connection on the server side is in state established.
+No additional data is appended after the PISA header.
+
\paragraph{De-Register}
+This packet is sent by a PISA client to close the connection and free all NAT
mappings associated with that connection.
+No additional data is appended after the PISA header.
+
\paragraph{De-Register ACK}
-\paragraph{Data}
-Unused, was obsoleted by using two separate UDP-Ports to multiplex control and
data packets.
-\paragraph{UNKNOWN HIT ?}
-Unused, intention unknown.
+This packet is sent by a PISA server as a response to a De-Register packet
after all state associated with that connection has been removed.
+No additional data is appended after the PISA header.
+
+\paragraph{Legacy Handover IND}
+A legacy handover indication is sent by the PISA server to the old legacy
router of the legacy client.
+This is necessary, because the old legacy router otherwise would not
re-register the NAT mapping for the legacy client if another handover back to
the old legacy router occurs.
+
+\subsection{Data Channel}
\section{Protocol Workflows}
--
This is the pisa developer mailing list. Please also subscribe to the main pisa
list at:
//www.freelists.org/list/pisa
Other related posts:
- » [pisa-src] r2427 - docs/protocol_spec/application.tex - Thomas Jansen
