table of contents
DKG-KEYSIGN(1) | User Commands | DKG-KEYSIGN(1) |
NAME¶
dkg-keysign -- threshold signature scheme for OpenPGP (only DSA/DSS)
SYNOPSIS¶
dkg-keysign [options] PEERS
DESCRIPTION¶
This program generates one or more certification signatures for (selected) valid user IDs of a OpenPGP public key. The corresponding public key block is either given in so-called ASCII armor format by option "-i" and a path to the corresponding file or by option "-K" and a path to a keyring containing more than one key, e.g. a keyring file which has been built in preparation of a keysigning party. In that latter case by then mandatory option "-f" the fingerprint of the key selected for certification must be provided.
The application supposes that the private key for the threshold signature scheme of the signature issuer has been shared between multiple parties by dkg-generate(1). Thus, for successful signing at least 2s+1 different participants must join the protocol and provide their corresponding shares. The threshold parameter s has been fixed during distributed key generation and cannot changed at this stage of processing. There is one exception: if option "-y" is given, then the simple non-threshold variant is applied which works with any OpenPGP-compliant public-key algorithm. Only the primary key is used as certifying key. The program needs the corresponding privat key file in ASCII armor format as generated by dkg-generate(1) or any other OpenPGP software (in case of option "-y").
If option "-u" is added to command line, then only those valid user IDs will be signed that contain the given selector string. With "-1" through "-3" the level of identity validation is encoded in the corresponding signature type (i.e. either 0x11 through 0x13 or 0x10, if omitted).
By the option "-r" certification revocation signatures are generated, and with the option "-U" a policy URI for all generated signatures can be specified.
Currently, only DSA/DSS is supported as public-key algorithm of the issuer due to limitation of the threshold signature scheme from LibTMCG. The program needs the public key block (e.g. downloaded from a key server) to sign (option "-i") and the corresponding privat key file as generated by dkg-generate(1).
The program employs GNUnet for exchange of protocol messages, where PEERS must be a sufficient subset (i.e. at least 2s+1) of the GNUnet peer identities used during distributed key generation with dkg-generate(1) including the identity of the calling peer.
With the option "-w" the number of minutes can be adjusted until the distributed signing protocol is started. The default value is 5. It is crucial that all required participants are connected with GNUnet CADET within this waiting time. Otherwise the certification 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 the required confidentiality and integrity by itself. The passwords for all channels are defined as a string, where a slash (/) marks the end of each single 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 S_0 uses "A/B/C/" as its password string, then "B" is the password for his channel to S_1 and "C" is the password for his channel to S_2. That means, S_1 and S_2 must 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 needed and thus PEERS and all other communication options should be omitted.
OPTIONS¶
Arguments mandatory for long options are also mandatory for short options.
- -1, --one
- issuer has not done any verification of the claim of identity
- -2, --two
- issuer has done some casual verification of the claim of identity
- -3, --three
- issuer has done substantial verification of the claim of identity
- -a, --ask
- require confirmation from STDIN for each signature
- -c, --config=FILENAME
- use GNUnet configuration file FILENAME
- -e, --expiration=INTEGER
- expiration time of generated signatures in seconds
- -f, --fingerprint=STRING
- fingerprint of the public key for certification
- -h, --help
- print this list of options
- -H, --hostname=STRING
- hostname (e.g. onion address) of this peer within PEERS
- -i, --input=FILENAME
- create certification signatures on key from FILENAME
- -K, --keys=FILENAME
- select public key for certification from keyring FILENAME
- -k, --keyring=FILENAME
- use keyring FILENAME containing external revocation keys
- -L, --log=LOGLEVEL
- configure logging to use LOGLEVEL
- -l, --logfile=FILENAME
- configure logging to write logs to FILENAME
- -o, --output=FILENAME
- write key with certification signatures attached to FILENAME
- -p, --port=STRING
- GNUnet CADET port to listen/connect
- -P, --passwords=STRING
- exchanged passwords to protect private and broadcast channels
- -r, --revocation
- create certification revocation signatures
- -u, --userid=STRING
- sign only valid user IDs containing STRING
- -U, --URI=STRING
- policy URI tied to generated signatures
- -v, --version
- print the version number of the program
- -V, --verbose
- turn on verbose output
- -w, --wait=INTEGER
- minutes to wait until start of signing protocol
- -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 creates certification signatures on all valid user IDs
- of the public key provided in input file "foo.asc" with three participants defined by their GNUnet peer identities ("3PT1...4530", "S41S...G3N0", "WS3K...QKFG"). The signatures attached to the key are written in armored OpenPGP format to "bar.asc" and can be verified by any OpenPGP implementation.
dkg-keysign -i foo.asc -o bar.asc -w 10 3PT18Z2345NA6FM86BKVJ32DK88KXF0YWKTDPPQX1QJMBPEF4530 S41SNHFSGVR3A88ZPX3ZB3BKD2EN0Z29VEKKS1BMVMQNMWSRG3N0 WS3KHEYKKF6QQ6NDQKKCJ2B374RSSXJ05TB5D9W9FYKPPEJ3QKFG
At least 2s+1 parties must run such a process on the same input, i.e., public key and user ID. The program waits ten minutes before the distributed signing protocol is started, because establishing a CADET channel with GNUnet may take some time.
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¶
May 2019 | Distributed Privacy Guard 1.1.3 |