eSIM

Overview

SIM card is commonly used to identify subscriber on a mobile service provider, eSIM is an evolution of SIM card and allows multiple profiles to be stored on the same physical chip, and the user can switch between those profiles any time they want.

On newer devices the eSIM chip (eUICC) is soldered onto the logic board and is not user removable. eSIM adapters package eSIM chip into standard SIM form factor and allow devices without builtin eSIM chip (e.g. laptop with USB modem, older phone without eUICC) to use eSIM profiles.

Profiles stored inside the eSIM chip can persist OS re-installation, and on a given device, profiles installed from Android should transparently be usable from Debian, vice versa.

Glossary

APN: Access Point Name, default gateway for internet access over cellular network

eUICC: Embedded Universal Integrated Circuit Card, the actual hardware chip that stores the eSIM profiles, it can do other things too.

eSIM: Embedded Subscriber Identity Module

LPA: Local Profile Assistant, a program running on the phone to download and manage eSIM profiles, lpac(1) is the most common one on Linux

QMI: Qualcomm MSM Interface, see https://wiki.postmarketos.org/wiki/QMI

QRTR: Qualcomm IPC Router, used for the main OS to communicate with built in modem

Provision

Preparation

1. Install lpac and configure it to use the correct driver：

Most qcom devices use QMI-QRTR backend for eSIM management, and use slot 1 for physical SIM and slot 2 for eSIM.

Adjust the backend protocol based on your hardware, see a list of supported backend here: https://github.com/estkme-group/lpac/tree/main/docs/backends 

$ alias lpac="sudo LIBEUICC_DEBUG_APDU=true LPAC_APDU_QMI_UIM_SLOT=2 LPAC_APDU=qmi_qrtr /usr/bin/lpac"

A work-in-progress package for lpac is available from https://salsa.debian.org/erebion/lpac

2. Check if an eSIM chip is available: 

$ lpac chip info | jq
{
  "type": "lpa",
  "payload": {
    "code": 0,
    "message": "success",
    "data": {
...

There should also be a list of capability like this: 

        "uiccCapability": [
          "usimSupport",
          "isimSupport",
          "csimSupport",
          "akaMilenage",
          "akaCave",
          "akaTuak128",
          "akaTuak256",
          "gbaAuthenUsim",
          "gbaAuthenISim",
          "eapClient",
          "javacard",
          "multipleUsimSupport",
          "multipleIsimSupport",
          "multipleCsimSupport"
        ],

Obtaining an eSIM profile

3. Sign up for a mobile plan with eSIM support, get an activation link in the format of LPA:1$isp.rsp.server.example.tld$XXXXXXXXXXXXXXXXXXXX, scan the QRcode to obtain this string if manual activation is not an option.

4. Make sure the device is connected to the internet to download eSIM profile, then use lpac to download it and pass in the IMEI with -i. 

$ mmcli -m any  | grep imei #find IMEI
$ lpac profile download -i <IMEI> -a 'LPA:1$isp.rsp.server.example.tld$XXXXXXXXXXXXXXXXXXXX'

In the end there should be something like {"type":"lpa","payload":{"code":0,"message":"success","data":null}} in the output.

To check the profile is enabled and operational, run $ lpac profile list | jq and there should be something similar to 

{
  "type": "lpa",
  "payload": {
    "code": 0,
    "message": "success",
    "data": [
      {
        "iccid": "XXX",
        "isdpAid": "XXX",
        "profileState": "enabled",
        "profileNickname": null,
        "serviceProviderName": "XXX",
        "profileName": "XXX",
        "iconType": null,
        "icon": null,
        "profileClass": "operational"
      }
    ]
  }
}

Management

# list known profiles, show iccid for each profile
$ lpac profile list
# enable a profile
$ lpac profile enable <iccid>
# disable a profile
$ lpac profile disable <iccid>
# delete a profile, need to disable it first
$ lpac profile delete <iccid>
# list notification messages
$ lpac notification list

Configure APN

Remember to configure APN according to your ISP, automatic APN discovery might not be accurate especially for roaming eSIM providers.

Make sure to enable roaming when using a roaming provider, otherwise APN won't apply even if packet service is attached.

Transfer eSIM between devices

Some ISP allow transferring eSIM between devices without explicit re-issuance, the existing profile needs to first be deleted, and the ISP notified about the deletion, before the activation link/QR code can be reused. This process is near instant.

If the old eSIM profile exists on an iOS/Android device, delete it while connected to WiFi and that should be enough for the ISP to release the profile for reuse.

If the old eSIM profile exists on a Debian device, do this: 

# list known profiles, find the iccid to be transferred 
$ lpac profile list | jq
# disable that profile
$ lpac profile disable <iccid> | jq
# delete that profile
$ lpac profile delete <iccid> | jq
# find the seqNumber of the disable and delete message of the corresponding iccid (e.g. 3 and 4)
$ lpac notification list | jq
# send proof of deletion to the ISP to release the profile for reuse
$ lpac notification process <seqNumber_disable> <seqNumber_delete>

Now it should be possible to activate the same profile again on a new device.

Supported devices

- ?FairPhone5 (Specific modem firmware version required, see note below)

- Pixel3a/3aXL (Should work but untested, the Japanese version won't do eSIM)

Physical eSIM / eSIM adapter

For devices that lack a built-in eSIM chip (such as older phones, USB LTE dongles, or Linux phones like the ?PinePhone and Librem 5), you can use a physical eSIM adapter. These are essentially standard eUICC chips embedded into traditional removable SIM card form factors and allow you to download and use eSIM profiles like a built-in eSIM, and can be swapped between devices. A SIM card reader is required to download and manage profiles on them.

eSIM adapter vendors

Name

Storage Space

Tested with

Notes

Known Providers

/!\ Some providers charge extra for issuing profiles

Name

APN

Tested with

Notes

Roamless

Name: Roamless
APN: roamless

?FairPhone5, with Optus in Australia

- PAYG, Free unlimited re-issuance via support chat.
- Requires proprietary app for issuance and registration

Known Problems

- Fairphone5: firmware version

MPSS.HI.4.3.3.c6-00206.1-KODIAK_GEN_PACK-1.65385.5  1  [Apr 01 2024 06:00:00]

doesn't work, it needs the following version

MPSS.HI.4.3.3.c6-00202-KODIAK_GEN_PACK-1.58434.4.59740.4  1  [Feb 05 2024 05:00:00]

from a postmarketos rootfs. To override affected files: 

sudo cp -vr pm_rootfs/lib/firmware/qcom/qcm6490/fairphone5/modem* /lib/firmware/updates/qcom/qcm6490/fairphone5/

then reboot

- eSIM issued in Mainland China uses a different CA and is unlikely to work, however, eSIM issued by non-mainland China ISP should work within mainland China.

- QRCode activation is not supported, a link is required, but this should be easy to fix

- Roaming eSIM can use different APN in different locations, manual update upon traveling might be needed.

lpac: C-based eUICC LPA, CLI only #1080482

lpa-gtk: GUI LPA written in GTK4 for Linux phones

EasyLPAC: GUI frontend for lpac, written in Golang, not packaged yet

pySim: useful toolkit for inspecting and programming SIMs #1127804

See also

Demystifying eSIM Technology by Harald Welte https://media.ccc.de/v/camp2023-57190-demystifying_esim_technology

pySim-shell - next generation SIM configuration tool https://media.ccc.de/v/osmodevcall-20210409-laforge-pysim-shell

pySim ?WiKi https://osmocom.org/projects/pysim/wiki

Things to work on

- Test more eSIM capable devices!

- If eUICC reports ?JavaCard capability, can we run pgp card applet on Debian phone?

- How is APN obtained on Android? can we have the same on Mobian/Debian?

- How many profiles can we have? how to calculate space allocated by each profile?