Keybox User's Guide

How the Keybox Service works

A Keybox can be either a Widevine Keybox or an Android Attestation Keybox.

  • Widevine keybox is used for authenticating a device so it can acquire a license, then that license is used to decrypt DRM-protected contents.
  • Attestation keybox is used for Android keymaster to secure keys on the device.

The Keybox Service lets Android Partners generate Keyboxes for a number of device serial numbers and a particular device family. Android Partners can then install the Keybox on the device with the supplied unique device IDs (e.g. serial number).

How to query the Keybox Service

Set up a project in Google API console and create a project API key. The user must also have a GAIA account and have registered in partner.android.com.

Sample

The following example explains how to query the Keybox Service.

This following example is for the device named "shamu" or Nexus 6.

Generate a new request to create Keyboxes

We want to generate ANDROID ATTESTATION Keyboxes for devices with device serial numbers "123", "777", "888", "999", "aaa", "bbb", "ccc", "ddd", and "eee".

$ curl -X POST https://androidpartner.googleapis.com/v1/keyboxcohorts:streamCreateKeyboxCohort [ { device_name: "shamu", type: "ANDROID_ATTESTATION", device_ids: ["123"] }, { device_name: "shamu", type: "ANDROID_ATTESTATION", device_ids: ["777", "888", "999"] }, { device_name: "shamu", type: "ANDROID_ATTESTATION", device_ids: ["aaa", "bbb", "ccc", "ddd", "eee"] }, ]

The Keybox Service returns

{
  "name": "5197f0b5-acad-4418-a932-4051bfd28ffc"
}

"5197f0b5-acad-4418-a932-4051bfd28ffc" is the Keybox request ID.

Then the client should call Operations to query the Keybox generation status.

Operations

The client can use the company ID, device name and Keybox request ID to query the status of Keybox generation. Format should be //, e.g. "0/shamu/5197f0b5-acad-4418-a932-4051bfd28ffc" If you are unsure what your company ID is, please check with TAM

$ curl https://androidpartner.googleapis.com/v1/operations/keyboxcohort/0/shamu/5197f0b5-acad-4418-a932-4051bfd28ffc

This returns

{
  "name": "keyboxcohort/shamu/5197f0b5-acad-4418-a932-4051bfd28ffc",
  "done": true,
  "response": {
  "@type": "type.googleapis.com/google.rpc.DebugInfo",
  "stackEntries": [
    "\b\u0001\u0012\u0002shamu\u001a$5197f0b5-acad-4418-a932-4051bfd28ffc"
  ],
  "detail": "Google"
  }
}

The operation result can be either an error or a valid response. If done == false, neither error nor response is set. If done == true, exactly one of error or response is set.

Retrieve Keyboxes

The client can use the company ID, device name and the Keybox request ID to retrieve generated Keyboxes.

$ curl "https://androidpartner.googleapis.com/v1/keyboxcohorts/5197f0b5-acad-4418-a932-4051bfd28ffc/keyboxes?device_name=shamu&creator_company_id=0"

Or get single keybox cohort.

$ curl "https://androidpartner.googleapis.com/v1/keyboxcohorts/5197f0b5-acad-4418-a932-4051bfd28ffc?device_name=shamu&creator_company_id=0"

List Keybox generation requests

$ curl https://androidpartner.googleapis.com/v1/keyboxcohorts