docs: crypto - enhanced readme

walt-id · Nov 24, 2023 · c8ae777 · c8ae777
1 parent b2d4725
commit c8ae777
Show file tree

Hide file tree

Showing 3 changed files with 221 additions and 52 deletions.
diff --git a/README.md b/README.md
@@ -21,24 +21,4 @@ docker run -p 7000:7000 waltid/issuer --webHost=0.0.0.0 --webPort=7000 --baseUrl
 ```shell
 docker build -t waltid/verifier -f docker/verifier.Dockerfile .
 docker run -p 7001:7001 waltid/verifier --webHost=0.0.0.0 --webPort=7001 --baseUrl=http://localhost:7001
-```
-
-### (Optional) Setup Vault
-
-#### apt
-
-```shell
-wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
-echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo
-tee /etc/apt/sources.list.d/hashicorp.list
-sudo apt update && sudo apt install vault
-```
-
-```shell
-vault server -dev -dev-root-token-id="dev-only-token"
-```
-#### Docker
-
-```shell
-docker run -p 8200:8200 --cap-add=IPC_LOCK -e VAULT_DEV_ROOT_TOKEN_ID=myroot -e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 hashicorp/vault
-```
+```
diff --git a/waltid-crypto/README.md b/waltid-crypto/README.md
@@ -1,13 +1,37 @@
-# walt.id Crypto
+<div align="center">
+ <h1>Crypto - Kotlin multiplatform library</h1>
+ <span>by </span><a href="https://walt.id">walt.id</a>
+ <p>Multiplatform library implementing cryptographic functionality, such as
+signing and verifying content.<p>
 
-## Platforms available:
+[![CI/CD Workflow for walt.id Crypto](https://github.com/walt-id/waltid-crypto/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/walt-id/waltid-crypto/actions/workflows/release.yml)
+<a href="https://walt.id/community">
+<img src="https://img.shields.io/badge/Join-The Community-blue.svg?style=flat" alt="Join community!" />
+</a>
+<a href="https://twitter.com/intent/follow?screen_name=walt_id">
+<img src="https://img.shields.io/twitter/follow/walt_id.svg?label=Follow%20@walt_id" alt="Follow @walt_id" />
+</a>
 
-- Java: JVM
-- JS: Node.js or WebCrypto
-- Native: libsodium & OpenSSL (todo)
-- WebAssembly (WASM): (todo)
 
-## Signature schemes available:
+</div>
+
+## Available on platforms
+
+|  Platform   |           | Availability |
+|:-----------:|:---------:|:------------:|
+|    Java     |    JVM    |   &check;    |
+|     JS      |   Node    |   &check;    |
+|             | WebCrypto |   &check;    |
+|   Native    | libsodium |   &cross;    |
+|             |  OpenSSL  |   &cross;    |
+| WebAssembly |   WASM    |   &cross;    |
+
+## What it provides
+
+- key import / export functions - _jwk_, _pem_, _raw_ formats
+- key sign / verify functions - _jws_, _raw_ formats
+
+### Signature schemes
 
 | Type  |   ECDSA   | JOSE ID | Description                                                     |
 |:-----:|:---------:|:-------:|:----------------------------------------------------------------|
@@ -16,9 +40,7 @@
 | ECDSA | secp256k1 | ES256K  | ECDSA + SECG curve secp256k1 (Koblitz curve as used in Bitcoin) |
 |  RSA  |    RSA    |  RS256  | RSA                                                             |
 
-## Compatibility matrix:
-
-### JWS (recommended)
+### JWS compatibility (recommended)
 
 | Algorithm | JVM provider |   JS provider / platform    |
 |:---------:|:------------:|:---------------------------:|
@@ -27,7 +49,9 @@
 |  ES256K   | Nimbus JOSE  |       jose / Node.js        |
 |   RS256   | Nimbus JOSE  | jose / Node.js & Web Crypto |
 
-### LD Signatures (happy to add upon request - [email protected])
+### LD Signatures compatibility
+
+(happy to add upon request - [email protected])
 
 |            Suite            |    JVM provider    |    JS provider    |
 |:---------------------------:|:------------------:|:-----------------:|
@@ -37,6 +61,166 @@
 |      RsaSignature2018       | ld-signatures-java |                   |
 |    JsonWebSignature2020     | ld-signatures-java |                   |
 
+## How to use it
+
+The library offers the following key entities to work with:
+
+- [LocalKey
+  ](https://github.com/walt-id/waltid-identity/blob/main/waltid-crypto/src/commonMain/kotlin/id/walt/crypto/keys/LocalKey.kt) -
+  an implementation of a local (in-memory) key (private / public)
+- [TSEKey
+  ](https://github.com/walt-id/waltid-identity/blob/main/waltid-crypto/src/commonMain/kotlin/id/walt/crypto/keys/TSEKey.kt) -
+  an implementation of a Hashicorp Vault Transit Secrets Engine key (private / public)
+
+### Working with LocalKey
+
+**Create key**
+
+```kotlin
+val key = LocalKey.generate(KeyType.Ed25519, LocalKeyMetadata())
+```
+
+**Sign**
+
+- jws
+
+```kotlin
+val signature = key.signJws(payloadString.encodeToByteArray())
+```
+
+- raw
+
+```kotlin
+val signature = key.signRaw(payloadString.encodeToByteArray())
+```
+
+**Verify**
+
+- jws
+
+```kotlin
+val verificationResult = key.getPublicKey().verifyJws(signature)
+```
+
+- raw
+
+```kotlin
+val verificationResult = key.getPublicKey().verifyRaw(signature as ByteArray)
+```
+
+**Import key**
+
+- jwk
+
+```kotlin
+val keyResult = LocalKey.importJWK(jwkString)
+```
+
+- pem
+
+```kotlin
+val keyResult = LocalKey.importPEM(pemString)
+```
+
+- raw
+
+```kotlin
+val key = LocalKey.importRawPublicKey(KeyType.Ed25519, bytes, LocalKeyMetadata())
+```
+
+**Export public key**
+
+- jwk
+
+```kotlin
+val jwkString = key.exportJWK()
+```
+
+- pem
+
+```kotlin
+val pemString = key.exportPEM()
+```
+
+- JsonObject
+
+```kotlin
+val jwkObject = key.exportJWKObject()
+```
+
+### Working with TSEKey
+
+A Hashicorp Vault's Transit Secrets Engine instance is required in order to be able to use a
+`TSEKey` for signing and verification. This implies covering the following steps:
+
+1. [set up the vault](#setup-vault)
+2. [enable a Transit Secrets Engine instance](#enable-a-transit-secrets-engine-instance)
+
+### Setup Vault
+
+More details about installing Hashicorp Vault can be found in the Hashicorp Vault
+[documentation](https://developer.hashicorp.com/vault/docs/install)
+and [tutorials](https://developer.hashicorp.com/vault/install).
+
+#### Linux
+
+- [binary download](https://developer.hashicorp.com/vault/install)
+- package manager (see below)
+
+Install the vault using the package manager:
+
+```shell
+wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
+echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo
+tee /etc/apt/sources.list.d/hashicorp.list
+sudo apt update && sudo apt install vault
+```
+
+Start up the vault server:
+
+```shell
+vault server -dev -dev-root-token-id="dev-only-token"
+```
+
+#### MacOS
+
+- [binary download](https://developer.hashicorp.com/vault/install)
+- package manager (see below)
+
+Install the vault using the package manager:
+
+```shell
+brew tap hashicorp/tap
+brew install hashicorp/tap/vault
+```
+
+Start up the vault server:
+
+```shell
+vault server -dev -dev-root-token-id="dev-only-token"
+```
+
+#### Windows
+
+- [binary download](https://developer.hashicorp.com/vault/install)
+
+#### Docker
+
+```shell
+docker run -p 8200:8200 --cap-add=IPC_LOCK -e VAULT_DEV_ROOT_TOKEN_ID=myroot -e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 hashicorp/vault
+```
+
+### Enable a Transit Secrets Engine instance
+
+1. log into the Vault (http://localhost:8200) using the token (_dev-only-token_)
+2. on the left-side menu, select 'Secrets Engines'
+3. on the 'Secrets Engines' page, select 'enable new engine'
+4. on the 'Enable a secrets engine' page, select 'Transit' from the 'Generic' group
+5. click 'Next', then 'Enable Engine'
+
+For usage examples on _create_, _sign_, _verify_, _import_ and _export_ functions see
+[Working with LocalKey](#working-with-localkey).
+
 
 ## Feature set status
 
@@ -139,10 +323,10 @@
             <td align="center" rowspan="2">jwk</td>
             <td align="center">private</td>
             <!-- local -->
-            <td align="center">&check;</td>
-            <td align="center">&check;</td>
-            <td align="center">&check;</td>
-            <td align="center">&check;</td>
+            <td align="center">&dash;</td>
+            <td align="center">&dash;</td>
+            <td align="center">&dash;</td>
+            <td align="center">&dash;</td>
             <!-- tse -->
             <td align="center">&dash;</td>
             <td align="center">&dash;</td>
@@ -169,10 +353,10 @@
             <td align="center" rowspan="2">pem</td>
             <td align="center">private</td>
             <!-- local -->
-            <td align="center">&cross;</td>
-            <td align="center">&cross;</td>
-            <td align="center">&cross;</td>
-            <td align="center">&cross;</td>
+            <td align="center">&dash;</td>
+            <td align="center">&dash;</td>
+            <td align="center">&dash;</td>
+            <td align="center">&dash;</td>
             <!-- tse -->
             <td align="center">&dash;</td>
             <td align="center">&dash;</td>
@@ -199,10 +383,10 @@
             <td align="center" rowspan="2">JsonObject</td>
             <td align="center">private</td>
             <!-- local -->
-            <td align="center">&check;</td>
-            <td align="center">&check;</td>
-            <td align="center">&check;</td>
-            <td align="center">&check;</td>
+            <td align="center">&dash;</td>
+            <td align="center">&dash;</td>
+            <td align="center">&dash;</td>
+            <td align="center">&dash;</td>
             <!-- tse -->
             <td align="center">&dash;</td>
             <td align="center">&dash;</td>
@@ -320,3 +504,7 @@
         <!-- end import -->
     </tbody>
 </table>
+
+- &check; implemented
+- &cross; not implemented
+- &dash; not available
diff --git a/waltid-crypto/src/jvmTest/kotlin/ExportKeyTests.kt b/waltid-crypto/src/jvmTest/kotlin/ExportKeyTests.kt
@@ -27,14 +27,15 @@ class ExportKeyTests {
 
     @ParameterizedTest
     @MethodSource
-    fun `given key, when exporting JsonObject then the result is a valid jwk string`(keyFile: String, jwkFile: String) = runTest {
-        // given
-        val key = KeySerialization.deserializeKey(keyFile).getOrThrow()
-        // when
-        val export = key.exportJWKObject()
-        // then
-        assertEquals(jwkFile.replace("\\s".toRegex(), ""), export.toString())
-    }
+    fun `given key, when exporting JsonObject then the result is a valid jwk string`(keyFile: String, jwkFile: String) =
+        runTest {
+            // given
+            val key = KeySerialization.deserializeKey(keyFile).getOrThrow()
+            // when
+            val export = key.exportJWKObject()
+            // then
+            assertEquals(jwkFile.replace("\\s".toRegex(), ""), export.toString())
+        }
 
     @ParameterizedTest
     @MethodSource