Authorization tokens

Bearer token (JWT: RFC 7516) issued by Google to verify that the caller is authorized to encrypt or decrypt a resource.

To prevent abuse, the Key Access Control List Service (KACLS) should verify that the caller is authorized to encrypt the object (file or document) before wrapping the key and to decrypt it before unwrapping the DEK.

Authorization token for Docs & Drive, Calendar and Meet client-side encryption (CSE)

JSON representation
{
  "aud": string,
  "email": string,
  "email_verification_type": string,
  "exp": string,
  "iat": string,
  "iss": string,
  "kacls_url": string,
  "perimeter_id": string,
  "resource_name": string,
  "role": string
}
Fields
aud

string

The audience, as identified by Google. Should be checked against the local configuration.

email

string (UTF-8)

The user's email address.

email_verification_type

string

Contains one of the follow values:

  • google: This email belongs to a Google Account.
  • google-visitor: This email doesn't belong to a Google Account, but was PIN-code verified by Google.
  • customer-idp: This email doesn't belong to a Google Account, but the user's email was extracted using a customer-configured IdP.
  • The claim can be unset; in that case the default value is `google`.
exp

string

Expiration time.

iat

string

Issuance time.

iss

string

The token issuer. Should be validated against the trusted set of authentication issuers.

kacls_url

string

The configured base KACLS URL, used to prevent person-in-the-middle (PITM) attacks.

perimeter_id

string (UTF-8)

(Optional) A value tied to the document location that can be used to choose which perimeter will be checked when unwrapping. Maximum size: 128 bytes.

resource_name

string (UTF-8)

An identifier for the object encrypted by the DEK. Maximum size: 128 bytes.

role

string

Contains one of the follow values:

  • reader: Allowed to call unwrap only.
  • writer: Allowed to call both wrap and unwrap

Authorization token for Gmail CSE

JSON representation
{
  "aud": string,
  "email": string,
  "exp": string,
  "iat": string,
  "message_id": string,
  "iss": string,
  "kacls_url": string,
  "perimeter_id": string,
  "resource_name": string,
  "role": string,
  "spki_hash": string,
  "spki_hash_algorithm": string
}
Fields
aud

string

The audience, as identified by Google. Should be checked against the local configuration.

email

string (UTF-8)

The user's email address.

exp

string

Expiration time.

iat

string

Issuance time.

message_id

string

An identifier for the message on which the decryption or signing is performed. Used as client reason for auditing purposes.

iss

string

The token issuer. Should be validated against the trusted set of authentication issuers.

kacls_url

string

The configured base KACLS URL, used to prevent person-in-the-middle (PITM) attacks.

perimeter_id

string (UTF-8)

(Optional) A value tied to the document location that can be used to choose which perimeter is checked when unwrapping. Maximum size: 128 bytes.

resource_name

string (UTF-8)

An identifier for the object encrypted by the DEK. Maximum size: 512 bytes.

role

string

Contains one of the follow values:

  • descrypter: Can decrypt.
  • signer: Can sign.
spki_hash

string

Standard base64-encoded digest of the DER-encoded SubjectPublicKeyInfo of the private key being accessed.

spki_hash_algorithm

string

Algorithm used to produce spki_hash. Can be SHA-256.

Authorization token for KACLS migration service

JSON representation
{
  "aud": string,
  "email": string,
  "exp": string,
  "iat": string,
  "iss": string,
  "kacls_url": string,
  "resource_name": string,
  "role": string
}
Fields
aud

string

The audience, as identified by Google. Should be checked against the local configuration.

email

string (UTF-8)

The user's email address.

exp

string

Expiration time.

iat

string

Issuance time.

iss

string

The token issuer. Should be validated against the trusted set of authentication issuers.

kacls_url

string

The configured base KACLS URL, used to prevent person-in-the-middle (PITM) attacks.

role

string

Contains one of the follow values:

  • migrator: Allowed to call rewrap only.
  • verifier: Allowed to call digest only.