NAME
    gcloud alpha container binauthz attestors public-keys - create and manage
        public keys associated with Attestation Authorities

SYNOPSIS
    gcloud alpha container binauthz attestors public-keys COMMAND
        [GCLOUD_WIDE_FLAG ...]

EXAMPLES
    GPG is a common tool that implements the PGP standard.
      ▪ For general gpg usage examples, see gcloud alpha container binauthz
        help.
      ▪ For more detailed and complete documentation, see the GPG manual:
        https://gnupg.org/documentation/manuals.html

    To get the fingerprint of the public key:

        $ gpg \
              --with-colons \
              --with-fingerprint \
              --force-v4-certs \
              --list-keys \
              "${ATTESTING_USER}" | grep fpr | cut --delimiter=':' --fields 10

    To export a public key:

        $ gpg \
              --armor \
              --export "${FINGERPRINT}" \
              --output public_key1.pgp

    To add your new key to the attestor:

        $ gcloud alpha container binauthz attestors public-keys add \
              --attestor my_attestor \
              --pgp-public-key-file=public_key1.pgp

    To add a subkey to your PGP key:

        $ gpg \
              --quick-add-key ${FINGERPRINT} \
              default \
              sign
        ... FOLLOW PROMPTS ...

    To revoke a subkey from your PGP key:

        $ gpg \
              --edit-key ${FINGERPRINT}
        ... SNIP ...

        sec  rsa2048/8C124F0F782DA097
             created: 2018-01-01  expires: never       usage: SCEA
             trust: ultimate      validity: ultimate
        ssb  rsa3072/C9597E8F28359AE3
             created: 2018-01-01  expires: never       usage: E
        [ultimate] (1). User <attesting_user@example.com>

        gpg> key C9597E8F28359AE3
        ... SNIP ...
        gpg> revkey
        ... FOLLOW PROMPTS ...

    To update the modified PGP key on the attestor:

        $ gcloud alpha container binauthz attestors public-keys update \
              ${FINGERPRINT} \
              --attestor=my_attestor \
              --pgp-public-key-file=public_key1_updated.pgp

    To remove this new key from the attestor:

        $ gcloud alpha container binauthz attestors public-keys remove \
              ${FINGERPRINT} \
              --attestor my_attestor

GCLOUD WIDE FLAGS
    These flags are available to all commands: --help.

    Run $ gcloud help for details.

COMMANDS
    COMMAND is one of the following:

     add
        (ALPHA) Add a public key to an Attestor.

     remove
        (ALPHA) Remove a public key from an Attestor.

     update
        (ALPHA) Update a public key on an Attestor.

BACKGROUND
    PGP is an encryption standard used by Binary Authorization to create and
    verify attestations. A PGP identity is encapsulated by a "key" which can be
    used to sign arbitrary data and/or verify signatures to be valid. As with
    other asymmetric key cryptosystems, PGP keys have a "public" part and a
    "private" part.

PGP KEY STRUCTURE
    An important feature of PGP keys is that they are hierarchical: Every "PGP
    key" is composed of a "primary" key pair and zero or more "subkey" pairs
    certified by the primary. These key pairs are collectively known as the
    "PGP key." The "public" part of this PGP key contains the public keys of
    all the constituent keys as well as all associated metadata (e.g. an email
    address). And, as might be expected, the "private" part of the PGP key
    contains all constituent private keys and metadata.

    One property of subkeys is that they may be marked as "revoked" if they are
    compromised or otherwise need to be retired. This does not remove the
    subkey from the PGP key but simply adds metadata indicating this
    revocation. The primary key pair cannot be revoked by this same mechanism.

  COMMON KEY STRUCTURE
    The most common key structure is to have the primary key pair only used to
    certify subkey pairs while the subkeys are used to encrypt and sign as
    necessary. This allows the PGP key as a whole to act as a durable identity
    even if an encryption key is used improperly or a signing key is
    compromised.

USAGE IN BINARY AUTHORIZATION
      ▪ Authorities hold a set of PGP public keys that are used to verify
        attestations.
        ◆ These must be submitted in ASCII-armored format. With GPG, this is
          accomplished by adding the --armor flag to the export command.
      ▪ If any of the public keys held by an attestor verify a given
        attestation, then the attestor considers that attestation to be valid
        (see gcloud alpha container binauthz attestations create help for more
        details).
        ◆ As a result, the compromise of any constituent private key means
          that the attestor is at risk. The compromised subkey should be
          revoked and the PGP key re-uploaded or removed from the attestor.

NOTES
    This command is currently in alpha and might change without notice. If this
    command fails with API permission errors despite specifying the correct
    project, you might be trying to access an API with an invitation-only early
    access allowlist. These variants are also available:

        $ gcloud container binauthz attestors public-keys

        $ gcloud beta container binauthz attestors public-keys

