A VCN creates a virtualization layer to allow carriers to aggregate heterogeneous physical * networks, unifying them as a single carrier network. This enables infrastructure flexibility on * the part of carriers without impacting user connectivity, abstracting the physical network * technologies as an implementation detail of their public network. * *
Each VCN virtualizes a carrier's network by building tunnels to a carrier's core network over * carrier-managed physical links and supports a IP mobility layer to ensure seamless transitions * between the underlying networks. Each VCN is configured based on a Subscription Group (see {@link * android.telephony.SubscriptionManager}) and aggregates all networks that are brought up based on * a profile or suggestion in the specified Subscription Group. * *
The VCN can be configured to expose one or more {@link android.net.Network}(s), each with * different capabilities, allowing for APN virtualization. * *
If a tunnel fails to connect, or otherwise encounters a fatal error, the VCN will attempt to * reestablish the connection. If the tunnel still has not reconnected after a system-determined * timeout, the VCN Safe Mode (see below) will be entered. * *
The VCN Safe Mode ensures that users (and carriers) have a fallback to restore system * connectivity to update profiles, diagnose issues, contact support, or perform other remediation * tasks. In Safe Mode, the system will allow underlying cellular networks to be used as default. * Additionally, during Safe Mode, the VCN will continue to retry the connections, and will * automatically exit Safe Mode if all active tunnels connect successfully. * *
Apps targeting Android 15 or newer should check the existence of {@link * PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION} before querying the service. If the feature is * absent, {@link Context#getSystemService} may return null. */ @SystemService(VcnManager.VCN_MANAGEMENT_SERVICE_STRING) @RequiresFeature(PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION) public class VcnManager { @NonNull private static final String TAG = VcnManager.class.getSimpleName(); // TODO: b/366598445: Expose and use Context.VCN_MANAGEMENT_SERVICE /** @hide */ public static final String VCN_MANAGEMENT_SERVICE_STRING = "vcn_management"; /** * Key for WiFi entry RSSI thresholds * *
The VCN will only migrate to a Carrier WiFi network that has a signal strength greater * than, or equal to this threshold. * * @hide */ @NonNull public static final String VCN_NETWORK_SELECTION_WIFI_ENTRY_RSSI_THRESHOLD_KEY = "vcn_network_selection_wifi_entry_rssi_threshold"; /** * Key for WiFi entry RSSI thresholds * *
If the VCN's selected Carrier WiFi network has a signal strength less than this threshold, * the VCN will attempt to migrate away from the Carrier WiFi network. * * @hide */ @NonNull public static final String VCN_NETWORK_SELECTION_WIFI_EXIT_RSSI_THRESHOLD_KEY = "vcn_network_selection_wifi_exit_rssi_threshold"; /** * Key for the interval to poll IpSecTransformState for packet loss monitoring * * @hide */ @NonNull public static final String VCN_NETWORK_SELECTION_POLL_IPSEC_STATE_INTERVAL_SECONDS_KEY = "vcn_network_selection_poll_ipsec_state_interval_seconds"; /** * Key for the threshold of IPSec packet loss rate * * @hide */ @NonNull public static final String VCN_NETWORK_SELECTION_IPSEC_PACKET_LOSS_PERCENT_THRESHOLD_KEY = "vcn_network_selection_ipsec_packet_loss_percent_threshold"; /** * Key for detecting unusually large increases in IPsec packet sequence numbers. * *
If the sequence number increases by more than this value within a second, it may indicate * an intentional leap on the server's downlink. To avoid false positives, the packet loss * detector will suppress loss reporting. * *
By default, there's no maximum limit enforced, prioritizing detection of lossy networks. * To reduce false positives, consider setting an appropriate maximum threshold. * * @hide */ @NonNull public static final String VCN_NETWORK_SELECTION_MAX_SEQ_NUM_INCREASE_PER_SECOND_KEY = "vcn_network_selection_max_seq_num_increase_per_second"; /** * Key for the list of timeouts in minute to stop penalizing an underlying network candidate * * @hide */ @NonNull public static final String VCN_NETWORK_SELECTION_PENALTY_TIMEOUT_MINUTES_LIST_KEY = "vcn_network_selection_penalty_timeout_minutes_list"; // TODO: Add separate signal strength thresholds for 2.4 GHz and 5GHz /** * Key for transports that need to be marked as restricted by the VCN * *
Defaults to TRANSPORT_WIFI if the config does not exist * * @hide */ public static final String VCN_RESTRICTED_TRANSPORTS_INT_ARRAY_KEY = "vcn_restricted_transports"; /** * Key for number of seconds to wait before entering safe mode * *
A VcnGatewayConnection will enter safe mode when it takes over the configured timeout to * enter {@link ConnectedState}. * *
Defaults to 30, unless overridden by carrier config * * @hide */ @NonNull public static final String VCN_SAFE_MODE_TIMEOUT_SECONDS_KEY = "vcn_safe_mode_timeout_seconds_key"; /** * Key for maximum number of parallel SAs for tunnel aggregation * *
If set to a value > 1, multiple tunnels will be set up, and inbound traffic will be * aggregated over the various tunnels. * *
Defaults to 1, unless overridden by carrier config
*
* @hide
*/
@NonNull
public static final String VCN_TUNNEL_AGGREGATION_SA_COUNT_MAX_KEY =
"vcn_tunnel_aggregation_sa_count_max";
/** List of Carrier Config options to extract from Carrier Config bundles. @hide */
@NonNull
public static final String[] VCN_RELATED_CARRIER_CONFIG_KEYS =
new String[] {
VCN_NETWORK_SELECTION_WIFI_ENTRY_RSSI_THRESHOLD_KEY,
VCN_NETWORK_SELECTION_WIFI_EXIT_RSSI_THRESHOLD_KEY,
VCN_NETWORK_SELECTION_POLL_IPSEC_STATE_INTERVAL_SECONDS_KEY,
VCN_NETWORK_SELECTION_IPSEC_PACKET_LOSS_PERCENT_THRESHOLD_KEY,
VCN_NETWORK_SELECTION_MAX_SEQ_NUM_INCREASE_PER_SECOND_KEY,
VCN_NETWORK_SELECTION_PENALTY_TIMEOUT_MINUTES_LIST_KEY,
VCN_RESTRICTED_TRANSPORTS_INT_ARRAY_KEY,
VCN_SAFE_MODE_TIMEOUT_SECONDS_KEY,
VCN_TUNNEL_AGGREGATION_SA_COUNT_MAX_KEY,
};
private static final Map<
VcnNetworkPolicyChangeListener, VcnUnderlyingNetworkPolicyListenerBinder>
REGISTERED_POLICY_LISTENERS = new ConcurrentHashMap<>();
@NonNull private final Context mContext;
@NonNull private final IVcnManagementService mService;
/**
* Construct an instance of VcnManager within an application context.
*
* @param ctx the application context for this manager
* @param service the VcnManagementService binder backing this manager
*
* @hide
*/
public VcnManager(@NonNull Context ctx, @NonNull IVcnManagementService service) {
mContext = requireNonNull(ctx, "missing context");
mService = requireNonNull(service, "missing service");
}
/**
* Get all currently registered VcnNetworkPolicyChangeListeners for testing purposes.
*
* @hide
*/
@VisibleForTesting(visibility = Visibility.PRIVATE)
@NonNull
public static Map An app that has carrier privileges for any of the subscriptions in the given group may set
* a VCN configuration. If a configuration already exists for the given subscription group, it
* will be overridden. Any active VCN(s) may be forced to restart to use the new configuration.
*
* This API is ONLY permitted for callers running as the primary user.
*
* @param subscriptionGroup the subscription group that the configuration should be applied to
* @param config the configuration parameters for the VCN
* @throws SecurityException if the caller does not have carrier privileges for the provided
* subscriptionGroup, or is not running as the primary user
* @throws IOException if the configuration failed to be saved and persisted to disk. This may
* occur due to temporary disk errors, or more permanent conditions such as a full disk.
*/
@RequiresPermission("carrier privileges") // TODO (b/72967236): Define a system-wide constant
public void setVcnConfig(@NonNull ParcelUuid subscriptionGroup, @NonNull VcnConfig config)
throws IOException {
requireNonNull(subscriptionGroup, "subscriptionGroup was null");
requireNonNull(config, "config was null");
try {
mService.setVcnConfig(subscriptionGroup, config, mContext.getOpPackageName());
} catch (ServiceSpecificException e) {
throw new IOException(e);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Clears the VCN configuration for a given subscription group.
*
* An app that has carrier privileges for any of the subscriptions in the given group may
* clear a VCN configuration. This API is ONLY permitted for callers running as the primary
* user. Any active VCN associated with this configuration will be torn down.
*
* @param subscriptionGroup the subscription group that the configuration should be applied to
* @throws SecurityException if the caller does not have carrier privileges, is not the owner of
* the associated configuration, or is not running as the primary user
* @throws IOException if the configuration failed to be cleared from disk. This may occur due
* to temporary disk errors, or more permanent conditions such as a full disk.
*/
@RequiresPermission("carrier privileges") // TODO (b/72967236): Define a system-wide constant
public void clearVcnConfig(@NonNull ParcelUuid subscriptionGroup) throws IOException {
requireNonNull(subscriptionGroup, "subscriptionGroup was null");
try {
mService.clearVcnConfig(subscriptionGroup, mContext.getOpPackageName());
} catch (ServiceSpecificException e) {
throw new IOException(e);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Retrieves the list of Subscription Groups for which a VCN Configuration has been set.
*
* The returned list will include only subscription groups for which an associated {@link
* VcnConfig} exists, and the app is either:
*
* If the specified listener is not currently registered, this is a no-op.
*
* @param listener the VcnUnderlyingNetworkPolicyListener that will be removed
* @hide
*/
public void removeVcnUnderlyingNetworkPolicyListener(
@NonNull VcnUnderlyingNetworkPolicyListener listener) {
removeVcnNetworkPolicyChangeListener(listener);
}
/**
* Queries the underlying network policy for a network with the given parameters.
*
* Prior to a new NetworkAgent being registered, or upon notification that Carrier VCN policy
* may have changed via {@link VcnUnderlyingNetworkPolicyListener#onPolicyChanged()}, a Network
* Provider MUST poll for the updated Network policy based on that Network's capabilities and
* properties.
*
* @param networkCapabilities the NetworkCapabilities to be used in determining the Network
* policy for this Network.
* @param linkProperties the LinkProperties to be used in determining the Network policy for
* this Network.
* @throws SecurityException if the caller does not have permission NETWORK_FACTORY
* @return the VcnUnderlyingNetworkPolicy to be used for this Network.
* @hide
*/
@NonNull
@RequiresPermission(android.Manifest.permission.NETWORK_FACTORY)
public VcnUnderlyingNetworkPolicy getUnderlyingNetworkPolicy(
@NonNull NetworkCapabilities networkCapabilities,
@NonNull LinkProperties linkProperties) {
requireNonNull(networkCapabilities, "networkCapabilities must not be null");
requireNonNull(linkProperties, "linkProperties must not be null");
try {
return mService.getUnderlyingNetworkPolicy(networkCapabilities, linkProperties);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* VcnNetworkPolicyChangeListener is the interface through which internal system components
* (e.g. Network Factories) can register to receive updates for VCN-underlying Network policies
* from the System Server.
*
* Any Network Factory that brings up Networks capable of being VCN-underlying Networks
* should register a VcnNetworkPolicyChangeListener. VcnManager will then use this listener to
* notify the registrant when VCN Network policies change. Upon receiving this signal, the
* listener must check {@link VcnManager} for the current Network policy result for each of its
* Networks via {@link #applyVcnNetworkPolicy(NetworkCapabilities, LinkProperties)}.
*
* @hide
*/
@SystemApi
public interface VcnNetworkPolicyChangeListener {
/**
* Notifies the implementation that the VCN's underlying Network policy has changed.
*
* After receiving this callback, implementations should get the current {@link
* VcnNetworkPolicyResult} via {@link #applyVcnNetworkPolicy(NetworkCapabilities,
* LinkProperties)}.
*/
void onPolicyChanged();
}
/**
* Add a listener for VCN-underlying Network policy updates.
*
* A {@link VcnNetworkPolicyChangeListener} is eligible to begin receiving callbacks once it
* is registered. No callbacks are guaranteed upon registration.
*
* @param executor the Executor that will be used for invoking all calls to the specified
* Listener
* @param listener the VcnNetworkPolicyChangeListener to be added
* @throws SecurityException if the caller does not have permission NETWORK_FACTORY
* @throws IllegalStateException if the specified VcnNetworkPolicyChangeListener is already
* registered
* @hide
*/
@SystemApi
@RequiresPermission(android.Manifest.permission.NETWORK_FACTORY)
public void addVcnNetworkPolicyChangeListener(
@NonNull Executor executor, @NonNull VcnNetworkPolicyChangeListener listener) {
requireNonNull(executor, "executor must not be null");
requireNonNull(listener, "listener must not be null");
VcnUnderlyingNetworkPolicyListenerBinder binder =
new VcnUnderlyingNetworkPolicyListenerBinder(executor, listener);
if (REGISTERED_POLICY_LISTENERS.putIfAbsent(listener, binder) != null) {
throw new IllegalStateException("listener is already registered with VcnManager");
}
try {
mService.addVcnUnderlyingNetworkPolicyListener(binder);
} catch (RemoteException e) {
REGISTERED_POLICY_LISTENERS.remove(listener);
throw e.rethrowFromSystemServer();
}
}
/**
* Remove the specified VcnNetworkPolicyChangeListener from VcnManager.
*
* If the specified listener is not currently registered, this is a no-op.
*
* @param listener the VcnNetworkPolicyChangeListener that will be removed
* @throws SecurityException if the caller does not have permission NETWORK_FACTORY
* @hide
*/
@SystemApi
@RequiresPermission(android.Manifest.permission.NETWORK_FACTORY)
public void removeVcnNetworkPolicyChangeListener(
@NonNull VcnNetworkPolicyChangeListener listener) {
requireNonNull(listener, "listener must not be null");
VcnUnderlyingNetworkPolicyListenerBinder binder =
REGISTERED_POLICY_LISTENERS.remove(listener);
if (binder == null) {
return;
}
try {
mService.removeVcnUnderlyingNetworkPolicyListener(binder);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Applies the network policy for a {@link android.net.Network} with the given parameters.
*
* Prior to a new NetworkAgent being registered, or upon notification that Carrier VCN policy
* may have changed via {@link VcnNetworkPolicyChangeListener#onPolicyChanged()}, a Network
* Provider MUST poll for the updated Network policy based on that Network's capabilities and
* properties.
*
* @param networkCapabilities the NetworkCapabilities to be used in determining the Network
* policy result for this Network.
* @param linkProperties the LinkProperties to be used in determining the Network policy result
* for this Network.
* @throws SecurityException if the caller does not have permission NETWORK_FACTORY
* @return the {@link VcnNetworkPolicyResult} to be used for this Network.
* @hide
*/
@NonNull
@SystemApi
@RequiresPermission(android.Manifest.permission.NETWORK_FACTORY)
public VcnNetworkPolicyResult applyVcnNetworkPolicy(
@NonNull NetworkCapabilities networkCapabilities,
@NonNull LinkProperties linkProperties) {
requireNonNull(networkCapabilities, "networkCapabilities must not be null");
requireNonNull(linkProperties, "linkProperties must not be null");
final VcnUnderlyingNetworkPolicy policy =
getUnderlyingNetworkPolicy(networkCapabilities, linkProperties);
return new VcnNetworkPolicyResult(
policy.isTeardownRequested(), policy.getMergedNetworkCapabilities());
}
/** @hide */
@Retention(RetentionPolicy.SOURCE)
@IntDef({
VCN_STATUS_CODE_NOT_CONFIGURED,
VCN_STATUS_CODE_INACTIVE,
VCN_STATUS_CODE_ACTIVE,
VCN_STATUS_CODE_SAFE_MODE
})
public @interface VcnStatusCode {}
/**
* Value indicating that the VCN for the subscription group is not configured, or that the
* callback is not privileged for the subscription group.
*/
public static final int VCN_STATUS_CODE_NOT_CONFIGURED = 0;
/**
* Value indicating that the VCN for the subscription group is inactive.
*
* A VCN is inactive if a {@link VcnConfig} is present for the subscription group, but the
* provisioning package is not privileged.
*/
public static final int VCN_STATUS_CODE_INACTIVE = 1;
/**
* Value indicating that the VCN for the subscription group is active.
*
* A VCN is active if a {@link VcnConfig} is present for the subscription, the provisioning
* package is privileged, and the VCN is not in Safe Mode. In other words, a VCN is considered
* active while it is connecting, fully connected, and disconnecting.
*/
public static final int VCN_STATUS_CODE_ACTIVE = 2;
/**
* Value indicating that the VCN for the subscription group is in Safe Mode.
*
* A VCN will be put into Safe Mode if any of the gateway connections were unable to
* establish a connection within a system-determined timeout (while underlying networks were
* available).
*/
public static final int VCN_STATUS_CODE_SAFE_MODE = 3;
/** @hide */
@Retention(RetentionPolicy.SOURCE)
@IntDef({
VCN_ERROR_CODE_INTERNAL_ERROR,
VCN_ERROR_CODE_CONFIG_ERROR,
VCN_ERROR_CODE_NETWORK_ERROR
})
public @interface VcnErrorCode {}
/**
* Value indicating that an internal failure occurred in this Gateway Connection.
*/
public static final int VCN_ERROR_CODE_INTERNAL_ERROR = 0;
/**
* Value indicating that an error with this Gateway Connection's configuration occurred.
*
* For example, this error code will be returned after authentication failures.
*/
public static final int VCN_ERROR_CODE_CONFIG_ERROR = 1;
/**
* Value indicating that a Network error occurred with this Gateway Connection.
*
* For example, this error code will be returned if an underlying {@link android.net.Network}
* for this Gateway Connection is lost, or if an error occurs while resolving the connection
* endpoint address.
*/
public static final int VCN_ERROR_CODE_NETWORK_ERROR = 2;
/**
* VcnStatusCallback is the interface for Carrier apps to receive updates for their VCNs.
*
* VcnStatusCallbacks may be registered before {@link VcnConfig}s are provided for a
* subscription group.
*/
public abstract static class VcnStatusCallback {
private VcnStatusCallbackBinder mCbBinder;
/**
* Invoked when status of the VCN for this callback's subscription group changes.
*
* @param statusCode the code for the status change encountered by this {@link
* VcnStatusCallback}'s subscription group. This value will be one of VCN_STATUS_CODE_*.
*/
public abstract void onStatusChanged(@VcnStatusCode int statusCode);
/**
* Invoked when a VCN Gateway Connection corresponding to this callback's subscription group
* encounters an error.
*
* @param gatewayConnectionName the String GatewayConnection name for the GatewayConnection
* encountering an error. This will match the name for exactly one {@link
* VcnGatewayConnectionConfig} for the {@link VcnConfig} configured for this callback's
* subscription group
* @param errorCode the code to indicate the error that occurred. This value will be one of
* VCN_ERROR_CODE_*.
* @param detail Throwable to provide additional information about the error, or {@code
* null} if none
*/
public abstract void onGatewayConnectionError(
@NonNull String gatewayConnectionName,
@VcnErrorCode int errorCode,
@Nullable Throwable detail);
}
/**
* Registers the given callback to receive status updates for the specified subscription.
*
* Callbacks can be registered for a subscription before {@link VcnConfig}s are set for it.
*
* A {@link VcnStatusCallback} may only be registered for one subscription at a time. {@link
* VcnStatusCallback}s may be reused once unregistered.
*
* A {@link VcnStatusCallback} will only be invoked if the registering package has carrier
* privileges for the specified subscription at the time of invocation.
*
* A {@link VcnStatusCallback} is eligible to begin receiving callbacks once it is registered
* and there is a VCN active for its specified subscription group (this may happen after the
* callback is registered).
*
* {@link VcnStatusCallback#onStatusChanged(int)} will be invoked on registration with the
* current status for the specified subscription group's VCN. If the registrant is not
* privileged for this subscription group, {@link #VCN_STATUS_CODE_NOT_CONFIGURED} will be
* returned.
*
* @param subscriptionGroup The subscription group to match for callbacks
* @param executor The {@link Executor} to be used for invoking callbacks
* @param callback The VcnStatusCallback to be registered
* @throws IllegalStateException if callback is currently registered with VcnManager
*/
public void registerVcnStatusCallback(
@NonNull ParcelUuid subscriptionGroup,
@NonNull Executor executor,
@NonNull VcnStatusCallback callback) {
requireNonNull(subscriptionGroup, "subscriptionGroup must not be null");
requireNonNull(executor, "executor must not be null");
requireNonNull(callback, "callback must not be null");
synchronized (callback) {
if (callback.mCbBinder != null) {
throw new IllegalStateException("callback is already registered with VcnManager");
}
callback.mCbBinder = new VcnStatusCallbackBinder(executor, callback);
try {
mService.registerVcnStatusCallback(
subscriptionGroup, callback.mCbBinder, mContext.getOpPackageName());
} catch (RemoteException e) {
callback.mCbBinder = null;
throw e.rethrowFromSystemServer();
}
}
}
/**
* Unregisters the given callback.
*
* Once unregistered, the callback will stop receiving status updates for the subscription it
* was registered with.
*
* @param callback The callback to be unregistered
*/
public void unregisterVcnStatusCallback(@NonNull VcnStatusCallback callback) {
requireNonNull(callback, "callback must not be null");
synchronized (callback) {
if (callback.mCbBinder == null) {
// no Binder attached to this callback, so it's not currently registered
return;
}
try {
mService.unregisterVcnStatusCallback(callback.mCbBinder);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
} finally {
callback.mCbBinder = null;
}
}
}
/**
* Binder wrapper for added VcnNetworkPolicyChangeListeners to receive signals from System
* Server.
*
* @hide
*/
private static class VcnUnderlyingNetworkPolicyListenerBinder
extends IVcnUnderlyingNetworkPolicyListener.Stub {
@NonNull private final Executor mExecutor;
@NonNull private final VcnNetworkPolicyChangeListener mListener;
private VcnUnderlyingNetworkPolicyListenerBinder(
Executor executor, VcnNetworkPolicyChangeListener listener) {
mExecutor = executor;
mListener = listener;
}
@Override
public void onPolicyChanged() {
BinderUtils.withCleanCallingIdentity(
() -> mExecutor.execute(() -> mListener.onPolicyChanged()));
}
}
/**
* Binder wrapper for VcnStatusCallbacks to receive signals from VcnManagementService.
*
* @hide
*/
@VisibleForTesting(visibility = Visibility.PRIVATE)
public static class VcnStatusCallbackBinder extends IVcnStatusCallback.Stub {
@NonNull private final Executor mExecutor;
@NonNull private final VcnStatusCallback mCallback;
public VcnStatusCallbackBinder(
@NonNull Executor executor, @NonNull VcnStatusCallback callback) {
mExecutor = executor;
mCallback = callback;
}
@Override
public void onVcnStatusChanged(@VcnStatusCode int statusCode) {
BinderUtils.withCleanCallingIdentity(
() -> mExecutor.execute(() -> mCallback.onStatusChanged(statusCode)));
}
// TODO(b/180521637): use ServiceSpecificException for safer Exception 'parceling'
@Override
public void onGatewayConnectionError(
@NonNull String gatewayConnectionName,
@VcnErrorCode int errorCode,
@Nullable String exceptionClass,
@Nullable String exceptionMessage) {
final Throwable cause = createThrowableByClassName(exceptionClass, exceptionMessage);
BinderUtils.withCleanCallingIdentity(
() ->
mExecutor.execute(
() ->
mCallback.onGatewayConnectionError(
gatewayConnectionName, errorCode, cause)));
}
private static Throwable createThrowableByClassName(
@Nullable String className, @Nullable String message) {
if (className == null) {
return null;
}
try {
Class c = Class.forName(className);
return (Throwable) c.getConstructor(String.class).newInstance(message);
} catch (ReflectiveOperationException | ClassCastException e) {
return new RuntimeException(className + ": " + message);
}
}
}
}
*
*
* @throws SecurityException if the caller is not running as the primary user
*/
@NonNull
public List