Multiplatform library implementing cryptographic functionality, such as -signing and verifying content.
+
Create JSON Web Tokens (JWTs) that support Selective Disclosure
-[](https://github.com/walt-id/waltid-crypto/actions/workflows/release.yml)
-
-
| jwk | private | -‐ | -‐ | -‐ | -‐ | +✓ | +✓ | +✓ | +✓ | ‐ | ‐ | @@ -531,4 +296,222 @@ For usage examples on _create_, _sign_, _verify_, _import_ and _export_ function - ✓ implemented - ✗ not implemented -- ‐ not available \ No newline at end of file +- ‐ not available + +### Signature schemes + +| Type | ECDSA | JOSE ID | Description | +|:-----:|:---------:|:-------:|:----------------------------------------------------------------| +| EdDSA | Ed25519 | EdDSA | EdDSA + Curve25519 | +| ECDSA | secp256r1 | ES256 | ECDSA + SECG curve secp256r1 ("NIST P-256") | +| ECDSA | secp256k1 | ES256K | ECDSA + SECG curve secp256k1 (Koblitz curve as used in Bitcoin) | +| RSA | RSA | RS256 | RSA | + + +### Available on platforms + +| Platform | | Availability | +|:-----------:|:---------:|:------------:| +| Java | JVM | ✓ | +| JS | Node | ✓ | +| | WebCrypto | ✓ | +| Native | libsodium | ✗ | +| | OpenSSL | ✗ | +| WebAssembly | WASM | ✗ | + + + + +### JWS compatibility (recommended) + +| Algorithm | JVM provider | JS provider / platform | +|:---------:|:------------:|:---------------------------:| +| EdDSA | Nimbus JOSE | jose / Node.js | +| ES256 | Nimbus JOSE | jose / Node.js & Web Crypto | +| ES256K | Nimbus JOSE | jose / Node.js | +| RS256 | Nimbus JOSE | jose / Node.js & Web Crypto | + + +## 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 + +Check +the [encryption as a service tutorial](https://developer.hashicorp.com/vault/tutorials/encryption-as-a-service/eaas-transit#configure-transit-secrets-engine) +for more details on how to enable a Transit Secrets Engine. + +**Command line interface** + +Linux / MacOS + +```shell +export VAULT_TOKEN="dev-only-token" +export VAULT_ADDR='http://localhost:8200' +vault secrets enable transit +``` + +Windows + +```shell +set VAULT_TOKEN="dev-only-token" +set VAULT_ADDR=http://localhost:8200 +vault secrets enable transit +``` + +**User interface** + +1. log into the Vault (http://localhost:8200) with 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).