NAME¶

dkg-revoke -- threshold signature scheme for OpenPGP (only DSA/DSS)

SYNOPSIS¶

dkg-revoke [options] PEERS

DESCRIPTION¶

This program revokes an OpenPGP primary key and a corresponding single subkey, where the private DSA key has been shared between multiple parties by dkg-generate(1). For a successful revocation at least 2s+1 different participants must join the protocol and provide their corresponding signature shares. The threshold parameter s has been fixed during distributed key generation and cannot changed at this stage of processing. The program needs the corresponding privat key file as generated by dkg-generate(1). The results, i.e., so-called key revocation signatures, are written to the public and private key file in ASCII-armored OpenPGP format. Additionally, the updated public key is printed on STDOUT.

The program employs GNUnet for exchange of protocol messages, where PEERS must be a sufficient subset (i.e. at least 2s+1 parties) of the GNUnet peer identities used during distributed key generation with dkg-generate(1) including the calling peer.

By the additional option "-r" the caller can specify a reason for revocation (machine-readable code) as defined by RFC 4880:

With the option "-w" the number of minutes can be adjusted until the revocation protocol is started. The default value is 5. It is crucial that all participants are connected with GNUnet CADET within this waiting time. Otherwise the revocation may fail. The option "-W" defines the timeout of a message within the point-to-point network. The default value is 5 minutes. If the underlying network transport (i.e. GNUnet CADET or TCP/IP) is very slow then this value should be increased by all particpants.

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 R_0 uses A/B/C/ as password string, then "B" is the password for his channel to R_1 and "C" is the password for his channel to R_2. That means R_1 and R_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.

OPTIONS¶

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

-c, --config=FILENAME

use GNUnet configuration file FILENAME

-h, --help

print this list of options

-H, --hostname=STRING

hostname (e.g. onion address) of this peer within PEERS

-L, --log=LOGLEVEL

configure logging to use LOGLEVEL

-l, --logfile=FILENAME

configure logging to write logs to FILENAME

-p, --port=STRING

GNUnet CADET port to listen/connect

-P, --passwords=STRING

exchanged passwords to protect private and broadcast channels

-r, --reason=INTEGER

reason for revocation (OpenPGP machine-readable code)

-R, --Reason=STRING

reason for revocation (human-readable form)

-v, --version

print the version number of the program

-V, --verbose

turn on verbose output

-w, --wait=INTEGER

minutes to wait until start of revocation protocol

-W, --aiou-timeout=INTEGER

timeout for point-to-point messages in minutes

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 revokes the shared keys with three participants defined by

their GNUnet peer identities (3PT1...4530, S41S...G3N0, WS3K...QKFG). The corresponding public key with both revocation signatures in armored OpenPGP format is written to foo.txt.asc and can be verified by any OpenPGP implementation.

dkg-revoke -r 1 -w 10 3PT18Z2345NA6FM86BKVJ32DK88KXF0YWKTDPPQX1QJMBPEF4530 S41SNHFSGVR3A88ZPX3ZB3BKD2EN0Z29VEKKS1BMVMQNMWSRG3N0 WS3KHEYKKF6QQ6NDQKKCJ2B374RSSXJ05TB5D9W9FYKPPEJ3QKFG

At least 2s+1 parties must run such a process with the same revocation reason (here: key is superseded). The program waits ten minutes before the revocation protocol is started, because establishing a CADET channel with GNUnet may take some time.

COPYRIGHT¶

Copyright (C) 2017, 2018 Heiko Stamer <HeikoStamer@gmx.net>

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>.

SEE ALSO¶

dkg-generate(1), dkg-encrypt(1), dkg-decrypt(1), dkg-sign(1), dkg-verify(1)