laforge has submitted this change. ( https://gerrit.osmocom.org/c/erlang/osmo-epdg/+/36783?usp=email )
Change subject: docs: add basic manual of the osmo-epdg ......................................................................
docs: add basic manual of the osmo-epdg
Change-Id: I596b6a351b7356aefa7e69f95521bc4012b9264b --- A docs/manuals/Makefile 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/osmoepdg-usermanual-docinfo.xml A docs/manuals/osmoepdg-usermanual.adoc A docs/manuals/strongswan-ue-connection.msc A docs/manuals/ue-connects.msc A docs/manuals/ue-connects2.msc 11 files changed, 458 insertions(+), 0 deletions(-)
Approvals: laforge: Looks good to me, approved pespin: Looks good to me, but someone else must approve Jenkins Builder: Verified
diff --git a/docs/manuals/Makefile b/docs/manuals/Makefile new file mode 100644 index 0000000..36f64b5 --- /dev/null +++ b/docs/manuals/Makefile @@ -0,0 +1,13 @@ +# A simplistic Makefile to use without autoconf +# +# Install osmo-gsm-manuals or use `export OSMO_GSM_MANUALS_DIR=/path/to/osmo-gsm-manuals` + +OSMO_GSM_MANUALS_DIR ?= /usr/share/osmo-gsm-manuals/ +srcdir ?= $(realpath .) + +ASCIIDOC = osmoepdg-usermanual.adoc +ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc $(srcdir)/*.dot $(srcdir)/*.msc +include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc + +OSMO_REPOSITORY = osmo-epdg +include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc diff --git a/docs/manuals/chapters/osmo-epdg.adoc b/docs/manuals/chapters/osmo-epdg.adoc new file mode 100644 index 0000000..9318fcd --- /dev/null +++ b/docs/manuals/chapters/osmo-epdg.adoc @@ -0,0 +1,96 @@ +[[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 distributions, Osmocom provides package 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 + +The CEIA is the internal protocol between strongSwan and osmo-epdg/erlang. +See [CEIA] + +[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..c8cce9d --- /dev/null +++ b/docs/manuals/chapters/overview.adoc @@ -0,0 +1,73 @@ +[[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. +Furthermore, osmo-epdg speaks with strongSwan to handle communication towards UEs. +Both components communicate over the internal protocol CEIA based on GSUP. + +=== Components of the osmo-epdg + +The combined osmo-epdg consist of: + +* strongSwan (IKEv2/ESP) +* osmo-epdg/erlang (state handling, communication with other core components) +* Linux kernel (policy routing, firewall, gtp, esp for user-plane traffic) + +==== strongSwan + +strongSwan is a FOSS IPSec daemon developed by the strongSwan community. +strongSwan has been extended and modified to allow the osmo-epdg/erlang component to +control UE sessions, pass authentication, authorisation and configuration. + +See <<strongswan>> for further information. + +===== Interfaces of 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 + +The osmo-epdg/erlang daemon is the core of the combined ePDG and AAA. +It communicates to all relevant core components and control UE sessions of the strongSwan over the CEIA protocol. + +===== Interfaces of osmo-epdg/erlang + +* 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 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 +- [[[ieft-rfc-4555]]] IETF RFC 4555: IKEv2 Mobility and Multihoming Protocol (MOBIKE) +- [[[ieft-rfc-5996]]] IETF RFC 5996: Internet Key Exchange Protocol Version 2 (IKEv2) diff --git a/docs/manuals/chapters/strongswan.adoc b/docs/manuals/chapters/strongswan.adoc new file mode 100644 index 0000000..8828ed9 --- /dev/null +++ b/docs/manuals/chapters/strongswan.adoc @@ -0,0 +1,46 @@ +[[strongswan]] +== strongSwan + +strongSwan is a free software implementation of IPsec, it is developed +by the strongSwan community. +strongSwan has been extended and modified to allow the osmo-epdg/erlang component to +control UE sessions, pass authentication, authorisation and configuration. + +The modified strongSwan can be found at https://gitea.osmocom.org/ims-volte-vowifi/strongswan + +Example configuration for strongSwan can be found under https://gitea.osmocom.org/ims-volte-vowifi/ansible-prototype + +=== Concept of strongSwan within osmo-epdg + +The main role of strongSwan in the osmo-epdg is terminating SWu traffic (IKEv2 and ESP) of UEs. +strongSwan will also handle EAP traffic, as part of an AAA component. +The osmo-epdg/erlang component is the core of the osmo-epdg and the primary source of the truth. +For this reason strongSwan should keep as 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 it. Authentication, authorisation, configuration are communicated +over the CEIA. + +In the default configuration of osmo-epdg, strongSwan will use Linux kernel to handle ESP to +achieve high performance on the user-plane. +The Linux kernel will decrypt, decapsulate and forward traffic towards GTP tunnels. + +=== 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 +- Terminate UE sessions request by HSS (SWu) + +The initial connection of GSUP is done by strongSwan (client) towards +the osmo-epdg/erlang (server). +The protocol is re-using already defined PDU and messages of GSUP. +The default configuration will use TCP/IPA port 4222. + diff --git a/docs/manuals/osmo-epdg-erlang.dot b/docs/manuals/osmo-epdg-erlang.dot new file mode 100644 index 0000000..232451a --- /dev/null +++ b/docs/manuals/osmo-epdg-erlang.dot @@ -0,0 +1,31 @@ +digraph G { + node [shape=rect]; + rankdir=LR; + + eUE; + + subgraph cluster1 { + label="osmo-epdg (combined ePDG/AAA)"; + + { rank=same; strongswan; osmoepdg;} + osmoepdg [label="osmo-epdg/erlang"; color="blue"]; + } + + subgraph cluster2 { + rankdir=LR; + label="epc"; + + { rank=same; HSS; PGW; PCRF; } + PCRF -> PGW [dir="both"]; + } + + eUE -> strongswan [label="SWu (ePDG)", dir="both"]; + strongswan -> osmoepdg [label="CEIA/GSUP", dir="both"]; + osmoepdg -> HSS [label="SWx (AAA)", dir="both"]; + osmoepdg -> PGW [label="S2b (ePDG)", dir="both", weight=100]; + PGW -> ims [label="IPv4/IPv6", dir="both"]; + PGW -> osmoepdg [label="S6b (AAA)", dir="both"]; + + eUE -> ims [label="IPv4/IPv6 (tunnel)", style=dotted, weight=-1]; +} + diff --git a/docs/manuals/osmo-epdg-overview.dot b/docs/manuals/osmo-epdg-overview.dot new file mode 100644 index 0000000..6773946 --- /dev/null +++ b/docs/manuals/osmo-epdg-overview.dot @@ -0,0 +1,32 @@ +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/erlang"]; + } + + subgraph cluster2 { + rankdir=LR; + label="epc"; + + { rank=same; HSS; PGW; PCRF; } + PCRF -> PGW [dir="both"]; + } + + eUE -> strongswan [label="SWu (ePDG)", dir="both"]; + strongswan -> osmoepdg [label="CEIA/GSUP", dir="both"]; + osmoepdg -> HSS [label="SWx (AAA)", dir="both"]; + osmoepdg -> PGW [label="S2b (ePDG)", dir="both", weight=100]; + PGW -> ims [label="IPv4/IPv6", dir="both"]; + PGW -> osmoepdg [label="S6b (AAA)", dir="both"]; + + eUE -> ims [label="IPv4/IPv6 (tunnel)", style=dotted, weight=-1]; +} + diff --git a/docs/manuals/osmoepdg-usermanual-docinfo.xml b/docs/manuals/osmoepdg-usermanual-docinfo.xml new file mode 100644 index 0000000..7b96d81 --- /dev/null +++ b/docs/manuals/osmoepdg-usermanual-docinfo.xml @@ -0,0 +1,46 @@ +<revhistory> + <revision> + <revnumber>1</revnumber> + <date>April 23, 2024</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/osmoepdg-usermanual.adoc b/docs/manuals/osmoepdg-usermanual.adoc new file mode 100644 index 0000000..05eb6b0 --- /dev/null +++ b/docs/manuals/osmoepdg-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..0517b11 --- /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..1f31a8b --- /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" ]; +}