1. Manuals
  2. Tumbleweed
  3. dkgpg
  4. dkg-generate(1)

Scroll to navigation

DKG-GENERATE(1) User Commands DKG-GENERATE(1)

NAME

dkg-generate -- distributed key generation for OpenPGP (tDSS and tElG)

SYNOPSIS

dkg-generate [options] PEERS

DESCRIPTION

This program invokes the t-resilient distributed key generation protocol (DKG) by Gennaro et al. for discrete logarithm based cryptosystems as described in Journal of Cryptology, Vol. 20(1), 2007 from LibTMCG. Additionally, it will perform the adaptively-secure threshold DSS protocol (tDSS) by Canetti et al. for generating a shared DSA key as proposed in the extended version of a paper appeared under the title Adaptive Security for Threshold Cryptosystems in the proceedings of CRYPTO'99. Both protocols employ GNUnet or a simple built-in TCP/IP service as underlying peer-to-peer (P2P) network for the exchange of internal protocol messages between the participants. Thus either a working GNUnet peer or an interconnected host with appropriate TCP/IP port forwarding (e.g. via Tor Hidden Service) is necessary to proceed. Otherwise only local test instances with limited useability are started by default.

For each party either an individual or a shared DSA signing key is generated. This key acts as OpenPGP's primary key. Then the shared ElGamal encryption key (tElG) is arranged as subkey. Thus each party should verify after key generation, that the published public key of the group contains this shared ElGamal subkey, if no shared DSA signing key is used as some kind of integrity measure. The program generates two different files: First, one file that stores the individual private key shares in ASCII-armored OpenPGP format (experimental public-key algorithm IDs 107 and 109), and second, another file that contains the public key again in ASCII-armored format. These files have a common prefix of their filename: the GNUnet peer identity or the hostname of the calling party, i.e., the corresponding string from the n-element list PEERS. The first file must be kept confidential. A passphrase can be used to protect the private keys by OpenPGP iterated and salted S2K encryption scheme. If an empty passphrase is entered, then the corresponding secrets are stored in plain text and have to be protected otherwise.

The parameter t determines how many parties may deviate from the DKG protocol during the key generation and later during threshold decryption. At least t+1 participants are needed to recover a key share or to decrypt a OpenPGP message. This parameter can be adjusted by using the option "-t". The default value is (n-1)/2 where n is the number of participants. If the program is called with a zero t-resilience (i.e. "-t 0"), then no ElGamal encryption subkey is generated. It is always ensured by clipping that t <= n holds. Note that t+1 malicious participants together are able to compute the secrets of the remaining parties of such a shared key.

The option "-s" defines the parameter s, i.e., the s-resilience of the tDSS protocol. At least 2s+1 participants are required to create a signature of the shared DSA primary key, however, s+1 parties can recover all secret key shares. The default value for s is (n-1)/2. The generation of an unique shared DSA key is disabled, if parameter s is set to zero. In that case for each party an individual DSA key is generated, which allows full control over the shared encryption subkey.

There is one big exception to the above description: if option "-y" is given, then any threshold parameters are ignored and the program generates a non-shared DSA primary key and a non-shared ElGamal subkey as usual OpenPGP-compliant applications (e.g. GnuPG) would do. However, the underlying domain parameters are fixed for conveniance but can be changed easily (see next paragraph).

The underlying DDH-hard abelian group, i.e., a large prime-order subgroup of special form (sometimes called Schnorr group), can be tweaked by using the option "-g" with a so-called common reference string (CRS) also known as domain parameter set. The included program dkg-gencrs generates such a random string on that all participants must agree. The security level is increased step by step for each dummy argument given to dkg-gencrs. The generated domain parameters are verifiable up to a certain level. In particular there exists an option ("-f") for compliance with FIPS 186-4. However, it is recommended that this crucial part of the setup is either accomplished by some trusted members or all participants together on a trustworthy system (e.g. fresh GNU/Linux installation on a virtual machine). Without option "-g" a hard coded CRS with |p| = 3072 bit and |q| = 256 bit is used by default. It was created by the author of the program with a fixed seed and is fully compatible with DSA as defined in FIPS 186-4. Choices of domain parameters with |p| > 3072 bit may not be supported by any other OpenPGP implementations.

With the option "-w" the number of minutes can be adjusted until DKG/tDSS protocols are started. The default value is 5. It is crucial for the key generation that all participants are connected with GNUnet CADET within this waiting time. Otherwise the distributed key generation 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 private 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. Moreover, the broadcast channel has to be authenticated too. 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 P_0 uses A/B/C/ as password string, then "B" is the password for his channel to P_1 and "C" is the password for his channel to P_2. That means P_1 and P_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 case of option "-y" no communication channels are required and thus PEERS should contain only one element and all other communication options (e.g. option "-H") should be omitted.

The included program dkg-keyinfo shows some basic information about threshold parameters and the private key. Finally, the program dkg-refresh updates the individual DSA key shares and thus provides so-called proactive security against a mobile adversary, if it is used regularly. The refreshment should be handled very carefully because all parties not involved are excluded (disqualified) from all further private key operations.

Please note that the program interactively asks for a user ID (e.g. name or email) on STDIN, if the option "-u" is omitted. Moreover, according to RFC 4880 a passphrase is used to protect the private key. Given option "-N" this protection is disabled and the private key material is stored in clear.

OPTIONS

Arguments mandatory for long options are also mandatory for short options. Please note that interpreting of almost all options is done by a library function of GNUnet. Thus this program has to be compiled accordingly.

use GNUnet configuration file FILENAME
expiration time of generated keys in seconds
common reference string that defines the underlying DDH-hard group
print this list of options
hostname (e.g. onion address) of this peer within PEERS
configure logging to use LOGLEVEL
configure logging to write logs to FILENAME
disable private key protection by passphrase
GNUnet CADET port to listen/connect
exchanged passwords to protect private and broadcast channels
resilience of threshold DSS protocol (signature scheme)
resilience of DKG protocol (threshold decryption)
state that the generated key is used for timestamping
user ID of the generated key
print the version number of the program
turn on verbose output
minutes to wait until start of key generation protocol
timeout for point-to-point messages in minutes
yet another OpenPGP tool (i.e., generate usual keys)

SECURITY

The current implementation is in experimental state and should NOT be used in production environments. Note that for the key generation a lot of good randomness is required. Please ensure that your system can provide these randomness for libgcrypt without exceeding the defined protocol timeouts.

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

dkg-generate -w 10 -s 0 -t 2 WS3KHEYKKF6QQ6NDQKKCJ2B374RSSXJ05TB5D9W9FYKPPEJ3QKFG XS72STGDBKT6YRRVF8CPMGJFZ0FEYQE9EJECDNXWZJSB5G5H4ZVG 3PT18Z2345NA6FM86BKVJ32DK88KXF0YWKTDPPQX1QJMBPEF4530 S41SNHFSGVR3A88ZPX3ZB3BKD2EN0Z29VEKKS1BMVMQNMWSRG3N0


Each party must run such a process with identical parameter set,
    i.e., please configure always the same t-resilience. Note that, e.g.
    2-resilience, means that later at least three participants are needed in
    order to decrypt messages for the generated common ElGamal subkey. However,
    robustness of the DKG protocol is only guaranteed for t < n/2 which is
    violated in this example. Thus a malicious party may disturb the key
    generation without being identified and excluded. The s-resilience is set to
    zero, which means that individual DSA keys instead of a shared key are
    generated and used as OpenPGP primary keys. Thus dkg-sign(1) will not
    work with such restricted keys. The program waits ten minutes before the DKG
    protocol is started, because establishing a CADET channel with GNUnet may
    take some time.


Instead of using GNUnet for message exchange the built-in TCP/IP
    service (currently IPv4 only) can carry out this job. However, then each
    peer has to be reachable by all other peers over the underlying network. In
    this case resolvable hostnames instead of GNUnet peer identities are used as
    unique identifiers:




dkg-generate -t 2 -P secret1/secret2/secret3/secret4/ -H host2.example.com host1.example.com host2.example.com host3.example.com host4.example.com  





The s-resilience is non-zero in this example, which means that a shared DSA key
  is generated and used as OpenPGP primary key. Thus the shared encryption
  subkey (ElGamal) is protected against individual manipulation. This subkey is
  generated with a default threshold of t = (n-1)/2.

Last but not least, in the following example only a shared DSA
    key, e.g. for jointly code signing, is generated:




dkg-generate -t 0 -P secret1/secret2/secret3/ -H supertapir evilsloth supertapir lazyhedgehog 






You can start the program with torsocks to use Tor as underlying
    point-to-point network. Note that for this case the option
    "AllowInbound" must be enabled in torsocks.conf. Additionally, a
    hidden service with port redirection to localhost has to be configured in
    your torrc file:




HiddenServiceDir /var/lib/tor/dkg/
HiddenServicePort 55000 127.0.0.1:55000
HiddenServicePort 55001 127.0.0.1:55001
HiddenServicePort 55002 127.0.0.1:55002
HiddenServicePort 55003 127.0.0.1:55003
HiddenServicePort 55004 127.0.0.1:55004
HiddenServicePort 55005 127.0.0.1:55005
HiddenServicePort 55006 127.0.0.1:55006
HiddenServicePort 55007 127.0.0.1:55007
HiddenServicePort 55008 127.0.0.1:55008
HiddenServicePort 55009 127.0.0.1:55009
HiddenServicePort 55010 127.0.0.1:55010
HiddenServicePort 55011 127.0.0.1:55011
HiddenServicePort 55012 127.0.0.1:55012
HiddenServicePort 55013 127.0.0.1:55013
HiddenServicePort 55014 127.0.0.1:55014
HiddenServicePort 55015 127.0.0.1:55015
HiddenServicePort 55016 127.0.0.1:55016
HiddenServicePort 55017 127.0.0.1:55017
HiddenServicePort 55018 127.0.0.1:55018
HiddenServicePort 55019 127.0.0.1:55019
HiddenServicePort 55020 127.0.0.1:55020
HiddenServicePort 55021 127.0.0.1:55021
HiddenServicePort 55022 127.0.0.1:55022
HiddenServicePort 55023 127.0.0.1:55023
...
HiddenServicePort 55200 127.0.0.1:55200
...












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








SEE ALSO


dkg-encrypt(1), dkg-decrypt(1),
    dkg-keysign(1), dkg-sign(1), dkg-verify(1),
    dkg-revoke(1)









  

    March 2019
    Distributed Privacy Guard 1.1.3