LPAC(1)

📦 version 2.3.0, in ubuntu stonking

💖 NAME 💖

okay so bestie, meet lpac — the local profile agent program, compatible with SGP.22 version 2.2.2 ✨ it's the manual page for section 1 of the manual (LPAC(1)), and she's a whole icon 👑

🦋 SYNOPSIS 🦋

lpac <subcommand> [subcommand] [parameters]

✨ DESCRIPTION ✨

lpac supports the following features and more 👇

  • Custom IMEI sent to server
  • Profile Discovery (SM-DS)
  • Profile management: list, enable, disable, delete and nickname
  • Notification management: list, send and delete
  • Lookup eUICC chip info

so the APDU and HTTP interfaces of lpac have several backends, and you need to specify the $LPAC_APDU and $LPAC_HTTP environment variables to point at the interface library path 🌸 if you don't specify them? it just uses pcsc and curl. no big deal, but like. specify them if you need them, bestie 💅

🎀 RETURN VALUE 🎀

the return contents of lpac instructions are all in json format, and the returns of all instructions comply with the following format 👇

{
   "type": "lpa",
   "payload": {
      "code": 0,
      "message": "success",
      "data": {/* .... */}
   }
}
  • "type": "lpa": fixed content, she never changes 💅
  • code: if is 0, indicating successful execution, and other values are error codes 😭
  • message: is success if the operation is successful, or the error type is returned if an error occurs 💀
  • data: returns the returned content when the operation is successful, and is empty (but not NULL) when there is an error 🫶

🌈 SUBCOMMANDS 🌈

🧚 chip

View the EID, default SM-DP+ server and SM-DS server of eUICC. euicc_info2 is also supported ✨

  • info — View information about your eUICC card itself 👑
  • defaultsmdp — Modify the default SM-DP+ server address of your eUICC card. Example: lpac chip defaultsmdp <the address of the SM-DP+ server you want to modify>
  • purge — Reset the eUICC and will clear all profiles. Use with caution! 💀
fr fr bestie, purge is the nuclear option — it clears ALL your profiles. be so careful.

Return value example 👇

{
  "type": "lpa",
  "payload": {
    "code": 0,
    "message": "success",
    "data": {
      "eidValue": "[EID]",
      "EuiccConfiguredAddresses": {
        "defaultDpAddress": null,
        "rootDsAddress": "testrootsmds.gsma.com"
      },
      "EUICCInfo2": {
        "profileVersion": "2.1.0",
        "svn": "2.2.0",
        "euiccFirmwareVer": "4.6.0",
        "extCardResource": {
          "installedApplication": 0,
          "freeNonVolatileMemory": 291666,
          "freeVolatileMemory": 5970
        },
        "uiccCapability": [
          "usimSupport",
          "isimSupport",
          "csimSupport",
          "akaMilenage",
          "akaCave",
          "akaTuak128",
          "akaTuak256",
          "gbaAuthenUsim",
          "gbaAuthenISim",
          "eapClient",
          "javacard",
          "multipleUsimSupport",
          "multipleIsimSupport"
        ],
        "ts102241Version": "9.2.0",
        "globalplatformVersion": "2.3.0",
        "rspCapability": [
          "additionalProfile",
          "testProfileSupport"
        ],
        "euiccCiPKIdListForVerification": [
          "81370f5125d0b1d408d4c3b232e6d25e795bebfb"
        ],
        "euiccCiPKIdListForSigning": [
          "81370f5125d0b1d408d4c3b232e6d25e795bebfb"
        ],
        "euiccCategory": null,
        "forbiddenProfilePolicyRules": [
          "pprUpdateControl",
          "ppr1"
        ],
        "ppVersion": "0.0.1",
        "sasAcreditationNumber": "GI-BA-UP-0419",
        "certificationDataObject": {
          "platformLabel": "1.2.840.1234567/myPlatformLabel",
          "discoveryBaseURL": "https://mycompany.com/myDLOARegistrar"
        }
      }
    }
  }
}

* Starting from SGP.22 v2.1, javacardVersion is renamed to ts102241Version 🌸

** SGP.22 has been a typo, sasAcreditationNumber should be sasAccreditationNumber 🙈 (they said it, not me, i'm just the messenger)

🌸 profile

Profile management, you can list, set alias (nickname), enable, disable, delete, download and discovery Profiles 💖

  • list — enumerates your eUICC Profile 👑
  • nickname — sets an alias for the specified Profile. Example: lpac profile nickname <ICCID of Profile> <alias>
  • enable — enables the specified Profile. The RefreshFlag status is enabled by default and can be omitted. Example: lpac profile enable <ICCID/AID of Profile> [1/0]
  • disable — disables the specified Profile. The RefreshFlag state is enabled by default and can be omitted. Example: lpac profile disable <ICCID/AID of Profile> [1/0]
  • delete — deletes the specified Profile. Example: lpac profile delete <ICCID/AID of Profile>
  • download — Download profile from SM-DP server ✨
  • discovery — Detect available profile registered on SM-DS server 🔥
NOTE: Some eUICC chips have trouble when enabling profile (e.g. These removable eUICC cards from ECP), try AID, ICCID, refreshFlag with 1 or 0 to find out the working way for these chips 🫠
There is no secondary confirmation for deleting a Profile, so please perform it with caution. it's giving "one click and she's gone" 💀
NOTE: This function will only delete the Profile and issue a Notification, but it will not be sent automatically. You need to send it manually 😭

Download requires connection to SM-DP+ server and the following additional parameters 👇

  • -s — SM-DP+ server, optional, if not provided, it will try to read the default sm-dp+ attribute.
  • -m — Matching ID, activation code. optional.
  • -c — Confirmation Code, optional.
  • -i — The IMEI of the device to which Profile is to be downloaded, optional.
  • -a — LPA qrcode activation code string, e.g: LPA:1$<sm-dp+domain>$<matchingID>, if provided, this option takes precedence over the -s and -m options, optional.
  • -p — Interactive preview mode, optional.

Discovery requires connecting to the SM-DS server to query registered profile 🌈

The following parameters can be used to customize the IMEI and SM-DS server 👇

  • -s — SM-DS server. If not provided, it will be gsma official server lpa.ds.gsma.com
  • -i — IMEI of the device to which Profile is to be downloaded, optional

Return value example of lpac profile list 👇

{
  "type": "lpa",
  "payload": {
    "code": 0,
    "message": "success",
    "data": [
      {
        "iccid": "89353...",
        "isdpAid": "A0000005591010FFFFFFFF8900001000",
        "profileState": "disabled",
        "profileNickname": null,
        "serviceProviderName": "Vodafone IE",
        "profileName": "Vodafone IE eSIM",
        "iconType": "png",
        "icon": "iVBO...",
        "profileClass": "operational"
      }
    ]
  }
}
  • iccid: ICCID of Profile
  • isdpAid: Aid of Profile
  • profileState: State of Profile, "Enabled" or "Disabled"
  • profileNickname: Nickname of Profile
  • serviceProviderName: Telecom operators of Profile
  • profileName: Name of Profile
  • iconType: Profile icon data struct, "none", "png", "jpg"
  • icon: Profile icon data in base64
  • profileClass: Type of Profile

💜 notification

Used for the management of Notifications, which are sent by telecom operators during Profile operations. You can enumerate (list), send (process), and remove (remove) Notifications 💅

  • list — Enumerates your eUICC pending Notification list 👑
  • process — Send Notification. Example: lpac notification process <sequence ID>
  • remove — Remove Notification. Example: lpac notification remove <sequence ID>
NOTE: Downstream developers or end users should process Notification as soon as possible when they exist to comply with GSMA specifications. lpac will not automatically delete the Notification after sending it. You can pass -r to notification process or you need to delete it manually 😭

Return value example of lpac notification list 👇

{
  "type": "lpa",
  "payload": {
    "code": 0,
    "message": "success",
    "data": [
      {
        "seqNumber": 178,
        "profileManagementOperation": "install",
        "notificationAddress": "rsp-eu.redteamobile.com",
        "iccid": "89852..."
      }
    ]
  }
}
  • seqNumber: Sequence ID
  • profileManagementOperation: Which operation generated this notification
  • notificationAddress: Profile's notification reporting server address

Processing requires connection to server and the following optional parameters 👇

  • -a — Process all notifications
  • -r — Automatically remove processed notifications

Removing supports the following optional parameters 👇

  • -a — Remove all notifications

🦋 driver

Usage: driver <apdu|http|list>

View the backend list 👀

⭐ SEE ALSO ⭐

Upstream Documentations - https://github.com/estkme-group/lpac/tree/main/docs

okay that's the whole page bestie, you officially know lpac now 💖 this was LPAC(1), section 1 of the manual — go forth and manage those profiles, you main character 🎀✨👑

📦 where this page comes from