From e3dbdcb480f52310e48c127c8f8d5bca059d6bfa Mon Sep 17 00:00:00 2001 From: Peter Cai Date: Thu, 28 Dec 2023 21:38:39 -0500 Subject: [PATCH] Add README (finally) --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..bf0dbea --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +{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-flegded privileged variant. Intended to be run as a privileged system app (inside `/system/priv-app`) and serve as the system LPA. This can be used to manage all kinds of eSIM chips, embedded or removable. +- EasyEUICC: Unprivileged version that can run as a user app. An eSIM chip must include the certificate of EasyEUICC in its ARA-M field in order to grant access without system privileges. This is intended for removable eSIM chips such as those provided by eSTK. + - Prebuilt EasyEUICC apks can be downloaded [here](https://gitea.angry.im/PeterCxy/OpenEUICC/releases) + - For removable eSIM chip vendors: to have your chip supported by official builds of EasyEUICC, include the ARA-M hash `2A2FA878BC7C3354C2CF82935A5945A3EDAE4AFA` + +Building +=== + +Make sure you have all submodules cloned and updated by running + +```shell +git submodule update --init +``` + +A file `keystore.properties` is required in the root directory. Template: + +```ini +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: + +```shell +./gradlew :app:assembleRelease +``` + +For EasyEUICC: + +```shell +./gradlew :app-unpriv:assembleRelease +``` + +FAQs +=== + +- Q: Do you provide prebuilt binaries for OpenEUICC? +- A: No. 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. \ No newline at end of file