NAME¶

dkg-decrypt -- (threshold) message decryption according to OpenPGP

SYNOPSIS¶

dkg-decrypt [options] [PEERS]

DESCRIPTION¶

This program tries to decrypt a message given in ASCII armored or binary OpenPGP format. If public-key encryption was applied by the sender, then either a OpenPGP private key (option "-y") or a list of cooperating peers (PEERS) must be supplied by the user. The latter case means that the private key has been shared between multiple parties by dkg-generate(1). Then for successful decryption at least t+1 decryption shares from different participants are required for the given message. The threshold parameter t has been fixed during distributed key generation and cannot changed at this stage of processing. Currently, in the threshold case only ElGamal is supported as public-key algorithm.

In the general case all public-key algorithms from RFC 4880bis are supported. The program needs the corresponding private key file in so-called ASCII armor format as generated by dkg-generate(1) or any other OpenPGP software. If symmetric-key encryption was applied by the sender, then the argument list PEERS and the option "-y" can be omitted.

There are two modes of operation: First, in interactive mode either GNUnet or TCP/IP are empolyed for exchange of the decryption shares, where PEERS must be a sufficient subset (i.e. at least t+1) of the peer identities used during distributed key generation with dkg-generate(1) including the calling peer of the user. Second, in the non-interactive mode PEERS must contain only the single identity of the calling peer. After the first step of computation the corresponding decryption share is written to STDOUT. Next, t+1 users must exchange enough shares manually before the actual decryption of the message can start.

If the option "-k" is given, then each included signature is verified based on available public-keys from a keyring file. By option "-s" the program also process OpenPGP messages that are not encrypted but signed.

The established communication channels for the protocols should be protected with bilateral exchanged passwords for encryption and message authentication, if the underlying P2P network does not guarantee required confidentiality and integrity by itself. The passwords for all channels are defined as a string, where a slash (/) marks the end of each password. The order of the passwords depends on position of each peer in the canonicalized peer list, i.e., the sorted unique list of given PEERS. For example, if participant D_0 uses A/B/C/ as password string, then "B" is the password for his channel to D_1 and "C" is the password for his channel to D_2. That means D_1 and D_2 have to provide matching password strings, i.e., B/D/E/ and C/E/F/, respectively. The default value of option "-P" is an empty password string (simple default passwords) based on the assumption, that GNUnet will protect the exchanged protocol messages.

Instead of relying on GNUnet CADET service the messages can be exchanged by the built-in TCP/IP communication framework. In that case the given peer identities from PEERS must be resolvable hostnames and the corresponding option "-H" defines the name of the calling peer within that list. The program binds some TCP ports up from 55000 to listen for incoming connections and connects to other peers in that port range. The used port numbers are determined by the unique position of the name in the canonicalized peer list. Since the communication of TCP/IP is not protected by the network itself the option "-P" is mandatory in that case.

Please note that in the general case of option "-y" no communication channels are needed and thus PEERS and all other communication options should be omitted.

OPTIONS¶

Arguments mandatory for long options are also mandatory for short options.

-b, --binary: consider encrypted message from FILENAME as in binary input format
-c, --config=FILENAME: use GNUnet configuration file FILENAME (only interactive mode)
-h, --help: print this list of options
-H, --hostname=STRING: hostname (e.g. onion address) of this peer within PEERS
-i, --input=FILENAME: read encrypted message rather from FILENAME than STDIN
-k FILENAME: verify included signatures using keyring FILENAME
-K, --weak: allow weak keys to verify included signatures
-L, --log=LOGLEVEL: configure logging to use LOGLEVEL
-l, --logfile=FILENAME: configure logging to write logs to FILENAME
-n, --non-interactive: switch to non-interactive mode
-o, --output=FILENAME: write decrypted message rather to FILENAME than STDOUT
-p, --port=STRING: GNUnet CADET port to listen/connect (only interactive mode)
-P, --passwords=STRING: exchanged passwords to protect private and broadcast channels
-s, --signed-only: allow signed-only message
-v, --version: print the version number of the program
-V, --verbose: turn on verbose output
-w, --wait=INTEGER: minutes to wait until start of share exchange (only interactive mode)
-W, --aiou-timeout=INTEGER: timeout for point-to-point messages in minutes
-y, --yaot=FILENAME: yet another OpenPGP tool with private key in FILENAME

SECURITY¶

The current implementation is in experimental state and should NOT be used in production environments.

REPORTING BUGS¶

Security vulnerabilities or cryptographic complaints should be reported via an email directly to <HeikoStamer@gmx.net>. Reported problems will be published after they've been fixed.

Please report all other bugs via public bug tracker <https://savannah.nongnu.org/bugs/?func=additem&group=dkgpg>

Home page of Distributed Privacy Guard (DKGPG): <https://savannah.nongnu.org/projects/dkgpg/>

EXAMPLES¶

The following command performs a non-interactive threshold decryption for a: specific participant defined by its GNUnet peer identity (WS3K...QKFG). The encrypted message in ASCII-armored format is read from the given input file.

dkg-decrypt -i encrypted_msg.asc -n WS3KHEYKKF6QQ6NDQKKCJ2B374RSSXJ05TB5D9W9FYKPPEJ3QKFG

At least t+1 participants must run such a process on the same message to get a corresponding decryption share, where t is the t-resilience value used during key generation. The shares must be exchanged between the participants in a secure way, i.e., authenticated and confidential. Finally, the received decryption shares are given to the program one per line. After giving a trailing end of data sign (^D) the message is decrypted and printed to STDOUT.

Conversely, the following command performs an interactive threshold decryption with three participants defined by their GNUnet peer identities (3PT1...4530, S41S...G3N0, WS3K...QKFG).

dkg-decrypt -o decrypted_msg.txt -w 10 3PT18Z2345NA6FM86BKVJ32DK88KXF0YWKTDPPQX1QJMBPEF4530 S41SNHFSGVR3A88ZPX3ZB3BKD2EN0Z29VEKKS1BMVMQNMWSRG3N0 WS3KHEYKKF6QQ6NDQKKCJ2B374RSSXJ05TB5D9W9FYKPPEJ3QKFG

At least t+1 parties must run such a process on the same message, which is read from STDIN via an input prompt. The program then waits ten minutes before the threshold decryption protocol is started, because establishing a CADET channel with GNUnet may take some time. Finally, the decrypted message is written to the given output file, if anything went right.

COPYRIGHT¶

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the sources of this package and additionally can be obtained from Internet <https://www.gnu.org/licenses>.

Source file:	dkg-decrypt.1.en.gz (from dkgpg 1.1.3-1.18)
Source last updated:	2019-07-22T06:45:11Z
Converted to HTML:	2024-12-26T01:09:15Z