commit 9479b663fda654482588626d3fe10c1f8415909c
parent f1fd4a6c58e4d2bc7696bf9be64870ba09f1aec7
Author: Mikolai Gütschow <mikolai.guetschow@tu-dresden.de>
Date: Wed, 8 Apr 2026 17:01:15 +0200
crypto: add description for ECDH
Diffstat:
2 files changed, 391 insertions(+), 234 deletions(-)
diff --git a/draft-guetschow-taler-protocol.md b/draft-guetschow-taler-protocol.md
@@ -34,6 +34,7 @@ normative:
RFC2104:
RFC5869:
RFC6234:
+ RFC7748:
RFC8032:
HKDF: DOI.10.1007/978-3-642-14623-7_34
SHS: DOI.10.6028/NIST.FIPS.180-4
@@ -280,7 +281,84 @@ Output:
## Key Agreement
+### X25519
+Taler uses Elliptic Curve Diffie-Hellman (ECDH) on curve25519 as defined in Section 6.1 of [RFC7748],
+but reuses Ed25519 keypairs for one side of the agreement instead of random bytes.
+Depending on whether the private or public part is from Ed25519, two different functions are used.
+
+{::comment}
+see https://libsodium.gitbook.io/doc/advanced/scalar_multiplication
+see https://libsodium.gitbook.io/doc/advanced/ed25519-curve25519
+{:/}
+
+~~~
+ECDH-Ed25519-Priv(priv, pub) -> shared
+
+Input:
+ priv private Ed25519 key
+ pub public X25519 key
+
+Output:
+ shared shared secret based on the given keys
+~~~
+
+`shared` is calculated as follows, using the function X25519 defined in Section 5 of [RFC7748]:
+
+~~~
+priv' = SHA-512-256(priv)
+// todo: missing bit clamping from https://github.com/jedisct1/libsodium/blob/master/src/libsodium/crypto_sign/ed25519/ref10/keypair.c#L71
+shared' = X25519(priv', pub)
+shared = SHA-512(shared')
+~~~
+
+{::comment}
+see GNUNET_CRYPTO_eddsa_ecdh
+{:/}
+
+~~~
+ECDH-Ed25519-Pub(priv, pub) -> shared
+
+Input:
+ priv private X25519 key
+ pub public Ed25519 key
+
+Output:
+ shared shared secret based on the given keys
+~~~
+
+`shared` is calculated as follows, using the function X25519 defined in Section 5 of [RFC7748],
+and `Convert-Point-Ed25519-Curve25519(p)` which implements the birational map of Section 4.1 of [RFC7748]:
+
+~~~
+pub' = Convert-Point-Ed25519-Curve25519(pub)
+shared' = X25519(priv, pub')
+shared = SHA-512(shared')
+
+{::comment}
+see GNUNET_CRYPTO_eddsa_ecdh
+{:/}
+~~~
+
+~~~
+ECDH-GetPub(priv) -> pub
+
+Input:
+ priv private X25519 key
+
+Output:
+ pub public X25519 key
+~~~
+
+`pub` is calculated according to Section 6.1 of [RFC7748]:
+
+~~~
+pub = X25519(priv, 9)
+~~~
+
+{::comment}
+see GNUNET_CRYPTO_ecdhe_key_get_public
+{:/}
## Blind Signatures
@@ -843,7 +921,7 @@ The sum of the refresh fee of `denom` and the new denominations' values and with
must be smaller or equal to the residual value of the old `coin`.
The private key of each new coin candidate `⟨coinₖᵢ.priv⟩` is transitively derived from the old coin's private key `coin.priv`
-via a secret `⟨sharedₖᵢ⟩` according to `Refresh-Derive`.
+via a 512-bit secret `⟨sharedₖᵢ⟩` according to `Refresh-Derive`.
The secret is regeneratable with the knowledge of `coin.priv` via the link protocol (cf. {{link}}).
The derivation ensures that ownership of coins (knowledge of the private key) is correctly transferred,
and thereby that value transfer among untrusted parties can only happen via payment and deposit, not via refresh.
@@ -908,8 +986,6 @@ Knows coin |
where (for RSA, without age-restriction)
-// todo: document ECDH-EdDSA(priv, pub) (returns hash512)
-
{::comment}
// see TALER_EXCHANGE_get_melt_data
⟨batch_seedₖ⟩ // see TALER_refresh_expand_seed_to_kappa_batch_seeds
@@ -930,8 +1006,8 @@ refresh_seed = random(256)
for k in 0..κ:
⟨transferₖᵢ.priv⟩ = HKDF("refresh-transfer-private-keys", batch_seedₖ, "", n*32)
for i in 0..n:
- transferₖᵢ.pub = Ed25519-GetPub(transferₖᵢ.priv)
- sharedₖᵢ = ECDH-EdDSA(transferₖᵢ.priv, coin.pub)
+ transferₖᵢ.pub = ECDH-GetPub(transferₖᵢ.priv)
+ sharedₖᵢ = ECDH-Ed25519-Pub(transferₖᵢ.priv, coin.pub)
(coinₖᵢ, blind_secretₖᵢ, planchetₖᵢ, h_planchetₖᵢ) = Refresh-Derive(sharedₖᵢ, denomᵢ)
h_planchetsₖ = SHA-512( ⟨h_planchetₖᵢ⟩ )
value = coin.denom.fee_refresh + Sum ⟨denomᵢ.value⟩ + Sum ⟨denomᵢ.fee_withdraw⟩
@@ -1027,8 +1103,8 @@ Check not done // todo: sure?
for k in 0..κ and k != ɣ:
⟨transferₖᵢ.priv⟩ = HKDF("refresh-transfer-private-keys", batch_seedₖ, "", n*32)
for i in 0..n:
- transferₖᵢ.pub = Ed25519-GetPub(transferₖᵢ.priv)
- sharedₖᵢ = ECDH-EdDSA(transferₖᵢ.priv, coin.pub)
+ transferₖᵢ.pub = ECDH-GetPub(transferₖᵢ.priv)
+ sharedₖᵢ = ECDH-Ed25519-Pub(transferₖᵢ.priv, coin.pub)
(_, _, _, h_planchetₖᵢ) = Refresh-Derive(sharedₖᵢ, denomᵢ)
h_planchetsₖ = SHA-512( ⟨h_planchetₖᵢ⟩ )
value = coin.denom.fee_refresh + Sum ⟨denomᵢ.value⟩ + Sum ⟨denomᵢ.fee_withdraw⟩
@@ -1128,7 +1204,7 @@ for i in 0..n:
denomᵢ = Lookup by h_denomᵢ
for k in 0..κ:
for i in 0..n:
- sharedₖᵢ = ECDH-EdDSA(coin.priv, transferₖᵢ.pub)
+ sharedₖᵢ = ECDH-Ed25519-Priv(coin.priv, transferₖᵢ.pub)
(coinₖᵢ, blind_secretₖᵢ _, h_planchetₖᵢ) = Refresh-Derive(sharedₖᵢ, denomᵢ)
h_planchetsₖ = SHA-512( ⟨h_planchetₖᵢ⟩ )
value = coin.denom.fee_refresh + Sum ⟨denomᵢ.value⟩ + Sum ⟨denomᵢ.fee_withdraw⟩
diff --git a/draft-guetschow-taler-protocol.xml b/draft-guetschow-taler-protocol.xml
@@ -31,13 +31,13 @@
<keyword>ecash</keyword>
<keyword>payments</keyword>
<abstract>
- <?line 44?>
+ <?line 45?>
<t>[ TBW ]</t>
</abstract>
</front>
<middle>
- <?line 48?>
+ <?line 49?>
<section anchor="introduction">
<name>Introduction</name>
@@ -284,6 +284,63 @@ Output:
</section>
<section anchor="key-agreement">
<name>Key Agreement</name>
+ <section anchor="x25519">
+ <name>X25519</name>
+ <t>Taler uses Elliptic Curve Diffie-Hellman (ECDH) on curve25519 as defined in Section 6.1 of <xref target="RFC7748"/>,
+but reuses Ed25519 keypairs for one side of the agreement instead of random bytes.
+Depending on whether the private or public part is from Ed25519, two different functions are used.</t>
+ <artwork><![CDATA[
+ECDH-Ed25519-Priv(priv, pub) -> shared
+
+Input:
+ priv private Ed25519 key
+ pub public X25519 key
+
+Output:
+ shared shared secret based on the given keys
+]]></artwork>
+ <t><tt>shared</tt> is calculated as follows, using the function X25519 defined in Section 5 of <xref target="RFC7748"/>:</t>
+ <artwork><![CDATA[
+priv' = SHA-512-256(priv)
+// todo: missing bit clamping from https://github.com/jedisct1/libsodium/blob/master/src/libsodium/crypto_sign/ed25519/ref10/keypair.c#L71
+shared' = X25519(priv', pub)
+shared = SHA-512(shared')
+]]></artwork>
+ <artwork><![CDATA[
+ECDH-Ed25519-Pub(priv, pub) -> shared
+
+Input:
+ priv private X25519 key
+ pub public Ed25519 key
+
+Output:
+ shared shared secret based on the given keys
+]]></artwork>
+ <t><tt>shared</tt> is calculated as follows, using the function X25519 defined in Section 5 of <xref target="RFC7748"/>,
+and <tt>Convert-Point-Ed25519-Curve25519(p)</tt> which implements the birational map of Section 4.1 of <xref target="RFC7748"/>:</t>
+ <artwork><![CDATA[
+pub' = Convert-Point-Ed25519-Curve25519(pub)
+shared' = X25519(priv, pub')
+shared = SHA-512(shared')
+
+{::comment}
+see GNUNET_CRYPTO_eddsa_ecdh
+{:/}
+]]></artwork>
+ <artwork><![CDATA[
+ECDH-GetPub(priv) -> pub
+
+Input:
+ priv private X25519 key
+
+Output:
+ pub public X25519 key
+]]></artwork>
+ <t><tt>pub</tt> is calculated according to Section 6.1 of <xref target="RFC7748"/>:</t>
+ <artwork><![CDATA[
+pub = X25519(priv, 9)
+]]></artwork>
+ </section>
</section>
<section anchor="blind-signatures">
<name>Blind Signatures</name>
@@ -816,7 +873,7 @@ i.e. where <tt>contribution <= denom.value</tt></t>
<t>The sum of the refresh fee of <tt>denom</tt> and the new denominations' values and withdrawal fees (defined by the exchange)
must be smaller or equal to the residual value of the old <tt>coin</tt>.</t>
<t>The private key of each new coin candidate <tt>⟨coinₖᵢ.priv⟩</tt> is transitively derived from the old coin's private key <tt>coin.priv</tt>
-via a secret <tt>⟨sharedₖᵢ⟩</tt> according to <tt>Refresh-Derive</tt>.
+via a 512-bit secret <tt>⟨sharedₖᵢ⟩</tt> according to <tt>Refresh-Derive</tt>.
The secret is regeneratable with the knowledge of <tt>coin.priv</tt> via the link protocol (cf. <xref target="link"/>).
The derivation ensures that ownership of coins (knowledge of the private key) is correctly transferred,
and thereby that value transfer among untrusted parties can only happen via payment and deposit, not via refresh.</t>
@@ -879,7 +936,6 @@ Knows coin |
| |
]]></artwork>
<t>where (for RSA, without age-restriction)</t>
- <t>// todo: document ECDH-EdDSA(priv, pub) (returns hash512)</t>
<artwork><