From 98fafea1d8c08a3a36fd8aeea70fb149aba4c0fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bernd=20Pr=C3=BCnster?= Date: Thu, 16 Jan 2025 21:44:33 +0100 Subject: [PATCH] update docs --- docs/docs/supreme.md | 10 ++++++++++ .../asitplus/signum/supreme/agreement/KeyAgreement.kt | 4 ++++ 2 files changed, 14 insertions(+) diff --git a/docs/docs/supreme.md b/docs/docs/supreme.md index 9afb75ec..49fbad73 100644 --- a/docs/docs/supreme.md +++ b/docs/docs/supreme.md @@ -345,6 +345,16 @@ signer.keyAgreement(publicKey) { } ``` +!!! tip inline end + If you have an EC private key and know the curve, you already know the public key! + Hence, requiring the public keys of both parties for an ECDH key agreement is, in fact, a non-issue. + +Even though key agreement uses the private key of one party and the public key of another, the `keyAgreement` function +is only implemented for `CryptoPrivateKey.WithPublicKey`. I.e., both public keys need to be known. +This is necessary to assure that both keys lie on the same curve and are indeed compatible.
+ + + ## Digest Calculation The Supreme KMP crypto provider introduces a `digest()` extension function on the `Digest` class. For a list of supported algorithms, check out the [feature matrix](features.md#supported-algorithms). diff --git a/supreme/src/commonMain/kotlin/at/asitplus/signum/supreme/agreement/KeyAgreement.kt b/supreme/src/commonMain/kotlin/at/asitplus/signum/supreme/agreement/KeyAgreement.kt index c9449e63..81d7e590 100644 --- a/supreme/src/commonMain/kotlin/at/asitplus/signum/supreme/agreement/KeyAgreement.kt +++ b/supreme/src/commonMain/kotlin/at/asitplus/signum/supreme/agreement/KeyAgreement.kt @@ -41,6 +41,8 @@ suspend fun CryptoPublicKey.EC.keyAgreement( /** * Elliptic-curve Diffie-Hellman key agreement. * Curves of public key and signer need to match! + * This only works if both public keys are known, because otherwise, it is impossible + * to assure that both keys lie on the same curve. */ suspend fun CryptoPrivateKey.WithPublicKey.keyAgreement(publicKey: CryptoPublicKey.EC) = (SignatureAlgorithm.ECDSA(this.publicKey.curve.nativeDigest, this.publicKey.curve) @@ -52,6 +54,8 @@ suspend fun CryptoPrivateKey.WithPublicKey.keyAgreement(publ /** * Elliptic-curve Diffie-Hellman key agreement. * Curves of public key and signer need to match! + * This only works if both public keys are known, because otherwise, it is impossible + * to assure that both keys lie on the same curve. */ suspend fun CryptoPublicKey.EC.keyAgreement(privateKey: CryptoPrivateKey.WithPublicKey) = privateKey.keyAgreement(this)