lynxis lazus has uploaded this change for review. ( 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/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" ]; +}