Browse Source
ChangeLog-Added: New `getsharedsecret` command, which lets you compute a shared secret with this node knowing only a public point. This implements the BOLT standard of hashing the ECDH point, and is incompatible with ECIES.travis-debug
ZmnSCPxj jxPCSnmZ
5 years ago
committed by
Rusty Russell
10 changed files with 284 additions and 2 deletions
@ -0,0 +1,96 @@ |
|||||
|
.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, \fBgetsharedsecret\fR returns a field \fIshared_secret\fR, |
||||
|
which is a hexadecimal string of the 256-bit SHA-2 of the |
||||
|
compressed public key DER-encoding of the SECP256K1 point |
||||
|
that is the shared secret generated using the |
||||
|
Elliptic Curve Diffie-Hellman algorithm\. |
||||
|
This field is 32 bytes (64 hexadecimal characters in a string)\. |
||||
|
|
||||
|
|
||||
|
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 |
@ -0,0 +1,93 @@ |
|||||
|
lightning-getsharedsecret -- Command for computing an ECDH |
||||
|
========================================================== |
||||
|
|
||||
|
SYNOPSIS |
||||
|
-------- |
||||
|
|
||||
|
**getsharedsecret** *point* |
||||
|
|
||||
|
DESCRIPTION |
||||
|
----------- |
||||
|
|
||||
|
The **getsharedsecret** RPC command computes a shared secret from a |
||||
|
given public *point*, and the secret key of this node. |
||||
|
The *point* is a hexadecimal string of the compressed public |
||||
|
key DER-encoding of the SECP256K1 point. |
||||
|
|
||||
|
RETURN VALUE |
||||
|
------------ |
||||
|
|
||||
|
On success, **getsharedsecret** returns a field *shared\_secret*, |
||||
|
which is a hexadecimal string of the 256-bit SHA-2 of the |
||||
|
compressed public key DER-encoding of the SECP256K1 point |
||||
|
that is the shared secret generated using the |
||||
|
Elliptic Curve Diffie-Hellman algorithm. |
||||
|
This field is 32 bytes (64 hexadecimal characters in a string). |
||||
|
|
||||
|
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. |
||||
|
|
||||
|
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 `lightningd` 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 *point*, you do not need to |
||||
|
even call **getsharedsecret**, 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 **getsharedsecret** 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. |
||||
|
|
||||
|
AUTHOR |
||||
|
------ |
||||
|
|
||||
|
ZmnSCPxj <<ZmnSCPxj@protonmail.com>> is mainly responsible. |
||||
|
|
||||
|
SEE ALSO |
||||
|
-------- |
||||
|
|
||||
|
RESOURCES |
||||
|
--------- |
||||
|
|
||||
|
* BOLT 4: <https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#shared-secret> |
||||
|
* BOLT 8: <https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md#handshake-state> |
||||
|
* SECG SEC-1 ECIES: <https://secg.org/sec1-v2.pdf> |
||||
|
* Main web site: <https://github.com/ElementsProject/lightning> |
||||
|
|
Loading…
Reference in new issue