From ad48814746878647e6b86173283b693e55a06cac Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Sun, 13 Oct 2019 15:49:37 +1030 Subject: [PATCH] doc: man pages for checkmessage and signmessage. They're a little subtle, so let's spell out exactly what checkmessage means. In particular, we avoid discussing key derivation from a signature, as it tends to get people (like me!) into trouble: we describe it instead as iterating through every known node. Signed-off-by: Rusty Russell --- doc/Makefile | 2 ++ doc/index.rst | 2 ++ doc/lightning-checkmessage.7 | 49 +++++++++++++++++++++++++++++++ doc/lightning-checkmessage.7.md | 51 +++++++++++++++++++++++++++++++++ doc/lightning-signmessage.7 | 35 ++++++++++++++++++++++ doc/lightning-signmessage.7.md | 38 ++++++++++++++++++++++++ 6 files changed, 177 insertions(+) create mode 100644 doc/lightning-checkmessage.7 create mode 100644 doc/lightning-checkmessage.7.md create mode 100644 doc/lightning-signmessage.7 create mode 100644 doc/lightning-signmessage.7.md diff --git a/doc/Makefile b/doc/Makefile index a51bcb101..682e488cd 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -9,6 +9,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightningd-config.5 \ doc/lightning-autocleaninvoice.7 \ doc/lightning-check.7 \ + doc/lightning-checkmessage.7 \ doc/lightning-close.7 \ doc/lightning-connect.7 \ doc/lightning-decodepay.7 \ @@ -33,6 +34,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-plugin.7 \ doc/lightning-sendpay.7 \ doc/lightning-setchannelfee.7 \ + doc/lightning-signmessage.7 \ doc/lightning-txprepare.7 \ doc/lightning-txdiscard.7 \ doc/lightning-txsend.7 \ diff --git a/doc/index.rst b/doc/index.rst index 1c791ac51..7e59b0345 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -31,6 +31,7 @@ c-lightning Documentation lightningd-config lightning-autocleaninvoice lightning-check + lightning-checkmessage lightning-cli lightning-close lightning-connect @@ -56,6 +57,7 @@ c-lightning Documentation lightning-plugin lightning-sendpay lightning-setchannelfee + lightning-signmessage lightning-txdiscard lightning-txprepare lightning-txsend diff --git a/doc/lightning-checkmessage.7 b/doc/lightning-checkmessage.7 new file mode 100644 index 000000000..ad03f7ba0 --- /dev/null +++ b/doc/lightning-checkmessage.7 @@ -0,0 +1,49 @@ +.TH "LIGHTNING-CHECKMESSAGE" "7" "" "" "lightning-checkmessage" +.SH NAME +lightning-checkmessage - Command to check a signature is from a node +.SH SYNOPSIS + +\fBcheckmessage\fR \fImessage\fR \fIzbase\fR [\fIpubkey\fR] + +.SH DESCRIPTION + +The \fBcheckmessage\fR RPC command is the counterpart to +\fBsignmessage\fR: given a node id (\fIpubkey\fR), signature (\fIzbase\fR) and a +\fImessage\fR, it verifies that the signature was generated by that node +for that message (more technically: by someone who knows that node's +secret)\. + + +As a special case, if \fIpubkey\fR is not specified, we will try every +known node key (as per \fIlistnodes\fR), and verification succeeds if it +matches for any one of them\. Note: this is implemented far more +efficiently than trying each one, so performance is not a concern\. + +.SH RETURN VALUE + +On correct usage, an object with attribute \fIverified\fR will be +returned\. + + +If \fIverified\fR is true, the signature was generated by the returned +\fIpubkey\fR for that given message\. \fIpubkey\fR is the one specified as +input, or if none was specified, the known node which must have +produced this signature\. + + +If \fIverified\fR is false, the signature is meaningless\. \fIpubkey\fR may +also be returned, which is they \fIpubkey\fR (if any) for which this +signature would be valid\. This is usually not useful\. + +.SH AUTHOR + +Rusty Russell \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-signmessage\fR(7) + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + diff --git a/doc/lightning-checkmessage.7.md b/doc/lightning-checkmessage.7.md new file mode 100644 index 000000000..bcd45b484 --- /dev/null +++ b/doc/lightning-checkmessage.7.md @@ -0,0 +1,51 @@ +lightning-checkmessage -- Command to check a signature is from a node +===================================================================== + +SYNOPSIS +-------- + +**checkmessage** *message* *zbase* \[*pubkey*\] + +DESCRIPTION +----------- + +The **checkmessage** RPC command is the counterpart to +**signmessage**: given a node id (*pubkey*), signature (*zbase*) and a +*message*, it verifies that the signature was generated by that node +for that message (more technically: by someone who knows that node's +secret). + +As a special case, if *pubkey* is not specified, we will try every +known node key (as per *listnodes*), and verification succeeds if it +matches for any one of them. Note: this is implemented far more +efficiently than trying each one, so performance is not a concern. + +RETURN VALUE +------------ + +On correct usage, an object with attribute *verified* will be +returned. + +If *verified* is true, the signature was generated by the returned +*pubkey* for that given message. *pubkey* is the one specified as +input, or if none was specified, the known node which must have +produced this signature. + +If *verified* is false, the signature is meaningless. *pubkey* may +also be returned, which is they *pubkey* (if any) for which this +signature would be valid. This is usually not useful. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-signmessage(7) + +RESOURCES +--------- + +Main web site: diff --git a/doc/lightning-signmessage.7 b/doc/lightning-signmessage.7 new file mode 100644 index 000000000..296caa9e5 --- /dev/null +++ b/doc/lightning-signmessage.7 @@ -0,0 +1,35 @@ +.TH "LIGHTNING-SIGNMESSAGE" "7" "" "" "lightning-signmessage" +.SH NAME +lightning-signmessage - Command to create a signature from this node +.SH SYNOPSIS + +\fBsignmessage\fR \fImessage\fR + +.SH DESCRIPTION + +The \fBsignmessage\fR RPC command creates a digital signature of +\fImessage\fR using this node's secret key\. A receiver who knows your +node's \fIid\fR and the \fImessage\fR can be sure that the resulting signature could +only be created by something with access to this node's secret key\. + + +\fImessage\fR must be less that 65536 characters\. + +.SH RETURN VALUE + +An object with attributes \fIsignature\fR, \fIrecid\fR and \fIzbase\fR is +returned\. \fIzbase\fR is the result of \fIsignature\fR and \fIrecid\fR encoded in +a style compatible with \fBlnd\fR's \fBSignMessageRequest\fR (\fIhttps://api.lightning.community/#grpc-request-signmessagerequest\fR)\. + +.SH AUTHOR + +Rusty Russell \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-checkmessage\fR(7) + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + diff --git a/doc/lightning-signmessage.7.md b/doc/lightning-signmessage.7.md new file mode 100644 index 000000000..01ea5d073 --- /dev/null +++ b/doc/lightning-signmessage.7.md @@ -0,0 +1,38 @@ +lightning-signmessage -- Command to create a signature from this node +===================================================================== + +SYNOPSIS +-------- + +**signmessage** *message* + +DESCRIPTION +----------- + +The **signmessage** RPC command creates a digital signature of +*message* using this node's secret key. A receiver who knows your +node's *id* and the *message* can be sure that the resulting signature could +only be created by something with access to this node's secret key. + +*message* must be less that 65536 characters. + +RETURN VALUE +------------ +An object with attributes *signature*, *recid* and *zbase* is +returned. *zbase* is the result of *signature* and *recid* encoded in +a style compatible with **lnd**'s [SignMessageRequest](https://api.lightning.community/#grpc-request-signmessagerequest). + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-checkmessage(7) + +RESOURCES +--------- + +Main web site: