1RNPKEYS(1) RNP Manual RNPKEYS(1)
2
6 RNPKEYS - OpenPGP key management utility.
7
9 rnpkeys [--homedir dir] [OPTIONS] COMMAND
10
12 The rnpkeys command-line utility is part of the RNP suite and provides
13 OpenPGP key management functionality, including:
14 • key listing;
16 • key generation;
18 • key import/export; and
20 • key editing.
22 BASICS
24 By default, rnp will apply a COMMAND, additionally configured with
25 OPTIONS, to all INPUT_FILE(s) or stdin if no INPUT_FILE is given. There
26 are some special cases for INPUT_FILE :
27 • - (dash) substitutes to stdin
29 • env:VARIABLE_NAME substitutes to the contents of environment
31 variable VARIABLE_NAME
32 Depending on the input, output may be written:
34 • to the specified file with a removed or added file extension (.pgp,
36 .asc, .sig); or
37 • to stdout.
39 Without the --armor option, output will be in binary.
41 If COMMAND requires public or private keys, rnp will look for the
43 keyrings in ~/.rnp. The options --homedir and --keyfile override this
44 (see below).
45 If COMMAND needs a password, rnp will ask for it via stdin or tty,
47 unless the --password or --pass-fd option was specified.
48 By default, rnpkeys will use keyrings stored in the ~/.rnp directory.
50 This behavior may be overridden with the --homedir option.
52 If COMMAND needs a password, the command will prompt the caller via
54 stdin or tty, unless the --password or --pass-fd options were also
55 used.
56 SPECIFYING KEYS
58 Most rnpkeys commands require a key locator or a filter, representing
59 one or more keys.
60 It may be specified in one of the following ways:
62 userid
64 Or just part of the userid. For "Alice alice@rnpgp.com the
65 following methods are considered identical:
66 • alice
68 • alice@rnpgp
70 • rnpgp.com
72 keyid
74 Or its right-most 8 characters. With or without 0x at the beginning
75 and spaces/tabs inside. Such as:
76 • 0x725F6F2D6D5F6120
78 • "725F6F2D 6D5F6120"
80 • 0x6D5F6120
82 key fingerprint: The 40-character key fingerprint, such as:
84 • "0x416E746F 6E537669 72696465 6E6B6F20"
86
88 INFORMATIONAL
89 -h, --help
90 Displays a short help message. No options are expected.
91 -V, --version
93 Displays version information. No options are expected.
94 -l, --list-keys
96 List out keys and some brief information about each.
97 Additional options:
99 --with-sigs
101 Additionally display signatures of listed keys.
102 KEY GENERATION
104 -g, --generate-key
105 Generate a new keypair.
106 Without additional options, an RSA primary key pair with an RSA
108 sub-key pair will be generated, and prompting for the encryption
109 password afterwards.
110 Additional options:
112 --numbits
114 Overrides the default RSA key size of 2048 bits.
115 --expiration TIME
117 Set key and subkey expiration time, counting from the creation
118 time.
119 By default generated keys do not expire.
121 Expiration time can be specified as:
123 • expiration date in the ISO 8601:2019 date format
125 (yyyy-mm-dd); or
126 • hours/days/months/years since creation time with the syntax
128 of 20h/30d/1m/1y;
129 • number of seconds.
131 --expert
133 Select key algorithms interactively and override default
134 settings.
135 --userid
137 Specifies the userid to be used in generation.
138 --hash
140 Specify the hash algorithm used in generation.
141 --cipher
143 Specify the encryption algorithm used in generation.
144 --s2k-iterations
146 Specify the number of iterations for the S2K (string-to-key)
147 process.
148 This is used during the derivation of the symmetric key, which
150 encrypts a secret key from the password.
151 --s2k-msec
153 Specify that rnpkeys should automatically pick a
154 --s2k-iterations value such that the single key derivation
155 operation would take NUMBER of milliseconds on the current
156 system.
157 For example, setting it to 2000 would mean that each secret key
159 decryption operation would take around 2 seconds (on the
160 current machine).
161 KEY/SIGNATURE IMPORT
163 --import, --import-keys, --import-sigs
164 Import keys or signatures.
165 While rnpkeys automatically detects the input data format, one may
167 still wish to specify whether the input provides keys or
168 signatures.
169 By default, the import process will stop on the first discovered
171 erroneous key or signature.
172 Additional options:
174 --permissive
176 Skip errored or unsupported packets during the import process.
177 KEY/SIGNATURE EXPORT
179 --export-key [--userid=FILTER] [FILTER]
180 Export key(s). Only export keys that match FILTER if FILTER is
181 given.
182 If filter matches a primary key, the subkeys of the primary key are
184 also exported.
185 By default, key data is written to stdout in ASCII-armored format.
187 Additional options:
189 --output PATH
191 Specifies output to be written to a file name instead of
192 stdout.
193 --secret
195 Without this option specified, the command will only export
196 public key(s). This option must be provided to export secret
197 key(s).
198 --export-rev KEY
200 Export the revocation signature for a specified secret key.
201 The revocation signature can be used later in a case of key loss or
203 compromise.
204 Additional options:
206 --rev-type
208 Specifies type of key revocation.
209 --rev-reason
211 Specifies reason for key revocation.
212 KEY MANIPULATION
214 --revoke-key KEY
215 Issue revocation signature for the secret key, and save it in the
216 keyring.
217 Revoked keys cannot be used further.
219 Additional options:
221 --rev-type
223 Specifies type of key revocation, see options section for the
224 available values.
225 --rev-reason
227 Specifies reason for key revocation.
228 --remove-key KEY
230 Remove the specified key.
231 If a primary key is specified, then all of its subkeys are also
233 removed.
234 If the specified key is a secret key, then it will not be deleted
236 without confirmation.
237 Additional options:
239 --force
241 Forces removal of a secret key without prompting the user.
242 --edit-key KEY
244 Edit or update information, associated with a key. Should be
245 accompanied with editing option.
246 Currently the following options are available:
248 --add-subkey
250 Generate and add a new subkey to the existing primary key. All
251 additional options for the --generate-key command apply for
252 subkey generation as well, except --userid.
253 --check-cv25519-bits
255 Check whether least significant/most significant bits of
256 Curve25519 ECDH subkey are correctly set. RNP internally sets
257 those bits to required values (3 least significant bits and
258 most significant bit must be zero) during decryption, however
259 other implementations (GnuPG) may require those bits to be set
260 in key material. KEY must specify the exact subkey via keyid or
261 fingerprint.
262 --fix-cv25519-bits
264 Set least significant/most significant bits of Curve25519 ECDH
265 subkey to the correct values, and save a key. So later export
266 of the key would ensure compatibility with other
267 implementations (like GnuPG). This operation would require the
268 password for your secret key. Since version 0.16.0 of RNP
269 generated secret key is stored with bits set to a needed value,
270 however, this may be needed to fix older keys or keys generated
271 by other implementations. KEY must specify the exact subkey via
272 keyid or fingerprint.
273 --set-expire TIME
275 Set key expiration time. See the description of the
276 --expiration option for possible time formats. Setting argument
277 to 0 removes key expiration, the key would never expire. It is
278 not recommended due to security reasons.
279 OPTIONS
281 --homedir DIR
282 Change homedir (where RNP looks for keyrings) to the specified
283 value.
284 The default homedir is ~/.rnp .
286 --output PATH
288 Write data processing related output to the file specified.
289 Combine it with --overwrite to overwrite file if it already exists.
291 --overwrite
293 Overwrite output file if it already exists.
294 --userid USERID
296 Use the specified userid during key generation and in some
297 key-searching operations.
298 --numbits BITS
300 Specify size in bits for the generated key and subkey.
301 bits may be in range 1024-16384, as long as the public key
303 algorithm does not place additional limits.
304 --cipher ALGORITHM
306 Set the key encryption algorithm. This is only used in key
307 generation.
308 The default value is AES256.
310 --hash ALGORITHM
312 Use the specified hash algorithm for signatures and derivation of
313 the encrypting key from password for secret key encryption.
314 The default value is SHA256.
316 --expert
318 Use the expert key generation mode, allowing the selection of
319 key/subkey algorithms.
320 The following types of keys can be generated in this mode:
322 • DSA key with ElGamal encryption subkey
324 • DSA key with RSA subkey
326 • ECDSA key with ECDH subkey
328 • EdDSA key with x25519 subkey
330 • SM2 key with subkey
332 Specifically, for ECDSA and ECDH the underlying curve can also be
334 specified:
335 • NIST P-256, NIST P-384, NIST P-521
337 • brainpoolP256r1, brainpoolP384r1, brainpoolP512r1
339 • secp256k1
341 --pass-fd FD
343 Specify a file descriptor to read passwords from instead of from
344 stdin/tty.
345 Useful for automated or non-interactive sessions.
347 --password PASSWORD
349 Use the specified password when it is needed.
350 Warning
352 Not recommended for production use due to potential
353 security issues. Use --pass-fd for batch operations instead.
354 --with-sigs
356 Print signature information when listing keys via the -l command.
357 --force
359 Force actions to happen without prompting the user.
360 This applies to cases such as secret key removal, revoking an
362 already revoked key and so on.
363 --permissive
365 Skip malformed or unknown keys/signatures during key import.
366 By default, rnpkeys will stop on the first erroring packet and exit
368 with an error.
369 --rev-type TYPE
371 Use the specified type during revocation signature generation
372 instead of the default 0.
373 The following values are supported:
375 • 0, or "no": no revocation type specified.
377 • 1, or "superseded": key was superseded with another key.
379 • 2, or "compromised": key was compromised and no longer valid.
381 • 3, or "retired": key is retired.
383 Please refer to IETF RFC 4880 for details.
385 --rev-reason REASON
387 Add the specified human-readable revocation REASON to the signature
388 instead of an empty string.
389 --s2k-iterations NUMBER
391 Specify the number of iterations for the S2K (string-to-key)
392 process.
393 This is used during the derivation of the symmetric key, which
395 encrypts a secret key from the password.
396 Please refer to IETF RFC 4880 for further details.
398 --s2k-msec NUMBER
400 Specify that rnpkeys should automatically pick a --s2k-iterations
401 value such that the single key derivation operation would take
402 NUMBER of milliseconds on the current system.
403 For example, setting it to 2000 would mean that each secret key
405 decryption operation would take around 2 seconds (on the current
406 machine).
407 --notty
409 Disable use of tty.
410 By default RNP would detect whether TTY is attached and use it for
412 user prompts.
413 This option overrides default behaviour so user input may be passed
415 in batch mode.
416 --current-time TIME
418 Override system’s time with a specified value.
419 By default RNP uses system’s time in all signature/key checks,
421 however in some scenarios it could be needed to override this.
422 TIME could be specified in the ISO 8601-1:2019 date format
424 (yyyy-mm-dd), or in the UNIX timestamp format.
425
427 0
428 Success.
429 Non-zero
431 Failure.
432
434 The following examples demonstrate method of usage of the rnpkeys
435 command.
436 EXAMPLE 1: IMPORT EXISTING KEYS FROM THE GNUPG
438 Following oneliner may be used to import all public keys from the
439 GnuPG:
440 gpg -a --export | rnpkeys --import -
442 To import all secret keys the following command should be used (please
444 note, that you’ll be asked for secret key password(s)):
445 gpg -a --export-secret-keys | rnpkeys --import -
447 EXAMPLE 2: GENERATE A NEW KEY
449 This example generates a new key with specified userid and expiration.
450 Also it enables "expert" mode, allowing the selection of key/subkey
451 algorithms.
452 rnpkeys --generate --userid "john@doe.com --expert --expiration 1y
454
456 Please report issues via the RNP public issue tracker at:
457 https://github.com/rnpgp/rnp/issues.
458 Security reports or security-sensitive feedback should be reported
460 according to the instructions at: https://www.rnpgp.org/feedback.
461
463 RNP is an open source project led by Ribose and has received
464 contributions from numerous individuals and organizations.
465
467 Web site: https://www.rnpgp.org
468 Source repository: https://github.com/rnpgp/rnp
470
472 Copyright (C) 2017-2021 Ribose. The RNP software suite is freely
473 licensed: please refer to the LICENSE file for details.
474
476 rnp(1), librnp(3)
477
479 RNP
480RNP 0.17.0 2023-05-02 RNPKEYS(1)