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 <rusty@rustcorp.com.au>

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 \

doc/index.rst

@@ -31,6 +31,7 @@ c-lightning Documentation
    lightningd-config <lightningd-config.5.md>
    lightning-autocleaninvoice <lightning-autocleaninvoice.7.md>
    lightning-check <lightning-check.7.md>
+   lightning-checkmessage <lightning-checkmessage.7.md>
    lightning-cli <lightning-cli.1.md>
    lightning-close <lightning-close.7.md>
    lightning-connect <lightning-connect.7.md>
@@ -56,6 +57,7 @@ c-lightning Documentation
    lightning-plugin <lightning-plugin.7.md>
    lightning-sendpay <lightning-sendpay.7.md>
    lightning-setchannelfee <lightning-setchannelfee.7.md>
+   lightning-signmessage <lightning-signmessage.7.md>
    lightning-txdiscard <lightning-txdiscard.7.md>
    lightning-txprepare <lightning-txprepare.7.md>
    lightning-txsend <lightning-txsend.7.md>

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<rusty@rustcorp.com.au\fR> is mainly responsible\.
+
+.SH SEE ALSO
+
+\fBlightning-signmessage\fR(7)
+
+.SH RESOURCES
+
+Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
+

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 <<rusty@rustcorp.com.au>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-signmessage(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>

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<rusty@rustcorp.com.au\fR> is mainly responsible\.
+
+.SH SEE ALSO
+
+\fBlightning-checkmessage\fR(7)
+
+.SH RESOURCES
+
+Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
+

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 <<rusty@rustcorp.com.au>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-checkmessage(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>