table of contents
| DKG-SIGN(1) | User Commands | DKG-SIGN(1) |
NAME¶
dkg-sign -- (threshold) message signing according to OpenPGP
SYNOPSIS¶
dkg-sign [options] [PEERS]
DESCRIPTION¶
This program generates a detached or a cleartext signature for a given file. It requires either a OpenPGP private key (option "-y") or a list of cooperating peers (PEERS). The latter case means that the private key 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 signature shares. The threshold parameter s has been fixed during distributed key generation and cannot changed at this stage of processing. Currently, in the threshold case only DSA/DSS 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. Note that only the primary key is used for creating the signature, i.e., signing-capable subkeys will be ignored. Moreover, the hash algorithm is fixed (SHA2-512).
By the option "-U" a policy URI for the generated signature can be specified, with option "-t" a canonical text document signature is created, and with option "-C" the cleartext signature framework (cf. RFC 4880) is applied.
In the threshold case the program employs either GNUnet or TCP/IP for exchange of protocol messages, where PEERS must be a sufficient subset (i.e. at least 2s+1) of the peer identities used during distributed key generation with dkg-generate(1) including the calling peer.
With the option "-w" the number of minutes can be adjusted until the signing 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 signature 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 via Tor) 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 S_0 uses A/B/C/ as 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 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 needed and thus PEERS and all other communication options should be omitted.
OPTIONS¶
Arguments mandatory for long options are also mandatory for short options.
- -5, --v5
- generate a v5 signature (cf. RFC 4880bis)
- -c, --config=FILENAME
- use GNUnet configuration file FILENAME
- -C, --clear
- apply cleartext signature framework (cf. RFC 4880)
- -e, --expiration=INTEGER
- expiration time of generated signature in seconds
- -h, --help
- print this list of options
- -H, --hostname=STRING
- hostname (e.g. onion address) of this peer within PEERS
- -i, --input=FILENAME
- create signature from FILENAME
- -L, --log=LOGLEVEL
- configure logging to use LOGLEVEL
- -l, --logfile=FILENAME
- configure logging to write logs to FILENAME
- -o, --output=FILENAME
- write generated signature to FILENAME
- -p, --port=STRING
- GNUnet CADET port to listen/connect
- -P, --passwords=STRING
- exchanged passwords to protect private and broadcast channels
- -t, --text
- create canonical text document signature
- -U, --URI=STRING
- policy URI tied to generated signature
- -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 encrypted email directly to <HeikoStamer@gmx.net>. Such 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 a detached signature of the file foo.txt with
- three participants defined by their GNUnet peer identities (3PT1...4530, S41S...G3N0, WS3K...QKFG). The signature in armored OpenPGP format is written to foo.txt.asc and can be verified by any OpenPGP implementation.
dkg-sign -i foo.txt -o foo.txt.asc -w 10 3PT18Z2345NA6FM86BKVJ32DK88KXF0YWKTDPPQX1QJMBPEF4530 S41SNHFSGVR3A88ZPX3ZB3BKD2EN0Z29VEKKS1BMVMQNMWSRG3N0 WS3KHEYKKF6QQ6NDQKKCJ2B374RSSXJ05TB5D9W9FYKPPEJ3QKFG
At least 2s+1 parties must run such a process on the same input file. The program waits ten minutes before the threshold signature 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¶
dkg-generate(1), dkg-revoke(1), dkg-keysign(1), dkg-verify(1)
| June 2019 | Distributed Privacy Guard 1.1.3 |