98 lines
3.1 KiB
Groff
98 lines
3.1 KiB
Groff
.TH "LIGHTNING-GETSHAREDSECRET" "7" "" "" "lightning-getsharedsecret"
|
|
.SH NAME
|
|
lightning-getsharedsecret - Command for computing an ECDH
|
|
.SH SYNOPSIS
|
|
|
|
\fBgetsharedsecret\fR \fIpoint\fR
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The \fBgetsharedsecret\fR RPC command computes a shared secret from a
|
|
given public \fIpoint\fR, and the secret key of this node\.
|
|
The \fIpoint\fR is a hexadecimal string of the compressed public
|
|
key DER-encoding of the SECP256K1 point\.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
On success, an object is returned, containing:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBshared_secret\fR (hex): the SHA-2 of the compressed encoding of the shared secp256k1 point (always 64 characters)
|
|
|
|
.RE
|
|
|
|
This command may fail if communications with the HSM has a
|
|
problem;
|
|
by default lightningd uses a software "HSM" which should
|
|
never fail in this way\.
|
|
(As of the time of this writing there is no true hardware
|
|
HSM that lightningd can use, but we are leaving this
|
|
possibilty open in the future\.)
|
|
In that case, it will return with an error code of 800\.
|
|
|
|
.SH CRYPTOGRAPHIC STANDARDS
|
|
|
|
This serves as a key agreement scheme in elliptic-curve based
|
|
cryptographic standards\.
|
|
|
|
|
|
However, note that most key agreement schemes based on
|
|
Elliptic-Curve Diffie-Hellman do not hash the DER-compressed
|
|
point\.
|
|
Standards like SECG SEC-1 ECIES specify using the X coordinate
|
|
of the point instead\.
|
|
The Lightning BOLT standard (which \fBlightningd\fR uses), unlike
|
|
most other cryptographic standards, specifies the SHA-256 hash
|
|
of the DER-compressed encoding of the point\.
|
|
|
|
|
|
It is not possible to extract the X coordinate of the ECDH point
|
|
via this API, since there is no known way to reverse the 256-bit
|
|
SHA-2 hash function\.
|
|
Thus there is no way to implement ECIES and similar standards using
|
|
this API\.
|
|
|
|
|
|
If you know the secret key behind \fIpoint\fR, you do not need to
|
|
even call \fBgetsharedsecret\fR, you can just multiply the secret key
|
|
with the node public key\.
|
|
|
|
|
|
Typically, a sender will generate an ephemeral secret key
|
|
and multiply it with the node public key,
|
|
then use the result to derive an encryption key
|
|
for a symmetric encryption scheme
|
|
to encrypt a message that can be read only by that node\.
|
|
Then the ephemeral secret key is multiplied
|
|
by the standard generator point,
|
|
and the ephemeral public key and the encrypted message is
|
|
sent to the node,
|
|
which then uses \fBgetsharedsecret\fR to derive the same key\.
|
|
|
|
|
|
The above sketch elides important details like
|
|
key derivation function, stream encryption scheme,
|
|
message authentication code, and so on\.
|
|
You should follow an established standard and avoid
|
|
rolling your own crypto\.
|
|
|
|
.SH AUTHOR
|
|
|
|
ZmnSCPxj \fI<ZmnSCPxj@protonmail.com\fR> is mainly responsible\.
|
|
|
|
.SH SEE ALSO
|
|
.SH RESOURCES
|
|
.RS
|
|
.IP \[bu]
|
|
BOLT 4: \fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#shared-secret\fR
|
|
.IP \[bu]
|
|
BOLT 8: \fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md#handshake-state\fR
|
|
.IP \[bu]
|
|
SECG SEC-1 ECIES: \fIhttps://secg.org/sec1-v2.pdf\fR
|
|
.IP \[bu]
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
.RE
|
|
\" SHA256STAMP:cff207f06144d00f76e494f84357e8d25609437376403656d6f61e64d49d9da1
|