'\" t
.\"     Title: rnpkeys
.\"    Author: RNP
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2023-05-25
.\"    Manual: RNP Manual
.\"    Source: RNP 0.17.0
.\"  Language: English
.\"
.TH "RNPKEYS" "1" "2023-05-25" "RNP 0.17.0" "RNP Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
RNPKEYS \- OpenPGP key management utility.
.SH "SYNOPSIS"
.sp
\fBrnpkeys\fP [\fI\-\-homedir\fP \fIdir\fP] [\fIOPTIONS\fP] \fICOMMAND\fP
.SH "DESCRIPTION"
.sp
The \fIrnpkeys\fP command\-line utility is part of the \fIRNP\fP suite and
provides OpenPGP key management functionality, including:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
key listing;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
key generation;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
key import/export; and
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
key editing.
.RE
.SS "BASICS"
.sp
By default, \fBrnp\fP will apply a \fICOMMAND\fP, additionally configured with \fIOPTIONS\fP,
to all \fIINPUT_FILE\fP(s) or \fIstdin\fP if no \fIINPUT_FILE\fP is given.
There are some special cases for \fIINPUT_FILE\fP :
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI\-\fP (dash) substitutes to \fIstdin\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
env:VARIABLE_NAME substitutes to the contents of environment variable VARIABLE_NAME
.RE
.sp
Depending on the input, output may be written:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
to the specified file with a removed or added file extension (\fI.pgp\fP, \fI.asc\fP, \fI.sig\fP); or
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
to \fIstdout\fP.
.RE
.sp
Without the \fB\-\-armor\fP option, output will be in binary.
.sp
If \fICOMMAND\fP requires public or private keys, \fBrnp\fP will look for the keyrings in \fB~/.rnp\fP. The options \fB\-\-homedir\fP and \fB\-\-keyfile\fP override this (see below).
.sp
If \fICOMMAND\fP needs a password, \fBrnp\fP will ask for it via \fBstdin\fP or \fBtty\fP,
unless the \fB\-\-password\fP or \fB\-\-pass\-fd\fP option was specified.
.sp
By default, \fBrnpkeys\fP will use keyrings stored in the \fI~/.rnp\fP directory.
.sp
This behavior may be overridden with the \fI\-\-homedir\fP option.
.sp
If \fICOMMAND\fP needs a password, the command will prompt the caller
via \fIstdin\fP or \fItty\fP, unless the \fB\-\-password\fP or \fB\-\-pass\-fd\fP
options were also used.
.SS "SPECIFYING KEYS"
.sp
Most \fBrnpkeys\fP commands require a key locator or a filter,
representing one or more keys.
.sp
It may be specified in one of the following ways:
.sp
\fBuserid\fP
.RS 4
Or just part of the \fBuserid\fP.
For \fB"Alice \c
.MTO "alice\(atrnpgp.com" "" ""\fP,"
the following methods are considered identical:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fIalice\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fIalice@rnpgp\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fIrnpgp.com\fP
.RE
.RE
.sp
\fBkeyid\fP
.RS 4
Or its right\-most 8 characters. With or without \fI0x\fP at the beginning and spaces/tabs inside. Such as:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI0x725F6F2D6D5F6120\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI"725F6F2D 6D5F6120"\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI0x6D5F6120\fP
.RE
.RE
.sp
\fBkey fingerprint\fP: The 40\-character key fingerprint, such as:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI"0x416E746F 6E537669 72696465 6E6B6F20"\fP
.RE
.SH "COMMANDS"
.SS "INFORMATIONAL"
.sp
\fB\-h\fP, \fB\-\-help\fP
.RS 4
Displays a short help message. No options are expected.
.RE
.sp
\fB\-V\fP, \fB\-\-version\fP
.RS 4
Displays version information. No options are expected.
.RE
.sp
\fB\-l\fP, \fB\-\-list\-keys\fP
.RS 4
List out keys and some brief information about each.
.br
.sp
Additional options:
.sp
\fB\-\-with\-sigs\fP
.RS 4
Additionally display signatures of listed keys.
.RE
.RE
.SS "KEY GENERATION"
.sp
\fB\-g\fP, \fB\-\-generate\-key\fP
.RS 4
Generate a new keypair.
.br
.sp
Without additional options, an RSA primary key pair with an RSA sub\-key pair will be generated, and prompting for the encryption password afterwards.
.sp
Additional options:
.sp
\fB\-\-numbits\fP
.RS 4
Overrides the default RSA key size of \fB2048\fP bits.
.RE
.sp
\fB\-\-expiration\fP \fITIME\fP
.RS 4
Set key and subkey expiration time, counting from the creation time.
.br
.sp
By default generated keys do not expire.
.br
.sp
Expiration time can be specified as:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
expiration date in the ISO 8601:2019 date format (\fIyyyy\-mm\-dd\fP); or
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
hours/days/months/years since creation time with the syntax of \fI20h\fP/\fI30d\fP/\fI1m\fP/\fI1y\fP;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
number of seconds.
.RE
.RE
.sp
\fB\-\-expert\fP
.RS 4
Select key algorithms interactively and override default settings.
.RE
.sp
\fB\-\-userid\fP
.RS 4
Specifies the \fIuserid\fP to be used in generation.
.RE
.sp
\fB\-\-hash\fP
.RS 4
Specify the hash algorithm used in generation.
.RE
.sp
\fB\-\-cipher\fP
.RS 4
Specify the encryption algorithm used in generation.
.RE
.sp
\fB\-\-s2k\-iterations\fP
.RS 4
Specify the number of iterations for the S2K (string\-to\-key) process.
.br
.sp
This is used during the derivation of the symmetric key, which
encrypts a secret key from the password.
.br
.RE
.sp
\fB\-\-s2k\-msec\fP
.RS 4
Specify that \fBrnpkeys\fP should automatically pick a
\fB\-\-s2k\-iterations\fP value such that the single key derivation operation
would take \fINUMBER\fP of milliseconds on the current system.
.br
.sp
For example, setting it to \fI2000\fP would mean that each secret key
decryption operation would take around 2 seconds (on the current machine).
.RE
.RE
.SS "KEY/SIGNATURE IMPORT"
.sp
\fB\-\-import\fP, \fB\-\-import\-keys\fP, \fB\-\-import\-sigs\fP
.RS 4
Import keys or signatures.
.br
.sp
While \fBrnpkeys\fP automatically detects the input data format,
one may still wish to specify whether the input provides keys or signatures.
.br
.sp
By default, the import process will stop on the first discovered
erroneous key or signature.
.br
.sp
Additional options:
.sp
\fB\-\-permissive\fP
.RS 4
Skip errored or unsupported packets during the import process.
.RE
.RE
.SS "KEY/SIGNATURE EXPORT"
.sp
\fB\-\-export\-key\fP [\fB\-\-userid\fP=\fIFILTER\fP] [\fIFILTER\fP]
.RS 4
Export key(s). Only export keys that match \fIFILTER\fP if \fIFILTER\fP is given.
.br
.sp
If filter matches a primary key, the subkeys of the primary key are also exported.
.sp
By default, key data is written to \fIstdout\fP in ASCII\-armored format.
.sp
Additional options:
.sp
\fB\-\-output\fP \fIPATH\fP
.RS 4
Specifies output to be written to a file name instead of \fIstdout\fP.
.RE
.sp
\fB\-\-secret\fP
.RS 4
Without this option specified, the command will only export public key(s).
This option must be provided to export secret key(s).
.RE
.RE
.sp
\fB\-\-export\-rev\fP \fIKEY\fP
.RS 4
Export the revocation signature for a specified secret key.
.br
.sp
The revocation signature can be used later in a case of key loss or compromise.
.sp
Additional options:
.sp
\fB\-\-rev\-type\fP
.RS 4
Specifies type of key revocation.
.RE
.sp
\fB\-\-rev\-reason\fP
.RS 4
Specifies reason for key revocation.
.RE
.RE
.SS "KEY MANIPULATION"
.sp
\fB\-\-revoke\-key\fP \fIKEY\fP
.RS 4
Issue revocation signature for the secret key, and save it in the keyring.
.br
.sp
Revoked keys cannot be used further.
.br
.sp
Additional options:
.sp
\fB\-\-rev\-type\fP
.RS 4
Specifies type of key revocation, see \fBoptions\fP section for the available values.
.RE
.sp
\fB\-\-rev\-reason\fP
.RS 4
Specifies reason for key revocation.
.RE
.RE
.sp
\fB\-\-remove\-key\fP \fIKEY\fP
.RS 4
Remove the specified key.
.br
.sp
If a primary key is specified, then all of its subkeys are also removed.
.br
.sp
If the specified key is a secret key, then it will not be deleted without
confirmation.
.sp
Additional options:
.sp
\fB\-\-force\fP
.RS 4
Forces removal of a secret key without prompting the user.
.RE
.RE
.sp
\fB\-\-edit\-key\fP \fIKEY\fP
.RS 4
Edit or update information, associated with a key. Should be accompanied with editing option.
.br
.sp
Currently the following options are available:
.br
.sp
\fB\-\-add\-subkey\fP
.RS 4
Generate and add a new subkey to the existing primary key. All additional options for the
\fB\-\-generate\-key\fP command apply for subkey generation as well, except \fB\-\-userid\fP.
.RE
.sp
\fB\-\-check\-cv25519\-bits\fP
.RS 4
Check whether least significant/most significant bits of Curve25519 ECDH subkey are correctly set.
RNP internally sets those bits to required values (3 least significant bits and most significant bit must be zero) during decryption,
however other implementations (GnuPG) may require those bits to be set in key material.
\fIKEY\fP must specify the exact subkey via keyid or fingerprint.
.RE
.sp
\fB\-\-fix\-cv25519\-bits\fP
.RS 4
Set least significant/most significant bits of Curve25519 ECDH subkey to the correct values, and save a key.
So later export of the key would ensure compatibility with other implementations (like GnuPG).
This operation would require the password for your secret key.
Since version 0.16.0 of RNP generated secret key is stored with bits set to a needed value,
however, this may be needed to fix older keys or keys generated by other implementations.
\fIKEY\fP must specify the exact subkey via keyid or fingerprint.
.RE
.sp
\fB\-\-set\-expire\fP \fITIME\fP
.RS 4
Set key expiration time. See the description of the \fB\-\-expiration\fP option for possible time formats.
Setting argument to 0 removes key expiration, the key would never expire. It is not recommended
due to security reasons.
.RE
.RE
.SS "OPTIONS"
.sp
\fB\-\-homedir\fP \fIDIR\fP
.RS 4
Change homedir (where RNP looks for keyrings) to the specified value.
.br
.sp
The default homedir is \fI~/.rnp\fP .
.RE
.sp
\fB\-\-output\fP \fIPATH\fP
.RS 4
Write data processing related output to the file specified.
.br
.sp
Combine it with \fB\-\-overwrite\fP to overwrite file if it already exists.
.RE
.sp
\fB\-\-overwrite\fP
.RS 4
Overwrite output file if it already exists.
.br
.RE
.sp
\fB\-\-userid\fP \fIUSERID\fP
.RS 4
Use the specified \fIuserid\fP during key generation and in some
key\-searching operations.
.RE
.sp
\fB\-\-numbits\fP \fIBITS\fP
.RS 4
Specify size in bits for the generated key and subkey.
.br
.sp
\fIbits\fP may be in range \fB1024\fP\-\fB16384\fP, as long as the public key algorithm
does not place additional limits.
.RE
.sp
\fB\-\-cipher\fP \fIALGORITHM\fP
.RS 4
Set the key encryption algorithm. This is only used in key generation.
.br
.sp
The default value is \fIAES256\fP.
.RE
.sp
\fB\-\-hash\fP \fIALGORITHM\fP
.RS 4
Use the specified hash algorithm for signatures and derivation of the encrypting key from password for secret key encryption.
.br
.sp
The default value is \fISHA256\fP.
.RE
.sp
\fB\-\-expert\fP
.RS 4
Use the \fBexpert key generation\fP mode, allowing the selection of
key/subkey algorithms.
.br
.sp
The following types of keys can be generated in this mode:
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBDSA\fP key with \fBElGamal\fP encryption subkey
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBDSA\fP key with \fBRSA\fP subkey
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBECDSA\fP key with \fBECDH\fP subkey
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBEdDSA\fP key with \fBx25519\fP subkey
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBSM2\fP key with subkey
.RE
.sp
Specifically, for \fBECDSA\fP and \fBECDH\fP the underlying curve can also be specified:
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fINIST P\-256\fP, \fINIST P\-384\fP, \fINIST P\-521\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fIbrainpoolP256r1\fP, \fIbrainpoolP384r1\fP, \fIbrainpoolP512r1\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fIsecp256k1\fP
.RE
.RE
.sp
\fB\-\-pass\-fd\fP \fIFD\fP
.RS 4
Specify a file descriptor to read passwords from instead of from \fIstdin\fP/\fItty\fP.
.br
.sp
Useful for automated or non\-interactive sessions.
.RE
.sp
\fB\-\-password\fP \fIPASSWORD\fP
.RS 4
Use the specified password when it is needed.
.br
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Warning
.ps -1
.br
.sp
Not recommended for production use due to potential security issues.
Use \fB\-\-pass\-fd\fP for batch operations instead.
.sp .5v
.RE
.RE
.sp
\fB\-\-with\-sigs\fP
.RS 4
Print signature information when listing keys via the \fB\-l\fP command.
.RE
.sp
\fB\-\-force\fP
.RS 4
Force actions to happen without prompting the user.
.br
.sp
This applies to cases such as secret key removal, revoking an already revoked key and so on.
.RE
.sp
\fB\-\-permissive\fP
.RS 4
Skip malformed or unknown keys/signatures during key import.
.br
.sp
By default, \fBrnpkeys\fP will stop on the first erroring packet
and exit with an error.
.RE
.sp
\fB\-\-rev\-type\fP \fITYPE\fP
.RS 4
Use the specified type during revocation signature generation instead of the default \fI0\fP.
.br
.sp
The following values are supported:
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
0, or "no": no revocation type specified.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
1, or "superseded": key was superseded with another key.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
2, or "compromised": key was compromised and no longer valid.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
3, or "retired": key is retired.
.RE
.sp
Please refer to \fBIETF RFC 4880\fP for details.
.RE
.sp
\fB\-\-rev\-reason\fP \fIREASON\fP
.RS 4
Add the specified human\-readable revocation \fIREASON\fP to the
signature instead of an empty string.
.RE
.sp
\fB\-\-s2k\-iterations\fP \fINUMBER\fP
.RS 4
Specify the number of iterations for the S2K (string\-to\-key) process.
.br
.sp
This is used during the derivation of the symmetric key, which
encrypts a secret key from the password.
.br
.sp
Please refer to IETF RFC 4880 for further details.
.RE
.sp
\fB\-\-s2k\-msec\fP \fINUMBER\fP
.RS 4
Specify that \fBrnpkeys\fP should automatically pick a
\fB\-\-s2k\-iterations\fP value such that the single key derivation operation
would take \fINUMBER\fP of milliseconds on the current system.
.br
.sp
For example, setting it to \fI2000\fP would mean that each secret key
decryption operation would take around 2 seconds (on the current machine).
.RE
.sp
\fB\-\-notty\fP
.RS 4
Disable use of tty.
.br
.sp
By default RNP would detect whether TTY is attached and use it for user prompts.
.br
.sp
This option overrides default behaviour so user input may be passed in batch mode.
.RE
.sp
\fB\-\-current\-time\fP \fITIME\fP
.RS 4
Override system\(cqs time with a specified value.
.br
.sp
By default RNP uses system\(cqs time in all signature/key checks, however in some scenarios it could be needed to override this.
.br
.sp
\fBTIME\fP could be specified in the ISO 8601\-1:2019 date format (\fIyyyy\-mm\-dd\fP), or in the UNIX timestamp format.
.RE
.SH "EXIT STATUS"
.sp
\fI0\fP
.RS 4
Success.
.RE
.sp
\fINon\-zero\fP
.RS 4
Failure.
.RE
.SH "EXAMPLES"
.sp
The following examples demonstrate method of usage of the \fIrnpkeys\fP command.
.SS "EXAMPLE 1: IMPORT EXISTING KEYS FROM THE GNUPG"
.sp
Following oneliner may be used to import all public keys from the GnuPG:
.sp
\fBgpg\fP \fB\-a\fP \fB\-\-export\fP | \fBrnpkeys\fP \fB\-\-import\fP \fI\-\fP
.sp
To import all secret keys the following command should be used (please note, that you\(cqll be asked for secret key password(s)):
.sp
\fBgpg\fP \fB\-a\fP \fB\-\-export\-secret\-keys\fP | \fBrnpkeys\fP \fB\-\-import\fP \fI\-\fP
.SS "EXAMPLE 2: GENERATE A NEW KEY"
.sp
This example generates a new key with specified userid and expiration.
Also it enables "expert" mode, allowing the selection of key/subkey algorithms.
.sp
\fBrnpkeys\fP \fB\-\-generate\fP \fB\-\-userid\fP \fB"\c
.MTO "john\(atdoe.com" "" ""\fP"
\fB\-\-expert\fP \fB\-\-expiration\fP \fB1y\fP
.SH "BUGS"
.sp
Please report \fIissues\fP via the RNP public issue tracker at:
.URL "https://github.com/rnpgp/rnp/issues" "" "."
.sp
\fISecurity reports\fP or \fIsecurity\-sensitive feedback\fP should be reported
according to the instructions at:
.URL "https://www.rnpgp.org/feedback" "" "."
.SH "AUTHORS"
.sp
\fBRNP\fP is an open source project led by Ribose and has
received contributions from numerous individuals and
organizations.
.SH "RESOURCES"
.sp
\fBWeb site\fP: \c
.URL "https://www.rnpgp.org" "" ""
.sp
\fBSource repository\fP: \c
.URL "https://github.com/rnpgp/rnp" "" ""
.SH "COPYING"
.sp
Copyright (C) 2017\-2021 Ribose.
The RNP software suite is \fIfreely licensed\fP:
please refer to the \fBLICENSE\fP file for details.
.SH "SEE ALSO"
.sp
\fBrnp(1)\fP, \fBlibrnp(3)\fP
.SH "AUTHOR"
.sp
RNP