eSIM LPA (Local Profile Assistant) implementation for Android. System privilege or ARA-M allowlisting required.

Peter Cai 348395c48d chore: Bump lpac 1 year ago
.forgejo e587af9714 workflows: Run only on runners with android app keystore 1 year ago
.idea 632b6b4931 refactor: Create OpenEuiccUIContextMarker to facilitate easy access to application-global singletons 1 year ago
app 1a69c5294b refactor: Use DI techniques for EuiccChannel's as well 1 year ago
app-common 09e19412e3 fix: Show less logs in UI than what we will save 1 year ago
app-deps 06fe15bb11 app-deps: Exclude jetbrains kotlin stdlib 1 year ago
app-unpriv 124d1690ab fix: Clear status icon when compat check items are recycled 1 year ago
buildSrc 8ee3c53492 buildSrc: Use HEAD rev count as version code 1 year ago
gradle c6d7db3c59 chore: Upgrade gradle plugin 1 year ago
libs 348395c48d chore: Bump lpac 1 year ago
.gitignore 396647919f .gitignore: Add .idea/deploymentTargetDropDown.xml 1 year ago
.gitmodules 85af3bcfc0 refactor: [1/n] Introduce the lpac project and lpac_jni 1 year ago
Android.bp a53ff97ecc Android.bp: Fix building on AOSP 14 (finally) 1 year ago
Android.mk 7c21cda40c Implement Android.bp building with AOSP for lpac_jni 1 year ago
LICENSE a4b1ebdc08 relicense under GPLv2 *only* 2 years ago
README.md 9f3977dc5e README: Fix fragments 1 year ago
build.gradle.kts 50c7b4a3be refactor: Migrate to build.gradle.kts 1 year ago
gradle.properties c6d7db3c59 chore: Upgrade gradle plugin 1 year ago
gradlew 3c6cffae84 initial commit 2 years ago
gradlew.bat 3c6cffae84 initial commit 2 years ago
privapp_whitelist_im.angry.openeuicc.xml cacab05892 Add privapp permission whitelist for production builds 2 years ago
settings.gradle.kts b580193624 Generate Android.bp and dependencies with LineageOS's GenerateBp plugin 1 year ago

README.md

{Open,Easy}EUICC

A fully free and open-source Local Profile Assistant implementation for Android devices.

There are two variants of this project:

  • OpenEUICC: The full-fledged privileged variant.
    • Due to its privilege requirement, OpenEUICC must be placed inside /system/priv-app and be signed with the platform certificate.
    • The preferred way to including OpenEUICC in a system image is to build it along with AOSP.
  • EasyEUICC: Unprivileged version that can run as a user app.
    • Due to obvious security requirements, EasyEUICC is only able to access eSIM chips whose ARF/ARA contains the hash of EasyEUICC's signing certificate.
    • Prebuilt release-mode EasyEUICC apks can be downloaded here
    • For removable eSIM chip vendors: to have your chip supported by official builds of EasyEUICC, include the ARA-M hash 2A2FA878BC7C3354C2CF82935A5945A3EDAE4AFA

Building (Gradle)

Make sure you have all submodules cloned and updated by running

git submodule update --init

A file keystore.properties is required in the root directory. Template:

storePassword=my-store-password
keyPassword=my-password
keyAlias=my-key
unprivKeyPassword=my-unpriv-password
unprivKeyAlias=my-unpriv-key
storeFile=/path/to/android/keystore

Note that you must have a Java-compatible keystore generated first.

To build the privileged OpenEUICC:

./gradlew :app:assembleRelease

For EasyEUICC:

./gradlew :app-unpriv:assembleRelease

Building (AOSP)

There are two ways to include OpenEUICC in your AOSP-based system image:

  1. Include this project and its dependencies inside the AOSP tree.
    • If inclusion in manifest.xml is required, remember to set the sync-s option to clone submodules.
    • The module name is OpenEUICC. You can include it in PRODUCT_PACKAGES, or simply build it standalone using mm.
    • Compilation of this project is only tested against the latest AOSP release version. The app itself should be compatible with older AOSP versions, but the source may not compile against an older AOSP source tree.
  2. If compilation against AOSP source tree is not possible, consider building with gradle and import the apk as a prebuilt.
    • No official Android.bp is provided for this case but it should be straightforward to write.
    • You might want to include privapp_whitelist_im.angry.openeuicc.xml as well.

FAQs

  • Q: Do you provide prebuilt binaries for OpenEUICC?
  • A: Debug-mode APKs are available continuously as an artifact of the Actions CI used by this project. However, these debug-mode APKs are not intended for inclusion inside system images, nor are they supported by the developer in any sense. If you are a custom ROM developer, either include the entire OpenEUICC repository in your AOSP source tree, or generate an APK using gradle and import that as a prebuilt system app. Note that you might want privapp_whitelist_im.angry.openeuicc.xml as well.

  • Q: AOSP's Settings app seems to be confused by OpenEUICC (for example, disabling / enabling profiles from the Networks page do not work properly)

  • A: When your device has internal eSIM chip(s) and you have inserted a removable eSIM chip, the Settings app can misbehave since it was never designed for this scenario. Please prefer using OpenEUICC's own management interface whenever possible. In the future, there might be an option to exclude removable SIMs from being reported to the Android system.

  • Q: Can EasyEUICC manage my phone's internal eSIM?

  • A: No. For EasyEUICC to work, the eSIM chip MUST proactively grant access via its ARA-M field.

  • Q: Removable eSIMs? Are they a joke?

  • A: No, even though the name "removable embedded SIM" can sound like an oxymoron. In fact, there can be many advantages to these chips compared to fully embedded ones. For example, the ability to transfer eSIM profiles without carrier support or approval, or the ability to use eSIM on devices that do not and may never get the support, such as Wi-Fi hotspots.

Copyright

Everything except libs/lpac-jni:

Copyright 2022-2024 OpenEUICC contributors

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation, version 2.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

libs/lpac-jni:

Copyright (C) 2022-2024 OpenEUICC contributiors

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, version 2.1.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA