Method: rewrap

Re-encrypts an encrypted Data Encryption Key (DEK).

Use this method to migrate from an old Key Access Control List Service (KACLS) to a new KACLS, taking a DEK wrapped with the old KACLS wrap method, and returns a DEK wrapped with the new KACLS wrap method.

HTTP request

POST https://<kacls_url>/rewrap

Path parameters

None.

Request body

The request body contains data with the following structure:

JSON representation
{
  "authorization": string,
  "original_kacls_url": string,
  "reason": string,
  "wrapped_key": string
}
Fields
authorization

string

A JWT asserting that the user is allowed to unwrap a key for resource_name. See authorization tokens.

original_kacls_url

string

URL of current wrapped_key's KACLS.

reason

string (UTF-8)

A passthrough JSON string providing additional context about the operation. The JSON provided should be sanitized before being displayed. Max size: 1 KB.

wrapped_key

string

The base64 binary object returned by wrap.

Response body

If successful, this method returns an opaque binary object that will be stored by Google Workspace along the encrypted object and sent as-is in any subsequent key unwrapping operation. It should also return a checksum of the unwrapped DEK with the resource_name and "KaclMigration" prepended in order to allow validation of correctness.

The binary object should contain the only copy of the encrypted DEK, implementation specific data can be stored in it.

Do not store the DEK in your KACLS system, instead encrypt it and return it in the wrapped_key object. This prevents lifetime discrepancies between the document and its keys to ensure, for example, that the user's data is fully wiped out when they request it or that previous versions restored from a backup will be decryptable.

If the operation fails, a structured error reply should be returned.

JSON representation
{
  "checksum": string,
  "wrapped_key": string
}
Fields
checksum

string

SHA-256 of the unwrapped DEK with the Resource ID and "KaclMigration" prepended. This string should be a 43-character base64 string.

wrapped_key

string

The base64 encoded binary object. Max size: 1 KB.

Example

Request

POST https://mykacls.example.com/v1/rewrap

{
   "wrapped_key": "7qTh6Mp+svVwYPlnZMyuj8WHTrM59wl/UI50jo61Qt/QubZ9tfsUc1sD62xdg3zgxC9quV4r+y7AkbfIDhbmxGqP64pWbZgFzOkP0JcSn+1xm/CB2E5IknKsAbwbYREGpiHM3nzZu+eLnvlfbzvTnJuJwBpLoPYQcnPvcgm+5gU1j1BjUaNKS/uDn7VbVm7hjbKA3wkniORC2TU2MiHElutnfrEVZ8wQfrCEpuWkOXs98H8QxUK4pBM2ea1xxGj7vREAZZg1x/Ci/E77gHxymnZ/ekhUIih6Pwu75jf+dvKcMnpmdLpwAVlE1G4dNginhFVyV/199llf9jmHasQQuaMFzQ9UMWGjA1Hg2KsaD9e3EL74A5fLkKc2EEmBD5v/aP+1RRZ3ISbTOXvxqYIFCdSFSCfPbUhkc9I2nHS0obEH7Q7KiuagoDqV0cTNXWfCGJ1DtIlGQ9IA6mPDAjX8Lg==",
   "authorization": "eyJhbGciOi…"
   "original_kacls_url": "https://<kacl1_base_url>"
   "reason": "{client:'drive' op:'read'}"
}

Response

{
    "wrapped_key": "3qTh6Mp+svPwYPlnZMyuj8WHTrM59wl/UI50jo61Qt/QubZ9tfsUc1sD62xdg3zgxC9quV4r+y7AkbfIDhbmxGqP64pWbZgFzOkP0JcSn+1xm/CB2E5IknKsAbwbYREGpiHM3nzZu+eLnvlfbzvTnJuJwBpLoPYQcnPvcgm+5gU1j1BjUaNKS/uDn7VbVm7hjbKA3wkniORC2TU2MiHElutnfrEVZ8wQfrCEpuWkOXs98H8QxUK4pBM2ea1xxGj7vREAZZg1x/Ci/E77gHxymnZ/ekhUIih6Pwu75jf+dvKcMnpmdLpwAVlE1G4dNginhFVyV/199llf9jmHasQQuaMFzQ9UMWGjA1Hg2KsaD9e3EL74A5fLkKc2EEmBD5v/aP+1RRZ3ISbTOXvxqYIFCdSFSCfPbUhkc9I2nHS0obEH7Q7KiuagoDqV0cTNXWfCGJ1DtIlGQ9IA6mPDAjX8Lg=="
    "checksum": "4973b23de90101423de73b994ae273b0194ae273b94ae24ae273423de9b94ae2"
}