REST Resource: users.settings.cse.keypairs

Resource: CseKeyPair

A client-side encryption S/MIME key pair, which is comprised of a public key, its certificate chain, and metadata for its paired private key. Gmail uses the key pair to complete the following tasks:

  • Sign outgoing client-side encrypted messages.
  • Save and reopen drafts of client-side encrypted messages.
  • Save and reopen sent messages.
  • Decrypt incoming or archived S/MIME messages.

For administrators managing identities and keypairs for users in their organization, requests require authorization with a service account that has domain-wide delegation authority to impersonate users with the https://www.googleapis.com/auth/gmail.settings.basic scope.

For users managing their own identities and keypairs, requests require hardware key encryption turned on and configured.

JSON representation 
{
  "keyPairId": string,
  "pkcs7": string,
  "pem": string,
  "subjectEmailAddresses": [
    string
  ],
  "enablementState": enum (EnablementState),
  "disableTime": string,
  "privateKeyMetadata": [
    {
      object (CsePrivateKeyMetadata)
    }
  ]
}
Fields
keyPairId

string

Output only. The immutable ID for the client-side encryption S/MIME key pair.
pkcs7

string

Input only. The public key and its certificate chain. The chain must be in PKCS#7 format and use PEM encoding and ASCII armor.
pem

string

Output only. The public key and its certificate chain, in PEM format.
subjectEmailAddresses[]

string

Output only. The email address identities that are specified on the leaf certificate.
enablementState

enum (EnablementState)

Output only. The current state of the key pair.
disableTime

string (Timestamp format)

Output only. If a key pair is set to DISABLED, the time that the key pair's state changed from ENABLED to DISABLED. This field is present only when the key pair is in state DISABLED.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
privateKeyMetadata[]

object (CsePrivateKeyMetadata)

Metadata for instances of this key pair's private key.

EnablementState

The enumeration for the current state of the key pair.

Enums
stateUnspecified The current state of the key pair is not set. The key pair is neither turned on nor turned off.
enabled

The key pair is turned on. For any email messages that this key pair encrypts, Gmail decrypts the messages and signs any outgoing mail with the private key.

To turn on a key pair, use the keypairs.enable method.
disabled

The key pair is turned off. Authenticated users cannot decrypt email messages nor sign outgoing messages. If a key pair is turned off for more than 30 days, you can permanently delete it.

To turn off a key pair, use the keypairs.disable method.

CsePrivateKeyMetadata

Metadata for a private key instance.

JSON representation 
{
  "privateKeyMetadataId": string,

  // Union field metadata_variant can be only one of the following:
  "kaclsKeyMetadata": {
    object (KaclsKeyMetadata)
  },
  "hardwareKeyMetadata": {
    object (HardwareKeyMetadata)
  }
  // End of list of possible types for union field metadata_variant.
}
Fields
privateKeyMetadataId

string

Output only. The immutable ID for the private key metadata instance.
Union field metadata_variant. Union field: Exactly one of the following metadata variant types must be present. metadata_variant can be only one of the following:
kaclsKeyMetadata

object (KaclsKeyMetadata)

Metadata for a private key instance managed by an external key access control list service.
hardwareKeyMetadata

object (HardwareKeyMetadata)

Metadata for hardware keys.

KaclsKeyMetadata

Metadata for private keys managed by an external key access control list service. For details about managing key access, see Google Workspace CSE API Reference.

JSON representation 
{
  "kaclsUri": string,
  "kaclsData": string
}
Fields
kaclsUri

string

The URI of the key access control list service that manages the private key.
kaclsData

string

Opaque data generated and used by the key access control list service. Maximum size: 8 KiB.

HardwareKeyMetadata

Metadata for hardware keys.

If hardware key encryption is set up for the Google Workspace organization, users can optionally store their private key on their smart card and use it to sign and decrypt email messages in Gmail by inserting their smart card into a reader attached to their Windows device.

JSON representation 
{
  "description": string
}
Fields
description

string

Description about the hardware key.

Methods

create

 Creates and uploads a client-side encryption S/MIME public key certificate chain and private key metadata for the authenticated user.

disable

 Turns off a client-side encryption key pair.

enable

 Turns on a client-side encryption key pair that was turned off.

get

 Retrieves an existing client-side encryption key pair.

list

 Lists client-side encryption key pairs for an authenticated user.

obliterate

 Deletes a client-side encryption key pair permanently and immediately.