New command-line interface

[Daeinar]

Here's a first proposal for a new command-line interface. It still on-going work and some of the optional commands can probably be merged here and there.

The following commands provide general information about the drand software.

drand [-hV]

	Options:

    -h, --help
        Print a help message.

    —V, --version
        Output version.

The following commands start and stop the drand daemon.

drand start [--no-tls] [--tls-cert file] [--tls-key file] [--verbosity level]
    Start the drand daemon.
    
    Options:

    -n, --no-tls 
    	Disable TLS for all communications (not recommended).
    	
    -c, --tls-cert fullchain.pem
        Set the TLS certificate chain (in PEM format) for this drand node. If
        not specified previously and --no-tls is not set, drand asks the user to
        provide a path to a valid TLS certificate during boot up.
    	
    -k, --tls-key private-key.pem
        Set the TLS private key (in PEM format) for this drand node. If not
        specified previously and --no-tls is not set, drand asks the user to
        provide a path to a valid TLS private key during boot up.
    	
    -v, --verbosity level
    	Set verbosity to the given level.

drand stop 
	Stop the drand daemon.
        
The following commands interact with a remote drand node.

drand get cokey [--no-tls] address
    Get the collective public key from the drand node at the given address.

    Options:

    -n, --no-tls
    	Disable TLS for all communications (not recommended).

    -c, --tls-cert fullchain.pem
        Set the self-signed certificate of the remote drand node if necessary.

drand get public --cokey drand.cokey [--index num] [--no-tls] address
    Get the latest public randomness from the drand node at the given address
    and verify it against the given collective public key drand.cokey of the
    drand beacon.

    Options:

    -i, --index num
        Request the public randomness generated at index num. If the drand node
        does not have the requested value, it returns an error.

    -n, --no-tls
    	Disable TLS for all communications (not recommended).

    -c, --tls-cert fullchain.pem
        Set the self-signed certificate of the remote drand node if necessary.

drand get private --pubkey drand.public [--no-tls] address
    Get private randomness from the drand node at the given address. Requests
    are ECIES-encrypted towards the public key drand.public of the drand node.

    Options:

    -n, --no-tls
    	Disable TLS for all communications (not recommended).

    -c, --tls-cert fullchain.pem
        Set the self-signed certificate of the remote drand node if necessary.

The following commands interact with the drand node on localhost.

drand gen group <keys> group.toml
    Merge the given list of comma-separated drand.public keys into the
    group.toml file.

drand gen keypair
    Generate the longterm keypair (drand.private, drand.public).

drand gen dkg [--leader] group.toml
    Run the distributed key generation with the group specified in group.toml to
    generate the collective public key drand.cokey and a share drand.share for
    each node. Nodes which are not specified as a leader wait until being
    contacted by a node that is as a leader. After the dkg has been finished
    successfully, the leader automatically switches to the public randomness
    generation mode.

    Options:

    -l, --leader
        Initiate and coordinate the generation of the distributed key.

drand gen redkg [--leader] group-old.toml group-new.toml
    Reshare the distributed key from the nodes specified in group-old.toml
    towards those definied in group-new.toml. At least a threshold t-of-n nodes
    in group-old.toml have to be present to make this possible. Each node in
    group-new.toml that is not online at the time of the refresh will not get a
    new share and therefore will not become a member of the new group. Nodes
    which are not specified as a leader wait until being contacted by a node
    that is as a leader. After the resharing has been finished successfully, the
    new leader automatically switches to the public randomness generation mode.

    Options:

    -l, --leader
        Initiate and coordinate the resharing of the distributed key.

drand info cokey
    Print the collective public key drand.cokey.

drand info group
    Print the details about the group that the local drand node is part of
    currently.

drand info private
    Print the long-term private key drand.private.

drand info public
    Print the long-term public key drand.public.

drand info share
    Print the private key share drand.share.

[Daeinar]

Okay, I think the --no-tls options for the drand get command are not necessary. Usage of TLS is set by the operator of a node which is nothing that the client can enforce. We should, however, print a clear warning on the client-side if the contacted node does not use TLS.

[nikkolasg]

Nice thanks !
A few comments:

• drand gen dkg [--leader] group.toml and drand gen redkg [--leader] group.toml new.toml: Maybe we can just call it "setup" or something more abstract, than DKG ? And what about if there is 2 arguments, we automatically say it's a "share resharing operation" vs having a separate command about it ?
• cokey mmhh.. sounds a bit too much like cocky don't you think ? :D But dkey is not really better ahah.
• drand get private --pubkey drand.public [--no-tls] address : We should not need the address in this case since it's already present in the drand.public key.

[nikkolasg]

@Daeinar For drand get public the client does not know if he must contact via TLS or not since it's not written in the dist key file. So that means it should try to contact over TLS by default and fallback to plaintext if destination's not in TLS mode.

[Daeinar]

@nikkolasg: So your proposal would be something like

drand setup [--leader] [--update group-new.toml] group.toml

where the optional --update triggers resharing and if not set we just do a regular DKG? Yeah I like that.

cokey vs. dkey vs. distkey: I like the notion of a collective (public) key because it's collectively generated by all the nodes in a distributed manner. The public key itself is not distributed, the private key is though via the private key shares. That's why I'm not too happy with distkey, for example, but maybe I'm just nitpicky. I'm open to other naming proposals instead of cokey.

Agreed to all the other comments.

[Daeinar]

Okay next attempt. Feedback welcome (/cc @nikkolasg @PizzaWhisperer). Should have probably committed a regular markdown file to track diffs, simplify commenting, etc.

The following commands provide general information about the drand software.

drand [-hV]

    Options:

    -h, --help
        Print a help message.

    —V, --version
        Output version.
        
The following commands interact with a remote drand node.

drand get private [-c file] [-n address] group.toml
    Get private randomness from the drand beacon as specified in group.toml.
    Only one node is contacted by default. Requests are ECIES-encrypted towards
    the public key of the contacted node. This command attempts to connect to
    the drand beacon via TLS and falls back to plaintext communication if the
    contacted node has not activated TLS in which case it prints a warning.

    Options:

    -c, --tls-cert <certificate>
        Set the self-signed TLS certificates (in PEM format) of the contacted
        nodes if necessary. The certificates have to be specified as a list of
        whitespace-separated file paths. This command is only useful when being
        combined with the --nodes option.

    -n, --nodes <address>
        Contact the nodes at the given list of whitespace-separated addresses
        which have to be present in group.toml.

drand get public [-c file] [-i num] [-n address] group.toml
    Get the latest public randomness from the drand beacon and verify it against
    the collective public key as specified in group.toml. Only one node is
    contacted by default. This command attempts to connect to the drand beacon
    via TLS and falls back to plaintext communication if the contacted node has
    not activated TLS in which case it prints a warning.

    Options:

    -c, --tls-cert <certificate>
        Set the self-signed TLS certificates (in PEM format) of the contacted
        nodes if necessary. The certificates have to be specified as a list of
        whitespace-separated file paths. This command is only useful when being
        combined with the --nodes option.

    -i, --index <num>
        Request the public randomness generated at index num. If the drand
        beacon does not have the requested value, it returns an error.

    -n, --nodes <address>
        Contact the nodes at the given list of whitespace-separated addresses
        which have to be present in group.toml.

The following commands interact with the drand node on localhost.

drand generate-keypair
    Generate the longterm keypair (drand.private, drand.public) for this node.

drand group <keys> <group.toml>
    Merge the given list of whitespace-separated drand.public keys into the
    group.toml file.

drand show <cokey|group|private|public|share>
    Print the information about the collective public key (drand.cokey), the
    group details (group.toml), the long-term private key (drand.private), the
    long-term public key (drand.public), or the private key share (drand.share),
    respectively.

drand start [-dDl] [-c cert] [-C port] [-k key] [-L addr] [-v level] group.toml
    Start the drand daemon.

    If the distributed key generation has not been executed before, the node
    waits to receive the signal from a leader to start the process of generating
    the collective public key drand.cokey and its private share drand.share
    together with the other nodes in group.toml.

    Otherwise, if there has been already a successful distributed key generation
    before, the node automatically switches to the public randomness generation
    mode after a potential state-syncing phase with the other nodes in
    group.toml.
    
    Options:

    -c, --tls-cert <certificate>
        Set the TLS certificate chain (in PEM format) for this drand node. This
        parameter is required by default and can only be omitted if the
        --tls-disable flag is used.

    -C, --control <port>
        Set the port number (default: 8888) on which drand should listen for
        control commands.

    -d, --tls-disable 
        Disable TLS for all communications (not recommended).

    -D, --debug
        Log debug output.
        
    -k, --tls-key <key>
        Set the TLS private key (in PEM format) for this drand node. This
        parameter is required by default and can only be omitted if the
        --tls-disable flag is used.

    -l, --leader
        Set this node as the initator of the distributed key generation process.

    -L, --listen <address>
        Set a (internal) listening / binding address. Useful if drand runs
        behind a proxy, for example.
        
    -v, --verbosity <level>
        Set verbosity to the given level.

drand stop 
    Stop the drand daemon.

drand update [-l] old-group.toml new-group.toml
    Reshare the distributed key from the original set of nodes (old-group.toml)
    towards a new set (new-group.toml). 
    
    To execute this resharing at least t-of-n nodes from the original group have
    to be present. The new configuration can deviate arbitrarily from the old
    one including a different number of nodes n' or recovery threshold t'. 
    
    After the resharing has been finished successfully, all nodes in the new
    group switch to the public randomness generation mode while all nodes in the
    original group delete their outdated private key shares.

    Options:

    -l, --leader
        Set this node as the initator of the updating process.

[nikkolasg]

I'm coding the `update" function (well the beginning of it) and I'm thinking of a simpler way to call that:

drand update [-l] [--from oldGroup.toml] newGroup.toml

If you are an already established drand node, you should not need to specify from which old group you want to reshare, since there's only one and drand already got it saved for you in its folders. If you are a new drand node, you have to specify both since drand does not know any of these two informations.

That way we avoid an extra command for "old nodes" to retrieve the path of the old group toml to be able to give it to this drand command (while drand already knows it!).

I'm going this way I think for the moment, but please, I'm all ears for suggestions / comments & critics.

[Daeinar]

@nikkolasg Sorry I completely missed your message. Yeah I see your point and I agree.

Perhaps make the name of the flag a bit more explicit like --old-group old-group.toml?

Alternatively, we could specify the update command in such a way that if you give it only one parameter then it automatically assumes that you are an established node processing the file as new-group.toml and if you give it two then the first one is interpreted as old-group.toml and the second one as new-group.toml? Or would that be inconsistent to the other commands?

[nikkolasg]

Perhaps make the name of the flag a bit more explicit like --old-group old-group.toml?
Yes totally agree.

The only thing I'm afraid for the alternative with one or two arguments is the order of these arguments. There's no way to check if the client did ordered them correctly or the newgroup is at the first position or not.

[jeffallen]

drand stop currently gives a "not implemented yet" panic, which is a bit of an unwelcome surprise.