Skip to content

Commit

Permalink
doc : added aws documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@SuperBatata
SuperBatata committed Oct 16, 2024
1 parent 6012218 commit de4e034
Showing 1 changed file with 150 additions and 38 deletions.
188 changes: 150 additions & 38 deletions waltid-libraries/crypto/waltid-crypto/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,49 +11,32 @@
</a>
</div>

## Installation

Add the crypto library as a dependency to your Kotlin or Java project.

### walt.id Repository

Add the Maven repository which hosts the walt.id libraries to your build.gradle file.

```kotlin
repositories {
maven { url = uri("https://maven.waltid.dev/releases") }
}
```

### Library Dependency

Adding the crypto library as dependency. Specify the version that coincides with the latest or required
snapshot for your project. [Latest releases](https://github.com/walt-id/waltid-identity/releases).

```kotlin
dependencies {
implementation("id.walt.crypto:waltid-crypto:<version>")
}
```
## What it provides

Replace `version` with the version of the walt.id crypto library you want to use.
Note: As the crypto lib is part of the mono-repo walt.id identity, you need to use the version of
walt.id identity.
The library provides the following key entities to work with:

## What it provides
- [JWKKey](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-crypto/src/commonMain/kotlin/id/walt/crypto/keys/jwk/JWKKey.kt) -
an implementation of a local (in-memory) key (private / public)
- [TSEKey](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-crypto/src/commonMain/kotlin/id/walt/crypto/keys/tse/TSEKey.kt) -
an implementation of a Hashicorp Vault Transit Secrets Engine key (private / public)
- [OCIKey](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-crypto/src/commonMain/kotlin/id/walt/crypto/keys/oci/OCIKeyRestApi.kt) -
an implementation of an OCI key (private / public)
- [AWSKey](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-crypto/src/commonMain/kotlin/id/walt/crypto/keys/aws/AWSKey.kt) -
an implementation of an AWS key (private / public)

<table>
<tbody>
<!-- header -->
<tr>
<td align="center" rowspan="3">Feature</td>
<td align="center" rowspan="3" colspan="2">Category</td>
<td align="center" colspan="8">Key</td>
<td align="center" colspan="12">Key</td>
</tr>
<!-- sub-header key type -->
<tr>
<td align="center" colspan="4">Local</td>
<td align="center" colspan="4">TSE</td>
<td align="center" colspan="4">AWS</td>
</tr>
<!-- sub-sub-header key algorithm -->
<tr>
Expand All @@ -67,6 +50,11 @@ walt.id identity.
<td align="center">secp256k1</td>
<td align="center">secp256r1</td>
<td align="center">rsa</td>
<!-- aws -->
<td align="center">ed25519</td>
<td align="center">secp256k1</td>
<td align="center">secp256r1</td>
<td align="center">rsa</td>
</tr>
<!-- content -->
<!-- sign -->
Expand All @@ -84,6 +72,11 @@ walt.id identity.
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
<!-- aws -->
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
</tr>
<!-- raw -->
<tr>
Expand All @@ -98,6 +91,11 @@ walt.id identity.
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
<!-- aws -->
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
</tr>
<!-- end sign -->
<tr><td align="center" colspan="11"></td></tr>
Expand All @@ -116,6 +114,11 @@ walt.id identity.
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
<!-- aws -->
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
</tr>
<!-- raw -->
<tr>
Expand All @@ -130,6 +133,11 @@ walt.id identity.
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
<!-- aws -->
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
</tr>
<!-- end verify -->
<tr><td align="center" colspan="11"></td></tr>
Expand All @@ -150,6 +158,11 @@ walt.id identity.
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<!-- aws -->
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
</tr>
<!-- public -->
<tr>
Expand All @@ -164,6 +177,11 @@ walt.id identity.
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<!-- aws -->
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
<td align="center">&check;</td>
</tr>
<!-- pem -->
<!-- private -->
Expand All @@ -180,6 +198,11 @@ walt.id identity.
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<!-- aws -->
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
</tr>
<!-- public -->
<tr>
Expand All @@ -194,6 +217,11 @@ walt.id identity.
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<!-- aws -->
<td align="center">&cross;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
</tr>
<!-- JsonObject -->
<!-- private -->
Expand All @@ -210,6 +238,11 @@ walt.id identity.
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<!-- aws -->
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
</tr>
<!-- public -->
<tr>
Expand All @@ -224,6 +257,11 @@ walt.id identity.
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<!-- aws -->
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
</tr>
<!-- end export -->
<tr><td align="center" colspan="11"></td></tr>
Expand All @@ -244,6 +282,11 @@ walt.id identity.
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<!-- aws -->
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
</tr>
<!-- public -->
<tr>
Expand All @@ -258,6 +301,11 @@ walt.id identity.
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<!-- aws -->
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
</tr>
<!-- pem -->
<!-- private -->
Expand All @@ -274,6 +322,11 @@ walt.id identity.
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<!-- aws -->
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
</tr>
<!-- public -->
<tr>
Expand All @@ -288,6 +341,11 @@ walt.id identity.
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<!-- aws -->
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
</tr>
<!-- raw -->
<!-- private -->
Expand All @@ -304,6 +362,11 @@ walt.id identity.
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<!-- aws -->
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
<td align="center">&dash;</td>
</tr>
<!-- public -->
<tr>
Expand All @@ -318,6 +381,11 @@ walt.id identity.
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<!-- aws -->
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
<td align="center">&cross;</td>
</tr>
<!-- end import -->
</tbody>
Expand All @@ -327,6 +395,35 @@ walt.id identity.
- &cross; not implemented
- &dash; not available

## Installation

Add the crypto library as a dependency to your Kotlin or Java project.

### walt.id Repository

Add the Maven repository which hosts the walt.id libraries to your build.gradle file.

```kotlin
repositories {
maven { url = uri("https://maven.waltid.dev/releases") }
}
```

### Library Dependency

Adding the crypto library as dependency. Specify the version that coincides with the latest or required
snapshot for your project. [Latest releases](https://github.com/walt-id/waltid-identity/releases).

```kotlin
dependencies {
implementation("id.walt.crypto:waltid-crypto:<version>")
}
```

Replace `version` with the version of the walt.id crypto library you want to use.
Note: As the crypto lib is part of the mono-repo walt.id identity, you need to use the version of
walt.id identity.

### Signature schemes

| Type | ECDSA | JOSE ID | Description |
Expand Down Expand Up @@ -358,13 +455,6 @@ walt.id identity.

## How to use it

The library provides the following key entities to work with:

- [JWKKey](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-crypto/src/commonMain/kotlin/id/walt/crypto/keys/jwk/JWKKey.kt) -
an implementation of a local (in-memory) key (private / public)
- [TSEKey](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-crypto/src/commonMain/kotlin/id/walt/crypto/keys/tse/TSEKey.kt) -
an implementation of a Hashicorp Vault Transit Secrets Engine key (private / public)
- [OCIKey](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-crypto/src/commonMain/kotlin/id/walt/crypto/keys/oci/OCIKeyRestApi.kt) - an implementation of an OCI key (private / public)
### Working with JWKKey

**Create key**
Expand Down Expand Up @@ -398,7 +488,7 @@ val verificationResult = key.getPublicKey().verifyJws(signature)
- raw

```kotlin
val verificationResult = key.getPublicKey().verifyRaw(signature , payloadString.encodeToByteArray())
val verificationResult = key.getPublicKey().verifyRaw(signature, payloadString.encodeToByteArray())
```

**Import key**
Expand Down Expand Up @@ -429,7 +519,6 @@ val key = JWKKey.importRawPublicKey(KeyType.Ed25519, bytes, JWKKeyMetadata())
val jwkString = key.exportJWK()
```


- JsonObject

```kotlin
Expand Down Expand Up @@ -530,5 +619,28 @@ vault secrets enable transit
4. on the 'Enable a secrets engine' page, select 'Transit' from the 'Generic' group
5. click 'Next', then 'Enable Engine'

### Working with AWSKey

An AWS account is required in order to be able to use an `AWSKey` for signing and verification. This
implies covering the following steps:

1. [create an AWS account](https://aws.amazon.com/resources/create-account/)
2. [create an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html)
3. [create an access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user_manage_add-key.html)

#### AwsKeyMetadata

The `AWSKeyMetadata` class is used to specify the AWS access key ID, secret access key, and region.
It is used when creating an `AWSKey` instance.

```kotlin
@Serializable
data class AWSKeyMetadata(
val accessKeyId: String,
val secretAccessKey: String,
val region: String
)
```

For usage examples on _create_, _sign_, _verify_, _import_ and _export_ functions see
[Working with JWKKey](#working-with-jwkKey).

0 comments on commit de4e034

Please sign in to comment.