1= rnpkeys(1) 2RNP 3:doctype: manpage 4:release-version: {component-version} 5:man manual: RNP Manual 6:man source: RNP {release-version} 7 8== NAME 9 10RNPKEYS - OpenPGP key management utility. 11 12== SYNOPSIS 13 14*rnpkeys* [_--homedir_ _dir_] [_OPTIONS_] _COMMAND_ 15 16== DESCRIPTION 17 18The _rnpkeys_ command-line utility is part of the _RNP_ suite and 19provides OpenPGP key management functionality, including: 20 21* key listing; 22* key generation; 23* key import/export; and 24* key editing. 25 26 27=== BASICS 28 29By default, *rnp* will apply a _COMMAND_, additionally configured with _OPTIONS_, 30to all _INPUT_FILE_(s) or _stdin_ if no _INPUT_FILE_ is given. 31There are some special cases for _INPUT_FILE_ : 32 33* _-_ (dash) substitutes to _stdin_ 34* env:VARIABLE_NAME substitutes to the contents of environment variable VARIABLE_NAME 35 36Depending on the input, output may be written: 37 38* to the specified file with a removed or added file extension (_.pgp_, _.asc_, _.sig_); or 39* to _stdout_. 40 41Without the *--armor* option, output will be in binary. 42 43If _COMMAND_ requires public or private keys, *rnp* will look for the keyrings in *~/.rnp*. The options *--homedir* and *--keyfile* override this (see below). 44 45If _COMMAND_ needs a password, *rnp* will ask for it via *stdin* or *tty*, 46unless the *--password* or *--pass-fd* option was specified. 47 48 49By default, *rnpkeys* will use keyrings stored in the _~/.rnp_ directory. 50 51This behavior may be overridden with the _--homedir_ option. 52 53If _COMMAND_ needs a password, the command will prompt the caller 54via _stdin_ or _tty_, unless the *--password* or *--pass-fd* 55options were also used. 56 57=== SPECIFYING KEYS 58 59Most *rnpkeys* commands require a key locator or a filter, 60representing one or more keys. 61 62It may be specified in one of the following ways: 63 64*userid*:: 65Or just part of the *userid*. 66For *"Alice <alice@rnpgp.com>"*, the following methods are considered identical: 67 68** _alice_ 69** _alice@rnpgp_ 70** _rnpgp.com_ 71 72*keyid*:: 73Or its right-most 8 characters. With or without _0x_ at the beginning and spaces/tabs inside. Such as: 74 75** _0x725F6F2D6D5F6120_ 76** _"725F6F2D 6D5F6120"_ 77** _0x6D5F6120_ 78 79*key fingerprint*: The 40-character key fingerprint, such as: 80 81** _"0x416E746F 6E537669 72696465 6E6B6F20"_ 82 83 84 85== COMMANDS 86 87=== INFORMATIONAL 88 89*-h*, *--help*:: 90Displays a short help message. No options are expected. 91 92*-V*, *--version*:: 93Displays version information. No options are expected. 94 95*-l*, *--list-keys*:: 96List out keys and some brief information about each. + 97+ 98Additional options: 99 100*--with-sigs*::: 101Additionally display signatures of listed keys. 102 103 104=== KEY GENERATION 105 106*-g*, *--generate-key*:: 107Generate a new keypair. + 108+ 109Without additional options, an RSA primary key pair with an RSA sub-key pair will be generated, and prompting for the encryption password afterwards. 110+ 111Additional options: 112 113*--numbits*::: 114Overrides the default RSA key size of *2048* bits. 115 116*--expiration* _TIME_::: 117Set key and subkey expiration time, counting from the creation time. + 118+ 119By default generated keys do not expire. + 120+ 121Expiration time can be specified as: 122 123* expiration date in the ISO 8601:2019 date format (_yyyy-mm-dd_); or 124* hours/days/months/years since creation time with the syntax of _20h_/_30d_/_1m_/_1y_; 125* number of seconds. 126 127*--expert*::: 128Select key algorithms interactively and override default settings. 129 130*--userid*::: 131Specifies the _userid_ to be used in generation. 132 133*--hash*::: 134Specify the hash algorithm used in generation. 135 136*--cipher*::: 137Specify the encryption algorithm used in generation. 138 139*--s2k-iterations*::: 140Specify the number of iterations for the S2K (string-to-key) process. + 141+ 142This is used during the derivation of the symmetric key, which 143encrypts a secret key from the password. + 144 145*--s2k-msec*::: 146Specify that *rnpkeys* should automatically pick a 147*--s2k-iterations* value such that the single key derivation operation 148would take _NUMBER_ of milliseconds on the current system. + 149+ 150For example, setting it to _2000_ would mean that each secret key 151decryption operation would take around 2 seconds (on the current machine). 152 153 154=== KEY/SIGNATURE IMPORT 155 156*--import*, *--import-keys*, *--import-sigs*:: 157Import keys or signatures. + 158+ 159While *rnpkeys* automatically detects the input data format, 160one may still wish to specify whether the input provides keys or signatures. + 161+ 162By default, the import process will stop on the first discovered 163erroneous key or signature. + 164+ 165Additional options: 166 167*--permissive*::: 168Skip errored or unsupported packets during the import process. 169 170=== KEY/SIGNATURE EXPORT 171 172*--export-key* [*--userid*=_FILTER_] [_FILTER_]:: 173Export key(s). Only export keys that match _FILTER_ if _FILTER_ is given. + 174+ 175If filter matches a primary key, the subkeys of the primary key are also exported. 176+ 177By default, key data is written to _stdout_ in ASCII-armored format. 178+ 179Additional options: 180 181*--output* _PATH_::: 182Specifies output to be written to a file name instead of _stdout_. 183 184*--secret*::: 185Without this option specified, the command will only export public key(s). 186This option must be provided to export secret key(s). 187 188*--export-rev* _KEY_:: 189Export the revocation signature for a specified secret key. + 190+ 191The revocation signature can be used later in a case of key loss or compromise. 192+ 193Additional options: 194 195*--rev-type*::: 196Specifies type of key revocation. 197 198*--rev-reason*::: 199Specifies reason for key revocation. 200 201 202=== KEY MANIPULATION 203 204*--revoke-key* _KEY_:: 205Issue revocation signature for the secret key, and save it in the keyring. + 206+ 207Revoked keys cannot be used further. + 208+ 209Additional options: 210 211*--rev-type*::: 212Specifies type of key revocation, see *options* section for the available values. 213 214*--rev-reason*::: 215Specifies reason for key revocation. 216 217 218*--remove-key* _KEY_:: 219Remove the specified key. + 220+ 221If a primary key is specified, then all of its subkeys are also removed. + 222+ 223If the specified key is a secret key, then it will not be deleted without 224confirmation. 225+ 226Additional options: 227 228*--force*::: 229Forces removal of a secret key without prompting the user. 230 231*--edit-key* _KEY_:: 232Edit or update information, associated with a key. Should be accompanied with editing option. + 233+ 234Currently the following options are available: + 235+ 236*--check-cv25519-bits*::: 237Check whether least significant/most significant bits of Curve25519 ECDH subkey are correctly set. 238RNP internally sets those bits to required values (3 least significant bits and most significant bit must be zero) during decryption, 239however other implementations (GnuPG) may require those bits to be set in key material. 240_KEY_ must specify the exact subkey via keyid or fingerprint. 241 242*--fix-cv25519-bits*::: 243Set least significant/most significant bits of Curve25519 ECDH subkey to the correct values, and save a key. 244So later export of the key would ensure compatibility with other implementations (like GnuPG). 245This operation would require the password for your secret key. 246Since version 0.16.0 of RNP generated secret key is stored with bits set to a needed value, 247however, this may be needed to fix older keys or keys generated by other implementations. 248_KEY_ must specify the exact subkey via keyid or fingerprint. 249 250=== OPTIONS 251 252*--homedir* _DIR_:: 253Change homedir (where RNP looks for keyrings) to the specified value. + 254+ 255The default homedir is _~/.rnp_ . 256 257*--output* _PATH_:: 258Write data processing related output to the file specified. + 259+ 260Combine it with *--overwrite* to overwrite file if it already exists. 261 262*--overwrite*:: 263Overwrite output file if it already exists. + 264+ 265 266*--userid* _USERID_:: 267Use the specified _userid_ during key generation and in some 268key-searching operations. 269 270*--numbits* _BITS_:: 271Specify size in bits for the generated key and subkey. + 272+ 273_bits_ may be in range *1024*-*16384*, as long as the public key algorithm 274does not place additional limits. 275 276*--cipher* _ALGORITHM_:: 277Set the key encryption algorithm. This is only used in key generation. + 278+ 279The default value is _AES256_. 280 281*--hash* _ALGORITHM_:: 282Use the specified hash algorithm for signatures and derivation of the encrypting key from password for secret key encryption. + 283+ 284The default value is _SHA256_. 285 286*--expert*:: 287Use the *expert key generation* mode, allowing the selection of 288key/subkey algorithms. + 289+ 290The following types of keys can be generated in this mode: + 291+ 292-- 293** *DSA* key with *ElGamal* encryption subkey 294** *DSA* key with *RSA* subkey 295** *ECDSA* key with *ECDH* subkey 296** *EdDSA* key with *x25519* subkey 297** *SM2* key with subkey 298-- 299+ 300Specifically, for *ECDSA* and *ECDH* the underlying curve can also be specified: + 301+ 302-- 303** _NIST P-256_, _NIST P-384_, _NIST P-521_ 304** _brainpoolP256r1_, _brainpoolP384r1_, _brainpoolP512r1_ 305** _secp256k1_ 306-- 307 308*--pass-fd* _FD_:: 309Specify a file descriptor to read passwords from instead of from _stdin_/_tty_. + 310+ 311Useful for automated or non-interactive sessions. 312 313*--password* _PASSWORD_:: 314Use the specified password when it is needed. + 315+ 316WARNING: Not recommended for production use due to potential security issues. 317Use *--pass-fd* for batch operations instead. 318 319*--with-sigs*:: 320Print signature information when listing keys via the *-l* command. 321 322*--force*:: 323Force actions to happen without prompting the user. + 324+ 325This applies to cases such as secret key removal, revoking an already revoked key and so on. 326 327*--permissive*:: 328Skip malformed or unknown keys/signatures during key import. + 329+ 330By default, *rnpkeys* will stop on the first erroring packet 331and exit with an error. 332 333*--rev-type* _TYPE_:: 334Use the specified type during revocation signature generation instead of the default _0_. + 335+ 336The following values are supported: + 337+ 338-- 339** 0, or "no": no revocation type specified. 340** 1, or "superseded": key was superseded with another key. 341** 2, or "compromised": key was compromised and no longer valid. 342** 3, or "retired": key is retired. 343-- 344+ 345Please refer to *IETF RFC 4880* for details. 346 347*--rev-reason* _REASON_:: 348Add the specified human-readable revocation _REASON_ to the 349signature instead of an empty string. 350 351*--s2k-iterations* _NUMBER_:: 352Specify the number of iterations for the S2K (string-to-key) process. + 353+ 354This is used during the derivation of the symmetric key, which 355encrypts a secret key from the password. + 356+ 357Please refer to IETF RFC 4880 for further details. 358 359*--s2k-msec* _NUMBER_:: 360Specify that *rnpkeys* should automatically pick a 361*--s2k-iterations* value such that the single key derivation operation 362would take _NUMBER_ of milliseconds on the current system. + 363+ 364For example, setting it to _2000_ would mean that each secret key 365decryption operation would take around 2 seconds (on the current machine). 366 367*--notty*:: 368Disable use of tty. + 369+ 370By default RNP would detect whether TTY is attached and use it for user prompts. + 371+ 372This option overrides default behaviour so user input may be passed in batch mode. 373 374== EXIT STATUS 375 376_0_:: 377 Success. 378 379_Non-zero_:: 380 Failure. 381 382== EXAMPLES 383 384The following examples demonstrate method of usage of the _rnpkeys_ command. 385 386=== EXAMPLE 1: IMPORT EXISTING KEYS FROM THE GNUPG 387 388Following oneliner may be used to import all public keys from the GnuPG: 389 390*gpg* *-a* *--export* | *rnpkeys* *--import* _-_ 391 392To import all secret keys the following command should be used (please note, that you'll be asked for secret key password(s)): 393 394*gpg* *-a* *--export-secret-keys* | *rnpkeys* *--import* _-_ 395 396== BUGS 397 398Please report _issues_ via the RNP public issue tracker at: 399https://github.com/rnpgp/rnp/issues. 400 401_Security reports_ or _security-sensitive feedback_ should be reported 402according to the instructions at: 403https://www.rnpgp.org/feedback. 404 405 406== AUTHORS 407 408*RNP* is an open source project led by Ribose and has 409received contributions from numerous individuals and 410organizations. 411 412 413== RESOURCES 414 415*Web site*: https://www.rnpgp.org 416 417*Source repository*: https://github.com/rnpgp/rnp 418 419 420== COPYING 421 422Copyright \(C) 2017-2021 Ribose. 423The RNP software suite is _freely licensed_: 424please refer to the *LICENSE* file for details. 425 426 427 428== SEE ALSO 429 430*rnp(1)*, *librnp(3)* 431