symbol Asset 1

rnpkeys(1)

01 Jun 2021

NAME

RNPKEYS - OpenPGP key management utility.

SYNOPSIS

rnpkeys [--homedir dir] [OPTIONS] COMMAND

DESCRIPTION

The rnpkeys command-line utility is part of the RNP suite and provides OpenPGP key management functionality, including:

  • key listing;

  • key generation;

  • key import/export; and

  • key editing.

BASICS

By default, rnp will apply a COMMAND, additionally configured with OPTIONS, to all INPUT_FILE(s) or stdin if no INPUT_FILE is given.

Depending on the input, output may be written:

  • to the specified file with a removed or added file extension (.pgp, .asc, .sig); or

  • to stdout.

Without the --armor option, output will be in binary.

If COMMAND requires public or private keys, rnp will look for the keyrings in ~/.rnp. The options --homedir and --keyfile override this (see below).

If COMMAND needs a password, rnp will ask for it via stdin or tty, unless the --password or --pass-fd option was specified.

By default, rnpkeys will use keyrings stored in the ~/.rnp directory.

This behavior may be overridden with the --homedir option.

If COMMAND needs a password, the command will prompt the caller via stdin or tty, unless the --password or --pass-fd options were also used.

SPECIFYING KEYS

Most rnpkeys commands require a key locator or a filter, representing one or more keys.

It may be specified in one of the following ways:

userid

Or just part of the userid. For "Alice <alice@rnpgp.com>", the following methods are considered identical:

  • alice

  • alice@rnpgp

  • rnpgp.com

keyid

Or its right-most 8 characters. With or without 0x at the beginning and spaces/tabs inside. Such as:

  • 0x725F6F2D6D5F6120

  • "725F6F2D 6D5F6120"

  • 0x6D5F6120

key fingerprint: The 40-character key fingerprint, such as:

  • "0x416E746F 6E537669 72696465 6E6B6F20"

COMMANDS

INFORMATIONAL

-h, --help

Displays a short help message. No options are expected.

-V, --version

Displays version information. No options are expected.

-l, --list-keys

List out keys and some brief information about each.

Additional options:

--with-sigs

Additionally display signatures of listed keys.

KEY GENERATION

-g, --generate-key

Generate a new keypair.

Without additional options, an RSA primary key pair with an RSA sub-key pair will be generated, and prompting for the encryption password afterwards.

Additional options:

--numbits

Overrides the default RSA key size of 2048 bits.

--expert

Select key algorithms interactively and override default settings.

--userid

Specifies the userid to be used in generation.

--hash

Specify the hash algorithm used in generation.

--cipher

Specify the encryption algorithm used in generation.

--s2k-iterations

Specify the number of iterations for the S2K (string-to-key) process.

This is used during the derivation of the symmetric key, which encrypts a secret key from the password.

--s2k-msec

Specify that rnpkeys should automatically pick a --s2k-iterations value such that the single key derivation operation would take NUMBER of milliseconds on the current system.

For example, setting it to 2000 would mean that each secret key decryption operation would take around 2 seconds (on the current machine).

KEY/SIGNATURE IMPORT

--import, --import-keys, --import-sigs

Import keys or signatures.

While rnpkeys automatically detects the input data format, one may still wish to specify whether the input provides keys or signatures.

By default, the import process will stop on the first discovered erroneous key or signature.

Additional options:

--permissive

Skip errored or unsupported packets during the import process.

KEY/SIGNATURE EXPORT

--export-key [--userid=FILTER] [FILTER]

Export key(s). Only export keys that match FILTER if FILTER is given.

If filter matches a primary key, the subkeys of the primary key are also exported.

By default, key data is written to stdout in ASCII-armored format.

Additional options:

--output PATH

Specifies output to be written to a file name instead of stdout.

--secret

Without this option specified, the command will only export public key(s). This option must be provided to export secret key(s).

--export-rev KEY

Export the revocation signature for a specified secret key.

The revocation signature can be used later in a case of key loss or compromise.

Additional options:

--rev-type

Specifies type of key revocation.

--rev-reason

Specifies reason for key revocation.

KEY MANIPULATION

--revoke-key KEY

Issue revocation signature for the secret key, and save it in the keyring.

Revoked keys cannot be used further.

Additional options:

--rev-type

Specifies type of key revocation.

--rev-reason

Specifies reason for key revocation.

--remove-key KEY

Remove the specified key.

If a primary key is specified, then all of its subkeys are also removed.

If the specified key is a secret key, then it will not be deleted without confirmation.

Additional options:

--force

Forces removal of a secret key without prompting the user.

OPTIONS

--homedir DIR

Change homedir (where RNP looks for keyrings) to the specified value.

The default homedir is ~/.rnp .

--output PATH

Write data processing related output to the file specified.

Combine it with --force to overwrite file if it already exists.

--userid USERID

Use the specified userid during key generation and in some key-searching operations.

--numbits BITS

Specify size in bits for the generated key and subkey.

bits may be in range 1024-16384, as long as the public key algorithm does not place additional limits.

--cipher ALGORITHM

Set the key encryption algorithm. This is only used in key generation.

The default value is AES256.

--hash ALGORITHM

Use the specified hash algorithm for signatures and derivation of the encrypting key from password for secret key encryption.

The default value is SHA256.

--expert

Use the expert key generation mode, allowing the selection of key/subkey algorithms.

The following types of keys can be generated in this mode:

  • DSA key with ElGamal encryption subkey

  • DSA key with RSA subkey

  • ECDSA key with ECDH subkey

  • EdDSA key with x25519 subkey

  • SM2 key with subkey

Specifically, for ECDSA and ECDH the underlying curve can also be specified:

  • NIST P-256, NIST P-384, NIST P-521

  • brainpoolP256r1, brainpoolP384r1, brainpoolP512r1

  • secp256k1

--pass-fd FD

Specify a file descriptor to read passwords from instead of from stdin/tty.

Useful for automated or non-interactive sessions.

--password PASSWORD

Use the specified password when it is needed.

Warning
Not recommended for production use due to potential security issues. Use --pass-fd for batch operations instead.
--with-sigs

Print signature information when listing keys via the -l command.

--force

Force actions to happen without prompting the user.

This applies to cases such as output file overwrite, secret key removal, and revoking an already revoked key.

--permissive

Skip malformed or unknown keys/signatures during key import.

By default, rnpkeys will stop on the first erroring packet and exit with an error.

--rev-type TYPE

Use the specified type during revocation signature generation instead of the default 0.

The following values are supported:

  • 0, or "no": no revocation type specified.

  • 1, or "superseded": key was superseded with another key.

  • 2, or "compromised": key was compromised and no longer valid.

  • 3, or "retired": key is retired.

Please refer to IETF RFC 4880 for details.

--rev-reason REASON

Add the specified human-readable revocation REASON to the signature instead of an empty string.

--s2k-iterations NUMBER

Specify the number of iterations for the S2K (string-to-key) process.

This is used during the derivation of the symmetric key, which encrypts a secret key from the password.

Please refer to IETF RFC 4880 for further details.

--s2k-msec NUMBER

Specify that rnpkeys should automatically pick a --s2k-iterations value such that the single key derivation operation would take NUMBER of milliseconds on the current system.

For example, setting it to 2000 would mean that each secret key decryption operation would take around 2 seconds (on the current machine).

EXIT STATUS

0

Success.

Non-zero

Failure.

BUGS

Please report issues via the RNP public issue tracker at: https://github.com/rnpgp/rnp/issues.

Security reports or security-sensitive feedback should be reported according to the instructions at: https://www.rnpgp.org/feedback.

AUTHORS

RNP is an open source project led by Ribose and has received contributions from numerous individuals and organizations.

RESOURCES

COPYING

Copyright (C) 2017-2021 Ribose. The RNP software suite is freely licensed: please refer to the LICENSE file for details.

SEE ALSO

rnp(1), librnp(3)