AppAuthenticator

public class AppAuthenticator
extends Object

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


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

Summary

Constants

int PERMISSION_DENIED_NO_MATCH

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

int PERMISSION_DENIED_PACKAGE_UID_MISMATCH

This is returned by checkCallingAppIdentity(String, String) and checkCallingAppIdentity(String, String, int, int) 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 Binder.getCallingUid().

int PERMISSION_DENIED_UNKNOWN_PACKAGE

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

int PERMISSION_GRANTED

This is returned by checkCallingAppIdentity(String, String) and checkCallingAppIdentity(String, String, int, int) when the specified package name has the expected signing identity for the provided permission.

int SIGNATURE_MATCH

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

int SIGNATURE_NO_MATCH

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

Public methods

int checkAppIdentity(String packageName)

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

int checkCallingAppIdentity(String packageName, String permission, int pid, int uid)

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

int checkCallingAppIdentity(String packageName, String permission)

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

static AppAuthenticator createFromInputStream(Context context, 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 AppAuthenticator createFromResource(Context context, 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 enforceAppIdentity(String packageName)

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

void enforceCallingAppIdentity(String packageName, String permission)

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

void enforceCallingAppIdentity(String packageName, 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.

Inherited methods

Constants

PERMISSION_DENIED_NO_MATCH

public static final int PERMISSION_DENIED_NO_MATCH

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

Constant Value: -3 (0xfffffffd)

PERMISSION_DENIED_PACKAGE_UID_MISMATCH

public static final int PERMISSION_DENIED_PACKAGE_UID_MISMATCH

This is returned by checkCallingAppIdentity(String, String) and checkCallingAppIdentity(String, String, int, int) 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 Binder.getCallingUid().

Constant Value: -5 (0xfffffffb)

PERMISSION_DENIED_UNKNOWN_PACKAGE

public static final int PERMISSION_DENIED_UNKNOWN_PACKAGE

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

Constant Value: -4 (0xfffffffc)

PERMISSION_GRANTED

public static final int PERMISSION_GRANTED

This is returned by checkCallingAppIdentity(String, String) and checkCallingAppIdentity(String, String, int, int) when the specified package name has the expected signing identity for the provided permission.

Constant Value: 0 (0x00000000)

SIGNATURE_MATCH

public static final int SIGNATURE_MATCH

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

Constant Value: 0 (0x00000000)

SIGNATURE_NO_MATCH

public static final int SIGNATURE_NO_MATCH

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

Constant Value: -1 (0xffffffff)

Public methods

checkAppIdentity

public int checkAppIdentity (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
packageName String: the name of the package to be verified

Returns
int SIGNATURE_MATCH if the specified package has the expected signing identity

checkCallingAppIdentity

public int checkCallingAppIdentity (String packageName, 
                String permission, 
                int pid, 
                int uid)

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

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

Parameters
packageName String: the name of the package to be verified

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

pid int: the expected pid of the process

uid int: 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

public int checkCallingAppIdentity (String packageName, 
                String permission)

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

This method should be used when verifying the identity of a calling process of an IPC. This is the same as calling checkCallingAppIdentity(String, String, int, int) with the pid and uid returned by Binder.getCallingPid() and Binder.getCallingUid().

Parameters
packageName String: the name of the package to be verified

permission String: 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,
PERMISSION_DENIED_PACKAGE_UID_MISMATCH if the uid as returned from Binder.getCallingUid() does not match the uid assigned to the package

createFromInputStream

public static AppAuthenticator createFromInputStream (Context context, 
                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
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
AppAuthenticator a new AppAuthenticator that can be used to enforce the signing identities defined in the provided XML InputStream

Throws
AppAuthenticatorXmlException if the provided XML InputStream is not in the proper format to create a new AppAuthenticator
IOException if an IO error is encountered when attempting to read the XML InputStream

createFromResource

public static AppAuthenticator createFromResource (Context context, 
                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
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
AppAuthenticator a new AppAuthenticator that can be used to enforce the signing identities defined in the provided XML resource

Throws
AppAuthenticatorXmlException if the provided XML resource is not in the proper format to create a new AppAuthenticator
IOException if an IO error is encountered when attempting to read the XML resource

enforceAppIdentity

public void enforceAppIdentity (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
packageName String: the name of the package to be verified

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

enforceCallingAppIdentity

public void enforceCallingAppIdentity (String packageName, 
                String permission)

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

This method should be used when verifying the identity of a calling process of an IPC. This is the same as calling enforceCallingAppIdentity(String, String, int, int) with the pid and uid returned by Binder.getCallingPid() and Binder.getCallingUid().

Parameters
packageName String: the name of the package to be verified

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

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

enforceCallingAppIdentity

public void enforceCallingAppIdentity (String packageName, 
                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 when verifying the identity of a calling process of an IPC.

Parameters
packageName String: the name of the package to be verified

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

pid int: the expected pid of the process

uid int: the expected uid of the package

Throws
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