Nanny (permission-nanny-sdk)

java.lang.Object
- com.permissionnanny.lib.Nanny

```
public class Nanny
extends Object
```
Permission Nanny

Permission Nanny is an application that can access resources which are protected by permissions on your behalf, so that your application does not need to declare permission usage in your AndroidManifest.xml. With Permission Nanny, it is possible for your application to not require any permissions at all, yet still be able to access permission-protected resources.
From a high-level perspective, Permission Nanny acts as a proxy server between client applications and the Android operating system. When a client needs to access a resource that is protected by Android permissions, the client will send a request to Permission Nanny. Permission Nanny will then show a dialog to the user, asking the user for authorization to grant the client access to the resource. If the user allows the request, Permission Nanny will access the resource and return results to the client; if the user denies the request, Permission Nanny will simply return an error response.

Permission Police Protocol

Clients communicate with Permission Nanny using broadcast Intents following the Permission Police Protocol (PPP). PPP is heavily inspired by HTTP with a few minor tweaks, borrowing attributes such as status codes, headers and entity. There are 3 handshake flows depending on the type of the request - One-shot, Ongoing and Content Query.
If you are not interested in low-level details of how the handshakes are implemented and would like to know how to make requests and listen for responses using the SDK or integrating your application with Permission Nanny, please feel free to skip the rest and proceed to PermissionRequest.

One-shot Request Handshake Flow

A request that accesses a resource at a single point in time - such as WifiRequest.getConnectionInfo() - is considered a one-shot request.
Clients start the flow by broadcasting an Intent to Permission Nanny's ClientRequestReceiver, a BroadcastReceiver that validates incoming Intents. The Intent must contain a PROTOCOL_VERSION String and an ENTITY_BODY Bundle containing valid request metadata. Request metadata must contain a SENDER_IDENTITY so that Permission Nanny knows who sent the request, REQUEST_PARAMS to know what resource to access. Request metadata may contain a REQUEST_REASON String to explain to the user why the client needs access to the resource. The request may also contain a CLIENT_ADDRESS String to tell Permission Nanny where to deliver the response. If CLIENT_ADDRESS is empty, Permission Nanny will not return a response and you will not know the status of your request, nor be able to retrieve the requested resources.
```
  {
      PROTOCOL_VERSION*
      CLIENT_ADDRESS
      ENTITY_BODY* = {
          SENDER_IDENTITY*
          REQUEST_PARAMS*
          REQUEST_REASON
      }
  }
 
```
Permission Nanny will return an authorization response. The response Intent must contain a PROTOCOL_VERSION String, a STATUS_CODE integer similar to HTTP, a CONNECTION String fixed to CLOSE and a SERVER String fixed to AUTHORIZATION_SERVICE. If STATUS_CODE indicates success, the response must contain an ENTITY_BODY Bundle containing the requested resource; otherwise, the response must contain an ENTITY_ERROR.
```
  {
      PROTOCOL_VERSION*
      STATUS_CODE*
      CONNECTION* = CLOSE
      SERVER* = AUTHORIZATION_SERVICE
      ENTITY_BODY
      ENTITY_ERROR
  }
 
```
Privacy and CLIENT_ADDRESS

Because PPP is implemented using broadcast Intents, anyone with the correct IntentFilters could intercept the communication between clients and Permission Nanny. To ensure no 3rd parties can intercept Permission Nanny's responses, whenever the client makes a request, it uses SecureRandom to generate a nonce. The client's response BroadcastReceiver will be listening for Intents whose action and nonce match. This nonce is known as the CLIENT_ADDRESS that the client's response receiver is listening on and is packaged in the request so that Permission Nanny knows where to send responses to.

Ongoing Request Handshake Flow

A request that accesses a stream of resources over a period of time and requires an Android callback - such as LocationRequest.requestLocationUpdates(long, float, Criteria, LocationListener, Looper) is considered an ongoing request.
The requirements for an ongoing request is exactly the same as one-shot requests.
Permission Nanny will return one authorization response followed by a series of resource responses.

Authorization Response

Similar to one-shot responses, the authorization response must contain PROTOCOL_VERSION, STATUS_CODE and SERVER. But it's CONNECTION String must not be set to CLOSE. In addition, it must not contain an ENTITY_BODY; resources are packaged in the subsequent resource responses. It may contain an ENTITY_ERROR if the request failed.
```
  {
      PROTOCOL_VERSION*
      STATUS_CODE*
      SERVER = AUTHORIZATION_SERVICE*
      ENTITY_ERROR
  }
 
```
Resource Response

If the user authorizes the request, a series of resource responses will follow the authorization response. Resource responses must contain PROTOCOL_VERSION, STATUS_CODE, SERVER and ENTITY_BODY. SERVER must not be set to AUTHORIZATION_SERVICE. ENTITY_BODY must contain the requested resource and an ACK_SERVER_ADDRESS, which is used by the client the send acknowledgements for resource responses.
```
  {
      PROTOCOL_VERSION*
      STATUS_CODE*
      SERVER*
      ENTITY_BODY* = {
          ACK_SERVER_ADDRESS*
      }
      ENTITY_ERROR
  }
 
```
Acknowledging Ongoing Resource Responses

When the client receives an ongoing resource response, it must let Permission Nanny know by sending an acknowledgement Intent to Permission Nanny. If no acknowledgement is sent, Permission Nanny will deem the client dormant, stop delivering resources and tell the client to close its connection. The client can make another request to re-establish the connection.
The acknowledgement must contain PROTOCOL_VERSION and CLIENT_ADDRESS.
```
  {
      PROTOCOL_VERSION*
      CLIENT_ADDRESS*
  }
 
```
Content Query Handshake Flow

A request that queries resources stored in ContentProviders is considered a content query. Requests that insert, update and delete resources in ContentProviders are one-shot requests, not content queries.
The requirements for a content query is exactly the same as one-shot requests. Clients start the flow by sending a content query to Permission Nanny. If the user authorizes the query, Permission Nanny will return a content response. The content response must contain an ENTITY_BODY Bundle, which must only contain a ContentRequest.SELECT URI. The client must then make a 2nd request to Permission Nanny's content provider with the URI appended to PROVIDER_AUTHORITY. The 2nd request will be handled by Permission Nanny's ProxyContentProvider which will execute the content query and return results.
```
  {
      PROTOCOL_VERSION*
      STATUS_CODE*
      CONNECTION* = CLOSE
      SERVER* = AUTHORIZATION_SERVICE
      ENTITY_BODY = {
          ContentRequest.SELECT*
      }
      ENTITY_ERROR
  }
 
```
Query URI and CrossProcessCursorWrapper

Android 15 introduced the CrossProcessCursorWrapper, which facilitated sending Cursor data between processes. Permission Nanny uses this mechanism to deliver content resources to the client. After the 1st handshake, Permission Nanny uses SecureRandom to generate a key to cache the query parameters; the key is returned to the client as the ContentRequest.SELECT URI. The client then appends the key to the PROVIDER_AUTHORITY and starts the 2nd handshake with ProxyContentProvider.
If you would like to know how to make requests and listen for responses using the SDK or integrating your application with Permission Nanny, please proceed to PermissionRequest.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ACK_SERVER_ADDRESS` Entity field:
`static String`	`ACTION_GET_PERMISSION_MANIFEST` Broadcast Action: Sent when Permission Nanny wants to know which permissions clients are using.
`static String`	`AUTHORIZATION_SERVICE` Response value: Service that authorizes requests.
`static String`	`CLIENT_ADDRESS` Request field: Address client is listening on.
`static String`	`CLIENT_PERMISSION_MANIFEST_RECEIVER` Server Component that listens for client permission usages.
`static String`	`CLIENT_REQUEST_RECEIVER` Server Component that handles client requests.
`static String`	`CLOSE` Response value: Client shall receive no further responses from the server; it is safe to unregister receivers or unbind services.*
`static String`	`CONNECTION` Response field: Connection options.
`static android.net.Uri`	`DEBUG_PROVIDER`
`static String`	`ENTITY_BODY` Request/Response field: Resource payload.
`static String`	`ENTITY_ERROR` Response field: Error payload.
`static String`	`GPS_STATUS_SERVICE` Response value: Service that delivers GPS status updates.
`static String`	`LOCATION_SERVICE` Response value: Service that delivers location updates.
`static String`	`NMEA_SERVICE` Response value: Service that delivers NMEA updates.
`static String`	`PERMISSION_MANIFEST` Entity field:
`static String`	`PPP_0_1` Request/Response value: Permission Police Protocol v0.1
`static String`	`PROTOCOL_VERSION` Request/Response field: Protocol version of the request the client is using.
`static android.net.Uri`	`PROVIDER`
`static String`	`PROVIDER_AUTHORITY` Authority that resolves to Permission Nanny's proxy content provider.
`static String`	`REQUEST_PARAMS` Entity field:
`static String`	`REQUEST_REASON` Entity field:
`static int`	`SC_BAD_REQUEST` Response value: Server could not process request due to incorrect request parameters.
`static int`	`SC_FORBIDDEN` Response value: User denied your request.
`static int`	`SC_OK` Response value: Request succeeded.
`static int`	`SC_UNAUTHORIZED` Response value: Client is not authorized to make a request.
`static String`	`SENDER_IDENTITY` Entity field:
`static String`	`SERVER` Response field: Service that handled the request.
`static String`	`SERVER_APP_ID` Permission Nanny's Release build application ID.
`static String`	`SERVER_DEBUG_APP_ID` Permission Nanny's Debug build application ID.
`static String`	`SERVER_PACKAGE_NAME` Permission Nanny's root package name.
`static String`	`STATUS_CODE` Response field: Result status code.
`static String`	`TYPE` Entity field:

Constructor Summary

Constructors
Constructor and Description

Nanny()

Constructors
Constructor and Description
`Nanny()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`configureServer(boolean targetDebugBuild)` Configure the SDK to communicate with Permission Nanny's Debug or Release build variant.
`static android.net.Uri`	`getProxyContentProvider()` Return Permission Nanny's proxy content provider's URI, which changes depending on the build variant to avoid conflict with each other.
`static String`	`getServerAppId()` Return Permission Nanny's app ID, which changes depending on the build variant to avoid conflict with each other.
`static boolean`	`isPermissionNannyInstalled(android.content.Context context)` Checks if Permission Nanny is installed.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - PROTOCOL_VERSION
```
public static final String PROTOCOL_VERSION
```
    Request/Response field: Protocol version of the request the client is using. Type: String
    
    See Also:
    
    Constant Field Values
  - PPP_0_1
```
public static final String PPP_0_1
```
    Request/Response value: Permission Police Protocol v0.1
    
    See Also:
    
    Constant Field Values
  - STATUS_CODE
```
public static final String STATUS_CODE
```
    Response field: Result status code. Type: int
    
    See Also:
    
    Constant Field Values
  - SC_OK
```
public static final int SC_OK
```
    Response value: Request succeeded.
    
    See Also:
    
    Constant Field Values
  - SC_BAD_REQUEST
```
public static final int SC_BAD_REQUEST
```
    Response value: Server could not process request due to incorrect request parameters.
    
    See Also:
    
    Constant Field Values
  - SC_UNAUTHORIZED
```
public static final int SC_UNAUTHORIZED
```
    Response value: Client is not authorized to make a request.
    
    See Also:
    
    Constant Field Values
  - SC_FORBIDDEN
```
public static final int SC_FORBIDDEN
```
    Response value: User denied your request.
    
    See Also:
    
    Constant Field Values
  - CLIENT_ADDRESS
```
public static final String CLIENT_ADDRESS
```
    Request field: Address client is listening on.
    
    See Also:
    
    Constant Field Values
  - CONNECTION
```
public static final String CONNECTION
```
    Response field: Connection options. Type: String
    
    See Also:
    
    Constant Field Values
  - CLOSE
```
public static final String CLOSE
```
    Response value: Client shall receive no further responses from the server; it is safe to unregister receivers or unbind services.*
    
    See Also:
    
    Constant Field Values
  - SERVER
```
public static final String SERVER
```
    Response field: Service that handled the request. Type: String
    
    See Also:
    
    Constant Field Values
  - AUTHORIZATION_SERVICE
```
public static final String AUTHORIZATION_SERVICE
```
    Response value: Service that authorizes requests.
    
    See Also:
    
    Constant Field Values
  - LOCATION_SERVICE
```
public static final String LOCATION_SERVICE
```
    Response value: Service that delivers location updates.
    
    See Also:
    
    Constant Field Values
  - GPS_STATUS_SERVICE
```
public static final String GPS_STATUS_SERVICE
```
    Response value: Service that delivers GPS status updates.
    
    See Also:
    
    Constant Field Values
  - NMEA_SERVICE
```
public static final String NMEA_SERVICE
```
    Response value: Service that delivers NMEA updates.
    
    See Also:
    
    Constant Field Values
  - ENTITY_BODY
```
public static final String ENTITY_BODY
```
    Request/Response field: Resource payload. Type: Bundle.
    
    See Also:
    
    Constant Field Values
  - ENTITY_ERROR
```
public static final String ENTITY_ERROR
```
    Response field: Error payload. Type: NannyException.
    
    See Also:
    
    Constant Field Values
  - TYPE
```
public static final String TYPE
```
    Entity field:
    
    See Also:
    
    Constant Field Values
  - REQUEST_PARAMS
```
public static final String REQUEST_PARAMS
```
    Entity field:
    
    See Also:
    
    Constant Field Values
  - REQUEST_REASON
```
public static final String REQUEST_REASON
```
    Entity field:
    
    See Also:
    
    Constant Field Values
  - SENDER_IDENTITY
```
public static final String SENDER_IDENTITY
```
    Entity field:
    
    See Also:
    
    Constant Field Values
  - PERMISSION_MANIFEST
```
public static final String PERMISSION_MANIFEST
```
    Entity field:
    
    See Also:
    
    Constant Field Values
  - ACK_SERVER_ADDRESS
```
public static final String ACK_SERVER_ADDRESS
```
    Entity field:
    
    See Also:
    
    Constant Field Values
  - SERVER_PACKAGE_NAME
```
public static final String SERVER_PACKAGE_NAME
```
    Permission Nanny's root package name.
    
    See Also:
    
    Constant Field Values
  - SERVER_APP_ID
```
public static final String SERVER_APP_ID
```
    Permission Nanny's Release build application ID.
    
    See Also:
    
    Constant Field Values
  - SERVER_DEBUG_APP_ID
```
public static final String SERVER_DEBUG_APP_ID
```
    Permission Nanny's Debug build application ID.
    
    See Also:
    
    Constant Field Values
  - CLIENT_REQUEST_RECEIVER
```
public static final String CLIENT_REQUEST_RECEIVER
```
    Server Component that handles client requests.
    
    See Also:
    
    Constant Field Values
  - CLIENT_PERMISSION_MANIFEST_RECEIVER
```
public static final String CLIENT_PERMISSION_MANIFEST_RECEIVER
```
    Server Component that listens for client permission usages.
    
    See Also:
    
    Constant Field Values
  - ACTION_GET_PERMISSION_MANIFEST
```
public static final String ACTION_GET_PERMISSION_MANIFEST
```
    Broadcast Action: Sent when Permission Nanny wants to know which permissions clients are using.
    
    See Also:
    
    Constant Field Values
  - PROVIDER_AUTHORITY
```
public static final String PROVIDER_AUTHORITY
```
    Authority that resolves to Permission Nanny's proxy content provider.
    
    See Also:
    
    Constant Field Values
  - PROVIDER
```
public static final android.net.Uri PROVIDER
```
  - DEBUG_PROVIDER
```
public static final android.net.Uri DEBUG_PROVIDER
```
- Constructor Detail
  - Nanny
```
public Nanny()
```
- Method Detail
  - configureServer
```
public static void configureServer(boolean targetDebugBuild)
```
    Configure the SDK to communicate with Permission Nanny's Debug or Release build variant. The Release build is published to app stores, while Debug build is used for development.
    
    Parameters:
    
    targetDebugBuild - true to issue requests to a Debug build, false to target a Release build
  - getServerAppId
```
public static String getServerAppId()
```
    Return Permission Nanny's app ID, which changes depending on the build variant to avoid conflict with each other.
  - getProxyContentProvider
```
public static android.net.Uri getProxyContentProvider()
```
    Return Permission Nanny's proxy content provider's URI, which changes depending on the build variant to avoid conflict with each other.
  - isPermissionNannyInstalled
```
public static boolean isPermissionNannyInstalled(android.content.Context context)
```
    Checks if Permission Nanny is installed.
    
    Parameters:
    
    context - Activity, Service, etc.
    
    Returns:
    
    true if Permission Nanny is installed

Class Nanny

Permission Nanny

Permission Police Protocol

One-shot Request Handshake Flow

Privacy and CLIENT_ADDRESS

Ongoing Request Handshake Flow

Authorization Response

Resource Response

Acknowledging Ongoing Resource Responses

Content Query Handshake Flow

Query URI and CrossProcessCursorWrapper

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PROTOCOL_VERSION

PPP_0_1

STATUS_CODE

SC_OK

SC_BAD_REQUEST

SC_UNAUTHORIZED

SC_FORBIDDEN

CLIENT_ADDRESS

CONNECTION

CLOSE

SERVER

AUTHORIZATION_SERVICE

LOCATION_SERVICE

GPS_STATUS_SERVICE

NMEA_SERVICE

ENTITY_BODY

ENTITY_ERROR

TYPE

REQUEST_PARAMS

REQUEST_REASON

SENDER_IDENTITY

PERMISSION_MANIFEST

ACK_SERVER_ADDRESS

SERVER_PACKAGE_NAME

SERVER_APP_ID

SERVER_DEBUG_APP_ID

CLIENT_REQUEST_RECEIVER

CLIENT_PERMISSION_MANIFEST_RECEIVER

ACTION_GET_PERMISSION_MANIFEST

PROVIDER_AUTHORITY

PROVIDER

DEBUG_PROVIDER

Constructor Detail

Nanny

Method Detail

configureServer

getServerAppId

getProxyContentProvider

isPermissionNannyInstalled