Embedded SIM (eSIM, or eUICC) technology allows mobile users to download a carrier profile and activate a carrier's service without having a physical SIM card. It's a global specification driven by the GSMA that enables remote SIM provisioning (RSP) of any mobile device. Starting with Android 9, the Android framework provides standard APIs for accessing eSIM and managing subscription profiles on the eSIM. These eUICC APIs enable third parties to develop their own carrier apps and local profile assistants (LPAs) on eSIM-enabled Android devices.
The LPA is a standalone, system app that should be included in the Android build image. Management of the profiles on the eSIM is generally done by the LPA, as it serves as a bridge between the SM-DP+ (remote service that prepares, stores, and delivers profile packages to devices) and the eUICC chip. The LPA APK can optionally include a UI component, called the LPA UI or LUI, to provide a central place for the end user to manage all embedded subscription profiles. The Android framework automatically discovers and connects to the best available LPA, and routes all the eUICC operations through an LPA instance.
Figure 1. Simplified RSP architecture
Mobile network operators interested in creating a carrier app should look at
the APIs in
EuiccManager,
which provides high-level profile management operations such as
downloadSubscription(), switchToSubscription(), and
deleteSubscription().
If you're a device OEM interested in creating your own LPA system app, you must
extend
EuiccService
for the Android framework to connect to your LPA services. In addition, you
should use the APIs in
EuiccCardManager,
which provide ES10x functions based on GSMA RSP v2.0.
These functions are used to issue commands to the eUICC chip, such as
prepareDownload(), loadBoundProfilePackage(), retrieveNotificationList(),
and resetMemory().
The APIs in
EuiccManager
require a properly implemented LPA app to function and the caller of
EuiccCardManager
APIs must be an LPA. This is enforced by the Android framework.
Devices running Android 10 or higher can support devices with multiple eSIMs. For more information, see Supporting multiple eSIMs.
Making a carrier app
The eUICC APIs in Android 9 make it possible for mobile network operators to create carrier-branded apps to manage their profiles directly. This includes downloading and deleting subscription profiles owned by the carrier, as well as switching to a profile owned by a carrier.
EuiccManager
EuiccManager is the main entry point for apps to interact with the
LPA. This includes carrier apps that download, delete, and switch to
subscriptions owned by the carrier. This also includes the LUI system app, which
provides a central location/UI for managing all embedded subscriptions, and
can be a separate app from the one that provides the EuiccService.
To use the public APIs, a carrier app must first obtain the instance of
EuiccManager through Context#getSystemService:
EuiccManager mgr = (EuiccManager) context.getSystemService(Context.EUICC_SERVICE);
You should check whether eSIM is supported on the device before performing any
eSIM operations. EuiccManager#isEnabled() generally returns true if the
android.hardware.telephony.euicc feature is defined and an LPA package is
present.
boolean isEnabled = mgr.isEnabled();
if (!isEnabled) {
return;
}
To get information about the eUICC hardware and the eSIM OS version:
EuiccInfo info = mgr.getEuiccInfo();
String osVer = info.getOsVersion();
Many APIs, such as downloadSubscription() and switchToSubscription(), use
PendingIntent callbacks as they may take seconds or even minutes to complete.
PendingIntent is sent with a result code in the
EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_ space, which provides
framework-defined error codes, as well as an arbitrary detailed result code
propagated from the LPA as EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, allowing
the carrier app to track for logging/debugging purposes. The PendingIntent
callback must be BroadcastReceiver.
To download a given subscription (created from an activation code or a QR code):
// Register receiver.
static final String ACTION_DOWNLOAD_SUBSCRIPTION = "download_subscription";
static final String LPA_DECLARED_PERMISSION
= "com.your.company.lpa.permission.BROADCAST";
BroadcastReceiver receiver =
new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
if (!action.equals(intent.getAction())) {
return;
}
resultCode = getResultCode();
detailedCode = intent.getIntExtra(
EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
0 /* defaultValue*/);
resultIntent = intent;
}
};
context.registerReceiver(receiver,
new IntentFilter(ACTION_DOWNLOAD_SUBSCRIPTION),
LPA_DECLARED_PERMISSION /* broadcastPermission*/,
null /* handler */);
// Download subscription asynchronously.
DownloadableSubscription sub = DownloadableSubscription
.forActivationCode(code /* encodedActivationCode*/);
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
getContext(), 0 /* requestCode */, intent,
PendingIntent.FLAG_UPDATE_CURRENT);
mgr.downloadSubscription(sub, true /* switchAfterDownload */,
callbackIntent);
To switch to a subscription given the subscription ID:
// Register receiver.
static final String ACTION_SWITCH_TO_SUBSCRIPTION = "switch_to_subscription";
static final String LPA_DECLARED_PERMISSION
= "com.your.company.lpa.permission.BROADCAST";
BroadcastReceiver receiver =
new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
if (!action.equals(intent.getAction())) {
return;
}
resultCode = getResultCode();
detailedCode = intent.getIntExtra(
EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
0 /* defaultValue*/);
resultIntent = intent;
}
};
context.registerReceiver(receiver,
new IntentFilter(ACTION_SWITCH_TO_SUBSCRIPTION),
LPA_DECLARED_PERMISSION /* broadcastPermission*/,
null /* handler */);
// Switch to a subscription asynchronously.
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
getContext(), 0 /* requestCode */, intent,
PendingIntent.FLAG_UPDATE_CURRENT);
mgr.switchToSubscription(1 /* subscriptionId */, callbackIntent);
For a complete list of EuiccManager APIs and code examples, see
eUICC APIs.
Resolvable errors
There are some cases where the system is unable to complete the eSIM operation
but the error can be resolved by the user. For example, downloadSubscription
may fail if the profile metadata indicates that a carrier confirmation code
is required. Or switchToSubscription may fail if the carrier app has carrier
privileges over the destination profile (that is, carrier owns the profile) but
doesn't have carrier privileges over the currently enabled profile, and hence
user consent is required.
For these cases, the caller's callback is called with
EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR. The callback
Intent contains internal extras such that when the caller passes it to
EuiccManager#startResolutionActivity,
resolution can be requested through the LUI. Using the confirmation code for
example again,
EuiccManager#startResolutionActivity
triggers an LUI screen that allows the user to enter a confirmation code;
after the code is entered, the download operation is resumed. This approach
provides the carrier app with full control over when the UI is shown, but gives
the LPA/LUI an extensible method for adding new handling of user-recoverable
issues in the future without needing client apps to change.
Android 9 defines these resolvable errors in
EuiccService,
which the LUI should handle:
/**
* Alert the user that this action will result in an active SIM being
* deactivated. To implement the LUI triggered by the system, you need to define
* this in AndroidManifest.xml.
*/
public static final String ACTION_RESOLVE_DEACTIVATE_SIM =
"android.service.euicc.action.RESOLVE_DEACTIVATE_SIM";
/**
* Alert the user about a download/switch being done for an app that doesn't
* currently have carrier privileges.
*/
public static final String ACTION_RESOLVE_NO_PRIVILEGES =
"android.service.euicc.action.RESOLVE_NO_PRIVILEGES";
/** Ask the user to resolve all the resolvable errors. */
public static final String ACTION_RESOLVE_RESOLVABLE_ERRORS =
"android.service.euicc.action.RESOLVE_RESOLVABLE_ERRORS";
Carrier privileges
If you're a carrier developing your own carrier app that calls EuiccManager
to download profiles onto a device, your profile should include carrier
privilege rules corresponding to your carrier app in the metadata. This is
because subscription profiles belonging to different carriers can co-exist in
the eUICC of a device, and each carrier app should only be allowed to access the
profiles owned by that carrier. For example, carrier A should not be able to
download, enable, or disable a profile owned by carrier B.
To ensure a profile is only accessible to its owner, Android uses a mechanism to
grant special privileges to the profile owner's app (that is, carrier app). The
Android platform loads certificates stored in the profile's access rule file
(ARF) and grants permission to apps signed by these certificates to make calls
to EuiccManager APIs. The high-level process is described below:
- Operator signs the carrier app APK; the apksigner tool attaches the public-key certificate to the APK.
Operator/SM-DP+ prepares a profile and its metadata, which include an ARF that contains:
- Signature (SHA-1 or SHA-256) of the carrier app's public-key certificate (required)
- Package name of the carrier app (optional)
Carrier app tries to perform an eUICC operation via
EuiccManagerAPI.Android platform verifies SHA-1 or SHA-256 hash of the caller app's certificate matches the signature of the certificate obtained from the target profile's ARF. If the package name of the carrier app is included in the ARF, it must also match the package name of the caller app.
After the signature and the package name (if included) are verified, the carrier privilege is granted to the caller app over the target profile.
Because profile metadata can be available outside of the profile itself (so that LPA can retrieve the profile metadata from SM-DP+ before the profile is downloaded, or from ISD-R when the profile is disabled), it should contain the same carrier privilege rules as in the profile.
The eUICC OS and SM-DP+ must support a proprietary tag BF76 in the profile
metadata. The tag content should be the same carrier privilege rules as returned
by the access rule applet (ARA) defined in
UICC Carrier Privileges:
RefArDo ::= [PRIVATE 2] SEQUENCE { -- Tag E2
refDo [PRIVATE 1] SEQUENCE { -- Tag E1
deviceAppIdRefDo [PRIVATE 1] OCTET STRING (SIZE(20|32)), -- Tag C1
pkgRefDo [PRIVATE 10] OCTET STRING (SIZE(0..127)) OPTIONAL -- Tag CA
},
arDo [PRIVATE 3] SEQUENCE { -- Tag E3
permArDo [PRIVATE 27] OCTET STRING (SIZE(8)) -- Tag DB
}
}
For more details on app signing, see Sign your app. For details on carrier privileges, see UICC Carrier Privileges.
Making an LPA app
You can implement your own LPA, which must be hooked up with Android Euicc APIs. The following sections give a brief overview of making an LPA app and integrating it with the Android system.
Hardware/modem requirements
The LPA and the eSIM OS on the eUICC chip must support at least GSMA RSP (Remote SIM Provisioning) v2.0 or v2.2. You should also plan to use SM-DP+ and SM-DS servers that have a matching RSP version. For detailed RSP architecture, see GSMA SGP.21 RSP Architecture Specification.
In addition, to integrate with the eUICC APIs in Android 9, the device modem should send terminal capabilities with the support for eUICC capabilities encoded (local profile management and profile download). It also needs to implement the following methods:
- IRadio HAL v1.1:
setSimPower IRadio HAL v1.2:
getIccCardStatusIRadioConfig HAL v1.0:
getSimSlotsStatus
The modem should recognize the eSIM with the default boot profile enabled as a valid SIM and keep the SIM power on.
For devices running Android 10, a nonremovable eUICC
slot ID array must be defined. For example, see
arrays.xml.
<resources>
<!-- Device-specific array of SIM slot indexes which are are embedded eUICCs.
e.g. If a device has two physical slots with indexes 0, 1, and slot 1 is an
eUICC, then the value of this array should be:
<integer-array name="non_removable_euicc_slots">
<item>1</item>
</integer-array>
If a device has three physical slots and slot 1 and 2 are eUICCs, then the value of
this array should be:
<integer-array name="non_removable_euicc_slots">
<item>1</item>
<item>2</item>
</integer-array>
This is used to differentiate between removable eUICCs and built in eUICCs, and should
be set by OEMs for devices which use eUICCs. -->
<integer-array name="non_removable_euicc_slots">
<item>1</item>
</integer-array>
</resources>
For a complete list of modem requirements, see Modem Requirements for eSIM Support.
EuiccService
An LPA consists of two separate components (may both be implemented in the same APK): the LPA backend, and the LPA UI or LUI.
To implement the LPA backend, you must extend
EuiccService
and declare this service in your manifest file. The service must require the
android.permission.BIND_EUICC_SERVICE system permission to ensure that only
the system can bind to it. The service must also include an intent filter with
the android.service.euicc.EuiccService action. The priority of the intent
filter should be set to a non-zero value in case multiple implementations are
present on the device. For example:
<service
android:name=".EuiccServiceImpl"
android:permission="android.permission.BIND_EUICC_SERVICE">
<intent-filter android:priority="100">
<action android:name="android.service.euicc.EuiccService" />
</intent-filter>
</service>
Internally, the Android framework determines the active LPA and interacts with
it as needed to support the Android eUICC APIs. PackageManager is queried for
all apps with the android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS permission,
which specifies a service for the android.service.euicc.EuiccService action.
The service with the highest priority is selected. If no service is found, LPA
support is disabled.
To implement the LUI, you must provide an activity for the following actions:
android.service.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONSandroid.service.euicc.action.PROVISION_EMBEDDED_SUBSCRIPTION
As with the service, each activity must require the
android.permission.BIND_EUICC_SERVICE system permission. Each should have an
intent filter with the appropriate action, the
android.service.euicc.category.EUICC_UI category, and a non-zero priority.
Similar logic is used to pick the implementations for these activities as
with picking the implementation of
EuiccService.
For example:
<activity android:name=".MyLuiActivity"
android:exported="true"
android:permission="android.permission.BIND_EUICC_SERVICE">
<intent-filter android:priority="100">
<action android:name="android.service.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONS" />
<action android:name="android.service.euicc.action.PROVISION_EMBEDDED_SUBSCRIPTION" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.service.euicc.category.EUICC_UI" />
</intent-filter>
</activity>
This implies that the UI implementing these screens can come from a different
APK from the one that implements
EuiccService.
Whether to have a single APK or multiple APKs (for example, one that implements
EuiccService and one that provides LUI activities) is a design choice.
EuiccCardManager
EuiccCardManager is the interface for communicating with the eSIM chip. It
provides ES10 functions (as described in the GSMA RSP spec) and handles the
low-level APDU request/response commands as well as ASN.1 parsing.
EuiccCardManager is a system API and can be called only by system-privileged
apps.
Figure 2. Both carrier app and LPA use Euicc APIs
The profile operation APIs through EuiccCardManager require the caller to be
an LPA. This is enforced by the Android framework. This means the caller must
extend EuiccService and be declared in your manifest file, as described in
the previous sections.
Similar to EuiccManager, to use the EuiccCardManager APIs, your LPA must
first obtain the instance of EuiccCardManager through
Context#getSystemService:
EuiccCardManager cardMgr = (EuiccCardManager) context.getSystemService(Context.EUICC_CARD_SERVICE);
Then, to get all the profiles on the eUICC:
ResultCallback<EuiccProfileInfo[]> callback =
new ResultCallback<EuiccProfileInfo[]>() {
@Override
public void onComplete(int resultCode,
EuiccProfileInfo[] result) {
if (resultCode == EuiccCardManagerReflector.RESULT_OK) {
// handle result
} else {
// handle error
}
}
};
cardMgr.requestAllProfiles(eid, AsyncTask.THREAD_POOL_EXECUTOR, callback);
Internally, EuiccCardManager binds to EuiccCardController (which runs in the
phone process) through an AIDL interface, and each EuiccCardManager method
receives its callback from the phone process through a different, dedicated AIDL
interface. When using EuiccCardManager APIs, the caller (LPA) must provide an
Executor
object through which the callback is invoked. This Executor object may run on
a single thread or on a thread pool of your choice.
Most EuiccCardManager APIs have the same usage pattern. For example, to load a
bound profile package onto the eUICC:
...
cardMgr.loadBoundProfilePackage(eid, boundProfilePackage,
AsyncTask.THREAD_POOL_EXECUTOR, callback);
To switch to a different profile with a given ICCID:
...
cardMgr.switchToProfile(eid, iccid, true /* refresh */,
AsyncTask.THREAD_POOL_EXECUTOR, callback);
To get the default SM-DP+ address from the eUICC chip:
...
cardMgr.requestDefaultSmdpAddress(eid, AsyncTask.THREAD_POOL_EXECUTOR,
callback);
To retrieve a list of notifications of the given notification events:
...
cardMgr.listNotifications(eid,
EuiccNotification.Event.INSTALL
| EuiccNotification.Event.DELETE /* events */,
AsyncTask.THREAD_POOL_EXECUTOR, callback);
Supporting multiple eSIMs
For devices running Android 10 or higher, the
EuiccManager class supports devices
with multiple eSIMs. Devices with a single eSIM that are upgrading to
Android 10
don't require any modification to the LPA implementation as the platform
automatically associates the EuiccManager instance with the default eUICC. The
default eUICC is determined by the platform for devices with radio HAL version
1.2 or higher and by the LPA for devices with radio HAL versions lower than
1.2.
Requirements
To support multiple eSIMs, the device must have more than one eUICC, which can be either a built-in eUICC or a physical SIM slot where removable eUICCs can be inserted.
Radio HAL version 1.2 or higher is required to support multiple eSIMs. Radio HAL version 1.4 and RadioConfig HAL version 1.2 are recommended.
Implementation
To support multiple eSIMs (including removable eUICCs or programmable SIMs), the
LPA must implement
EuiccService,
which receives the slot ID corresponding to the caller-provided card ID.
The
non_removable_euicc_slots
resource specified in
arrays.xml
is an array of integers that represent the slot IDs of a device's built-in
eUICCs. You must specify this resource to allow the platform to determine
whether an inserted eUICC is removable or not.
Carrier app for device with multiple eSIMs
When making a carrier app for a device with multiple eSIMs, use the
createForCardId
method in EuiccManager to create an EuiccManager object that is pinned to a
given card ID. The card ID is an integer value that uniquely identifies a UICC
or an eUICC on the device.
To get the card ID for the device's default eUICC, use the
getCardIdForDefaultEuicc
method in TelephonyManager. This method returns
UNSUPPORTED_CARD_ID
if the radio HAL version is lower than 1.2 and returns
UNINITIALIZED_CARD_ID
if the device hasn't read the eUICC.
You can also get card IDs from
getUiccCardsInfo
and getUiccSlotsInfo (system API) in TelephonyManager, and
getCardId
in SubscriptionInfo.
When an EuiccManager object has been instantiated with a specific card ID, all
operations are directed to the eUICC with that card ID. If the eUICC becomes
unreachable (for example, when it is turned off or removed) EuiccManager no
longer works.
You can use the following code samples to create a carrier app.
Example 1: Get active subscription and instantiate EuiccManager
// Get the active subscription and instantiate an EuiccManager for the eUICC which holds
// that subscription
SubscriptionManager subMan = (SubscriptionManager)
mContext.getSystemService(Context.TELEPHONY_SUBSCRIPTION_SERVICE);
int cardId = subMan.getActiveSubscriptionInfo().getCardId();
EuiccManager euiccMan = (EuiccManager) mContext.getSystemService(Context.EUICC_SERVICE)
.createForCardId(cardId);
Example 2: Iterate through UICCs and instantiate EuiccManager for a
removable eUICC
// On a device with a built-in eUICC and a removable eUICC, iterate through the UICC cards
// to instantiate an EuiccManager associated with a removable eUICC
TelephonyManager telMan = (TelephonyManager)
mContext.getSystemService(Context.TELEPHONY_SERVICE);
List<UiccCardInfo> infos = telMan.getUiccCardsInfo();
int removableCardId = -1; // valid cardIds are 0 or greater
for (UiccCardInfo info : infos) {
if (info.isRemovable()) {
removableCardId = info.getCardId();
break;
}
}
if (removableCardId != -1) {
EuiccManager euiccMan = (EuiccManager) mContext.getSystemService(Context.EUICC_SERVICE)
.createForCardId(removableCardId);
}
Validation
AOSP doesn't come with an LPA implementation and you aren't expected to have an LPA available on all Android builds (not every phone supports eSIM). For this reason, there are no end-to-end CTS test cases. However, basic test cases are available in AOSP to ensure the exposed eUICC APIs are valid in Android builds.
You should make sure the builds pass the following CTS test cases (for public APIs): /platform/cts/tests/tests/telephony/current/src/android/telephony/euicc/cts.
Carriers implementing a carrier app should go through their normal in-house quality assurance cycles to ensure all implemented features are working as expected. At the minimum, the carrier app should be able to list all the subscription profiles owned by the same operator, download and install a profile, activate a service on the profile, switch between profiles, and delete profiles.
If you're making your own LPA, you should go through much more rigorous testing. You should work with your modem vendor, eUICC chip or eSIM OS vendor, SM-DP+ vendors, and carriers to resolve issues and ensure interoperability of your LPA within the RSP architecture. A good amount of manual testing is inevitable. For best test coverage, you should follow the GSMA SGP.23 RSP Test Plan.