lynxis lazus has uploaded this change for review.
docs: add basic manual of the osmo-epdg
Change-Id: I596b6a351b7356aefa7e69f95521bc4012b9264b
---
A docs/manuals/chapters/epcrequirements.adoc
A docs/manuals/chapters/osmo-epdg.adoc
A docs/manuals/chapters/overview.adoc
A docs/manuals/chapters/strongswan.adoc
A docs/manuals/osmo-epdg-erlang.dot
A docs/manuals/osmo-epdg-overview.dot
A docs/manuals/osmo-epdg-usermanual-docinfo.xml
A docs/manuals/osmo-epdg-usermanual.adoc
A docs/manuals/strongswan-ue-connection.msc
A docs/manuals/ue-connects.msc
A docs/manuals/ue-connects2.msc
11 files changed, 453 insertions(+), 0 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/erlang/osmo-epdg refs/changes/83/36783/1
diff --git a/docs/manuals/chapters/epcrequirements.adoc b/docs/manuals/chapters/epcrequirements.adoc
new file mode 100644
index 0000000..036b1ff
--- /dev/null
+++ b/docs/manuals/chapters/epcrequirements.adoc
@@ -0,0 +1,18 @@
+[[epcrequirements]]
+== EPC requirements
+
+The osmo-epdg was tested and developed against open5gs (version 2.7.0.83.290df).
+
+=== HSS
+
+When a UE connects it requests an APN via SWu. By default the UE will request
+the APN "ims". The subscriber entry must allow connections to the requested APN to succeed.
+
+=== PGW
+
+The osmo-epdg/erlang expects the PGW to support and use S2b and S6b.
+A UE will request attributes via IKEv2 which are translated into additional PCO in GTP on the S2b
+reference point. THe PGW should support additional PCO via S2b.
+open5gs supports additional PCO by 2.7.1.
+
+osmo-epdg only supports S2b over GTP.
diff --git a/docs/manuals/chapters/osmo-epdg.adoc b/docs/manuals/chapters/osmo-epdg.adoc
new file mode 100644
index 0000000..36c7ee9
--- /dev/null
+++ b/docs/manuals/chapters/osmo-epdg.adoc
@@ -0,0 +1,93 @@
+[[osmoepdg]]
+== osmo-epdg/erlang
+
+The core component of the osmo-epdg is the osmo-epdg/erlang daemon.
+It holds the state of the UE and communicates with the relevant core components.
+
+[[fig-osmo-epdg-erlang]]
+.osmo-epdg/erlang structure
+[graphviz]
+----
+include::{srcdir}/osmo-epdg-erlang.dot[]
+----
+
+=== Debian packages
+
+For Debian based distribution osmocom provides packages repositories:
+
+- https://osmocom.org/projects/cellular-infrastructure/wiki/Latest_Builds
+- https://osmocom.org/projects/cellular-infrastructure/wiki/Nightly_Builds
+
+The osmo-epdg package contains a systemd.service file and a default example configuration.
+
+=== Configuration
+
+The osmo-epdg/erlang is configured via Erlang configuration (https://www.erlang.org/doc/man/config.html).
+When using the osmo-epdg debian package, the default location for the configuration is
+*/etc/osmocom/osmo-epdg.config*.
+
+===== CEIA: Connection for strongSwan
+
+[format="csv",options="header"]
+|===
+key, default, description
+gsup_local_ip, 127.0.0.1, bind IP of the GSUP server (TCP). strongSwan connects to this IP.
+gsup_local_port, 4222, bind TCP server port
+|===
+
+===== SWx (diameter)
+
+SWx (<<3gpp-ts-29-273>>): Interface between AAA and HSS.
+The AAA will retrieve authentication, authorize the UE and
+update the location (AAA, PGW address) in the HSS.
+
+See Erlang diameter specific behaviour on https://www.erlang.org/doc/man/diameter.html
+
+[format="csv",options="header"]
+|===
+key,default,description
+dia_swx_remote_ip, 127.0.0.1, Remote IP of the HSS
+dia_swx_remote_port, 3868, SCTP port of the HSS
+dia_swx_proto, sctp, Protocol. sctp or tcp
+dia_swx_connect_timer, 30000, Watchdog Connect timer in ms. RFC 6733.dia_swx_watchdog_timer, 30000, Watchdog TwInit. RFC 3539.
+dia_swx_watchdog_config, "[ok, suspect]", See https://www.erlang.org/doc/man/diameter.html
+dia_swx_transmit_timer, 10000, SWx Transmit Timeout (ms)
+dia_swx_vendor_id, 0, Diameter Vendor Id
+dia_swx_origin_host, epdg.localdomain, Diameter Origin Host
+dia_swx_origin_realm, localdomain, Diameter Origin Realm
+|===
+
+===== S6b (diameter)
+
+S6b (<<3gpp-ts-29-273>>): Interface between AAA and PGW.
+Authorize the GTP session of the ePDG.
+
+See Erlang diameter specific behaviour on https://www.erlang.org/doc/man/diameter.html
+
+[format="csv",options="header"]
+|===
+key,default,description
+dia_s6b_local_ip, 127.0.0.10, local bind IP
+dia_s6b_local_port, 3868, local bind Port
+dia_s6b_proto, sctp, Protocol. sctp or tcp
+dia_s6b_connect_timer, 30000, Watchdog Connect timer in ms. RFC 6733.
+dia_s6b_watchdog_timer, 30000, Watchdog TwInit. RFC 3539.
+dia_s6b_watchdog_config, "[ok, suspect]", See https://www.erlang.org/doc/man/diameter.html
+dia_s6b_vendor_id, 0, Diameter Vendor Id
+dia_s6b_origin_host, aaa.localdomain, Diameter Origin Host
+dia_s6b_origin_realm, localdomain, Diameter Origin Realm
+|===
+
+===== S2b (GTPv2)
+
+S2b (<<3gpp-ts-29-273>>): Interface between ePDG and PGW.
+GTP control plane for the UE traffic.
+
+[format="csv",options="header"]
+|===
+key,default,description
+gtpc_local_ip, 127.0.0.2, local bind IP
+gtpc_local_port, 2123, local bind Port
+gtpc_remote_ip, 127.0.0.1, remote IP of the PGW
+gtpc_remote_port, 2123, remote port of the PGW
+|===
diff --git a/docs/manuals/chapters/overview.adoc b/docs/manuals/chapters/overview.adoc
new file mode 100644
index 0000000..75a0d02
--- /dev/null
+++ b/docs/manuals/chapters/overview.adoc
@@ -0,0 +1,61 @@
+[[overview]]
+== Overview
+
+This manual should help you getting started with osmo-epdg. It will cover
+aspects of configuring and running the osmo-epdg.
+
+[[intro_overview]]
+=== About osmo-epdg
+
+osmo-epdg is a combined ePDG (Evolved Packet Data Gateway) and AAA (Authorization, Authentication, Accounting).
+The ePDG is used by an UE to connect via an untrusted non-3GPP access network towards the PGW to allow
+VoWifi (Voice over Wifi).
+
+The UE will establish a tunnel using IPSec (IKEv2 and ESP) towards the ePDG (SWu interface).
+The ePDG will authenticate and authorize the UE by using an AAA and will forward the traffic from the UE towards
+a PGW.
+
+[[fig-osmo-epdg-overview]]
+.`osmo-epdg` structure
+[graphviz]
+----
+include::{srcdir}/osmo-epdg-overview.dot[]
+----
+
+The core of the osmo-epdg is the erlang daemon (osmo-epdg/erlang).
+It communicates with core components by 3GPP protocols and contains the state of UEs.
+Further the osmo-epdg is using strongSwan to handle the communication towards UEs.
+Both components communicate over the internal protocol CEIA based on GSUP.
+
+=== Components of the osmo-epdg
+
+* strongSwan (IKEv2/ESP)
+* osmo-epdg (state handling, communication with other core components)
+* Linux generic policy routing and firewall (user plane)
+
+=== Interfaces of the osmo-epdg
+
+==== strongSwan
+
+* SWu: IPsec/IKEv2 towards the UE.
+* netlink: with the Linux kernel to encrypt and decrypt ESP traffic.
+* CEIA: internal communication to osmo-epdg/erlang to forward authentication and state based on GSUP.
+
+==== osmo-epdg/erlang
+
+Interface to other core components. In round brackets the represented core component of the osmo-epdg side.
+
+* SWx: with HSS for authentication, authorisation, accounting (AAA)
+* S2b: with PGW to create GTP session (ePDG)
+* S6b: with PGW for authorisation of a GTP session (AAA)
+* netlink: with the Linux kernel to create GTP tunnels (ePDG)
+* CEIA: internal communication to osmo-epdg/erlang to forward authentication and state based on GSUP. (ePDG/AAA)
+
+==== Relevant 3gpp specifications
+
+- [[[3gpp-ts-23-402]]] 3GPP TS 23.402 Architecture enhancements for non-3GPP accesses
+- [[[3gpp-ts-24-302]]] 3GPP TS 24.302 Architecture enhancements for non-3GPP accesses
+- [[[3gpp-ts-29-273]]] 3GPP TS 29.273: 3GPP EPS AAA interfaces
+- [[[3gpp-ts-20-274]]] 3GPP TS 29.274: Tunnelling Protocol for Control plane (GTPv2-C)
+- [[[3gpp-ts-33-402]]] 3GPP TS 33.402: Security aspects of non-3GPP accesses
+
diff --git a/docs/manuals/chapters/strongswan.adoc b/docs/manuals/chapters/strongswan.adoc
new file mode 100644
index 0000000..6a06eec
--- /dev/null
+++ b/docs/manuals/chapters/strongswan.adoc
@@ -0,0 +1,58 @@
+[[strongswan]]
+== strongSwan
+
+strongSwan is a free software implementationo of IPsec.
+It can support multiple different IPsec standards.
+osmo-epdg is using strongSwan to terminate SWu (IKEv2 and ESP) traffic.
+
+strongSwan has been extended to support this role in the osmo-epdg.
+
+Example configuration for strongSwan can be found under https://gitea.osmocom.org/ims-volte-vowifi/ansible-prototype
+
+=== Concept of strongSwan within osmo-epdg
+
+strongSwan will be used as interface towards SWu (IKEv2 and ESP).
+The osmo-epdg/erlang component is the core and the primary source of the truth.
+strongSwan should keep a little state as possible while osmo-epdg/erlang keeps the full state.
+
+strongSwan/osmo-epdg and osmo-epdg/erlang communicates via the CEIA (Charon External AKA Interface)
+and share state over this protocol.
+CEIA is implemented on top of GSUP based on TCP port 4222.
+
+strongSwan will handle and terminate EAP traffic instead of forwarding this towards
+a AAA core component. It will request authentication quintlet via CEIA.
+Further strongSwan handles IKEv2 traffic and communicates with the Linux kernel to handle
+the ESP (user-plane) traffic. The Linux kernel will decrypt, decapsulate and forward traffic
+towards GTP tunnels.
+
+It is possible to modify the given configuration example to change or extend certain aspects
+of the usage of strongSwan. But the example configuration is expected as given for this chapter.
+
+=== CEIA (Charon External AKA Interface)
+
+The Charon External AKA interface is used by strongSwan/osmo-epdg to communicate
+with osmo-epdg/erlang.
+It is based on GSUP (https://ftp.osmocom.org/docs/osmo-hlr/master/osmohlr-usermanual.pdf)
+
+strongSwan/osmo-epdg is using the CEAI to:
+
+- authenticate UEs
+- authorize UEs
+- prepare user plane to forward traffic
+- notify about termination of UEs
+
+Further it allows the osmo-epdg/erlang to:
+
+- terminate UE sessions (SWu)
+
+The initial connection of GSUP is done by strongSwan/osmo-epdg (client) towards
+the osmo-epdg/erlang (server).
+The protocol is re-using already defined PDU and messages of GSUP.
+
+==== UE connecting
+
+[mscgen]
+----
+include::{srcdir}/strongswan-ue-connection.msc[]
+----
+
diff --git a/docs/manuals/osmo-epdg-erlang.dot b/docs/manuals/osmo-epdg-erlang.dot
new file mode 100644
index 0000000..a3d8872
--- /dev/null
+++ b/docs/manuals/osmo-epdg-erlang.dot
@@ -0,0 +1,28 @@
+digraph G {
+ node [shape=rect];
+ rankdir=LR;
+
+ eUE;
+
+ subgraph cluster1 {
+ color=black;
+ label="osmo-epdg (combined epdg/AAA)";
+
+ { rank=same; strongswan; osmoepdg;}
+ osmoepdg [label="osmo-epdg/erlang"; color="blue"];
+ }
+
+ subgraph cluster2 {
+ label="epc";
+ hss;
+ pgw;
+ }
+
+ eUE -> strongswan [label="IKEv2/ESP", dir="both"];
+ strongswan -> osmoepdg [label="CEIA/GSUP", dir="both"];
+ osmoepdg -> hss [label="SWx (AAA)", dir="both"];
+ osmoepdg -> pgw [label="S2b (ePDG)", dir="both"];
+ pgw -> ims [label="IPv4/IPv6", dir="both"];
+ pgw -> osmoepdg [label="S6b (AAA)", dir="both"];
+}
+
diff --git a/docs/manuals/osmo-epdg-overview.dot b/docs/manuals/osmo-epdg-overview.dot
new file mode 100644
index 0000000..74dce89
--- /dev/null
+++ b/docs/manuals/osmo-epdg-overview.dot
@@ -0,0 +1,28 @@
+digraph G {
+ node [shape=rect];
+ rankdir=LR;
+
+ eUE;
+
+ subgraph cluster1 {
+ color=blue;
+ label="osmo-epdg (combined ePDG/AAA)";
+
+ { rank=same; strongswan; osmoepdg;}
+ osmoepdg [label="osmo-epdg"];
+ }
+
+ subgraph cluster2 {
+ label="epc";
+ hss;
+ pgw;
+ }
+
+ eUE -> strongswan [label="IKEv2/ESP", dir="both"];
+ strongswan -> osmoepdg [label="CEIA/GSUP", dir="both"];
+ osmoepdg -> hss [label="SWx (AAA)", dir="both"];
+ osmoepdg -> pgw [label="S2b (ePDG)", dir="both"];
+ pgw -> ims [label="IPv4/IPv6", dir="both"];
+ pgw -> osmoepdg [label="S6b (AAA)", dir="both"];
+}
+
diff --git a/docs/manuals/osmo-epdg-usermanual-docinfo.xml b/docs/manuals/osmo-epdg-usermanual-docinfo.xml
new file mode 100644
index 0000000..6216b3c
--- /dev/null
+++ b/docs/manuals/osmo-epdg-usermanual-docinfo.xml
@@ -0,0 +1,46 @@
+<revhistory>
+ <revision>
+ <revnumber>1</revnumber>
+ <date>April 23, 2014</date>
+ <authorinitials>AC</authorinitials>
+ <revremark>
+ Initial version.
+ </revremark>
+ </revision>
+</revhistory>
+
+<authorgroup>
+ <author>
+ <firstname>Alexander</firstname>
+ <surname>Couzens</surname>
+ <email>acouzens@sysmocom.de</email>
+ <authorinitials>AC</authorinitials>
+ <affiliation>
+ <shortaffil>sysmocom</shortaffil>
+ <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+ <jobtitle>Developer</jobtitle>
+ </affiliation>
+ </author>
+</authorgroup>
+
+<copyright>
+ <year>2024</year>
+ <holder>sysmocom - s.f.m.c. GmbH</holder>
+</copyright>
+
+<legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with no Invariant Sections, no Front-Cover Texts,
+ and no Back-Cover Texts. A copy of the license is included in
+ the section entitled "GNU Free Documentation License".
+ </para>
+ <para>
+ The Asciidoc source code of this manual can be found at
+ <ulink url="https://gitea.osmocom.org/erlang/osmo-epdg">
+ https://gitea.osmocom.org/erlang/osmo-epdg
+ </ulink>
+ </para>
+</legalnotice>
diff --git a/docs/manuals/osmo-epdg-usermanual.adoc b/docs/manuals/osmo-epdg-usermanual.adoc
new file mode 100644
index 0000000..05eb6b0
--- /dev/null
+++ b/docs/manuals/osmo-epdg-usermanual.adoc
@@ -0,0 +1,14 @@
+:gfdl-enabled:
+:program-name: osmo-epdg
+
+osmo-ePDG User Manual
+=====================
+Alexander Couzens <acouzens@sysmocom.de>
+
+
+include::{commondir}/chapters/preface.adoc[]
+
+include::{srcdir}/chapters/overview.adoc[]
+
+include::{srcdir}/chapters/strongswan.adoc[]
+include::{srcdir}/chapters/osmo-epdg.adoc[]
diff --git a/docs/manuals/strongswan-ue-connection.msc b/docs/manuals/strongswan-ue-connection.msc
new file mode 100644
index 0000000..02d366b
--- /dev/null
+++ b/docs/manuals/strongswan-ue-connection.msc
@@ -0,0 +1,31 @@
+msc {
+ hscale = 2;
+ UE,
+ sswan [label="strongSwan"],
+ ePDG [label="osmo-epdg/erlang"],
+ PGW,
+ HSS;
+
+ UE <=> sswan [label="IKE: SA_INIT"];
+ UE => sswan [label="IKE: AUTH_REQ (IDi=NAI, IDr=APN, CFG Req)"];
+ sswan => ePDG [label="GSUP: Send Auth Information Req (NAI, APN)"];
+ ePDG => HSS [label="SWx MAR (Multimedia Authentication Request)"];
+ ePDG <= HSS [label="SWx MAA (Multimedia Authentication Answer)"];
+ sswan <= ePDG [label="GSUP: Send Auth Information Res (Quintlet)"];
+ UE <= sswan [label="IKE: AUTH_RESP (EAP-Request/AKA-Challenge)"];
+ UE => sswan [label="IKE: AUTH_REQ (EAP-Request/AKA-Response)"];
+ sswan => ePDG [label="GSUP: Location Update Req"];
+ ePDG => HSS [label="SWx SAR (Server Assignment Request)"];
+ ePDG <= HSS [label="SWx SAA (Server Assignment Answer)"];
+ sswan <= ePDG [label="GSUP: Location Update Res"];
+ UE <= sswan [label="IKE: AUTH_RESP (EAP Success)"];
+ UE => sswan [label="IKE: AUTH_REQ"];
+ sswan => ePDG [label="GSUP: Tunnel Req"];
+ ePDG => PGW [label="S2b: Create Session Request"];
+ ePDG => HSS [label="SWx SAR (Server Assignment Request)"];
+ ePDG <= HSS [label="SWx SAA (Server Assignment Answer)"];
+ ePDG <= PGW [label="S2b: Create Session Answer"];
+ sswan <= ePDG [label="GSUP: Tunnel Res"];
+ UE <= sswan [label="IKE: AUTH_RESP (CFG Reply)"];
+ UE <=> sswan [label="IPSEC SA"];
+}
diff --git a/docs/manuals/ue-connects.msc b/docs/manuals/ue-connects.msc
new file mode 100644
index 0000000..4ff38c5
--- /dev/null
+++ b/docs/manuals/ue-connects.msc
@@ -0,0 +1,35 @@
+# UE/ePDG/AAA/HSS/PGW
+msc {
+ hscale = 2;
+ UE, ePDG [label="osmo-epdg (ePDG/AAA)"], HSS, PGW;
+
+ UE => ePDG [ label="IKE SA INIT" ];
+ UE <= ePDG [ label="IKE SA INIT" ];
+
+ UE => ePDG [ label="IKE Auth Req (IDi=APN, IDr=NAI); TS; CFG (P-CSCF, IP, DNS)" ];
+ ePDG => HSS [ label="SWx Multimedia Auth Request (APN, NAI)" ];
+ ePDG <= HSS [ label="SWx Multimedia Auth Answer (APN, NAI)" ];
+ UE <= ePDG [ label="IKE Auth Resp (EAP AKA: Autn, Rand)" ];
+ UE => ePDG [ label="IKE Auth Req (EAP AKA: Res)" ];
+
+ ePDG => HSS [ label="SWx Server Assignment Request (APN, NAI)"];
+ ePDG <= HSS [ label="SWx Server Assignment Answer (APN, NAI)"];
+ UE <= ePDG [ label="IKE Auth Resp (EAP: Success)" ];
+
+--- [ label="UE authenticated" ];
+
+ UE => ePDG [ label="IKE Auth Req" ];
+
+ ePDG => PGW [ label="S2b Create Session Request (PCO: P-CSCF, IP, DNS)" ];
+ ePDG <= PGW [ label="S6b Authentication/Authorization Request" ];
+
+ ePDG => HSS [ label="SWx Server Assignment Request (APN, NAI)"];
+ ePDG <= HSS [ label="SWx Server Assignment Answer (APN, NAI)"];
+
+ ePDG => PGW [ label="S6b Authentication/Authorization Answer" ];
+ ePDG <= PGW [ label="S2b Create Session Answer (PCO: P-CSCF, IP, DNS)" ];
+
+ UE <= ePDG [ label="IKE Auth Resp" ];
+
+--- [ label="Tunnel established" ];
+}
diff --git a/docs/manuals/ue-connects2.msc b/docs/manuals/ue-connects2.msc
new file mode 100644
index 0000000..8eaefc3
--- /dev/null
+++ b/docs/manuals/ue-connects2.msc
@@ -0,0 +1,32 @@
+# UE/ePDG/AAA/HSS?PGW
+msc {
+ UE, ePDG [label="osmo-epdg (ePDG/AAA)"], HSS, PGW;
+
+ UE => ePDG [ label="IKE SA INIT" ];
+ UE <= ePDG [ label="IKE SA INIT" ];
+
+ UE => ePDG [ label="IKE Auth Req (APN, NAI)" ];
+ ePDG => HSS [ label="SWx Multimedia Auth Request (APN, NAI)" ];
+ ePDG <= HSS [ label="SWx Multimedia Auth Answer (APN, NAI)" ];
+ UE <= ePDG [ label="IKE Auth Resp (EAP AKA: Autn, Rand)" ];
+ UE => ePDG [ label="IKE Auth Req (EAP AKA: Res)" ];
+
+ ePDG => HSS [ label="SWx Server Assignment Request (APN, NAI)"];
+ ePDG <= HSS [ label="SWx Server Assignment Answer (APN, NAI)"];
+ UE <= ePDG [ label="IKE Auth Resp (EAP: Success)" ];
+
+ UE => ePDG [ label="IKE Auth Req" ];
+ UE <= ePDG [ label="IKE Auth Resp" ];
+
+--- [ label="IKE SA estabilished" ];
+
+ UE => ePDG [ label="IKE Create Child SA" ];
+ ePDG => PGW [ label="S2b Create Session Request" ];
+ ePDG <= PGW [ label="S6b Authentication/Authorization Request" ];
+
+ ePDG => HSS [ label="SWx Server Assignment Request (APN, NAI)" ];
+ ePDG <= HSS [ label="SWx Server Assignment Answer (APN, NAI)" ];
+
+ ePDG => PGW [ label="S6b Authentication/Authorization Answer" ];
+ ePDG <= PGW [ label="S2b Create Session Answer" ];
+}
To view, visit change 36783. To unsubscribe, or for help writing mail filters, visit settings.