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.
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.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

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.

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.