Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add wiki pages for identity v1.1 #1414

Merged
merged 21 commits into from
Feb 7, 2024
Merged
Show file tree
Hide file tree
Changes from 14 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions banners/identity-06-deprecation-migration.mdx

This file was deleted.

1 change: 0 additions & 1 deletion banners/identity-deprecated.mdx

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -20,21 +20,20 @@ See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/

### Replay Attacks

A verifiable presentation without a challenge and domain properties could potentially be stored by a malicious actor
A verifiable presentation without a challenge could potentially be stored by a malicious actor
and replayed to a different verifier, impersonating the holder.
This is because the holder's signature on a presentation would still be seen as valid indefinitely,
until they [rotate](https://www.w3.org/TR/did-core/#verification-method-rotation) the verification method used.

To mitigate this, verifiers should always send a unique challenge and domain when requesting a verifiable presentation.
These properties are then included in the proof section of the presentation by the holder during signing using [Proof Options](#proof-options).
To mitigate this, verifiers should always send a unique challenge when requesting a verifiable presentation.
This challenge can be set as the `nonce` property of the JWS by the holder during signing.
The digital signature prevents these properties from being altered as it would invalidate the signature, effectively preventing a malicious
actor from injecting different values into old verifiable presentations. A presentation without a challenge and domain
in its proof that matches what was sent by the verifier should be considered invalid.
actor from injecting different values into old verifiable presentations. A presentation without a challenge in its proof that matches what was
sent by the verifier should be considered invalid.

The challenge string should be sufficiently random and unique for each verifiable presentation requested by a verifier to avoid
being predicted. The domain, which does not need to be random, is an additional measure. In the unlikely occurrence
of two verifiers generating the same random challenge, the domain would sufficiently distinguish those requests.
being predicted.

Holders may additionally specify that their signature on a verifiable presentation expires after a short duration, as
per [Proof Options](./../how-tos/verifiable-presentations/create-and-validate.mdx#proof-options). However, verifiers and different implementations could choose to ignore that property,
so setting a signature expiration alone should not be relied upon.
per `JwtPresentationOptions`. However, verifiers and different implementations could choose to ignore that property,
so setting a signature expiration alone should not be relied upon.
2 changes: 1 addition & 1 deletion docs/build/identity.rs/1.0/docs/getting-started/rust.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ identity_iota = { git = "https://github.com/iotaledger/identity.rs", branch = "m

## Examples

To try out the [examples](https://github.com/iotaledger/identity.rs/tree/main/examples), you should:
To try out the [examples](https://github.com/iotaledger/identity.rs/tree/v1.0.0/examples), you should:

1. Clone the repository:

Expand Down
2 changes: 1 addition & 1 deletion docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -341,4 +341,4 @@ You may find it useful to see how the WASM bindings are being used in existing a

## [API Reference](/identity.rs/references/api/wasm)

## [Examples](https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/README.md)
## [Examples](https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/README.md)
Original file line number Diff line number Diff line change
Expand Up @@ -45,14 +45,14 @@ you will need an output with actual Shimmer or IOTA funds to create a new Alias
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L52
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs#L52
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L40-L51
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L40-L51
```

</TabItem>
Expand All @@ -77,14 +77,14 @@ the DID inside the document.
<TabItem value="rust" label="Rust">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L59-L71
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs#L59-L71
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L55C44-L65
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L55C44-L65
```

</TabItem>
Expand All @@ -107,14 +107,14 @@ However, they must be unlocked in order perform a state or governance transition
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L75
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs#L75
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L70
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L70
```

</TabItem>
Expand All @@ -139,14 +139,14 @@ the DID Document is stored on the ledger and can be [resolved](resolve.mdx) usin
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L78
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs#L78
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L74
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L74
```

</TabItem>
Expand All @@ -159,14 +159,14 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts
```

</TabItem>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,14 +46,14 @@ and optionally reclaiming the storage deposit.
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/3_deactivate_did.rs
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/3_deactivate_did.rs
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/3_deactivate_did.ts
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/3_deactivate_did.ts
```

</TabItem>
Expand Down Expand Up @@ -92,14 +92,14 @@ The following example demonstrates a governor destroys an IOTA Identity and send
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/4_delete_did.rs
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/4_delete_did.rs
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/4_delete_did.ts
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/4_delete_did.ts
```

</TabItem>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -167,14 +167,14 @@ and [credentials](./../../explanations/verifiable-credentials.mdx).
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/5_custom_resolution.rs
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/1_advanced/5_custom_resolution.rs
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/4_custom_resolution.ts
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/1_advanced/4_custom_resolution.ts
```

</TabItem>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -520,14 +520,14 @@ Publish the updated DID Document inside the Alias Output taking into account the
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/1_update_did.rs
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/1_update_did.rs
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/1_update_did.ts
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/1_update_did.ts
```

</TabItem>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -165,14 +165,14 @@ You can learn more
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/6_domain_linkage.rs
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/1_advanced/6_domain_linkage.rs
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/5_domain_linkage.ts
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/1_advanced/5_domain_linkage.ts
```

</TabItem>
Expand Down
8 changes: 4 additions & 4 deletions docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -119,14 +119,14 @@ This section shows the Rust and TypeScript `Memstore` implementations.
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/jwk_storage.ts
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/lib/jwk_storage.ts
```

</TabItem>
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_storage/memstore.rs
https://github.com/iotaledger/identity.rs/blob/v1.0.0/identity_storage/src/key_storage/memstore.rs
```

</TabItem>
Expand All @@ -138,14 +138,14 @@ https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_sto
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/key_id_storage.ts
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/lib/key_id_storage.ts
```

</TabItem>
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_id_storage/memstore.rs
https://github.com/iotaledger/identity.rs/blob/v1.0.0/identity_storage/src/key_id_storage/memstore.rs
```

</TabItem>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,31 +36,12 @@ In the IOTA Identity Framework, you can create a Verifiable Credential with the
- [**Evidence**](https://www.w3.org/TR/vc-data-model/#evidence): Optional list of objects that can be used by the issuer to provide the verifier with additional supporting information in a verifiable credential.
- [**Non-Transferable**](https://www.w3.org/TR/vc-data-model/#nontransferable-property): Optional flag that indicates that a verifiable credential must only be encapsulated in a [verifiable presentation](./../../explanations/verifiable-presentations.mdx) whose proof was issued by the credential subject.

## Signing {#signing}

After creation, the issuer signs the verifiable credential using one of their private keys,
embedding the digital signature in its [proof](https://www.w3.org/TR/vc-data-model/#proofs-signatures) section.

This is what allows verifiers to independently validate the credential using the corresponding public key from the issuer's DID Document.

### Proof Options {#proof-options}

A digital signature on a verifiable credential both provides data integrity and proves the DID of the issuer.
The proof section embedded in a credential may also include additional metadata.

The following metadata properties can be configured by the framework and are optional and omitted by default:

- **Created**: Timestamp of when the credential was signed, recommended.
- **Expires**: Timestamp after which the signature is no longer considered valid. Implementers should prefer to set the dedicated **Expiration Date** property on credentials instead.
- **Proof Purpose**: Indicates the purpose of the signature.
- **AssertionMethod**: To assert a claim. The signing verification method must have an [`assertionMethod`](https://www.w3.org/TR/did-core/#assertion) relationship to be valid.
- **Authentication**: To authenticate the signer. The signing verification method must have an [`authentication`](https://www.w3.org/TR/did-core/#authentication) relationship to be valid.

Most verifiable credentials should be signed with the assertion method proof purpose
to clearly indicate that the signature is asserting a claim and restrict it to valid verification methods.
Whereas a proof may be attached to a [verifiable presentation](./../../explanations/verifiable-presentations.mdx) for authentication purposes.
## Signing {#signing}

Other metadata fields such as `challenge` and `domain` may be included, however they are more pertinent for [verifiable presentations](./../../explanations/verifiable-presentations.mdx).
After preparing the verifiable credential, the issuer creates a signed JWT containing VC in the claims using one of their private keys. This is what allows verifiers to independently validate the credential using the corresponding public key from the issuer's DID Document.

## Validation

Expand All @@ -71,7 +52,7 @@ Verifiers should ensure certain properties of a credential are valid when receiv
The IOTA Identity Framework supports the following checks during credential validation:

- **Semantic structure**: Ensures the credential adheres to the specification.
- **Proof**: Verifies the signature against the DID Document of the issuer.
- **Signature**: Verifies the JWS against the DID Document of the issuer.
- **Optional validations**: Additional checks on credential properties, and the signature can be configured by specifying [Validation Options](#validation-options).

### Validation Options
Expand All @@ -80,7 +61,7 @@ These options specify conditions that specific properties in a credential must s

- **Expiry Date**: Check that the [`expirationDate`](https://www.w3.org/TR/vc-data-model/#expiration) property, if present, is not before a specific datetime. Defaults to the current datetime if unset.
- **Issuance Date**: Check that that [`issuanceDate`](https://www.w3.org/TR/vc-data-model/#issuance-date) property, if present, is not after a specific datetime. Defaults to the current datetime if unset.
- **Verifier Options**: Validates aspects of the credential signature and its metadata, see [Proof Options](#proof-options).
- **Verifier Options**: Validates aspects of the credential signature.

## Sharing Verifiable Credentials

Expand All @@ -102,14 +83,14 @@ In this example, the issuer signs a `UniversityDegreeCredential` with Alice's na
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs#L67-L98
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/5_create_vc.rs#L67-L98
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L51-L74
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L51-L74
```

</TabItem>
Expand All @@ -123,14 +104,14 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs#L105-L113
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/5_create_vc.rs#L105-L113
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L83-L88
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L83-L88
```

</TabItem>
Expand All @@ -146,14 +127,14 @@ allowing Alice to take control of it and share it with anyone.
<TabItem value="rust" label="Rust">

```rust reference
https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs
https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/5_create_vc.rs
```

</TabItem>
<TabItem value="typescript-node" label="Typescript (Node.js)">

```ts reference
https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts
https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts
```

</TabItem>
Expand Down
Loading
Loading