TestAppAuthenticatorBuilder

public final class TestAppAuthenticatorBuilder
extends Object

java.lang.Object
   ↳ androidx.security.app.authenticator.TestAppAuthenticatorBuilder

Builder class that can be used to facilitate the creation of a new AppAuthenticator which can be configured to meet the requirements of the test. Similar to the AppAuthenticator, the static factory methods for this class require either an XML resource or InputStream containing the app-authenticator configuration allowing verification of your declared config as part of the test.

There are several options to configure the behavior of the resulting AppAuthenticator.

  • setTestPolicy(int) - This sets a generic test policy. POLICY_SIGNATURE_ACCEPTED_FOR_DECLARED_PACKAGES will cause the AppAuthenticator to always return that a queried package has the expected signing identity as long as it is explicitly declared in your configuration; that is, the package must be declared in a package element within either an expected-identity or permission element. POLICY_DENY_ALL will cause the AppAuthenticator to always return that a queried package does not have the expected signing identity regardless of its declaration. These two policies can be used to verify good path and error path for scenarios where the package names can be explicitly declared in the XML configuration.

    POLICY_SIGNATURE_ACCEPTED_FOR_DECLARED_PACKAGES is the default policy when no other options are configured. When any of the other set methods (except for setUidForPackage(String, int)) are invoked they will set the policy to POLICY_CUSTOM.

  • setSignatureAcceptedForPackage(String) - This configures the AppAuthenticator to always return that the specified package has the expected signing identity. Note this still requires the app-authenticator have a path to verify the provided package; that is, the package must either be explicitly declared in a package element or fall under a all-packages element for the query being performed. This is to ensure that a package being verified during the test could also be successfully verified in production for the given query.
  • setSigningIdentityForPackage(String, String) - This sets an explicit signing identity for the provided package; the signing identity should be specified as the SHA-256 digest of the DER encoding of the signing certificate, similar to how digests are specified in the app-authenticator configuration file. While this can be used to set a signing identity to the expected value, this is more often used to set the signing identity to a value that should not be accepted. For instance, a test suite could have a test that verifies a key that is no longer trusted is never added back to the configuration file.
  • setPackageNotInstalled(String) - This configures the AppAuthenticator to treat the specified package as not installed on the device. Since a package that is not installed can result in a different return code from the AppAuthenticator methods this configuration can be used to verify an app's behavior when an expected app is not installed on the device.
  • setUidForPackage(String, int) - The AppAuthenticator will always verify the UID of the calling package matches the specified UID (or Binder.getCallingUid() if a UID is not specified). By default this test AppAuthenticator will use the result of Binder#getCallingUid() as the UID of all queried packages. This method can be used to verify the expected behavior when a calling package's UID does not match the expected UID.

Summary

Constants

int POLICY_CUSTOM

This test policy indicates that the caller will specify the expected results for each package individually.

int POLICY_DENY_ALL

This test policy will cause the AppAuthenticator to return that the signing identity of the package does that match the expect identity from the XML configuration for all queried packages.

int POLICY_SIGNATURE_ACCEPTED_FOR_DECLARED_PACKAGES

This test policy will cause the AppAuthenticator to return a successful signing identity for all packages explicitly declared in the XML configuration.

Public methods

AppAuthenticator build()

Builds an AppAuthenticator with the specified config that can be injected to satisfy test requirements.

static TestAppAuthenticatorBuilder createFromInputStream(Context context, InputStream xmlInputStream)

Returns a new TestAppAuthenticatorBuilder that can be used to create a new AppAuthenticator configured to behave as required for the test.

static TestAppAuthenticatorBuilder createFromResource(Context context, int xmlResource)

Returns a new TestAppAuthenticatorBuilder that can be used to create a new AppAuthenticator configured to behave as required for the test.

TestAppAuthenticatorBuilder setPackageNotInstalled(String packageName)

Treats the provided packageName as not being installed by the resulting AppAuthenticator.

TestAppAuthenticatorBuilder setSignatureAcceptedForPackage(String packageName)

Configures the resulting AppAuthenticator to always return that the signing identity matches the expected value when the specified packageName is queried.

TestAppAuthenticatorBuilder setSigningIdentityForPackage(String packageName, String certDigest)

Sets the provided certDigest as the signing identity for the specified packageName.

TestAppAuthenticatorBuilder setTestPolicy(int testPolicy)

Sets the policy to be used by the AppAuthenticator for the test.

TestAppAuthenticatorBuilder setUidForPackage(String packageName, int uid)

Sets the provided uid as the UID of the specified packageName.

Inherited methods

Constants

POLICY_CUSTOM

public static final int POLICY_CUSTOM

This test policy indicates that the caller will specify the expected results for each package individually. This is the default policy used when a new TestAppAuthenticator is built after calling any of the following: setSigningIdentityForPackage(String, String), setSignatureAcceptedForPackage(String), and setPackageNotInstalled(String). Once the policy has been set to this value it cannot be changed to any of the other policies.

Constant Value: 3 (0x00000003)

POLICY_DENY_ALL

public static final int POLICY_DENY_ALL

This test policy will cause the AppAuthenticator to return that the signing identity of the package does that match the expect identity from the XML configuration for all queried packages.

Constant Value: 2 (0x00000002)

POLICY_SIGNATURE_ACCEPTED_FOR_DECLARED_PACKAGES

public static final int POLICY_SIGNATURE_ACCEPTED_FOR_DECLARED_PACKAGES

This test policy will cause the AppAuthenticator to return a successful signing identity for all packages explicitly declared in the XML configuration. This is the default policy used when a new AppAuthenticator is built without calling setSigningIdentityForPackage(String, String), setSignatureAcceptedForPackage(String), and setPackageNotInstalled(String).

Constant Value: 1 (0x00000001)

Public methods

build

public AppAuthenticator build ()

Builds an AppAuthenticator with the specified config that can be injected to satisfy test requirements.

Returns
AppAuthenticator a new AppAuthenticator that will respond to queries as configured
Throws
AppAuthenticatorXmlException if the provided XML config file is not in the proper format to create a new AppAuthenticator
IOException if an IO error is encountered when attempting to read the XML config file

createFromInputStream

public static TestAppAuthenticatorBuilder createFromInputStream (Context context, 
                InputStream xmlInputStream)

Returns a new TestAppAuthenticatorBuilder that can be used to create a new AppAuthenticator configured to behave as required for the test.

Parameters
context Context: the context within which to create the AppAuthenticator
xmlInputStream InputStream: the XML InputStream containing the definitions for the permissions and expected identities based on packages / expected signing certificate digests
Returns
TestAppAuthenticatorBuilder this instance of the TestAppAuthenticatorBuilder

Throws
AppAuthenticatorXmlException

createFromResource

public static TestAppAuthenticatorBuilder createFromResource (Context context, 
                int xmlResource)

Returns a new TestAppAuthenticatorBuilder that can be used to create a new AppAuthenticator configured to behave as required for the test.

Parameters
context Context: the context within which to create the AppAuthenticator
xmlResource int: the ID of the XML resource containing the definitions for the permissions and expected identities based on package / expected signing certificate digests
Returns
TestAppAuthenticatorBuilder this instance of the TestAppAuthenticatorBuilder

setPackageNotInstalled

public TestAppAuthenticatorBuilder setPackageNotInstalled (String packageName)

Treats the provided packageName as not being installed by the resulting AppAuthenticator.

Parameters
packageName String: the name of the package to be treated as not installed
Returns
TestAppAuthenticatorBuilder this instance of the TestAppAuthenticatorBuilder

setSignatureAcceptedForPackage

public TestAppAuthenticatorBuilder setSignatureAcceptedForPackage (String packageName)

Configures the resulting AppAuthenticator to always return that the signing identity matches the expected value when the specified packageName is queried.

Note, the specified packageName must be defined either explicitly via a package element or implicitly via a all-packages element; this ensures that the XML configuration is correct and that the specified package could be verified on device.

Parameters
packageName String: the name of the package for which the signing identity should be treated as matching the expected value
Returns
TestAppAuthenticatorBuilder this instance of the TestAppAuthenticatorBuilder

setSigningIdentityForPackage

public TestAppAuthenticatorBuilder setSigningIdentityForPackage (String packageName, 
                String certDigest)

Sets the provided certDigest as the signing identity for the specified packageName.

Parameters
packageName String: the name of the package that will use the provided signing identity
certDigest String: the digest to be treated as the signing identity of the specified package
Returns
TestAppAuthenticatorBuilder this instance of the TestAppAuthenticatorBuilder

setTestPolicy

public TestAppAuthenticatorBuilder setTestPolicy (int testPolicy)

Sets the policy to be used by the AppAuthenticator for the test.

Parameters
testPolicy int: the test policy to be used by the {@code AppAuthenticator{}
Returns
TestAppAuthenticatorBuilder this instance of the TestAppAuthenticatorBuilder

setUidForPackage

public TestAppAuthenticatorBuilder setUidForPackage (String packageName, 
                int uid)

Sets the provided uid as the UID of the specified packageName.

This method can be used to verify the scenario where a calling package does not have the expected calling UID.

Parameters
packageName String: the name of the package that will be treated as having the provided uid
uid int: the uid to use for the specified package
Returns
TestAppAuthenticatorBuilder this instance of the TestAppAuthenticatorBuilder