OpenPGP-card-tools - ArchWiki

Jump to content

# OpenPGP-card-tools

From ArchWiki

Related articles

- GnuPG#Smartcards
- Nitrokey
- OpenPGP
- OpenPGP card
- Smartcards
- YubiKey

Openpgp-card-tools is a software package offering the commandline tool oct(1) for interacting with OpenPGP smartcards (using ccid).

## Installation

Install the openpgp-card-tools package.

## Configuration

The oct(1) tool relies on pcsclite and ccid. It requires to enable and start the `pcscd.socket`.

Note GnuPG by default uses its own, internal CCID driver. It is advisable to configure it to use pcsclite instead.

## Interact with OpenPGP cards

The oct(1) tool provides several subcommands, which provide functionality related to OpenPGP cards:

- oct-list(1) to list connected cards
- oct-status(1) to show information about data on a card
- oct-info(1) to show technical details about a card
- oct-ssh(1) to show a card's authentication key as an SSH public key
- oct-admin(1) to administer data on a card that require the admin PIN
- oct-pin(1) to manage PINs of a card
- oct-decrypt(1) to decrypt data using a card
- oct-sign(1) to sign data using a card
- oct-attestation(1) to attest that keys have been generated on a card (YubiKey only)
- oct-system(1) to interact with low-level card functionality

## Tips and tricks

### Machine readable output

The oct(1) tool offers machine readable output format for all subcommands by using the `--output-format` option.

To list attached cards in JSON output format:

    $ oct --output-format=json list

### Import an OpenPGP private key

With oct-admin-import(1) it is possible to directly import an OpenPGP private key.

To import a private key with the fingerprint `0123456789012345678901234567890123456789` to the card with the identifier `0123:01234567`:

    $ oct admin --card 0123:01234567 import <(gpg --export-secret-key 0123456789012345678901234567890123456789)

### Export SSH public key

With oct-ssh(1) it is possible to export the SSH public key (among other data) for the authentication slot of the card.

The below provides an example with dummy data:

    $ oct ssh

    OpenPGP card 0123:01234567

    Authentication key fingerprint:
    D3C4B18828E34FE079273C27DFEA102BC0BF7122

    SSH public key:
    ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIN3SwnYBGotQMbGxG6VRWc8vj6uq24Q2tUGvjkU4BGCd opgpcard:0123:01234567

To strip all data unnecessary for an `~/.ssh/authorized_keys` file (see ssh(1) § FILES), use the `--key-only` option:

    $ oct ssh -c 0123:01234567 --key-only

    ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIN3SwnYBGotQMbGxG6VRWc8vj6uq24Q2tUGvjkU4BGCd opgpcard:0123:01234567

### Sign data

With oct-sign(1) it is possible to sign data using a signing key on a card.

The following commands use an example card to sign the file `hello.txt`:

    $ echo "hello world" > hello.txt
    $ oct sign --card 0123:01234567 detached hello.txt 2>/dev/null
    Enter User PIN:
    -----BEGIN PGP MESSAGE-----

    wr0EABYKAG8FgmVcxgQJEHwxCjP5RdJLRxQAAAAAAB4AIHNhbHRAbm90YXRpb25z
    LnNlcXVvaWEtcGdwLm9yZ8BSR6PrXSIRnrQl6r6HEetWVjCVXQtR1Z3PzD9EfbWY
    FiEEuFXqMwYb6iFIyl2ufDEKM/lF0ksAAOY2AQC7+Tuh8Gal+kCCfVChD0VV+GUA
    yd+leLeylIySXV7qVwD9H2x5QBrgyF/vODNp1tdorTvPwieV/Bop9FCkHYbHJg8=
    =cOQ/
    -----END PGP MESSAGE-----

### Decrypt encrypted data

With oct-decrypt(1) it is possible to decrypt data using the encryption slot of a card.

In the below example a message is encrypted using sq-encrypt(1), using the OpenPGP public key `archie.pub`.

    $ echo "hey archie" | sq encrypt --recipient-file archie.pub > message.pgp
    $ oct decrypt --card 0123:01234567 message.pgp
    Enter User PIN:
    hey archie

### Switch identities of a Nitrokey Start

The Nitrokey Start offers using three separate identities on a single hardware token, each with their separate signing, encryption and authentication slot. Effectively, this is equal to having three separate OpenPGP smartcards with separate card identifiers.

With oct-system-set-identity(1) it is possible to switch between these identities.

To switch to the second identity, use:

    $ oct system set-identity --card FFFE:01234567 1

To switch back to the first identity, use:

    $ oct system set-identity --card FF01:01234567 0

## Troubleshooting

### Debug smartcard setup

Use oct-list(1) to list all connected cards that are available to pcscd(8). If the connected card is not showing up, it is likely that it is blocked by another process, such as scdaemon. The scdaemon(1) can be terminated using

    $ gpgconf --kill scdaemon

Categories:

- Authentication
- Encryption
- OpenPGP

OpenPGP-card-tools
Add topic