libraries/entitlement/ServiceEntitlement.java

/*
 * Copyright (C) 2021 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.libraries.entitlement;

import android.content.Context;

import androidx.annotation.Nullable;
import androidx.annotation.VisibleForTesting;

import com.android.libraries.entitlement.eapaka.EapAkaApi;

import com.google.common.collect.ImmutableList;

import java.util.List;

/**
 * Implemnets protocol for carrier service entitlement configuration query and operation, based on
 * GSMA TS.43 spec.
 */
public class ServiceEntitlement {
    /**
     * App ID for Voice-Over-LTE entitlement.
     */
    public static final String APP_VOLTE = "ap2003";
    /**
     * App ID for Voice-Over-WiFi entitlement.
     */
    public static final String APP_VOWIFI = "ap2004";
    /**
     * App ID for SMS-Over-IP entitlement.
     */
    public static final String APP_SMSOIP = "ap2005";
    /**
     * App ID for on device service activation (OSDA) for companion device.
     */
    public static final String APP_ODSA_COMPANION = "ap2006";
    /**
     * App ID for on device service activation (OSDA) for primary device.
     */
    public static final String APP_ODSA_PRIMARY = "ap2009";
    /**
     * App ID for data plan information entitlement.
     */
    public static final String APP_DATA_PLAN_BOOST = "ap2010";

    private final CarrierConfig carrierConfig;
    private final EapAkaApi eapAkaApi;

    /**
     * Creates an instance for service entitlement configuration query and operation for the
     * carrier.
     *
     * @param context           context of application
     * @param carrierConfig     carrier specific configs used in the queries and operations.
     * @param simSubscriptionId the subscroption ID of the carrier's SIM on device. This indicates
     *                          which SIM to retrieve IMEI/IMSI from and perform EAP-AKA
     *                          authentication with. See
     *                          {@link android.telephony.SubscriptionManager}
     *                          for how to get the subscroption ID.
     */
    public ServiceEntitlement(Context context, CarrierConfig carrierConfig, int simSubscriptionId) {
        this(
                context,
                carrierConfig,
                simSubscriptionId,
                /* saveHttpHistory= */ false,
                /* bypassEapAkaResponse= */ "");
    }

    /**
     * Creates an instance for service entitlement configuration query and operation for the
     * carrier.
     *
     * @param context context of application
     * @param carrierConfig carrier specific configs used in the queries and operations.
     * @param simSubscriptionId the subscroption ID of the carrier's SIM on device. This indicates
     *     which SIM to retrieve IMEI/IMSI from and perform EAP-AKA authentication with. See {@link
     *     android.telephony.SubscriptionManager} for how to get the subscroption ID.
     * @param saveHttpHistory set to {@code true} to save the history of request and response which
     *     can later be retrieved by {@code getHistory()}. Intended for debugging.
     */
    public ServiceEntitlement(
            Context context,
            CarrierConfig carrierConfig,
            int simSubscriptionId,
            boolean saveHttpHistory) {
        this(
                context,
                carrierConfig,
                simSubscriptionId,
                saveHttpHistory,
                /* bypassEapAkaResponse= */ "");
    }

    /**
     * Creates an instance for service entitlement configuration query and operation for the
     * carrier.
     *
     * @param context context of application
     * @param carrierConfig carrier specific configs used in the queries and operations.
     * @param simSubscriptionId the subscroption ID of the carrier's SIM on device. This indicates
     *     which SIM to retrieve IMEI/IMSI from and perform EAP-AKA authentication with. See {@link
     *     android.telephony.SubscriptionManager} for how to get the subscroption ID.
     * @param saveHttpHistory set to {@code true} to save the history of request and response which
     *     can later be retrieved by {@code getHistory()}. Intended for debugging.
     * @param bypassEapAkaResponse set to non empty string to bypass EAP-AKA authentication.
     *     The client will accept any challenge from the server and return this string as a
     *     response. Must not be {@code null}. Intended for testing.
     */
    public ServiceEntitlement(
            Context context,
            CarrierConfig carrierConfig,
            int simSubscriptionId,
            boolean saveHttpHistory,
            String bypassEapAkaResponse) {
        this.carrierConfig = carrierConfig;
        this.eapAkaApi =
                new EapAkaApi(context, simSubscriptionId, saveHttpHistory, bypassEapAkaResponse);
    }

    @VisibleForTesting
    ServiceEntitlement(CarrierConfig carrierConfig, EapAkaApi eapAkaApi) {
        this.carrierConfig = carrierConfig;
        this.eapAkaApi = eapAkaApi;
    }

    /**
     * Retrieves service entitlement configuration. For on device service activation (ODSA) of eSIM
     * for companion/primary devices, use {@link #performEsimOdsa} instead.
     *
     * <p>Supported {@code appId}: {@link #APP_VOLTE}, {@link #APP_VOWIFI}, {@link #APP_SMSOIP}.
     *
     * <p>This method sends an HTTP GET request to entitlement server, responds to EAP-AKA
     * challenge if needed, and returns the raw configuration doc as a string. The following
     * parameters are set in the HTTP request:
     *
     * <ul>
     * <li>"app": {@code appId}
     * <li>"vers": 0, or {@code request.configurationVersion()} if it's not 0.
     * <li>"entitlement_version": "2.0", or {@code request.entitlementVersion()} if it's not empty.
     * <li>"token": not set, or {@code request.authenticationToken()} if it's not empty.
     * <li>"IMSI": if "token" is set, set to {@link android.telephony.TelephonyManager#getImei}.
     * <li>"EAP_ID": if "token" is not set, set this parameter to trigger embedded EAP-AKA
     * authentication as decribed in TS.43 section 2.6.1. Its value is derived from IMSI as per
     * GSMA spec RCC.14 section C.2.
     * <li>"terminal_id": IMEI, or {@code request.terminalId()} if it's not empty.
     * <li>"terminal_vendor": {@link android.os.Build#MANUFACTURER}, or {@code
     * request.terminalVendor()} if it's not empty.
     * <li>"terminal_model": {@link android.os.Build#MODEL}, or {@code request.terminalModel()} if
     * it's not empty.
     * <li>"terminal_sw_version": {@llink android.os.Build.VERSION#BASE_OS}, or {@code
     * request.terminalSoftwareVersion()} if it's not empty.
     * <li>"app_name": not set, or {@code request.appName()} if it's not empty.
     * <li>"app_version": not set, or {@code request.appVersion()} if it's not empty.
     * <li>"notif_token": not set, or {@code request.notificationToken()} if it's not empty.
     * <li>"notif_action": {@code request.notificationAction()} if "notif_token" is set, otherwise
     * not set.
     * </ul>
     *
     * <p>Requires permission: READ_PRIVILEGED_PHONE_STATE, or carrier privilege.
     *
     * @param appId   an app ID string defined in TS.43 section 2.2, e.g. {@link #APP_VOWIFI}.
     * @param request contains parameters that can be used in the HTTP request.
     */
    @Nullable
    public String queryEntitlementStatus(String appId, ServiceEntitlementRequest request)
            throws ServiceEntitlementException {
        return eapAkaApi.queryEntitlementStatus(ImmutableList.of(appId), carrierConfig, request);
    }

    /**
     * Retrieves service entitlement configurations for multiple app IDs in one HTTP
     * request/response. For on device service activation (ODSA) of eSIM for companion/primary
     * devices, use {@link #performEsimOdsa} instead.
     *
     * <p>Same with {@link #queryEntitlementStatus(String, ServiceEntitlementRequest)} except that
     * multiple "app" parameters will be set in the HTTP request, in the order as they appear in
     * parameter {@code appIds}.
     */
    public String queryEntitlementStatus(ImmutableList<String> appIds,
            ServiceEntitlementRequest request)
            throws ServiceEntitlementException {
        return eapAkaApi.queryEntitlementStatus(appIds, carrierConfig, request);
    }

    /**
     * Performs on device service activation (ODSA) of eSIM for companion/primary devices.
     *
     * <p>Supported {@code appId}: {@link #APP_ODSA_COMPANION}, {@link #APP_ODSA_PRIMARY}.
     *
     * <p>Similar to {@link #queryEntitlementStatus(String, ServiceEntitlementRequest)}, this
     * method sends an HTTP GET request to entitlement server, responds to EAP-AKA challenge if
     * needed, and returns the raw configuration doc as a string. Additional parameters from {@code
     * operation} are set to the HTTP request. See {@link EsimOdsaOperation} for details.
     */
    public String performEsimOdsa(
            String appId, ServiceEntitlementRequest request, EsimOdsaOperation operation)
            throws ServiceEntitlementException {
        return eapAkaApi.performEsimOdsaOperation(appId, carrierConfig, request, operation);
    }

    /**
     * Retrieves the history of past HTTP request and responses if {@code saveHttpHistory} was set
     * in constructor.
     */
    public List<String> getHistory() {
        return eapAkaApi.getHistory();
    }

    /**
     * Clears the history of past HTTP request and responses.
     */
    public void clearHistory() {
        eapAkaApi.clearHistory();
    }
}