From daf0f98660729d48f0b73083b922a970881fb8bf Mon Sep 17 00:00:00 2001
From: Pol Henarejos <55573252+polhenarejos@users.noreply.github.com>
Date: Thu, 17 Mar 2022 00:43:44 +0100
Subject: [PATCH] Update asymmetric-ciphering.md

Adding examples for ECDH key derivation.
---
 doc/asymmetric-ciphering.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/doc/asymmetric-ciphering.md b/doc/asymmetric-ciphering.md
index 344b09b..7f461af 100644
--- a/doc/asymmetric-ciphering.md
+++ b/doc/asymmetric-ciphering.md
@@ -4,6 +4,7 @@ Pico HSM supports in place decryption with the following algorithms:
 * RSA-PKCS
 * RSA-X-509
 * RSA-PKCS-OAEP
+* ECDH-DERIVE
 
 First, we generate the data:
 ```
@@ -76,3 +77,36 @@ OAEP parameters: hashAlg=SHA256, mgf=MGF1-SHA256, source_type=0, source_ptr=0x0,
 This is a test string. Be safe, be secure.
 ```
 
+## ECDH-DERIVE
+ECC keys do not allow ciphering operations. Instead, the ECDH scheme provides a mechanism to exchange a shared symmetric key without transmitting it to the remote part. The shared key is composed by multiplying the local private key and the remote public key. 
+
+First, we create the remote part, Bob, by generating an ECC keypair and getting the public key:
+```
+$ openssl ecparam -genkey -name prime192v1 > bob.pem
+$ openssl ec -in bob.pem -pubout -outform DER > bob.der
+```
+
+We derive the shared key by giving the Bob's public key to the Pico HSM:
+```
+$ pkcs11-tool --pin 648219 --id 11 --derive -i bob.der -o mine-bob.der
+```
+
+We compute the other shared key, with Bob's private key and our public key:
+```
+$ openssl pkeyutl -derive -out bob-mine.der -inkey bob.pem -peerkey 11.pub
+```
+
+Finally, we compare both shared keys:
+```
+$ cmp bob-mine.der mine-bob.der
+```
+
+If both are equal, no output is displayed.
+
+or displayed:
+```
+$ xxd -p bob-mine.der             
+9874558aefa9d92cc051e5da6d1753987e5314925d6d78bf
+$ xxd -p mine-bob.der             
+9874558aefa9d92cc051e5da6d1753987e5314925d6d78bf
+```