FileDocCategorySizeDatePackage
TrustAgentService.javaAPI DocAndroid 5.1 API13875Thu Mar 12 22:22:10 GMT 2015android.service.trust

TrustAgentService

public class TrustAgentService extends android.app.Service
A service that notifies the system about whether it believes the environment of the device to be trusted.

Trust agents may only be provided by the platform. It is expected that there is only one trust agent installed on the platform. In the event there is more than one, either trust agent can enable trust.

To extend this class, you must declare the service in your manifest file with the {@link android.Manifest.permission#BIND_TRUST_AGENT} permission and include an intent filter with the {@link #SERVICE_INTERFACE} action. For example:

<service android:name=".TrustAgent"
android:label="@string/service_name"
android:permission="android.permission.BIND_TRUST_AGENT">
<intent-filter>
<action android:name="android.service.trust.TrustAgentService" />
</intent-filter>
<meta-data android:name="android.service.trust.trustagent"
android:value="@xml/trust_agent" />
</service>

The associated meta-data file can specify an activity that is accessible through Settings and should allow configuring the trust agent, as defined in {@link android.R.styleable#TrustAgent}. For example:

<trust-agent xmlns:android="http://schemas.android.com/apk/res/android"
android:settingsActivity=".TrustAgentSettings" />
hide

Fields Summary
private final String
TAG
private static final boolean
DEBUG
public static final String
SERVICE_INTERFACE
The {@link Intent} that must be declared as handled by the service.
public static final String
TRUST_AGENT_META_DATA
The name of the {@code meta-data} tag pointing to additional configuration of the trust agent.
private static final int
MSG_UNLOCK_ATTEMPT
private static final int
MSG_CONFIGURE
private static final int
MSG_TRUST_TIMEOUT
private static final int
MSG_DEVICE_LOCKED
private static final int
MSG_DEVICE_UNLOCKED
private ITrustAgentServiceCallback
mCallback
private Runnable
mPendingGrantTrustTask
private boolean
mManagingTrust
private final Object
mLock
private android.os.Handler
mHandler
Constructors Summary
Methods Summary
public final voidgrantTrust(java.lang.CharSequence message, long durationMs, boolean initiatedByUser)
Call to grant trust on the device.

param
message describes why the device is trusted, e.g. "Trusted by location".
param
durationMs amount of time in milliseconds to keep the device in a trusted state. Trust for this agent will automatically be revoked when the timeout expires unless extended by a subsequent call to this function. The timeout is measured from the invocation of this function as dictated by {@link SystemClock#elapsedRealtime())}. For security reasons, the value should be no larger than necessary. The value may be adjusted by the system as necessary to comply with a policy controlled by the system or {@link DevicePolicyManager} restrictions. See {@link #onTrustTimeout()} for determining when trust expires.
param
initiatedByUser this is a hint to the system that trust is being granted as the direct result of user action - such as solving a security challenge. The hint is used by the system to optimize the experience. Behavior may vary by device and release, so one should only set this parameter if it meets the above criteria rather than relying on the behavior of any particular device or release.
throws
IllegalStateException if the agent is not currently managing trust.

        synchronized (mLock) {
            if (!mManagingTrust) {
                throw new IllegalStateException("Cannot grant trust if agent is not managing trust."
                        + " Call setManagingTrust(true) first.");
            }
            if (mCallback != null) {
                try {
                    mCallback.grantTrust(message.toString(), durationMs, initiatedByUser);
                } catch (RemoteException e) {
                    onError("calling enableTrust()");
                }
            } else {
                // Remember trust has been granted so we can effectively grant it once the service
                // is bound.
                mPendingGrantTrustTask = new Runnable() {
                    @Override
                    public void run() {
                        grantTrust(message, durationMs, initiatedByUser);
                    }
                };
            }
        }
public final android.os.IBinderonBind(android.content.Intent intent)

        if (DEBUG) Slog.v(TAG, "onBind() intent = " + intent);
        return new TrustAgentServiceWrapper();
public booleanonConfigure(java.util.List options)
Called when device policy admin wants to enable specific options for agent in response to {@link DevicePolicyManager#setKeyguardDisabledFeatures(ComponentName, int)} and {@link DevicePolicyManager#setTrustAgentConfiguration(ComponentName, ComponentName, PersistableBundle)}.

Agents that support configuration options should overload this method and return 'true'.

param
options bundle containing all options or null if none.
return
true if the {@link TrustAgentService} supports configuration options.

        return false;
public voidonCreate()


    
       
        super.onCreate();
        ComponentName component = new ComponentName(this, getClass());
        try {
            ServiceInfo serviceInfo = getPackageManager().getServiceInfo(component, 0 /* flags */);
            if (!Manifest.permission.BIND_TRUST_AGENT.equals(serviceInfo.permission)) {
                throw new IllegalStateException(component.flattenToShortString()
                        + " is not declared with the permission "
                        + "\"" + Manifest.permission.BIND_TRUST_AGENT + "\"");
            }
        } catch (PackageManager.NameNotFoundException e) {
            Log.e(TAG, "Can't get ServiceInfo for " + component.toShortString());
        }
public voidonDeviceLocked()
Called when the device enters a state where a PIN, pattern or password must be entered to unlock it.
public voidonDeviceUnlocked()
Called when the device leaves a state where a PIN, pattern or password must be entered to unlock it.
private voidonError(java.lang.String msg)

        Slog.v(TAG, "Remote exception while " + msg);
public voidonTrustTimeout()
Called when the timeout provided by the agent expires. Note that this may be called earlier than requested by the agent if the trust timeout is adjusted by the system or {@link DevicePolicyManager}. The agent is expected to re-evaluate the trust state and only call {@link #grantTrust(CharSequence, long, boolean)} if the trust state should be continued.
public voidonUnlockAttempt(boolean successful)
Called after the user attempts to authenticate in keyguard with their device credentials, such as pin, pattern or password.

param
successful true if the user successfully completed the challenge.
public final voidrevokeTrust()
Call to revoke trust on the device.

        synchronized (mLock) {
            if (mPendingGrantTrustTask != null) {
                mPendingGrantTrustTask = null;
            }
            if (mCallback != null) {
                try {
                    mCallback.revokeTrust();
                } catch (RemoteException e) {
                    onError("calling revokeTrust()");
                }
            }
        }
public final voidsetManagingTrust(boolean managingTrust)
Call to notify the system if the agent is ready to manage trust. This property is not persistent across recreating the service and defaults to false. Therefore this method is typically called when initializing the agent in {@link #onCreate}.

param
managingTrust indicates if the agent would like to manage trust.

        synchronized (mLock) {
            if (mManagingTrust != managingTrust) {
                mManagingTrust = managingTrust;
                if (mCallback != null) {
                    try {
                        mCallback.setManagingTrust(managingTrust);
                    } catch (RemoteException e) {
                        onError("calling setManagingTrust()");
                    }
                }
            }
        }