public class AppAuthenticator

Provides methods to verify the signing identity of other apps on the device.

Summary

Constants
static final int

This is returned by checkCallingAppIdentity and checkCallingAppIdentity when the specified package name does not have any of the expected signing identities for the provided permission.
static final int

This is returned by checkCallingAppIdentity and checkCallingAppIdentity when the specified package name does not belong to the provided calling UID, or if the UID is not provided and the specified package name does not belong to the UID of the calling process as returned by getCallingUid.
static final int

This is returned by checkCallingAppIdentity and checkCallingAppIdentity when the specified package name does not belong to an app installed on the device.
static final int

This is returned by checkCallingAppIdentity and checkCallingAppIdentity when the specified package name has the expected signing identity for the provided permission.
static final int

This is returned by checkAppIdentity when the specified package name has the expected signing identity.
static final int

This is returned by checkAppIdentity when the specified package name does not have the expected signing identity.

Public methods
int

Checks the specified packageName has the expected signing identity as specified in the <expected-identity> tag.
int
checkCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission
)

Checks the specified packageName has the expected signing identity for the provided permission.
int
checkCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission,
    int uid
)

Checks the specified packageName running under uid has the expected signing identity for the provided permission.
int
checkCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission,
    int pid,
    int uid
)

Checks the specified packageName running with pid and uid has the expected signing identity for the provided permission.
static @NonNull AppAuthenticator
createFromInputStream(
    @NonNull Context context,
    @NonNull InputStream xmlInputStream
)

Creates a new AppAuthenticator that can be used to guard resources based on package name / signing identity as well as allow verification of expected signing identities before interacting with other apps on a device using the configuration defined in the provided xmlInputStream.
static @NonNull AppAuthenticator
createFromResource(@NonNull Context context, @XmlRes int xmlResource)

Creates a new AppAuthenticator that can be used to guard resources based on package name / signing identity as well as allow verification of expected signing identities before interacting with other apps on a device using the configuration defined in the provided XML resource.
void

Enforces the specified packageName has the expected signing identity as declared in the <expected-identity> tag.
void
enforceCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission
)

Enforces the specified packageName has the expected signing identity for the provided permission.
void
enforceCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission,
    int uid
)

Enforces the specified packageName belongs to the provided uid and has the expected signing identity for the permission.
void
enforceCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission,
    int pid,
    int uid
)

Enforces the specified packageName belongs to the provided pid / uid and has the expected signing identity for the permission.

Constants

PERMISSION_DENIED_NO_MATCH

Added in 1.0.0-beta01
public static final int PERMISSION_DENIED_NO_MATCH = -3

This is returned by checkCallingAppIdentity and checkCallingAppIdentity when the specified package name does not have any of the expected signing identities for the provided permission.

See also
SIGNATURE_NO_MATCH

PERMISSION_DENIED_PACKAGE_UID_MISMATCH

Added in 1.0.0-beta01
public static final int PERMISSION_DENIED_PACKAGE_UID_MISMATCH = -5

This is returned by checkCallingAppIdentity and checkCallingAppIdentity when the specified package name does not belong to the provided calling UID, or if the UID is not provided and the specified package name does not belong to the UID of the calling process as returned by getCallingUid.

PERMISSION_DENIED_UNKNOWN_PACKAGE

Added in 1.0.0-beta01
public static final int PERMISSION_DENIED_UNKNOWN_PACKAGE = -4

This is returned by checkCallingAppIdentity and checkCallingAppIdentity when the specified package name does not belong to an app installed on the device.

See also
SIGNATURE_UNKNOWN_PACKAGE

PERMISSION_GRANTED

Added in 1.0.0-beta01
public static final int PERMISSION_GRANTED = 0

This is returned by checkCallingAppIdentity and checkCallingAppIdentity when the specified package name has the expected signing identity for the provided permission.

SIGNATURE_MATCH

Added in 1.0.0-beta01
public static final int SIGNATURE_MATCH = 0

This is returned by checkAppIdentity when the specified package name has the expected signing identity.

See also
SIGNATURE_MATCH

SIGNATURE_NO_MATCH

Added in 1.0.0-beta01
public static final int SIGNATURE_NO_MATCH = -1

This is returned by checkAppIdentity when the specified package name does not have the expected signing identity.

See also
SIGNATURE_NO_MATCH

Public methods

checkAppIdentity

Added in 1.0.0-beta01
public int checkAppIdentity(@NonNull String packageName)

Checks the specified packageName has the expected signing identity as specified in the <expected-identity> tag.

This method should be used when an app's signing identity must be verified; for instance before a client connects to an exported service this method can be used to verify that the app comes from the expected developer.

Parameters
@NonNull String packageName

the name of the package to be verified
Returns
int

SIGNATURE_MATCH if the specified package has the expected signing identity

checkCallingAppIdentity

Added in 1.0.0-beta01
public int checkCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission
)

Checks the specified packageName has the expected signing identity for the provided permission.

This method should be used for verifying the identity of a package when the UID / PID is not available. For instance, this should be used within an activity that was started with startActivityForResult where the package name is available from getCallingPackage. For instances where the calling UID is available but the calling PID is not available, (checkCallingAppIdentity should be preferred.

Parameters
@NonNull String packageName

the name of the package to be verified
@NonNull String permission

the name of the permission as specified in the XML from which to verify the package / signing identity
Returns
int

PERMISSION_GRANTED if the specified packageName has the expected signing identity for the provided permission,PERMISSION_DENIED_NO_MATCH if the specified packageName does not have the expected signing identity for the provided permission,PERMISSION_DENIED_UNKNOWN_PACKAGE if the specified packageName does not exist on the device,

checkCallingAppIdentity

Added in 1.0.0-beta01
public int checkCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission,
    int uid
)

Checks the specified packageName running under uid has the expected signing identity for the provided permission.

This method should be used for verifying the identity of a package when the UID is available but the PID is not. For instance, this should be used within an activity that is started with setShareIdentityEnabled set to true; the package name would then be accessible via getLaunchedFromPackage and the UID from getLaunchedFromUid.

Parameters
@NonNull String packageName

the name of the package to be verified
@NonNull String permission

the name of the permission as specified in the XML from which to verify the package / signing identity
int uid

the expected uid of the package
Returns
int

PERMISSION_GRANTED if the specified packageName has the expected signing identity for the provided permission,PERMISSION_DENIED_NO_MATCH if the specified packageName does not have the expected signing identity for the provided permission,PERMISSION_DENIED_UNKNOWN_PACKAGE if the specified packageName does not exist on the device,PERMISSION_DENIED_PACKAGE_UID_MISMATCH if the specified uid does not match the uid assigned to the package

checkCallingAppIdentity

Added in 1.0.0-beta01
public int checkCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission,
    int pid,
    int uid
)

Checks the specified packageName running with pid and uid has the expected signing identity for the provided permission.

This method should be used for verifying the identity of a calling process of an IPC.

Parameters
@NonNull String packageName

the name of the package to be verified
@NonNull String permission

the name of the permission as specified in the XML from which to verify the package / signing identity
int pid

the expected pid of the process
int uid

the expected uid of the package
Returns
int

PERMISSION_GRANTED if the specified packageName has the expected signing identity for the provided permission,PERMISSION_DENIED_NO_MATCH if the specified packageName does not have the expected signing identity for the provided permission,PERMISSION_DENIED_UNKNOWN_PACKAGE if the specified packageName does not exist on the device,PERMISSION_DENIED_PACKAGE_UID_MISMATCH if the specified uid does not match the uid assigned to the package

createFromInputStream

Added in 1.0.0-beta01
public static @NonNull AppAuthenticator createFromInputStream(
    @NonNull Context context,
    @NonNull InputStream xmlInputStream
)

Creates a new AppAuthenticator that can be used to guard resources based on package name / signing identity as well as allow verification of expected signing identities before interacting with other apps on a device using the configuration defined in the provided xmlInputStream.

Parameters
@NonNull Context context

the context within which to create the AppAuthenticator
@NonNull InputStream xmlInputStream

the XML InputStream containing the definitions for the permissions and expected identities based on packages / expected signing certificate digests
Returns
@NonNull AppAuthenticator

a new AppAuthenticator that can be used to enforce the signing identities defined in the provided XML InputStream
Throws
androidx.security.app.authenticator.AppAuthenticatorXmlException

if the provided XML InputStream is not in the proper format to create a new AppAuthenticator
java.io.IOException

if an IO error is encountered when attempting to read the XML InputStream

createFromResource

Added in 1.0.0-beta01
public static @NonNull AppAuthenticator createFromResource(@NonNull Context context, @XmlRes int xmlResource)

Creates a new AppAuthenticator that can be used to guard resources based on package name / signing identity as well as allow verification of expected signing identities before interacting with other apps on a device using the configuration defined in the provided XML resource.

Parameters
@NonNull Context context

the context within which to create the AppAuthenticator
@XmlRes int xmlResource

the ID of the XML resource containing the definitions for the permissions and expected identities based on package / expected signing certificate digests
Returns
@NonNull AppAuthenticator

a new AppAuthenticator that can be used to enforce the signing identities defined in the provided XML resource
Throws
androidx.security.app.authenticator.AppAuthenticatorXmlException

if the provided XML resource is not in the proper format to create a new AppAuthenticator
java.io.IOException

if an IO error is encountered when attempting to read the XML resource

enforceAppIdentity

Added in 1.0.0-beta01
public void enforceAppIdentity(@NonNull String packageName)

Enforces the specified packageName has the expected signing identity as declared in the <expected-identity> tag.

This method should be used when an app's signing identity must be verified; for instance before a client connects to an exported service this method can be used to verify that the app comes from the expected developer.

Parameters
@NonNull String packageName

the name of the package to be verified
Throws
java.lang.SecurityException

if the signing identity of the package does not match that defined in the <expected-identity> tag

enforceCallingAppIdentity

Added in 1.0.0-beta01
public void enforceCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission
)

Enforces the specified packageName has the expected signing identity for the provided permission.

This method should be used for verifying the identity of a package when the UID / PID is not available. For instance, this should be used within an activity that was started with startActivityForResult where the package name is available from getCallingPackage. For instances where the calling UID is available but the calling PID is not available, (checkCallingAppIdentity should be preferred.

Parameters
@NonNull String packageName

the name of the package to be verified
@NonNull String permission

the name of the permission as specified in the XML from which to verify the package / signing identity
Throws
java.lang.SecurityException

if the signing identity of the package does not match that defined for the permission

enforceCallingAppIdentity

Added in 1.0.0-beta01
public void enforceCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission,
    int uid
)

Enforces the specified packageName belongs to the provided uid and has the expected signing identity for the permission.

This method should be used for verifying the identity of a package when the UID is available but the PID is not. For instance, this should be used within an activity that is started with setShareIdentityEnabled set to true; the package name would then be accessible via getLaunchedFromPackage and the UID from getLaunchedFromUid.

Parameters
@NonNull String packageName

the name of the package to be verified
@NonNull String permission

the name of the permission as specified in the XML from which to verify the package / signing identity
int uid

the expected uid of the package
Throws
java.lang.SecurityException

if the uid does not belong to the specified package, or if the signing identity of the package does not match that defined for the permission

enforceCallingAppIdentity

Added in 1.0.0-beta01
public void enforceCallingAppIdentity(
    @NonNull String packageName,
    @NonNull String permission,
    int pid,
    int uid
)

Enforces the specified packageName belongs to the provided pid / uid and has the expected signing identity for the permission.

This method should be used for verifying the identity of a calling process of an IPC.

Parameters
@NonNull String packageName

the name of the package to be verified
@NonNull String permission

the name of the permission as specified in the XML from which to verify the package / signing identity
int pid

the expected pid of the process
int uid

the expected uid of the package
Throws
java.lang.SecurityException

if the uid does not belong to the specified package, or if the signing identity of the package does not match that defined for the permission