openpgp-card/tools/scripting.md

Scripting around opgpcard

The opgpcard tool can manipulate an OpenPGP smart card (also known as hardware token). There are various manufacturers of these, but Yubikey by Yubico is well known. The tool is meant to work with any card that implements the OpenPGP smart card interface.

opgpcard supports structured output as JSON and YAML. The default is human readable text. The structured output it meant to be consumed by other programs, and is versioned.

For example, to list all the OpenPGP cards connected to a system:

$ opgpcard --output-format=json list
{
  "schema_version": "1.0.0",
  "idents": [
    "0006:11339805"
  ]
}
$

The structured output is versioned (text output is not), using the field name schema_version. The version numbering follows semantic versionin:

• if a field is added, the minor level is incremented, and patch level is set to zero
• if a field is removed, the major level is incremented, and minor and patch level are set to zero
• if there are changed with no semantic impatc, the patch level is incremented

Each version of opgpcard supports only the latest minor version for each major version. Consumers of the output have to be OK with added fields.

Thus, for example, if the opgpcard list command would add a new field for when the command was run, the output might look like this:

$ opgpcard --output-format=json list
{
  "schema_version": "1.1.0",
  "date": "Tue, 18 Oct 2022 18:07:41 +0300",
  "idents": [
    "0006:11339805"
  ]
}
$

A new field means the minor level in the schema version is incremented.

Legalese

SPDX-FileCopyrightText: 2022 Lars Wirzenius liw@liw.fi SPDX-License-Identifier: MIT OR Apache-2.0