vowifi-sms

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 17 Open GitHub ↗

VoWiFi (IMS/ePDG) client for receiving SMS over IMS

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# vowifi-sms
> Minimal VoWiFi/IMS client for receiving SMS over Wi-Fi using a physical USIM (PC/SC).

This client performs SIP registration to an IMS network with AKA (AKAv1-MD5) authentication via a physical USIM.  
Typical use case: establish IMS access over ePDG (SWu, IPsec) and run this client inside the corresponding network namespace or interface to receive SMS without a phone.

Reference guide for ePDG tunnel setup (strongSwan / SWu, IMS / VoWiFi):
**“VoWiFi with Asterisk” by Osmocom** — [osmocom.org/projects/foss-ims-client/wiki/VoWiFi_with_Asterisk](https://osmocom.org/projects/foss-ims-client/wiki/VoWiFi_with_Asterisk)

---

## Requirements
- Linux with XFRM support (`iproute2`) and IPv6  
- Go 1.21+ (recommended)  
- PC/SC stack: `pcscd`, `libpcsclite` / `libpcsclite-dev`, USB reader, and USIM  
- `tcpdump` (optional, required only when using `-d`)

Example for Debian/Ubuntu:
```bash
sudo apt update
sudo apt install -y golang iproute2 pcscd libpcsclite-dev pcsc-tools tcpdump
sudo systemctl enable --now pcscd
```

---

## Build or run
To build:
```bash
go build -o sip-client .
```

To run directly:
```bash
sudo ip netns exec ims go run . -p <PCSCF_IPV6>
```

---

## How it works (short)
1. Read IMSI and MNC length from the USIM via PC/SC.  
2. Send initial `REGISTER` (TCP/5060 to P-CSCF) with an empty `Authorization` header and proposed local SPI/ports in `Security-Client`.  
3. Receive `401 Unauthorized` with `WWW-Authenticate` (RAND/AUTN) and `Security-Server`.  
4. Perform AKA authentication (AKAv1-MD5).  
5. Configure XFRM policies for the negotiated client/server ports and SPI.  
6. Re-`REGISTER` over secured TCP (s-port, IPsec-protected) with `Security-Verify` → receive `200 OK`.  
7. Wait for incoming SIP `MESSAGE` packets containing SMS payloads.

---

## Connecting to ePDG (strongSwan / SWu)
This client requires an active SWu tunnel to the ePDG and a local IPv6 address on the interface `tun23` (preferably inside the `ims` namespace).  
The ePDG FQDN is derived from MCC/MNC as:  
```
epdg.epc.mncYYY.mccXXX.pub.3gppnetwork.org
```
(MNC and MCC are three-digit, zero-padded.)

Example:
```bash
dig epdg.epc.mnc001.mcc262.pub.3gppnetwork.org
```

You can read the IMSI using `pySim` or `pcsc-tools`.  
See the Osmocom guide: [VoWiFi with Asterisk](https://osmocom.org/projects/foss-ims-client/wiki/VoWiFi_with_Asterisk).

---

### Option A (recommended): strongSwan
Stable and scalable. Note: official strongSwan packages do **not** include native USIM/PCSC authentication — use the fork/branch referenced in the Osmocom guide.

Steps:
- Install or build strongSwan with USIM (PCSC) support — see “Option 2 → Install strongSwan” in the Osmocom guide.  
- Configure an SWu/IKEv2 profile for `epdg.epc.mncYYY.mccXXX.pub.3gppnetwork.org` using EAP-AKA (IMSI).  
- Use an up/down script to operate within a namespace and bind a virtual interface named `tun23` inside `ims` (the guide provides an example).  
- Start the connection and verify that `tun23` has an IPv6 address inside `ims`.

**Important:** strongSwan does not create network namespaces automatically — use an up/down script for that.  
Either name the interface `tun23` or modify the interface name in the code before building.

---

### Option B (simpler but less reliable; not compatible with all operators): SWu-IKEv2 (Python)
This method is easier to set up, but the tunnel may drop when idle and supports only one connection per IP address.

Steps:
- Clone [SWu-IKEv2](https://github.com/fasferraz/SWu-IKEv2), create a virtual environment, and install dependencies.  
- In `swu_emulator.py`, change the TUN name to `tun23`:  
  ```python
  self.tunnel = self.open_tun(23)
  ```
  (replace any existing reference to `open_tun(1)`).
- Run with correct MCC/MNC values (3 digits, MNC left, MCC right in the FQDN), always inside a namespace.

Example:
```bash
python3 swu_emulator.py -m0 -a ims -I 310240xxxxxxxxx -M 310 -N 240 -n i1 -d epdg.epc.mnc240.mcc310.pub.3gppnetwork.org
```

---

## Running the client
1. Ensure `tun23` has an IPv6 address inside the `ims` namespace:
```bash
sudo ip netns exec ims ip -6 addr show dev tun23
```

2. Find the P-CSCF IPv6 address — usually discovered via SRV/NAPTR for  
`ims.mncYYY.mccXXX.3gppnetwork.org`, or extracted from registration traces (`Path` header in the `401` response).

3. Start the client (inside the same namespace):
```bash
sudo ip netns exec ims ./sip-client -p <PCSCF_IPV6>
```
Where `-p` is the P-CSCF IPv6 address (no brackets, no port).  
The `-d` flag enables verbose logging and ESP packet capture.

When an SMS arrives, the client will:
- Send `200 OK` in response to the incoming SIP `MESSAGE`.  
- Decode the sender number and message text and print them to stdout.

---

## Debugging
- Use `-d` for verbose logs and automatic ESP packet capture (`ipsec_<ports>_<timestamp>.pcap`).  
- Verify that `pcscd` is running and the reader is visible using `pcsc_scan`.  
- Check `ip -6 xfrm state` and `ip -6 xfrm policy` for the expected SPI and port pairs after step 5.

vowifi-sms

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README