From 42023753a23db3828c045a00d5f509cb01d93ffd Mon Sep 17 00:00:00 2001 From: Benjamin Canou Date: Thu, 1 Feb 2018 22:43:09 +0100 Subject: [PATCH] Client: add signer modules documentation --- src/lib_client_base/client_keys.ml | 55 ++++++++++++++----- src/lib_client_base/client_keys.mli | 7 +++ .../client_signer_unencrypted.ml | 11 ++++ 3 files changed, 60 insertions(+), 13 deletions(-) diff --git a/src/lib_client_base/client_keys.ml b/src/lib_client_base/client_keys.ml index 7c3491c81..bde4d8292 100644 --- a/src/lib_client_base/client_keys.ml +++ b/src/lib_client_base/client_keys.ml @@ -115,6 +115,8 @@ module type SIGNER = sig type secret_key type public_key val scheme : string + val title : string + val description : string val sk_locator_of_human_input : Client_commands.logging_wallet -> string list -> sk_locator tzresult Lwt.t @@ -288,15 +290,30 @@ let commands () = ~parameter:"-show-secret" ~doc:"show the private key" in [ - command ~group ~desc: "List supported signing schemes." + command ~group + ~desc: "List supported signing schemes.\n\ + Signing schemes are identifiers for signer modules: the \ + built-in signing routines, a hardware wallet, an \ + external agent, etc.\n\ + Each signer has its own format for describing secret \ + keys, such a raw secret key for the default \ + `unencrypted` scheme, the path on a hardware security \ + module, an alias for an external agent, etc.\n\ + This command gives the list of signer modules that this \ + version of the tezos client supports." no_options (fixed [ "list" ; "signing" ; "schemes" ]) (fun () (cctxt : Client_commands.full_context) -> let schemes = Hashtbl.fold (fun k _ a -> k :: a) signers_table [] in let schemes = List.sort String.compare schemes in - Lwt_list.iter_s (cctxt#message "%s") schemes >>= return) ; + Lwt_list.iter_s + (fun n -> + let (module S : SIGNER) = Hashtbl.find signers_table n in + cctxt#message "@[Scheme `%s`: %s@,@[%a@]@]" + n S.title Format.pp_print_text S.description) + schemes >>= return) ; - command ~group ~desc: "Generate a pair of keys." + command ~group ~desc: "Generate a pair of (unencrypted) keys." (args1 Secret_key.force_switch) (prefixes [ "gen" ; "keys" ] @@ Secret_key.fresh_alias_param @@ -305,7 +322,7 @@ let commands () = Secret_key.of_fresh cctxt force name >>=? fun name -> gen_keys ~force cctxt name) ; - command ~group ~desc: "Generate keys including the given string" + command ~group ~desc: "Generate (unencrypted) keys including the given string." (args2 (switch ~doc:"the key must begin with tz1[word]" ~parameter:"-prefix") force_switch) @@ -322,12 +339,18 @@ let commands () = (prefix "import" @@ string ~name:"scheme" - ~desc:"Scheme to use when adding a secret key" + ~desc:"signer to use for this secret key\n\ + Use command `list signing schemes` for a list of \ + supported signers." @@ prefixes [ "secret" ; "key" ] @@ Secret_key.fresh_alias_param - @@ seq_of_param (string - ~name:"secret key specification" - ~desc:"Specification of a secret key")) + @@ seq_of_param + (string + ~name:"spec" + ~desc:"secret key specification\n\ + Varies from one scheme to the other.\n\ + Use command `list signing schemes` for more \ + information.")) (fun force scheme name spec cctxt -> Secret_key.of_fresh cctxt force name >>=? fun name -> Lwt.return (find_signer_for_key ~scheme) >>=? fun signer -> @@ -350,17 +373,23 @@ let commands () = please don't use -force" name) >>=? fun () -> Secret_key.add ~force cctxt name skloc) ; - command ~group ~desc: "add a public key to the wallet." + command ~group ~desc: "Add a public key to the wallet." (args1 Public_key.force_switch) (prefix "import" @@ string ~name:"scheme" - ~desc:"Scheme to use when adding a public key" + ~desc:"signer to use for this public key\n\ + Use command `list signing schemes` for a list of \ + supported signers." @@ prefixes [ "public" ; "key" ] @@ Public_key.fresh_alias_param - @@ seq_of_param (string - ~name:"public key specification" - ~desc:"Specification of a public key")) + @@ seq_of_param + (string + ~name:"spec" + ~desc:"public key specification\n\ + Varies from one scheme to the other.\n\ + Use command `list signing schemes` for more \ + information.")) (fun force scheme name location cctxt -> Public_key.of_fresh cctxt force name >>=? fun name -> Lwt.return (find_signer_for_key ~scheme) >>=? fun signer -> diff --git a/src/lib_client_base/client_keys.mli b/src/lib_client_base/client_keys.mli index 2f3405ddc..11aa08b5d 100644 --- a/src/lib_client_base/client_keys.mli +++ b/src/lib_client_base/client_keys.mli @@ -45,6 +45,13 @@ module type SIGNER = sig (** [scheme] is the name of the scheme implemented by this signer module. *) + val title : string + (** [title] is a one-line human readable description of the signer. *) + + val description : string + (** [description] is a multi-line human readable description of the + signer, that should include the format of key specifications. *) + val sk_locator_of_human_input : Client_commands.logging_wallet -> string list -> sk_locator tzresult Lwt.t diff --git a/src/lib_client_base/client_signer_unencrypted.ml b/src/lib_client_base/client_signer_unencrypted.ml index 9a38aadf8..dded020bd 100644 --- a/src/lib_client_base/client_signer_unencrypted.ml +++ b/src/lib_client_base/client_signer_unencrypted.ml @@ -12,6 +12,17 @@ open Client_keys module Unencrypted_signer : SIGNER = struct let scheme = "unencrypted" + let title = + "Built-in signer using raw unencrypted keys." + + let description = + "Do not use this signer except for playing on the test network.\n\ + The format for importing secret keys is either no argument (will \ + generate a key) or the raw Base58-encoded key (starting with \ + 'edsk').\n\ + The format for importing public keys is the raw Base58-encoded \ + key (starting with 'edpk')." + type secret_key = Ed25519.Secret_key.t type public_key = Ed25519.Public_key.t