1= rnp(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 10RNP - OpenPGP-compatible signatures and encryption. 11 12== SYNOPSIS 13 14*rnp* [_--homedir_ _dir_] [_OPTIONS_] _COMMAND_ [_INPUT_FILE_, ...] ... 15 16 17== DESCRIPTION 18 19The _rnp_ command-line utility is part of the _RNP_ suite and 20provides OpenPGP signing and encryption functionality 21compliant with IETF RFC 4880. 22 23_rnp_ does not allow manipulation of keys or keyrings -- 24please use _rnpkeys(1)_ for that purpose. 25 26=== BASICS 27 28By default, *rnp* will apply a _COMMAND_, additionally configured with _OPTIONS_, 29to all _INPUT_FILE_(s) or _stdin_ if no _INPUT_FILE_ is given. 30 31Depending on the input, output may be written: 32 33* to the specified file with a removed or added file extension (_.pgp_, _.asc_, _.sig_); or 34* to _stdout_. 35 36Without the *--armor* option, output will be in binary. 37 38If _COMMAND_ requires public or private keys, *rnp* will look for the keyrings in *~/.rnp*. The options *--homedir* and *--keyfile* override this (see below). 39 40If _COMMAND_ needs a password, *rnp* will ask for it via *stdin* or *tty*, 41unless the *--password* or *--pass-fd* option was specified. 42 43 44== COMMANDS 45 46=== INFORMATIONAL 47 48*-h*, *--help*:: 49Displays a short help message. No options are expected. 50 51*-V*, *--version*:: 52Displays version information. No options are expected. 53 54 55=== ENCRYPTION AND SIGNING 56 57*-e*, *--encrypt*:: 58Encrypt data with public key(s), and optionally sign, if the *--sign* command is added. + 59+ 60You would likely want to specify one or more *--recipient*(s) or pick a *--cipher* (instead of the default). 61+ 62Additional options: 63 64*--recipient*::: 65Specify one or more recipients. 66 67*--cipher*::: 68Select a specific cipher. 69 70*-z*, *--zip*, *--bzip*::: 71Select a compression algorithm. 72 73*--armor*::: 74Output ASCII data instead of binary via the *--armor* option. If the input file is _file.ext_, and *--output* is not specified, then the data will be written (depending on *--armor* option) to _file.ext.pgp_ or _file.ext.asc_. + 75 76*--overwrite*::: 77If the destination file already exists, and the *--overwrite* option is not given, the caller will be asked for the permission to overwrite or to provide a new file name. Please see the *OPTIONS* section for more information. 78 79*-c*, *--symmetric*:: 80Encrypt data with password(s). + 81+ 82Can be combined with the commands *--encrypt* and *--sign*. 83+ 84Options that apply to the *--encrypt* command also apply here. 85+ 86Additional options: 87 88*--passwords*::: 89Encryption to multiple passwords is possible with *--passwords* option. Each password would be asked via stdin/tty unless *--password* or *--pass-fd* is specified. + 90 91*-s*, *--sign*:: 92Digitally sign data, using one or more secret keys you own. + 93+ 94Public-key or password-based encryption may be added via the *--encrypt* and *--symmetric* commands. + 95+ 96Additional options: 97 98*-u*, *--userid*::: 99By default, the first secret key you own will be selected for signing. Apply this option to select a different key or to use multiple keys. 100 101*--detach*::: 102By default, the signature is stored together with signed data. This option detaches the data signature to a separate file (_file.ext.sig_). 103 104*--hash*::: 105You may want to use *--hash* option to override default hash algorithm settings. As with encryption, output may be converted to ascii via the *--armor* option. + 106+ 107Compression options also apply here. Since the secret key is usually stored encrypted, you will be asked for the password to decrypt it via _stdin_/_tty_ unless *--password* or *--pass-fd* is specified. 108 109*--clearsign*:: 110Digitally sign text data, producing human-readable output with the signature attached. + 111+ 112In this mode, data cannot be additionally encrypted or compressed. 113+ 114Other signing options, *--hash*, *-u*, *--password*, can still be used here. 115 116=== DECRYPTION AND VERIFICATION 117 118*-d*, *--decrypt*:: 119Decrypt and verify data from the _INPUT_FILE_ or stdin. + 120+ 121If the data is signed, signature verification information will be printed to _stdout_/_tty_. 122+ 123Additional options: 124 125*--output*::: 126Output, if not overridden with this option, will be written to the file with stripped _.pgp_ extension or stdout. If _INPUT_FILE_ does not end with the _.pgp_ extension, then output file name will be asked via _stdin_/_tty_. 127 128*--password*, *--pass-fd*::: 129Depending on encryption options, you may be asked for the password of one of your secret keys, or for the encryption password. These options override that behavior such that you can input the password through automated means. 130 131*-v*, *--verify*:: 132Verify signature(s) without writing embedded data out, if any. + 133+ 134To verify the detached signature of a file _file.ext_, the detached signature file in the file name pattern of _file.ext.sig_ or _file.ext.asc_ must exist. + 135+ 136If data is encrypted, you may be asked for password as in the *--decrypt* command. 137 138=== OTHER COMMANDS 139 140*--list-packets*:: 141Show detailed information about the OpenPGP data in _INPUT_FILE_ or stdin. 142Useful for curiosity, troubleshooting or debugging. + 143+ 144Additional options can be used: 145 146*--json*::: output JSON data instead of human-readable information 147*--grips*::: print out key fingerprints and grips 148*--mpi*::: print out all MPI values 149*--raw*::: print raw, hex-encoded packets too 150 151*--enarmor*[=_msg_|_pubkey_|_seckey_|_sign_]:: 152Convert binary data to the ASCII-armored as per OpenPGP standard. 153This includes the `-----BEGIN PGP MESSAGE-----` header and footer, 154and Base64-encoded data. + 155+ 156Output for _file.ext_ will be written to _file.ext.asc_ (if it does not exist) 157or to _stdout_. + 158+ 159The following OpenPGP headers may be specified: 160+ 161-- 162*msg*::: _-----BEGIN PGP MESSAGE-----_ 163*pubkey*::: _-----BEGIN PGP PUBLIC KEY BLOCK-----_ 164*seckey*::: _-----BEGIN PGP SECRET KEY BLOCK-----_ 165*sign*::: _-----BEGIN PGP SIGNATURE-----_ 166-- 167+ 168Additional options: 169 170*--overwrite*::: 171Forcefully overwrite existing destination file if it exists. 172 173*--output*::: 174Specify destination file path. 175 176 177*--dearmor*:: 178Attempts to convert data from an armored format to the binary format. + 179+ 180The _file.ext.asc_ output file would be written to _file.ext_. 181If the destination file already exists, it will prompt the user 182for a new filename. 183+ 184Additional options: 185 186*--overwrite*::: 187Forcefully overwrite existing destination file if it exists. 188 189*--output*::: 190Specify destination file path. 191 192 193== OPTIONS 194 195*--home*, *--homedir* _DIR_:: 196Change homedir (where RNP looks for keyrings) to the specified value. + 197+ 198The default homedir is _~/.rnp_ . 199 200*-f*, *--keyfile* _PATH_:: 201Instead of loading keyrings, use key(s) from the file specified. 202 203*-u*, *--userid* _KEY_:: 204Specify one or more signing keys, searching for it via the given value _KEY_. 205See *rnpkeys(1)* on how to find valid values. 206 207*-r*, *--recipient* _KEY_:: 208Add the message recipient, i.e. the public key to which message will be encrypted to. 209See *rnpkeys(1)* on how to find valid values. 210 211*--armor*, *--ascii*:: 212Apply ASCII armoring to the output, so that the resulting output 213can be transferred as plain text. + 214+ 215See IETF RFC 4880 for more details. 216 217*--detach*, *--detached*:: 218Create a detached signature. 219 220*--output* _PATH_:: 221Write data processing related output to the file specified. + 222+ 223If not specified, the output filename will be guessed from 224the input filename/extension or the command will prompt the user 225via _stdin_/_tty_. 226 227*--overwrite*:: 228Overwrite already existing files without prompt. 229 230*--hash* _ALGORITHM_:: 231Set hash algorithm which to be used for signing and derivation 232of the encryption key from a password. + 233+ 234The default value is _SHA256_. 235 236*--cipher* _ALGORITHM_:: 237Set the symmetric algorithm used during encryption. + 238+ 239The default value is _AES256_. 240 241*--aead* [_EAX_, _OCB_]:: 242Enable AEAD encryption and select algorithm to be used. 243 244*--aead-chunk-bits* _BITS_:: 245Change AEAD chunk size. This is used for testing or debugging. 246 247*--zip*, *--zlib*, *--bzip2*:: 248Select corresponding algorithm to compress data with. 249Please refer to IETF RFC 4880 for details. 250 251*-z* _0..9_:: 252Set compression level for the compression algorithms. + 253+ 254*9* is the highest compression level, where *0* disables compression. 255+ 256The default value is *6*. 257 258*--pass-fd* _FD_:: 259Specify a file descriptor to read passwords from instead of from _stdin_/_tty_. + 260+ 261Useful for automated or non-interactive sessions. 262 263*--password* _PASSWORD_:: 264Use the specified password when it is needed. + 265+ 266WARNING: Not recommended for production use due to potential security issues. 267Use *--pass-fd* for batch operations instead. 268 269*--passwords* _COUNT_:: 270Set the number of passwords for *--symmetric* encryption. + 271+ 272While not commonly used, you may encrypt a message to any reasonable number of passwords. 273 274*--creation* _TIME_:: 275Override signature creation time. + 276+ 277By default, creation time is set to current local computer time. + 278+ 279A specific time could be specified in the 280ISO 8601-1:2019 date format (_yyyy-mm-dd_), 281or in the UNIX timestamp format. 282 283*--expiration* _TIME_:: 284Set signature expiration time, counting from the creation time. + 285+ 286By default, signatures do not expire. + 287+ 288A specific expiration time can be specified as: 289 290*** expiration date in the ISO 8601:2019 date format (_yyyy-mm-dd_); or 291*** hours/days/months/years since creation time with the syntax of _20h_/_30d_/_1m_/_1y_; 292*** number of seconds. 293 294*--keystore-format* _GPG_|_KBX_|_G10_|_G21_:: 295Set keystore format. + 296+ 297RNP automatically detects the keystore format. + 298+ 299This option allows the auto-detection behavior to be overridden. 300 301*--debug* _FILENAME.CPP_:: 302Enable debug output for the source file specified. For development use only. 303 304 305== EXIT STATUS 306 307_0_:: 308 Success. 309 310_Non-zero_:: 311 Failure. 312 313 314== EXAMPLES 315 316The following examples demonstrate method of usage of the _rnp_ command. 317 318=== EXAMPLE 1 319 320*rnp* *--homedir* _.rnp_ *--encrypt* *-r* _0x6E69636B6F6C6179_ 321*--output* _document.txt.encrypted_ _document.txt_ 322 323Load keyrings from the _.rnp_ folder, 324encrypt the _document.txt_ file using the 325key with keyid _0x6E69636B6F6C6179_. 326 327=== EXAMPLE 2 328 329*rnp* *--keyfile* _john-sec.asc_ *-s* *--detach* *--hash* _SHA512_ _document.txt_ 330 331Generate a detached signature over the file _document.txt_, using the 332secret key stored in the file. 333Additionally override the hash algorithm to _SHA512_. 334 335=== EXAMPLE 3 336 337*rnp* *--keyfile* _john-pub.asc_ *--verify* _document.txt.sig_ 338 339Verify detached signature, using the key stored in the _john-pub.asc_ file. 340The signed data is assumed to be available from the file _document.txt_. 341 342=== EXAMPLE 4 343 344*rnp* *-e* *-c* *-s* *--passwords* _3_ 345*-r* _0x526F6E616C642054_ 346*-r* "_john@doe.com_" 347*-u* _0x44616E69656C2057_ 348_document.txt_ 349 350Encrypt _document.txt_ with 2 keys (specified via _keyid_ 351_0x526F6E616C642054_ and _userid_ _john@doe.com_), and 3 passwords, 352so *any* of these may be used to decrypt the resulting file. 353 354Additionally, the message will be signed with key _0x44616E69656C2057_. 355 356 357== BUGS 358 359Please report _issues_ via the RNP public issue tracker at: 360https://github.com/rnpgp/rnp/issues. 361 362_Security reports_ or _security-sensitive feedback_ should be reported 363according to the instructions at: 364https://www.rnpgp.org/feedback. 365 366 367== AUTHORS 368 369*RNP* is an open source project led by Ribose and has 370received contributions from numerous individuals and 371organizations. 372 373 374== RESOURCES 375 376*Web site*: https://www.rnpgp.org 377 378*Source repository*: https://github.com/rnpgp/rnp 379 380 381== COPYING 382 383Copyright \(C) 2017-2021 Ribose. 384The RNP software suite is _freely licensed_: 385please refer to the *LICENSE* file for details. 386 387 388== SEE ALSO 389 390*rnpkeys(1)*, *librnp(3)* 391